VAL
Virtuoso Authentication Layer
Package VAL.DBA

Functions

 acl_group_addCondition (varchar serviceId, varchar name, varchar criteria=null, varchar comparator=null, varchar value=null, varchar query=null, varchar property=null, any object=null, varchar realm, varchar ipAddressPattern=null)
 Add a condition to an existing conditional group. More...
 
 acl_group_list (varchar serviceId, varchar type=null, integer details=0, varchar format, varchar realm)
 
 acl_group_new (varchar serviceId, varchar name, varchar comment=null, varchar type="static", any members=null, varchar realm)
 Create a new group. More...
 
 acl_group_remove (varchar serviceId, varchar name, varchar realm)
 Remove an existing group. More...
 
 acl_group_removeCondition (varchar serviceId, varchar uri, varchar realm)
 Remove a condition from a conditional group. More...
 
 acl_group_removeConditions (varchar serviceId, varchar name, varchar criteria=null, varchar comparator=null, varchar value=null, varchar query=null, varchar realm)
 
 acl_group_update (varchar serviceId, varchar name, varchar newName, varchar newComment, any addMembers, any removeMembers, integer overwrite=0, varchar realm)
 Update an existing group. More...
 
 acl_iri (varchar s)
 
 acl_rule_get (varchar serviceId, any iris, varchar format, varchar realm)
 
 acl_rule_list (varchar serviceId, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, varchar realm=null, integer details=0, varchar format=null, varchar scope=null, varchar label=null)
 
 acl_rule_new (varchar serviceId, varchar subject=null, integer recursive=0, varchar agent=null, varchar agentClass=null, any access, varchar realm, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null)
 Create a new ACL rule. More...
 
 acl_rule_remove (varchar serviceId, varchar uri, varchar realm)
 
 acl_rule_update (varchar serviceId, varchar uri, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, integer overwrite=0, varchar realm, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null)
 
 acls_enabled_for_scope (varchar scope, varchar realm=null, int fallbackValue=0)
 Checks if ACL rule evaluation is enabled for a given scope. More...
 
 add_default_vdirs ()
 
 add_graph_ownership (varchar serviceId, varchar graphIri)
 
 add_ownership_graph (varchar uri, varchar scope)
 Add a resource ownership graph. More...
 
 add_resource_ownership (varchar scope, varchar resource, varchar serviceId)
 Add a resource ownership relation. More...
 
 add_same_as_relation (varchar serviceId1, varchar serviceId2)
 Mark two service ids as being the same. More...
 
 add_sid_to_url (varchar url, varchar service=null, varchar serviceId=null, varchar realm=null, varchar sidParamName="sid", varchar cookieSidName="sid", any options=null, varchar sid=null)
 
 authentication_details_for_connection (varchar sid, varchar serviceId, varchar uname, int isRealUser, varchar realm=null, varchar sidParamName="sid", any cert=null, varchar webidGraph=null)
 
 authentication_service_icon_path (varchar service, integer size)
 
 browserid_verify_assertion (varchar assertion, varchar audience, varchar browserid)
 Verify a BrowserID assertion. More...
 
 build_acl_rule_sparql_pattern (varchar usrIri, varchar ruleGraph, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, varchar realm=null, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null, int readOnly=0)
 
 build_restriction_sparql_pattern (varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, varchar parameter=null, varchar serviceId=null, varchar label=null)
 
 check_access_mode_for_resource (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm, varchar mode, varchar scope, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int evalRecursiveRules=0)
 Convinience procedure to check for a specific mode on one resource. More...
 
 check_acl_group_condition (varchar serviceId, varchar criteria, varchar compPattern, varchar value, varchar query, varchar property, varchar object, varchar maker, any cert=null, varchar webidGraph=null, varchar sameAsGraph=null)
 
 check_acls_for_named_graph (varchar serviceId, varchar uname=null, varchar ipAddress=null, varchar graphUri, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int includeVirtuosoSecurity=1)
 Check access for a given user and named graph. More...
 
 check_acls_for_resource (varchar serviceId, varchar ipAddress=null, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int evalRecursiveRules=0)
 Find permissions for resources as set by ACL rules in a certain realm. More...
 
 check_acls_for_resource_basic (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 Check Basic ACLs for a resource. More...
 
 check_acls_for_resource_conditional (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 Check Conditional ACLs for a resource. More...
 
 check_acls_for_resource_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 Check ACLs granting access to IP Addresses. More...
 
 check_acls_for_resource_public (varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 Check Public ACLs for a resource. More...
 
 check_conditional_group_membership (varchar groupIri, varchar serviceId, varchar owner, varchar realm, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null)
 Check if a given serviceId is part of a given conditional group. More...
 
 check_resource_ownership (varchar serviceId, varchar resource, varchar scope, varchar sameAsGraph=null)
 Check the ownership of a resource. More...
 
 clear_graph_acl_cache (varchar serviceId=null, varchar realm=null, int forced=0)
 Clear the named graph ACL cache for a given service id and realm. More...
 
 count_acl_rules_for_resource (varchar resource, varchar scope, varchar realm=null)
 Count the number of ACL rules for a given resource. More...
 
 create_acl_group_condition_uri (varchar serviceId)
 
 create_acl_group_uri (varchar serviceId)
 
 create_acl_rule_uri (varchar serviceId)
 
 create_login_page_url (varchar url, varchar deniedService=null, varchar deniedServiceId=null, varchar realm=null)
 
 create_restriction_uri ()
 
 create_val_vhosts (varchar vhost, varchar lhost, integer ssl=0, varchar httpsCert=null, varchar httpsKey=null, int httpsVerify=null, int httpsCvDepth=null)
 Create the necessary virtual hosts for using VAL authentication on the given endpoint. More...
 
 dav_resource_owner_by_url (varchar url, integer resOwnerId, varchar resOwnerUName, varchar resOwnerName, varchar resOwnerEmail)
 
 dav_resource_owner_get_service_accounts (integer resOwnerId)
 
 default_smtp_server ()
 Reads the default smpt server from the Virtuoso configuration. More...
 
 digest_authentication (varchar uname, varchar nonce, varchar pwdHash)
 
 email_address_for_service_id (varchar serviceId)
 Find an email address for the given service id. More...
 
 ensure_control_permissions_on_res (varchar serviceId, varchar resource, any access, varchar realm, varchar scope)
 
 exec_sparql (varchar query, any params=null, integer useCache=0)
 
 exec_sparql_with_format (varchar query, varchar format, integer useCache=0)
 
 exec_sql (varchar query, any params=null, int useCache=1)
 
 extract_acl_group_conditions_from_blob (varchar ruleData, varchar format)
 
 extract_acl_groups_from_blob (varchar groupData, varchar format)
 
 extract_acl_rules_from_blob (varchar ruleData, varchar format)
 
 extract_restrictions_from_blob (varchar restData, varchar format)
 
 find_acl_permissions_basic (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 
 find_acl_permissions_conditional (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 
 find_acl_permissions_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 
 find_acl_permissions_public (varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 
 find_group_by_name_or_iri (varchar serviceId, varchar name, varchar realm)
 
 find_group_condition_by_iri (varchar serviceId, varchar uri, varchar realm)
 
 find_oauth_session_for_service (varchar serviceId, varchar service, varchar requiredScope=null)
 
 find_restriction_by_iri (varchar serviceId, varchar uri, varchar realm)
 
 find_restrictions (varchar serviceId=null, varchar ipAddress=null, varchar resource, varchar realm, varchar webidGraph=null, any certificate=null, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
 Find the restriction values for a given resource. More...
 
 find_restrictions_basic (varchar serviceId, varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
 Find the restriction values from basic rules. More...
 
 find_restrictions_conditional (varchar serviceId, varchar resource, varchar realm, varchar webidGraph=null, any certificate=null, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
 Find the restriction values from conditional rules. More...
 
 find_restrictions_ip_address (varchar ipAddress, varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null)
 Find the restriction values from IP Address based rules. More...
 
 find_restrictions_max (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar parameter=null, varchar sameAsGraph=null)
 Get the maximum restriction value for a given resource. More...
 
 find_restrictions_min (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar parameter=null, varchar sameAsGraph=null)
 Get the minimum restriction value for a given resource. More...
 
 find_restrictions_public (varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null)
 Find the restriction values from public rules. More...
 
 find_rule_by_iri (varchar serviceId, varchar uri, varchar realm)
 
 foaf_iri (varchar s)
 
 get_accept_mime_type (varchar format=null)
 
 get_acl_schema_graph ()
 The VAL ACL Schema graph IRI. More...
 
 get_applicable_access_for_scope (varchar scope)
 Get the list of applicable access modes for a given scope. More...
 
 get_authentication_details_for_connection (varchar sid, varchar serviceId, varchar uname, int isRealUser, varchar realm=null, varchar sidParamName="sid", any cert, varchar webidGraph=null)
 Checks for existing authentication information in the current connection. More...
 
 get_connection_realm (varchar fallback=null)
 Get the realm for the current http connection. More...
 
 get_content_mime_type ()
 
 get_dav_scope ()
 The IRI of the DAV ACL rule scope. More...
 
 get_default_access_for_scope (varchar scope)
 Get the list of default access modes for a given scope. More...
 
 get_default_realm ()
 The default application realm. More...
 
 get_owned_graphs (varchar serviceId)
 Get the graphs owned by a given service id. More...
 
 get_ownership_graph_uri (varchar scope)
 
 get_profile_graph_uri (varchar serviceId)
 The graph URI for a given service id. More...
 
 get_profile_name (varchar serviceId)
 Get the full name for the given profile URI. More...
 
 get_profile_url (varchar serviceId, varchar service=null)
 Get a profile URL for a given service ID. More...
 
 get_query_scope ()
 The IRI of the Query ACL rule scope. More...
 
 get_realm_config_value (varchar realm, varchar property)
 Convinience procedure to get a config value from the given realm. More...
 
 get_resource_owner (varchar resource, varchar scope)
 Get the owner of a resource. More...
 
 get_restrictions_scope ()
 The IRI of the Restrictions ACL rule scope. More...
 
 get_service_client_key (varchar service, any clientId)
 Get the key and secret for the given service API. More...
 
 get_sparql_html_footer (varchar pageUrl)
 
 get_sparql_permissions (varchar serviceId, varchar uname=null, varchar ipAddress=null, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null)
 Check the generic SPARQL permissions for the given authentication information. More...
 
 get_sparql_permissions_for_sql_user (varchar uname)
 
 get_sparql_scope ()
 The IRI of the Private named graphs ACL rule scope. More...
 
 http_to_https_uri (varchar uri, int checkForVhost=0)
 Convert an HTTP URI into its HTTPS counterpart. More...
 
 is_admin_user (varchar uname)
 Check if a given SQL user is dba or in the admin group (role) More...
 
 load_triples_into_tmp_graph (varchar data, varchar format)
 
 logout (varchar sid=null, varchar sidParamName="sid")
 Clear authentication information. More...
 
 new_user_session (varchar uname, varchar realm=null, int checkDeactivated=0, any options=null)
 
 normalize_dav_path (varchar url)
 Normalizes the path in a DAV url. More...
 
 normalize_host (varchar vhost, varchar lhost)
 
 normalize_vhost_and_lhost (varchar vhost, varchar lhost)
 
 oauth_refresh_token (varchar service=null, varchar serviceId=null, int force=0, varchar oauthSid=null, varchar scope=null)
 Refresh an OAuth access token based on service type and service id. More...
 
 oplacl_iri (varchar s)
 
 oplres_iri (varchar s)
 
 ownership_graph_group (varchar scope)
 The URI of the graph group used to combine all resource ownership graphs. More...
 
 prepare_sql_params (varchar _sql, any _sqlParams, any _params)
 
 rdfs_iri (varchar s)
 
 remove_graph_ownership (varchar serviceId, varchar graphIri)
 
 remove_ownership_graph (varchar uri, varchar scope)
 Remove a resource ownership graph. More...
 
 remove_resource_ownership (varchar scope, varchar resource, varchar serviceId)
 
 remove_user_online_mapping (varchar service, varchar serviceId)
 
 request_login_nonce ()
 
 restriction_delete (varchar uri, varchar realm=null, varchar serviceId=null)
 Delete a restriction. More...
 
 restriction_get (any iris, varchar format, varchar realm, varchar serviceId=null)
 Get the details one or more restrictions. More...
 
 restriction_list (varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, integer details=0, varchar format=null, varchar parameter=null, varchar serviceId=null, varchar label=null)
 List restrictions defined in a realm. More...
 
 restriction_new (varchar name=null, varchar comment=null, varchar resource, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm=null, varchar parameter=null, varchar serviceId=null, varchar label=null)
 Create a new ACL restriction. More...
 
 restriction_update (varchar uri, varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, varchar parameter=null, varchar serviceId=null, varchar label=null)
 Update properties of an existing restriction. More...
 
 send_notification_email (varchar recipient, varchar subject, varchar text)
 Send a notification email to some email address from the system. More...
 
 service_from_profile_uri (varchar url)
 Extract service name from online account URI. More...
 
 service_id_to_sql_user (varchar serviceId)
 Try to find a connected SQL account for a given serviceId. More...
 
 session_id_for_connection (varchar sid, varchar serviceId, varchar realm=null, varchar sidParamName="sid")
 
 set_graph_context_query (varchar serviceId, varchar realm=null, any certificate=null, varchar webidGraph=null)
 Set the required connection settings for the read-only graph security system. More...
 
 set_graph_ownership (varchar serviceId, varchar graphIri)
 
 set_keyword (varchar name, any params, any value)
 
 set_resource_ownership (varchar scope, varchar resource, varchar serviceId)
 Set the owner of a resource in a given scope. More...
 
 setup_val_host (varchar httpVHost, varchar httpLHost, varchar httpsVHost, varchar httpsLHost, varchar httpsCert, varchar httpsKey)
 Setup a VAL host. More...
 
 smtp_server_available ()
 Check if a valid SMTP server has been configured. More...
 
 sparql_access_modes_to_bitmask (any modes)
 
 sparql_graph_ownership_graph ()
 Graph containing the ownership relations for named graphs. More...
 
 thirdparty_authentication_default_callback (varchar url, any opts, varchar service, varchar serviceId, any profile, any oauthInfo, varchar oauthSid)
 Default callback procedure for VAL.DBA.thirdparty_authentication_url. More...
 
 thirdparty_authentication_default_error_callback (varchar url, any opts, varchar service, any _sqlState, any _sqlMessage)
 
 thirdparty_authentication_url (varchar service, varchar data, varchar callback, varchar successProc=null, varchar errorProc=null, any params=null, varchar scope="basic", varchar clientIp=null, varchar realm=null)
 Create an authentication URL for any supported 3rd-party service. More...
 
 thirdparty_callback (varchar state)
 
 thirdparty_service_labels ()
 A simple map of all supported third-party authentication services and their labels. More...
 
 thirdparty_services ()
 A simple map of all supported third-party authentication services, their labels, and oauth apikey urls. More...
 
 thirdparty_supported_services ()
 A simple map of all the supported authentication services that can be used in thirdparty_authentication_url. More...
 
 update_graph_acl_cache (varchar serviceId, varchar realm=null, any certificate=null, varchar webidGraph=null, int forced=0)
 Update the named graph ACL cache VAL.DBA.VAL_GRAPH_ACL_CACHE. More...
 
 update_user_online_mapping (varchar service=null, varchar serviceId, varchar oauthSid=null, any uname)
 
 user_personal_uri (varchar uname)
 An SQL user's personal URI. More...
 
 username_for_online_account (varchar service=null, varchar serviceId, any cert=null, varchar webidGraph=null, varchar realm=null)
 
 val_acl_group_graph (varchar realm, int createGraph=0)
 
 val_acl_rule_graph (varchar realm, int createGraph=0)
 
 val_config_graph_uri ()
 
 val_get_certificate_info (int detail, any cert)
 
 val_restrictions_graph (varchar realm=null, int createGraph=0)
 
 vector_intersect (any v1, any v2)
 
 vector_merge (any v1, any v2)
 

Function Documentation

VAL.DBA.acl_iri ( varchar  s)

Create a ACL URI. The procedure simply appends the given s to the acl namespace.

Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;
VAL.DBA.add_default_vdirs ( )

Configure the default VAL vhosts

VAL.DBA.add_graph_ownership ( varchar  serviceId,
varchar  graphIri 
)
VAL.DBA.add_same_as_relation ( varchar  serviceId1,
varchar  serviceId2 
)

Mark two service ids as being the same.

VAL supports owl:sameAs relations for ACL rules and the like. This procedure allows to mark two service ids as being "the same". An owl:sameAs relation will be added to VAL's sameAs graph and optionally an entry will be added to VAL_USER_ONLINE_ACCOUNTS if applicable.

Caution: only ever call this procedure if you are certain that the two accounts are the same. This is typically the case if the user authenticated with one service while working with a session connected to the other.

See also
VAL.DBA.val_owl_sameas_graph()
VAL.DBA.authentication_details_for_connection ( varchar  sid,
varchar  serviceId,
varchar  uname,
int  isRealUser,
varchar  realm = null,
varchar  sidParamName = "sid",
any  cert = null,
varchar  webidGraph = null 
)
VAL.DBA.authentication_service_icon_path ( varchar  service,
integer  size 
)

Creates the path to an image that can be used to create a login button for the given service type. It uses the images provided by VAL.

Example:

If service type facebook and size \ 24 are given the following path is returned:

/val/img/social24/facebook.png

If no specific images does exist either ods.png or unknown.png are used, depending on whether the given service is an ODS instance added via ODS' admin.oauth.odshosts.new() API or not.

VAL.DBA.build_acl_rule_sparql_pattern ( varchar  usrIri,
varchar  ruleGraph,
varchar  subject = null,
integer  recursive = null,
varchar  agent = null,
varchar  agentClass = null,
any  access = null,
varchar  realm = null,
varchar  name = null,
varchar  comment = null,
varchar  scope = null,
varchar  label = null,
int  readOnly = 0 
)

This is an internal helper function to avoid code duplication in acl.rule.*

It creates a SPARQL pattern which selects the ACL rules as indicated by the paramters.

Also it improves input parameters by replacing empty strings with null values for easier processing.

VAL.DBA.build_restriction_sparql_pattern ( varchar  name = null,
varchar  comment = null,
varchar  resource = null,
varchar  agent = null,
varchar  agentClass = null,
decimal  minValue = null,
decimal  maxValue = null,
varchar  realm,
varchar  parameter = null,
varchar  serviceId = null,
varchar  label = null 
)

Build a SPARQL pattern to query or insert restrictions.

This procedure is used internally by the ACL restrictions system and should normally never be called in another context.

VAL.DBA.check_acl_group_condition ( varchar  serviceId,
varchar  criteria,
varchar  compPattern,
varchar  value,
varchar  query,
varchar  property,
varchar  object,
varchar  maker,
any  cert = null,
varchar  webidGraph = null,
varchar  sameAsGraph = null 
)

Check an ACL group condition.

Internal procedure used by VAL.DBA.find_acl_permissions_conditional().

VAL.DBA.check_conditional_group_membership ( varchar  groupIri,
varchar  serviceId,
varchar  owner,
varchar  realm,
varchar  webidGraph = null,
any  certificate = null,
varchar  sameAsGraph = null 
)

Check if a given serviceId is part of a given conditional group.

Parameters
groupIriThe IRI of the conditional group.
serviceIdThe IRI of the person to check for group membership.
ownerThe owner of the rule for which this test is relevant. This is used in check_acl_group_condition to set the graph permissions, only graph readable by the rule owner are used for evaluation of conditions.
realmThe application realm.
webidGraphThe graph in which the WebID profile is cached.
certificateThe client certificate in case of WebID authentication.
sameAsGraphThis is the graph from which VAL will read owl:sameAs triples to determine which service URIs denote the same person. This defaults to VAL.DBA.val_owl_sameas_graph () which is based on account mappings in VAL.DBA.VAL_USER_ONLINE_ACCOUNTS.
Returns
1 if serviceId is part of group groupIri, 0 otherwise.
VAL.DBA.clear_graph_acl_cache ( varchar  serviceId = null,
varchar  realm = null,
int  forced = 0 
)

Clear the named graph ACL cache for a given service id and realm.

Parameters
serviceIdThe service id (personal uri) of the grantee to clear the cache for. If null then the cache will be cleared for all service ids.
realmThe realm in which to clear the cache. Falls back to the default realm oplacl:DefaultRealm.
VAL.DBA.create_acl_group_condition_uri ( varchar  serviceId)

Internal helper procedure. Do not use outside of VAL!

VAL.DBA.create_acl_group_uri ( varchar  serviceId)

Internal helper procedure. Do not use outside of VAL!

VAL.DBA.create_acl_rule_uri ( varchar  serviceId)

Internal helper procedure. Do not use outside of VAL!

VAL.DBA.create_restriction_uri ( )

Internal helper procedure. Do not use outside of VAL!

VAL.DBA.create_val_vhosts ( varchar  vhost,
varchar  lhost,
integer  ssl = 0,
varchar  httpsCert = null,
varchar  httpsKey = null,
int  httpsVerify = null,
int  httpsCvDepth = null 
)

Create the necessary virtual hosts for using VAL authentication on the given endpoint.

This procedure will setup the required vhosts for /val and /val/api. The former is used to expose the VAL images and the 40x_page for /DAV. The latter only hosts the thirdparty_callback() function which is required for OAuth and OpenID authentication. In the case of an SSL vhost client certificates will be disabled on the host.

A typical configuration would be as follows:

VAL.DBA.create_val_vhosts ('mysite.com:443', 'mysite.com:443', 1, 'db:https_key_mysite_com', 'db:https_key_mysite_com');
Parameters
vhostThe virtual host name that the browser presents as Host: entry in the request headers. i.e. Name-based virtual hosting. The default value is taken from the Virtuoso INI file.
lhostThe address of the network interface the Virtuoso HTTP server uses to listen and accept connections. The default value is taken from the Virtuoso INI file.
ssl1 if the host to configure is SSL-secured. If this is set to null then the values are determined automatically based on the the first vdir found for the listener.
httpsCertThe name of the https certificate to use for the SSL endpoint. If this is set to null then the value is determined automatically based on the the first vdir found for the listener.
httpsKeyThe name of the https key to use for the SSL endpoint. Often the same as httpsCert. If this is set to null then the value is determined automatically based on the the first vdir found for the listener.
httpsVerifyThe https_verify value for the SSL listener. If this is set to null then the value is determined automatically based on the the first vdir found for the listener.
httpsCvDepthThe https_cv_depth value for the SSL listener. If this is set to null then the value is determined automatically based on the the first vdir found for the listener.

Typically this procedure is not called directly but via VAL.DBA.setup_val_host().

VAL.DBA.dav_resource_owner_by_url ( varchar  url,
integer  resOwnerId,
varchar  resOwnerUName,
varchar  resOwnerName,
varchar  resOwnerEmail 
)

Determine the owner of any DAV resource by URL.

Returns
1 on success, 0 if the resource could not be found.
Deprecated:
Use VAL.DBA.get_resource_owner() instead.
VAL.DBA.dav_resource_owner_get_service_accounts ( integer  resOwnerId)

Get the owner's service accounts which have a profile url

param resOwnerId The ID of the account

Returns
vector of vectors with NAME, URL
VAL.DBA.ensure_control_permissions_on_res ( varchar  serviceId,
varchar  resource,
any  access,
varchar  realm,
varchar  scope 
)

Checks if the given serviceId owns a given resource or has permission to grant the given access rights to anyone. Throws a signal if not.

Internal procedure. Do not use outside of VAL.

VAL.DBA.exec_sparql ( varchar  query,
any  params = null,
integer  useCache = 0 
)

Execute a sparql query via exec() and thow the signal in case of an error.

VAL.DBA.exec_sparql_with_format ( varchar  query,
varchar  format,
integer  useCache = 0 
)

Execute a describe or construct query, using the given result format.

Throws a signal on error.

VAL.DBA.exec_sql ( varchar  query,
any  params = null,
int  useCache = 1 
)

Execute a SQL query via exec() and thow the signal in case of an error.

VAL.DBA.extract_acl_group_conditions_from_blob ( varchar  ruleData,
varchar  format 
)

Reads the given ruleData and extract all the ACL group conditions given within.

Returns
A vector of vectors, each containing a condition where each condition contains: query or criteria, comparator, and value
VAL.DBA.extract_acl_groups_from_blob ( varchar  groupData,
varchar  format 
)

Reads the given ruleData and extract all the ACL groups given within.

Returns
A vector of vectors, each containing name, comment, type (oplacl:ConditionalGroup or null), vector or members, vector of conditions where each condition contains: type, query or criteria or ip pattern, comparator, and value
VAL.DBA.extract_acl_rules_from_blob ( varchar  ruleData,
varchar  format 
)

Reads the given ruleData and extract all the ACL rules given within.

Returns
A vector of vectors, each containing
  • subject
  • recursive (0 or 1)
  • agent
  • agentClass
  • access vector (containing uris like oplacl:Read or oplacl:GrantWrite)
  • name
  • comment
  • scope
VAL.DBA.extract_restrictions_from_blob ( varchar  restData,
varchar  format 
)

Extract a set of restriction objects from a blob of data.

Returns
A vector of vectors, each representing one restriction consisting of:
  • name
  • comment
  • resource
  • agent
  • agent class
  • min value
  • max value
  • restricted parameter
  • label
VAL.DBA.find_group_by_name_or_iri ( varchar  serviceId,
varchar  name,
varchar  realm 
)

This is a helper function which only exists to avoid code duplication in acl.group.*

It finds a group in a given named graph by name or IRI. If the group is not found an error is signaled.

VAL.DBA.find_group_condition_by_iri ( varchar  serviceId,
varchar  uri,
varchar  realm 
)

This is a helper function which only exists to avoid code duplication in acl.group.*

It finds a group condition by IRI. If the group is not found an error is signaled.

Returns
the uri of the group the condition belongs to.
VAL.DBA.find_oauth_session_for_service ( varchar  serviceId,
varchar  service,
varchar  requiredScope = null 
)

Get an OAuth session id (OAUTH..CLI_SESSIONS:CS_SID) for the given serviceId and the given service and scope. The service can be any of the VAL-supported OAuth services.

The serviceId doe not have to be for the given service, as long as a owl:sameAs relation exists.

Parameters
serviceIdThe authenticated person in need of an OAuth session for service service.
serviceThe service for which an OAUth session is required.
requiredScopeThe scope of the required OAuth session. If null any session can be used.
Returns
The OAuth session ID or null if no session matching the request could be found.
VAL.DBA.find_restriction_by_iri ( varchar  serviceId,
varchar  uri,
varchar  realm 
)

Check if a given restriction exists. If serviceId is given and is not the personal uri of dba, then the foaf:maker of the restriction is also checked.

Throws a signal in case the restriction is not found.

VAL.DBA.find_rule_by_iri ( varchar  serviceId,
varchar  uri,
varchar  realm 
)

This is a helper function which only exists to avoid code duplication in acl_rule*

It finds a rule for a given service uri and IRI. If the rule is not found an error is signaled.

VAL.DBA.foaf_iri ( varchar  s)

Create a foaf URI. The procedure simply appends the given s to the foaf namespace.

Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;
VAL.DBA.get_accept_mime_type ( varchar  format = null)

Get the mime type requested by the client from the request headers. Falling back to turtle and allowing to override with a parameter.

VAL.DBA.get_content_mime_type ( )

Get the mime type of the content provided by the client from the request headers.

VAL.DBA.get_ownership_graph_uri ( varchar  scope)

Internal procedure which returns the URI of the graph used to store ownership relations maintained by VAL itself via VAL.DBA.set_resource_ownership() and friends.

VAL.DBA.get_profile_graph_uri ( varchar  serviceId)

The graph URI for a given service id.

VAL does store certain profile details for all users that authenticated at some point via VAL. These details are stored in a private graph which only the person in question has read access to (see also VAL.DBA.store_profile_details()).

Since the Sponger already uses the service id itself as graph URI we use our own internal graph based on the service id and a urn prefix.

Returns
The profile graph URI or null if serviceId is null or empty.
VAL.DBA.get_realm_config_value ( varchar  realm,
varchar  property 
)

Convinience procedure to get a config value from the given realm.

VAL typically stores configuration by application realm. This means that most configuration settings are tied to the realm URI within the private configuration graph (VAL.DBA.val_config_graph_uri()).

This procedure simply returns the configured value for the given property or null if there is none.

Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.get_service_client_key ( varchar  service,
any  clientId 
)

Get the key and secret for the given service API.

This procedure reads client id and secret from OAUTH.DBA.APP_REG.

Parameters
serviceThe name of the service.
clientId[out]A vector containing the client ID and secret on success.
Returns
On success 1 is returned, 0 otherwise.
VAL.DBA.get_sparql_html_footer ( varchar  pageUrl)

Reads the HTML footer configured for the given web page and returns its contents or null if none was configured.

VAL.DBA.get_sparql_permissions_for_sql_user ( varchar  uname)

Find the SPARQL permissions for a given user. This refers to the system permissions which are defined by the three roles SPARQL_SELECT, SPARQL_SPONGE, and SPARQL_UPDATE.

Returns
A bitmask as follow:
  • 1 for Read
  • 2 for Write (returns 7 as write includes read and sponge)
  • 4 for Sponge (returns 5 as sponge includes read)
VAL.DBA.load_triples_into_tmp_graph ( varchar  data,
varchar  format 
)

Load the triples in data into a tmp graph and return the graph IRI.

VAL.DBA.normalize_dav_path ( varchar  url)

Normalizes the path in a DAV url.

Virtuoso allows to create different virtual dirs which point to different locations in the DAV system. This procedure allows to determine the actual DAV path (/DAV/...) of the resource in question.

Supported are both http(s) URLs and the special dav:/ urls which are used to create access-protocol-independant ACL rules on dav resources.

Example:

Given a virtual dir /test which points to /DAV/test/foo the following values for url would all return the same path:

Returns
The normalized path of the DAV resource to which url refers, or, if the given url could not be mapped to any virtual dir, the path from the url is returned.
VAL.DBA.normalize_host ( varchar  vhost,
varchar  lhost 
)

Normalizes a vhost value in the same way VHOST_DEFINE does but also replaces ini and sslini with default values from the config.

Returns
The VD in the form HOST:PORT.
VAL.DBA.normalize_vhost_and_lhost ( varchar  vhost,
varchar  lhost 
)

Normalizes vhost and lhost values the same way VHOST_DEFINE does. Running vhost and lhost values through this procedure will allow a lookup in HTTP_PATH.

VAL.DBA.oplacl_iri ( varchar  s)

Create an OPLACL URI. The procedure simply appends the given s to the oplacl namespace.

Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;
VAL.DBA.oplres_iri ( varchar  s)

Create an OPLRES URI. The procedure simply appends the given s to the oplres namespace.

VAL.DBA.prepare_sql_params ( varchar  _sql,
any  _sqlParams,
any  _params 
)
VAL.DBA.rdfs_iri ( varchar  s)

Create a RDFS URI. The procedure simply appends the given s to the RDFS namespace.

VAL.DBA.remove_graph_ownership ( varchar  serviceId,
varchar  graphIri 
)
VAL.DBA.remove_resource_ownership ( varchar  scope,
varchar  resource,
varchar  serviceId 
)
VAL.DBA.send_notification_email ( varchar  recipient,
varchar  subject,
varchar  text 
)

Send a notification email to some email address from the system.

The email will be sent from an address that can be supplied in the vad config page. However, if one is not supplied the it will use "noreply@HOST" where HOST matches the value of http_host() stripped of the port.

This proc will signal an error if email sending fails.

Parameters
recipientThe email address to send to, like foo@b.nosp@m.ar.c.nosp@m.om
subjectThe subject of the email.
textThe contents of the email.
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.service_id_to_sql_user ( varchar  serviceId)

Try to find a connected SQL account for a given serviceId.

Returns
The name of the SQL account or null if none was found.
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.set_graph_context_query ( varchar  serviceId,
varchar  realm = null,
any  certificate = null,
varchar  webidGraph = null 
)

Set the required connection settings for the read-only graph security system.

Virtuoso has a secondary graph security system which improves the performance for read-only queries considerably as compared to the graph security callback system (see also DB.DBA.SPARQL_GS_APP_CALLBACK_VAL_SPARQL_PERMS()). The idea is that one query returns the list of graphs a person has access to. This list is then cached and reused on the next query, even between connections.

Warning
Since conditional groups can be arbitrary and VAL has no way of knowing when the membership changes, it is up to the application or the administrator to invalidate the cache whenever ACLs change.
VAL.DBA.set_graph_ownership ( varchar  serviceId,
varchar  graphIri 
)
VAL.DBA.set_keyword ( varchar  name,
any  params,
any  value 
)
VAL.DBA.setup_val_host ( varchar  httpVHost,
varchar  httpLHost,
varchar  httpsVHost,
varchar  httpsLHost,
varchar  httpsCert,
varchar  httpsKey 
)

Setup a VAL host.

This procedure is used to setup an SSL-protected VAL installation. For this to work properly VAL needs to be able to map an http vhost to its https counterpart.

Without this setup WebID and OAuth services that require an https callback (like Box.com) will not work.

Example:

VAL.DBA.setup_val_host('*ini*', '*ini*', 'web.ods.openlinksw.com', ':443', 'db:https_key_web_ods', 'db:https_key_web_ods');
VAL.DBA.sparql_access_modes_to_bitmask ( any  modes)

Create a bitmask from a vector of mode uris.

  • 1 for Read
  • 2 for Write (returns 7 as write includes read and sponge)
  • 4 for Sponge (returns 5 as sponge includes read)
VAL.DBA.thirdparty_authentication_default_callback ( varchar  url,
any  opts,
varchar  service,
varchar  serviceId,
any  profile,
any  oauthInfo,
varchar  oauthSid 
)

Default callback procedure for VAL.DBA.thirdparty_authentication_url.

This callback procedure will create a session id and return the original url after setting a sid cookie. The session id can be mapped to the serviceId by querying VSPX_SESSION.

VAL.DBA.thirdparty_authentication_default_error_callback ( varchar  url,
any  opts,
varchar  service,
any  _sqlState,
any  _sqlMessage 
)
VAL.DBA.thirdparty_callback ( varchar  state)

Generic OAuth and OpenID callback. This procedure is exported as a public SOAP/HTTP call. It handles the results from the 3rd-party services and then continues on with the callback procedure as provided to VAL.DBA.thirdparty_authentication_url().

VAL.DBA.thirdparty_service_labels ( )

A simple map of all supported third-party authentication services and their labels.

Deprecated:
Please use VAL.DBA.thirdparty_services() instead.
VAL.DBA.update_graph_acl_cache ( varchar  serviceId,
varchar  realm = null,
any  certificate = null,
varchar  webidGraph = null,
int  forced = 0 
)

Update the named graph ACL cache VAL.DBA.VAL_GRAPH_ACL_CACHE.

VAL.DBA.val_acl_group_graph ( varchar  realm,
int  createGraph = 0 
)

Get the graph the groups are stored in for the given user.

Parameters
realmThe application realm for which groups should be stored.
serviceIdThe service id of the user or null for querying all groups.
VAL.DBA.val_acl_rule_graph ( varchar  realm,
int  createGraph = 0 
)

Get the graph the acl rules are stored in for the given user.

Parameters
realmThe application realm for which rules should be stored.
serviceIdThe service id of the user or null for querying all rules.
VAL.DBA.val_config_graph_uri ( )

The graph which contains the VAL configuration.

VAL.DBA.val_get_certificate_info ( int  detail,
any  cert 
)

A simple replacement for get_certificate_info which will return null if the given cert is null.

VAL.DBA.val_restrictions_graph ( varchar  realm = null,
int  createGraph = 0 
)

Get the graph the restrictions are stored in.

Parameters
realmThe application realm for which restrictions should be stored. Leave null for system restrictions.
VAL.DBA.vector_intersect ( any  v1,
any  v2 
)

Create the intersection of two vectors.

VAL.DBA.vector_merge ( any  v1,
any  v2 
)

Merge v2 into v1, eliminating duplicates.