Documentation Quick Overview

Quick Overview

Let's start by introducing the OACC architecture, which sets it apart from most application security frameworks for Java™

Architecture

Let's start with a simple example. Consider the following security relationship:

   (JohnDoe) has (READ,WRITE) permissions on (Sales2014.xls)

OACC provides an API to manage security relationships like the above. Most current security frameworks for Java™, however, do not, because their security model lacks an abstraction for the application resources being secured. This forces the application developer to implement a means to store and manage the security relationships. The abstraction for an application resource is core to OACC's security model.

In OACC the concept of a resource represents an application resource. This abstraction enables OACC to store and manage all security relationships. Since OACC manages the security relationships, it is able to provide API calls to grant and revoke permissions within a powerful security model. With OACC, an application no longer needs to manage security relationships.

The security relationships are stored in OACC's security data repository, backed by a set of relational database tables. As a result you will not see the concept of realms in OACC that exists in other security frameworks.

Session Management

An application interacts with OACC via an OACC session. An OACC session is an instance of an OACC AccessControlContext interface. The AccessControlContext instance is connected to an OACC security data reposistory. Typically an application would have an application session that is bound to the currently logged in user. An application is free to use any session manager to store the OACC session. A web application, for example, would typically use the HttpSession provided by the servlet container.

The AccessControlContext interface contains all the methods that an application uses to create resources, and to define and query security relationships. Next we use an AccessControlContext instance to work with resources.

Working with Resources

As we discussed earlier, a resource in OACC represents an entity in your application that you need to secure. The key idea behind OACC is that security relationships between entities in your application result from defining the relationships between the respective resources in OACC. Let's use a simple example to make this concrete.

For example, let's say you have a simple application with two types of entities: Users and Documents. Here is how you would link your application entities with OACC resources. Whenever you create a new User in your application you would subsequently register it within OACC by providing a globally unique external id String, as shown below:

    // persist your user object here, before creating a corresponding OACC resource
    User newUser = ...;

    // let OACC handle the association to your application object with a unique 3rd parameter `externalId`
    Resource userResource = accessControlContext.createResource("USER", "APP_DOMAIN", newUser.getId());

Alternatively, you could ask OACC for a new resource identifier first, and then store that identifier (a long integer) as an attribute of your new User entity. The OACC API call to create a resource for the user would then look like this:

    Resource userResource = accessControlContext.createResource("USER", "APP_DOMAIN");

    // persist userResource.getId() in your user object

Similarly, when you create a new Document in your application, you would again register it as a resource in OACC by providing a unique id of your Document object, as shown in the listing below. Alternatively, you could ask the OACC API for a resource reference for the document and persist it within your application model.

    // persist your document object here, before creating the corresponding OACC resource
    Document newDoc = ...;

    Resource documentResource = accessControlContext.createResource("DOCUMENT", "APP_DOMAIN", newDoc.getId());

The "USER" and "DOCUMENT" arguments in the calls above are resource class names, which an application registered with OACC. An application also registers with OACC the permission strings that are asscoiated with each resource class.

Your application is now ready to leverage OACC!

Let's say you wanted to specify that User:John_Doe has READ access to Document:2014_Sep_Sales.xls, you would do this by simply telling OACC to grant User:John_Doe the READ permission to Document:2014_Sep_Sales.xls, you would identify User:John_Doe and Document:2014_Sep_Sales.xls using the respective OACC resource identifiers that you associated with each of your objects. The OACC API call to do this is:

    accessControlContext.setResourcePermission(accessorResource, accessedResource, permissions);

Working with Resource Classes

An application must register with OACC the resource class names before they can be used. Registering resource classes could be done as part of an install/upgrade event for your application. The OACC API call to create a resource class look like this:

    accessControlContext.createResourceClass("USER", true, true);
    accessControlContext.createResourceClass("DOCUMENT", false, false);

Working with Permissions

For each resource class name, your application is allowed to define the permission names that apply to resources of that resource class. For example for the "DOCUMENT" resource class name the permission names allowed could look something like "VIEW", "EDIT" and "DELETE". For the "USER" resource class name the permission names allowed could look something like "VIEW", "EDIT" and "DEACTIVATE".

A key point to remember is that OACC does not attach any meaning to the permission we define (e.g. "VIEW", "EDIT"). OACC makes it easy for your application to check if a user has a permission and allow or disallow an action.

There are built-in permissions in OACC that do have meaning in OACC that cannot be changed, let's look at those next.

Built-in permissions

OACC defines built-in permissions that are automatically available to all resource classes. The built-in permissions for resources and their corresponding meanings are shown below:

*INHERIT
If resource A has this permission on resource B, resource A inherits all the permissions that resource B has.
*IMPERSONATE
If resource A has this permission on resource B, resource A is allowed to authenticate and act as resource B.
*RESET-CREDENTIALS
If resource A has this permission on resource B, resource A is allowed change the authentication credentials associated with resource B.
*DELETE
If resource A has this permission on resource B, resource A is allowed to delete resource B.
*QUERY
If resource A has this permission on resource B, resource A is allowed to retrieve or verify permissions on resource B, as well as retrieve resources by permission.

Working with Domains

Every resource in OACC lives inside a domain. Domains serve to scope/isolate groups of resources, since most security operations in OACC work within the context of a specified domain.