VAL
Virtuoso Authentication Layer
|
Functions | |
VAL.DBA.add_ownership_graph (varchar uri, varchar scope) | |
Add a resource ownership graph. More... | |
VAL.DBA.add_resource_ownership (varchar scope, varchar resource, varchar serviceId) | |
Add a resource ownership relation. More... | |
VAL.DBA.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... | |
VAL.DBA.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... | |
VAL.DBA.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... | |
VAL.DBA.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... | |
VAL.DBA.check_resource_ownership (varchar serviceId, varchar resource, varchar scope, varchar sameAsGraph=null) | |
Check the ownership of a resource. More... | |
VAL.DBA.find_acl_permissions_basic (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar sameAsGraph=null, int evalRecursiveRules=0) | |
VAL.DBA.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) | |
VAL.DBA.find_acl_permissions_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0) | |
VAL.DBA.find_acl_permissions_public (varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0) | |
VAL.DBA.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... | |
VAL.DBA.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... | |
VAL.DBA.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... | |
VAL.DBA.find_restrictions_public (varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null) | |
Find the restriction values from public rules. More... | |
VAL.DBA.get_acl_schema_graph () | |
The VAL ACL Schema graph IRI. More... | |
VAL.DBA.get_dav_scope () | |
The IRI of the DAV ACL rule scope. More... | |
VAL.DBA.get_owned_graphs (varchar serviceId) | |
Get the graphs owned by a given service id. More... | |
VAL.DBA.get_query_scope () | |
The IRI of the Query ACL rule scope. More... | |
VAL.DBA.get_resource_owner (varchar resource, varchar scope) | |
Get the owner of a resource. More... | |
VAL.DBA.get_restrictions_scope () | |
The IRI of the Restrictions ACL rule scope. More... | |
VAL.DBA.get_sparql_scope () | |
The IRI of the Private named graphs ACL rule scope. More... | |
VAL.DBA.ownership_graph_group (varchar scope) | |
The URI of the graph group used to combine all resource ownership graphs. More... | |
VAL.DBA.remove_ownership_graph (varchar uri, varchar scope) | |
Remove a resource ownership graph. More... | |
VAL.DBA.set_resource_ownership (varchar scope, varchar resource, varchar serviceId) | |
Set the owner of a resource in a given scope. More... | |
VAL.DBA.sparql_graph_ownership_graph () | |
Graph containing the ownership relations for named graphs. More... | |
The procedures in the utility API can be used in applications to enforce the ACL rules and to maintain Resource Ownership. Most notably VAL.DBA.val_prepare_sparql_permissions_for_query() needs to be called before each SPARQL query to ensure proper permissions.
In contrast to the procedures in VAL Internal ACL API the usage of these procedures is encouraged and often necessary.
VAL.DBA.add_ownership_graph | ( | varchar | uri, |
varchar | scope | ||
) |
Add a resource ownership graph.
VAL uses the ownership definitions in all ownershop graphs to determine if a user is allowed to create ACL rules for a resource.
This procedure allows to add a named graph for VAL to search. This graph should contain triples like
This would allow the authenticated user http://www.facebook.com/foobar
to create ACL rules for resource urn:someresource
.
Be aware that the SPARQL ownership is handled by VAL via VAL.DBA.add_graph_ownership() and VAL.DBA.remove_graph_ownership().
Also VAL provides convinience procedures like VAL.DBA.set_resource_ownership () to avoid the need for clients to define their own ownership graphs.
VAL.DBA.add_resource_ownership | ( | varchar | scope, |
varchar | resource, | ||
varchar | serviceId | ||
) |
Add a resource ownership relation.
Instead of defining an ownership graph manually and adding it via VAL.DBA.add_ownership_graph() one can simply use VAL.DBA.add_resource_ownership(), VAL.DBA.set_resource_ownership(), and VAL.DBA.remove_resource_ownership() to simplify things and let VAL handle the rest.
This procedure will try to add a new ownership relation. In contrast to VAL.DBA.set_resource_ownership() it will not overwrite existing ownership but throw a signal instead.
VAL.DBA.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.
Checks basic ACL rules for access to one or more resources. This includes rules which grant access to a person or a static group. Conditional groups are handled by VAL.DBA.check_acls_for_resource_conditional().
In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.
serviceId | The service id which access is requested for. |
resource | The optional resource to request access to. If not given all resources serviceId has access to are returned. |
realm | The application realm in which permissions should be checked. |
mode | The optional access mode to check for. If not given all granted access modes are returned. |
scope | The optional scope of the queried rules. A scope defines the type of resource. |
sameAsGraph | This 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. |
evalRecursiveRules | If 1 then recursive rules will be evaluated for scopes other than DAV . See Recursion Based On Relations for details on how the rules are evaluated. |
VAL.DBA.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.
Checks conditional ACL rules for access to one or more resources. This includes rules which grant access to a conditional group. Conditional groups are handled by VAL.DBA.check_acls_for_resource_basic().
In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.
serviceId | The service id which access is requested for. |
resource | The optional resource to request access to. If not given all resources serviceId has access to are returned. |
realm | The application realm in which permissions should be checked. |
mode | The optional access mode to check for. If not given all granted access modes are returned. |
scope | The optional scope of the queried rules. A scope defines the type of resource. |
webidGraph | The optional named graph which contains the triples imported from the WebID profile if certificate contains an embedded WebID. |
certificate | The optional client certificate used for authentication. |
sameAsGraph | This 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. |
evalRecursiveRules | If 1 then recursive rules will be evaluated for scopes other than DAV . See Recursion Based On Relations for details on how the rules are evaluated. |
VAL.DBA.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.
Checks ACL rules for access to one or more resources. ACLs which grant access for service ids are handled by VAL.DBA.check_acls_for_resource().
ipAddress | The IP address which access is requested for. |
resource | The optional resource to request access to. If not given all resources serviceId has access to are returned. |
realm | The application realm in which permissions should be checked. |
mode | The optional access mode to check for. If not given all granted access modes are returned. |
scope | The optional scope of the queried rules. A scope defines the type of resource. |
evalRecursiveRules | If 1 then recursive rules will be evaluated for scopes other than DAV . See Recursion Based On Relations for details on how the rules are evaluated. |
VAL.DBA.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.
Checks public ACL rules for access to one or more resources. This means rules that grant access to foaf:Agent
. Basic rules are handled by VAL.DBA.check_acls_for_resource_basic(), conditional groups are handled by VAL.DBA.check_acls_for_resource_conditional().
In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.
resource | The optional resource to request access to. If not given all resources serviceId has access to are returned. |
realm | The application realm in which permissions should be checked. |
mode | The optional access mode to check for. If not given all granted access modes are returned. |
scope | The optional scope of the queried rules. A scope defines the type of resource. |
evalRecursiveRules | If 1 then recursive rules will be evaluated for scopes other than DAV . See Recursion Based On Relations for details on how the rules are evaluated. |
VAL.DBA.check_resource_ownership | ( | varchar | serviceId, |
varchar | resource, | ||
varchar | scope, | ||
varchar | sameAsGraph = null |
||
) |
Check the ownership of a resource.
Check if the given serviceId
does own the given resource
in the given scope
. If scope
is not null
then specific ownership is tested. That means specific scopes can have their own way of defining ownership. A typical example is DAV which is checked via the permissions of the resource.
1
in case serviceId
does own resource
, 0
otherwise.VAL.DBA.find_acl_permissions_basic | ( | varchar | serviceId, |
varchar | resource = null , |
||
varchar | realm, | ||
varchar | mode = null , |
||
varchar | scope = null , |
||
varchar | sameAsGraph = null , |
||
int | evalRecursiveRules = 0 |
||
) |
Find all permissions a given serviceId
has on a given resource
(or any resource if omitted) in the given application realm
. If mode
is specified, only that mode is verified and returned. This procedure only checks basic rules, ie. such rules that grant permissions to a person or a static group.
This procedure creates a result set. As such it is suitable for queries and can be used as follows:
VAL.DBA.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 all permissions a given serviceId
has on a given resource
(or any resource if omitted) in the given application realm
. If mode
is specified, only that mode is verified and returned. This procedure only checks conditional rules, ie. such rules that grant permissions to a conditional group.
This procedure creates a result set. As such it is suitable for queries and can be used as follows:
VAL.DBA.find_acl_permissions_ip_address | ( | varchar | ipAddress, |
varchar | resource = null , |
||
varchar | realm, | ||
varchar | mode = null , |
||
varchar | scope = null , |
||
int | evalRecursiveRules = 0 |
||
) |
Find all permissions a given ipAddress
has on a given resource
(or any resource if omitted) in the given application realm
. If mode
is specified, only that mode is verified and returned.
This procedure creates a result set. As such it is suitable for queries and can be used as follows:
VAL.DBA.find_acl_permissions_public | ( | varchar | resource = null , |
varchar | realm, | ||
varchar | mode = null , |
||
varchar | scope = null , |
||
int | evalRecursiveRules = 0 |
||
) |
Find all permissions granted by public rules on a given resource
(or any resource if omitted) in the given application realm
. If mode
is specified, only that mode is verified and returned. This procedure only checks public rules, ie. such rules that grant permissions to foaf:Agent
.
This procedure creates a result set. As such it is suitable for queries and can be used as follows:
VAL.DBA.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.
This procedure will find the least restrictive values from all basic rules in the given realm
for the given resource
. This includes restrictions scoped to individuals and static groups.
sameAsGraph
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.
Typically one would use VAL.DBA.find_restrictions() instead.
VAL.DBA.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.
This procedure will find the least restrictive values from all conditional rules in the given realm
for the given resource
. This means restrictions scoped to conditional groups.
sameAsGraph
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.
Typically one would use VAL.DBA.find_restrictions() instead.
VAL.DBA.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.
This procedure will find the least restrictive values from all IP Address based rules in the given realm
for the given resource
.
Typically one would use VAL.DBA.find_restrictions() instead.
VAL.DBA.find_restrictions_public | ( | varchar | resource, |
varchar | realm, | ||
decimal | minValue, | ||
decimal | maxValue, | ||
varchar | parameter = null |
||
) |
Find the restriction values from public rules.
This procedure will find the least restrictive values from all public rules in the given realm
for the given resource
.
Typically one would use VAL.DBA.find_restrictions() instead.
VAL.DBA.get_acl_schema_graph | ( | ) |
The VAL ACL Schema graph IRI.
To ensure that nobody can tamper with default access modes and the like it is important that the Openlink ACL and restriction ontologies are stored in a private trusted graph.
VAL uses the ACL schema graph urn:virtuoso:val:acl:schema
for this purpose. It is mandatory for both the ACL and the restriction ontologies to be loaded into this graph for the VAL ACL system to work properly.
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: VAL.DBA.get_dav_scope | ( | ) |
The IRI of the DAV ACL rule scope.
This scope is special as VAL contains special ownership handling for DAV resources and collections. See DAV ACL Rules for details.
oplacl:Dav
.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: VAL.DBA.get_owned_graphs | ( | varchar | serviceId | ) |
Get the graphs owned by a given service id.
VAL manages the ownership relations for named graphs. This procedure lists all graphs which have been set as owned by the given person.
VAL.DBA.get_query_scope | ( | ) |
The IRI of the Query ACL rule scope.
This is used to group ACL rules which grant permission to execute SQL or SPARQL expressions in general. Applicable resources are:
urn:virtuoso:access:sql
- Grants read and/or write access for SQL expressions.urn:virtuoso:access:sparql
- Grants read, write, and sponge permissions for SPARQL in general. Access to specific graphs is handled via rules in the sparql scope.VAL.DBA.get_resource_owner | ( | varchar | resource, |
varchar | scope | ||
) |
Get the owner of a resource.
This procedure checks resource ownership graphs and handles DAV as a special case.
resource
or null
if none could be found.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: VAL.DBA.get_restrictions_scope | ( | ) |
The IRI of the Restrictions ACL rule scope.
This scope is only used for permissions for restriction creation. By default only dba
can create restrictions on any resource. ACL rules creates in this scope allow to grant the right to create restrictions to others.
oplres:Restrictions
.VAL.DBA.get_sparql_scope | ( | ) |
The IRI of the Private named graphs ACL rule scope.
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: VAL.DBA.ownership_graph_group | ( | varchar | scope | ) |
The URI of the graph group used to combine all resource ownership graphs.
Resource ownership is managed in several graphs. Applications can simply register their own ownership graphs via VAL.DBA.add_ownership_graph() for the ACL system to pick up the information within.
This graph group combines all the ownership graphs for one scope, ie. it can be used to query all ownership graphs at once.
VAL.DBA.remove_ownership_graph | ( | varchar | uri, |
varchar | scope | ||
) |
Remove a resource ownership graph.
VAL uses the ownership definitions in all ownershop graphs to determine if a user is allowed to create ACL rules for a resource.
This procedure allows to remove a named graph for VAL not to search anymore.
VAL.DBA.set_resource_ownership | ( | varchar | scope, |
varchar | resource, | ||
varchar | serviceId | ||
) |
Set the owner of a resource in a given scope.
Instead of defining an ownership graph manually and adding it via VAL.DBA.add_ownership_graph() one can simply use VAL.DBA.add_resource_ownership(), VAL.DBA.set_resource_ownership(), and VAL.DBA.remove_resource_ownership() to simplify things and let VAL handle the rest.
scope | The ACL scope for which the ownership should hold. |
resource | The resource which should be defined as being owned by the given service id. |
serviceId | The owner of the given resource . |
VAL.DBA.sparql_graph_ownership_graph | ( | ) |
Graph containing the ownership relations for named graphs.
VAL manages the ownership relations for named graphs. It maintains all ownership relations in this graph. Clients should only depend on VAL.DBA.add_graph_ownership(), VAL.DBA.set_graph_ownership(), and VAL.DBA.remove_graph_ownership() to avoid problems with mapping ACLs to Virtuoso's internal graph security system.