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:

• authentication
• impersonation
• creation
  • domain creation
  • resource creation
  • resource class creation
  • resource permission creation
• authorization
  • permission management
  • permission verification
• finding resources by permission
  • accessed resources
  • accessor resources
• meta information

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.

Functionality	Related API method(s)
Authenticate as a resource using credentials	authenticate(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 session	unauthenticate()
(Re-)set the credentials of a resource	setCredentials(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.

Functionality	Related API method(s)
Impersonate another resource	impersonate(Resource resource)
Stop impersonating a resource	unimpersonate()
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

Functionality	Related API method(s)
Create a new domain	createDomain(String domainName)
Create a new child domain, nested within another domain	createDomain(String domainName, String parentDomainName)
Delete a domain (and its children)	deleteDomain(String domainName)

Resource

Functionality	Related API method(s)
Create a new resource *	createResource(String resourceClassName, String domainName)   createResource(String resourceClassName, String domainName, String externalId)
Create a new authenticatable resource	createResource(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 resource	deleteResource(Resource obsoleteResource)

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

ResourceClass & ResourcePermission *

Functionality	Related 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

Functionality	Related API method(s)
Specify the DomainPermissions a resource would receive directly, if it were to create a new domain	setDomainCreatePermissions(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 domain	getDomainCreatePermissions(Resource accessorResource)
Retrieve all the DomainPermissions a resource would have, if it were to create a new domain	getEffectiveDomainCreatePermissions(Resource accessorResource)
overloaded convenience methods
Specify the DomainPermissions a resource would receive directly, if it were to create a new domain	grantDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)   revokeDomainCreatePermissions(Resource accessorResource, DomainCreatePermission domainCreatePermission, DomainCreatePermission... domainCreatePermissions)

DomainPermissions

Functionality	Related API method(s)
Specify the DomainPermissions a resource has directly to a domain	setDomainPermissions(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 domain	getDomainPermissions(Resource accessorResource, String domainName)
Retrieve the direct DomainPermissions a resource has to any domain, mapped by domain name	getDomainPermissionsMap(Resource accessorResource)
Retrieve all DomainPermissions a resource effectively has to a domain	getEffectiveDomainPermissions(Resource accessorResource, String domainName)
Retrieve all DomainPermissions a resource effectively has to any domain, mapped by domain name	getEffectiveDomainPermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the DomainPermissions a resource has directly to a domain	grantDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)   revokeDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)

ResourceCreatePermissions

Functionality	Related API method(s)
Specify the ResourcePermissions a resource would receive directly, if it were to create a new resource	setResourceCreatePermissions(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 resource	getResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve all the ResourcePermissions a resource would have, if it were to create a new resource	getEffectiveResourceCreatePermissions(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 class	getResourceCreatePermissionsMap(Resource accessorResource)
Retrieve the ResourcePermissions a resource effectively would have, if it were to create any new resource, mapped by domain and resource class	getEffectiveResourceCreatePermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the ResourcePermissions a resource would receive directly, if it were to create a new resource	grantResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)   revokeResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)

ResourcePermissions

Functionality	Related API method(s)
Specify the ResourcePermissions a resource has directly to another resource	setResourcePermissions(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 resource	getResourcePermissions(Resource accessorResource, Resource accessedResource)
Retrieve all ResourcePermissions a resource effectively has to another resource	getEffectiveResourcePermissions(Resource accessorResource, Resource accessedResource)
overloaded convenience methods
Specify the ResourcePermissions a resource has directly to another resource	grantResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)   revokeResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Global ResourcePermissions

Functionality	Related API method(s)
Specify the ResourcePermissions a resource has directly on all resources of a specified resource class in a domain	setGlobalResourcePermissions(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 domain	getGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName)
Retrieve all ResourcePermissions a resource effectively has on all resources of a specified resource class in a domain	getEffectiveGlobalResourcePermissions(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 name	getGlobalResourcePermissionsMap(Resource accessorResource)
Retrieve all ResourcePermissions a resource effectively has on all resources of a specified resource class, mapped by domain name and resource class name	getEffectiveGlobalResourcePermissionsMap(Resource accessorResource)
overloaded convenience methods
Specify the ResourcePermissions a resource has directly on all resources of a specified resource class in a domain	grantGlobalResourcePermissions(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

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

Post-create DomainPermission

Functionality	Related API method(s)
Checks if a resource would receive permissions on a domain, if it were to create that domain	hasPostCreateDomainPermissions(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 domain	hasPostCreateDomainPermissions(Resource accessorResource, DomainPermission domainPermission, DomainPermission... domainPermissions)   assertPostCreateDomainPermissions(Resource accessorResource, DomainPermission domainPermission, DomainPermission... domainPermissions)

DomainPermission

Functionality	Related API method(s)
Check if a resource has permission(s) on a domain	hasDomainPermissions(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 domain	hasDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)   assertDomainPermissions(Resource accessorResource, String domainName, DomainPermission domainPermission, DomainPermission... domainPermissions)

ResourcePermission

Functionality	Related API method(s)
Check if a resource has permission(s) on another resource	hasResourcePermissions(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 resource	hasResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)   assertResourcePermissions(Resource accessorResource, Resource accessedResource, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

Global ResourcePermission

Functionality	Related API method(s)
Check if a resource has permission(s) on all resources of a specified resource class in a domain	hasGlobalResourcePermissions(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 domain	hasGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)   assertGlobalResourcePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourcePermission resourcePermission, ResourcePermission... resourcePermissions)

ResourceCreatePermission

Functionality	Related API method(s)
Checks if a resource has the specified resource create permissions for a specified resource class in a domain	hasResourceCreatePermissions(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 domain	hasResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)   assertResourceCreatePermissions(Resource accessorResource, String resourceClassName, String domainName, ResourceCreatePermission resourceCreatePermission, ResourceCreatePermission... resourceCreatePermissions)

Post-Create ResourcePermission

Functionality	Related API method(s)
Check if a resource would have permission(s) on a resource if it were to create that resource in a domain	hasPostCreateResourcePermissions(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 domain	hasPostCreateResourcePermissions(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.

Functionality	Related API method(s)
Retrieve the resources to which the accessor has certain permission(s), from any domain	getResourcesByResourcePermissions(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 resource	getAccessorResourcesByResourcePermissions(Resource accessedResource, String resourceClassName, Set<ResourcePermission> resourcePermissions)
overloaded convenience methods
Retrieve the resources to which the accessor has certain permission(s), from any domain	getResourcesByResourcePermissions(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 resource	getAccessorResourcesByResourcePermissions(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.

Functionality	Related API method(s)
Look up the domain names to which the resource belongs	getDomainNameByResource(Resource resource)
Look up the names of nested domains within a specified domain	getDomainDescendants(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 classes	getResourceClassNames()
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