Documentation API Overview

Overview of the OACC API

This document aims to provide an overview and to serve as a reference to the OACC API.

AccessControlContext

An AccessControlContext is the interface with which to define and control access to OACC resources.

An instance of AccessControlContext is used to both define the OACC resources and the security privileges to them, as well as to query the security system in order to implement access control to these resources.

The API methods can be grouped into the following major functions:

The SQLAccessControlContextFactory in com.acciente.oacc.sql provides getAccessControlContext() methods to get a hold of an instance of an OACC AccessControlContext.

The rest of this document breaks down the AccessControlContext API methods, grouped by functionality, as described above. For more detailed information on each API method, please refer to OACC's Javadoc documentation.

Definitions:
"session"
An instance of the AccessControlContext interface that has been authenticated, that is, security credentials have been associated with this session
"authenticated resource"
The resource that authenticated an AccessControlContext session, that is, the resource that logged into the session with a call to one of the authenticate methods
"session resource"
The resource whose security privileges are associated with an AccessControlContext session. This is the same as the authenticated resource, unless another resource is being impersonated.

Authentication

OACC requires the AccessControlContext session to be authenticated. The authenticated resource's security privileges are the ones applicable to a session, unless the authenticated resource is impersonating another resource.

OACC delegates authentication to an AuthenticationProvider and defaults to a built-in implementation that uses encrypted password-based Credentials when no custom AuthenticationProvider implementation is provided to the SQLAccessControlContextFactory's getAccessControlContext() methods. The PasswordCredentials class provides a newInstance() factory method for password-based credentials to be used with the built-in AuthenticationProvider.

Note that unless an AccessControlContext session is authenticated, all attempts to call any methods other than authenticate(), unauthenticate(), unimpersonate() or a special case of createResource(), will fail with a NotAuthenticatedException.

FunctionalityRelated API method(s)
Authenticate as a resource using credentialsauthenticate(Resource resource, Credentials credentials)
Authenticate as a resource *authenticate(Resource resource)
Authenticate as a resource using only credentials **authenticate(Credentials credentials)
Unauthenticate, i.e. "log out" the current sessionunauthenticate()
(Re-)set the credentials of a resourcesetCredentials(Resource resource, Credentials newCredentials)
Get the currently authenticated resource
(compare with session resource below)
getAuthenticatedResource()

(*) requires a custom AuthenticationProvider that supports authenticating a resource without explicit credentials (**) requires a custom AuthenticationProvider that supports authenticating a resource that is only identified within the credentials, e.g. as part of the payload of an encrypted auth-token

Impersonation

The authenticated resource can change the security privileges associated with an AccessControlContext session to those of another resource by impersonating that resource, provided it is authorized to do so.

FunctionalityRelated API method(s)
Impersonate another resourceimpersonate(Resource resource)
Stop impersonating a resourceunimpersonate()
Get the resource whose security privileges the current session is using *getSessionResource()

(*) when not impersonating, this is the same as the authenticated resource

Creation

A session resource can create new domains and resources, provided it is authorized to do so with the appropriate create permissions. Similarly, a session resource with the appropriate DELETE permission is authorized to delete a resource or domain.

When creating a new resource with an externalId as an alternate resource identifier, that String parameter has to globally uniquely identify the resource to be created, i.e. it has to be unique across all resource classes and domains.

Note that only the system resource can create new resource classes or define new resource permissions, since these operations register your application model within OACC and don't typically occur dynamically.

Domain
FunctionalityRelated API method(s)
Create a new domaincreateDomain(String domainName)
Create a new child domain, nested within another domaincreateDomain(String domainName, String parentDomainName)
Delete a domain (and its children)deleteDomain(String domainName)
Resource
FunctionalityRelated API method(s)
Create a new resource *createResource(String resourceClassName, String domainName)
 
createResource(String resourceClassName, String domainName, String externalId)
Create a new authenticatable resourcecreateResource(String resourceClassName, String domainName, Credentials credentials)
 
createResource(String resourceClassName, String domainName, String externalId, Credentials credentials)
Set the immutable alternative resource identifier (requires CREATE permission)setExternalId(Resource resource, String externalId)
Delete a resourcedeleteResource(Resource obsoleteResource)

(*) a custom AuthenticationProvider implementation is required to support creation of an authenticatable resource without providing credentials

ResourceClass & ResourcePermission *
FunctionalityRelated API method(s)
Create a new resource class *createResourceClass(String resourceClassName, boolean authenticatable, boolean unauthenticatedCreateAllowed)
Create a new resource permission applicable to resources of a resource class *createResourcePermission(String resourceClassName, String permissionName)

(*) only the system resource can create resource classes or define new resource permissions

Authorization: Permission Management

Authorization - verifying that a resource has a certain permission - is the primary goal of OACC. Before we can verify permissions, we first need to be able to grant them to resources. This section describes the methods OACC provides to manage authorization by assigning permissions and retrieving them.

OACC provides assignment and retrieval methods for DomainCreatePermissions, DomainPermissions, ResourceCreatePermissions, ResourcePermissions and global ResourcePermissions.

Permission assignment

All OACC methods that control which permissions a resource has operate on that resource's direct permissions, that is, those permissions that have been directly assigned to the resource, and thus do not include indirect permissions, such as global permissions or ones that were inherited from another resource or domain.

OACC provides set- methods for each permission type, in order to specify to which permissions a resource is privileged. A successful invocation of a set- method for a permission type always assigns all direct permissions at once, thus overriding any existing direct permissions.

For more fine-grained control of permission assignment, OACC also provides grant and revoke methods for each permission type, which allow to add or remove one (or more) permissions from the set of existing direct permissions, respectively. Grant -methods can never remove an already existing permission; they can only add new permissions or expand the granting rights of existing ones. Conversly, revoke- methods can only be used to remove existing permissions (regardless of granting rights).

In order to downgrade an existing permission's granting rights, one either has to first revoke and then grant the permission with the desired granting rights, or specify the entire set of applicable direct permissions using a single invocation of a set -method.

Permission retrieval

There are essentially two kinds of get- methods for each permission type:

"direct"
A direct get-method is symmetric to the set-method, that is, it only returns those permissions that have been directly assigned by the respective set-method, and doesn't include indirect permissions such as global permissions or ones that were inherited from another resource or domain
"effective"
An effective get-method returns any applicable permissions of the specified type that are in effect for the queried resource, that is, not just direct permissions, but also any global permissions, permissions inherited from other resources or domains, or implicit permissions in effect via SUPER-USER privileges.

In order to retrieve permissions for a resource other than the session resource, one must have query authorization on that resource. Explicit query authorization is granted with the QUERY system permission, whereas implicit query authorization is acquired by having IMPERSONATE permission, or SUPER-USER privileges. In other words, the session resource must either be the specified accessor resource, have SUPER-USER permission to its (parent-)domain, or must have QUERY or IMPERSONATE permissions to the specified accessor resource.

DomainCreatePermissions
FunctionalityRelated API method(s)
Specify the DomainPermissions a resource would receive directly, if it were to create a new domainsetDomainCreatePermissions(Resource accessorResource, Set<DomainCreatePermission> domainCreatePermissions)
 
grantDomainCreatePermissions(Resource accessorResource, Set<DomainCreatePermission> domainCreatePermissions)
 
revokeDomainCreatePermissions(Resource accessorResource, Set<DomainCreatePermission> domainCreatePermissions)
Retrieve the DomainPermissions a resource would have directly, if it were to create a new domaingetDomainCreatePermissions(Resource accessorResource)
Retrieve all the DomainPermissions a resource would have, if it were to create a new domaingetEffectiveDomainCreatePermissions(Resource accessorResource)
overloaded convenience methods
Specify the DomainPermissions a resource would receive directly, if it were to create a new domaingrantDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)
 
revokeDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)

DomainPermissions
FunctionalityRelated API method(s)
Specify the DomainPermissions a resource has directly to a domainsetDomainPermissions(Resource accessorResource, String domainName, Set<DomainPermission> domainPermissions)
 
grantDomainPermissions(Resource accessorResource, String domainName, Set<DomainPermission> domainPermissions)
 
revokeDomainPermissions(Resource accessorResource, String domainName, Set<DomainPermission> domainPermissions)
Retrieve the direct DomainPermissions a resource has to a domaingetDomainPermissions(Resource accessorResource, String domainName)
Retrieve the direct DomainPermissions a resource has to any domain, mapped by domain namegetDomainPermissionsMap(Resource accessorResource)
Retrieve all DomainPermissions a resource effectively has to a domaingetEffectiveDomainPermissions(Resource accessorResource, String domainName)
Retrieve all DomainPermissions a resource effectively has to any domain, mapped by domain namegetEffectiveDomainPermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the DomainPermissions a resource has directly to a domaingrantDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)
 
revokeDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)

ResourceCreatePermissions
FunctionalityRelated API method(s)
Specify the ResourcePermissions a resource would receive directly, if it were to create a new resourcesetResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourceCreatePermission> resourceCreatePermissions)
 
grantResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourceCreatePermission> resourceCreatePermissions)
 
revokeResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourceCreatePermission> resourceCreatePermissions)
Retrieve the ResourcePermissions a resource would have directly, if it were to create a new resourcegetResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve all the ResourcePermissions a resource would have, if it were to create a new resourcegetEffectiveResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve the ResourcePermissions a resource would have directly, if it were to create any new resource, mapped by domain and resource classgetResourceCreatePermissionsMap(Resource accessorResource)
Retrieve the ResourcePermissions a resource effectively would have, if it were to create any new resource, mapped by domain and resource classgetEffectiveResourceCreatePermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the ResourcePermissions a resource would receive directly, if it were to create a new resourcegrantResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)
 
revokeResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)

ResourcePermissions
FunctionalityRelated API method(s)
Specify the ResourcePermissions a resource has directly to another resourcesetResourcePermissions(Resource accessorResource, Resource accessedResource, Set<ResourcePermission> resourcePermissions)
 
grantResourcePermissions(Resource accessorResource, Resource accessedResource, Set<ResourcePermission> resourcePermissions)
 
revokeResourcePermissions(Resource accessorResource, Resource accessedResource, Set<ResourcePermission> resourcePermissions)
Retrieve the direct ResourcePermissions a resource has to another resourcegetResourcePermissions(Resource accessorResource, Resource accessedResource)
Retrieve all ResourcePermissions a resource effectively has to another resourcegetEffectiveResourcePermissions(Resource accessorResource, Resource accessedResource)
overloaded convenience methods
Specify the ResourcePermissions a resource has directly to another resourcegrantResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
 
revokeResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Global ResourcePermissions
FunctionalityRelated API method(s)
Specify the ResourcePermissions a resource has directly on all resources of a specified resource class in a domainsetGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
 
grantGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
 
revokeGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
Retrieve the direct ResourcePermissions a resource has on all resources of a specified resource class in a domaingetGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve all ResourcePermissions a resource effectively has on all resources of a specified resource class in a domaingetEffectiveGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve the direct ResourcePermissions a resource has on all resources of a specified resource class, mapped by domain name and resource class namegetGlobalResourcePermissionsMap(Resource accessorResource)
Retrieve all ResourcePermissions a resource effectively has on all resources of a specified resource class, mapped by domain name and resource class namegetEffectiveGlobalResourcePermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the ResourcePermissions a resource has directly on all resources of a specified resource class in a domaingrantGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
 
revokeGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Authorization: Permission Verification

To verify if a resource has authorization to do something, OACC provides two types of methods that take a permission: has-permission-methods and assert-methods. If the resource isn't authorized, i.e. the resource does not have the specified permission, a has-permission method returns false, whereas an assert-method fails and throws a NotAuthorizedException.

All has-permission and assert methods take a (non-empty) set of permissions, or accept one or more permission arguments (as the last vararg parameter), and verify that the resource has authorization for all the specified permissions.

The has-permission methods are a convenience that spare the client from first calling get-methods that return effective permissions, and then checking if the results contain the required permission. In other words, the has-permission methods take into account any direct, inherited or global permissions, as well as any super-user privileges. The assert methods simply wrap the has-permission methods and throw an unchecked exception when authorization fails.

Similarly to retrieving permissions, in order to verify permissions for a resource other than the session resource, one must have query authorization on that resource. Explicit query authorization is granted with the QUERY system permission, whereas implicit query authorization is acquired by having IMPERSONATE permission, or SUPER-USER privileges. In other words, the session resource must either be the specified accessor resource, have SUPER-USER permission to its (parent-)domain, or must have QUERY or IMPERSONATE permissions to the specified accessor resource.

OACC provides has-permission and assert methods for DomainCreatePermissions, post-create CreatePermissions, DomainPermissions, ResourcePermissions, global ResourcePermissions, ResourceCreatePermissions and post-create ResourcePermissions.

DomainCreatePermission
FunctionalityRelated API method(s)
Checks if a resource has the specified domain create permissionshasDomainCreatePermissions(Resource accessorResource, Set<DomainCreatePermission> domainCreatePermissions)
 
assertDomainCreatePermissions(Resource accessorResource, Set<DomainCreatePermission> domainCreatePermissions)
overloaded convenience methods
Checks if a resource has the specified domain create permissionshasDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)
 
assertDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)

Post-create DomainPermission
FunctionalityRelated API method(s)
Checks if a resource would receive permissions on a domain, if it were to create that domainhasPostCreateDomainPermissions(Resource accessorResource, Set<DomainPermission> domainPermissions)
 
assertPostCreateDomainPermissions(Resource accessorResource, Set<DomainPermission> domainPermissions)
overloaded convenience methods
Checks if a resource would receive permissions on a domain, if it were to create that domainhasPostCreateDomainPermissions(Resource accessorResource, DomainPermission domainPermission, DomainPermission... domainPermissions)
 
assertPostCreateDomainPermissions(Resource accessorResource, DomainPermission domainPermission, DomainPermission... domainPermissions)

DomainPermission
FunctionalityRelated API method(s)
Check if a resource has permission(s) on a domainhasDomainPermissions(Resource accessorResource, String domainName, Set<DomainPermission> domainPermissions)
 
assertDomainPermissions(Resource accessorResource, String domainName, Set<DomainPermission> domainPermissions)
overloaded convenience methods
Check if a resource has permission(s) on a domainhasDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)
 
assertDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)

ResourcePermission
FunctionalityRelated API method(s)
Check if a resource has permission(s) on another resourcehasResourcePermissions(Resource accessorResource, Resource accessedResource, Set<ResourcePermission> resourcePermissions)
 
assertResourcePermissions(Resource accessorResource, Resource accessedResource, Set<ResourcePermission> resourcePermissions)
overloaded convenience methods
Check if a resource has permission(s) on another resourcehasResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
 
assertResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Global ResourcePermission
FunctionalityRelated API method(s)
Check if a resource has permission(s) on all resources of a specified resource class in a domainhasGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
 
assertGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
overloaded convenience methods
Check if a resource has permission(s) on all resources of a specified resource class in a domainhasGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
 
assertGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

ResourceCreatePermission
FunctionalityRelated API method(s)
Checks if a resource has the specified resource create permissions for a specified resource class in a domainhasResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourceCreatePermission> resourceCreatePermissions)
 
assertResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourceCreatePermission> resourceCreatePermissions)
overloaded convenience methods
Checks if a resource has the specified resource create permissions for a specified resource class in a domainhasResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)
 
assertResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)

Post-Create ResourcePermission
FunctionalityRelated API method(s)
Check if a resource would have permission(s) on a resource if it were to create that resource in a domainhasPostCreateResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, String<ResourcePermission> resourcePermissions)
 
assertPostCreateResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
overloaded convenience methods
Check if a resource would have permission(s) on a resource if it were to create that resource in a domainhasPostCreateResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
 
assertPostCreateResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Retrieve Resources by Permission

OACC provides the following methods to find

  • all resources that a resource could access
  • or all resources that could access a resource

by having all of the specified permissions. These methods take into account direct, inherited, global and SUPER-USER permissions.

Similarly to retrieving or verifying permissions, in order to retrieve resources by permissions for a resource other than the session resource, one must have query authorization on that resource. Explicit query authorization is granted with the QUERY system permission, whereas implicit query authorization is acquired by having IMPERSONATE permission, or SUPER-USER privileges. In other words, the session resource must either be the specified resource, have SUPER-USER permission to its (parent-)domain, or must have QUERY or IMPERSONATE permissions to the specified resource.

FunctionalityRelated API method(s)
Retrieve the resources to which the accessor has certain permission(s), from any domaingetResourcesByResourcePermissions(Resource accessorResource, String resourceClassName, Set<ResourcePermission> resourcePermissions)
Retrieve the resources - within a domain - to which the accessor has certain permission(s)getResourcesByResourcePermissionsAndDomain(Resource accessorResource, String resourceClassName, String domainName, Set<ResourcePermission> resourcePermissions)
Retrieve all resources that have certain permission(s) to the accessed resourcegetAccessorResourcesByResourcePermissions(Resource accessedResource, String resourceClassName, Set<ResourcePermission> resourcePermissions)
overloaded convenience methods
Retrieve the resources to which the accessor has certain permission(s), from any domaingetResourcesByResourcePermissions(Resource accessorResource, String resourceClassName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
Retrieve the resources - within a domain - to which the accessor has certain permission(s)getResourcesByResourcePermissionsAndDomain(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)
Retrieve all resources that have certain permission(s) to the accessed resourcegetAccessorResourcesByResourcePermissions(Resource accessedResource, String resourceClassName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Meta Information

The following methods provide useful meta information about specific resources, or about the resource classes and domains that define the application model registered in your OACC deployment. No query authorization (neither explicit or implicit) is required to retrieve meta information for any resource, not even for resources other than the session resource.

FunctionalityRelated API method(s)
Look up the domain names to which the resource belongsgetDomainNameByResource(Resource resource)
Look up the names of nested domains within a specified domaingetDomainDescendants(String domainName)
Retrieve a ResourceClassInfo object describing the resource class *getResourceClassInfo(String resourceClassName)
Retrieve a ResourceClassInfo object describing the resource class of a specified resource *getResourceClassInfoByResource(Resource resource)
Look up names for all resource classesgetResourceClassNames()
Look up names for all resource permissions defined for a specified resource class (including custom permission and built-in system permissions)getResourcePermissionNames(String resourceClassName)

(*) ResourceClassInfo describes if resources of this resource class are authenticatable and/or if resources can be created from an unauthenticated session