Package com.ibm.sec.authz.jaccplus


This document is the API specification for JACCPlus.
See:
Description

Interface Summary

Interface Description
EvaluationContext This is the interface to an evaluation context from which the authorization engine can retrieve various context objects specific to each access request.
IAttributesHandler This interface implements handlers that retrieve attributes for runtime evaluation decisions.
IAuthzProvider This is an internal interface.
IContextObligationHandler This class provides the interface to registered obligation handlers in an application context.
IEvaluationContextHandler This class provides the interface to various handlers of context data.
IObligationManager This class provides the interface to the Obligations manager for obligation support.

Class Summary

Class Description
ApplicationAttributes Manages the instances of IAttributesHandler for a particular section of a request, such as Subject or Resource.
ApplicationEvaluationContext An implementation of EvaluationContext that requires the application code to create and register an ApplicationSubject instance representing the currently authenticated user.
ApplicationGroupPrincipal An implementation of a Principal that represents a group by a string identifier.
ApplicationPermission The mechanism by which a resource identifier and an action identifier are passed to the authorization engine for evaluation.
ApplicationPolicy The primary interface for invoking authorization decisions.
ApplicationSubject The container for user ID and group information for use with ApplicationEvaluationContext.
ApplicationSubjectContext An IEvaluationContextHandler implementation for the handling of the Subject and SubjectAttributes keys when container security is not used.
ApplicationUserPrincipal An implementation of a Principal that represents a user by a string identifier.
ContainerEvaluationContext An implementation of EvaluationContext for use when using the authenticated subject from a a supported container such as WebSphere Application Server.
ContainerProperties An internal class.
DelegatedPermissionCollection Primarily used for passing to ApplicationPolicy.implies( String, EvaluationContext, PermissionCollection), and typically contains ApplicationPermission objects.
GenericRoleRefPermission An implementation of Permission that can be used as a holder for a role name.
ObligationManager An implementation of the IObligationManager interface.

Package com.ibm.sec.authz.jaccplus Description

This document is the API specification for JACCPlus.

This API extends the Java Authorization Contract for Containers (JACC) API to allow an application to control the context within which the authorization decision is made. The caller provides context information (such as the currently authenticated user), the resource involved, and the action being performed; a boolean result is returned.

There are a number of important high-level concepts:

Examples

This section provides some examples of how to invoke the API.

Using a container-authenticated subject

In this scenario, we let WebSphere authenticate the user and JACCPlus automatically uses this information at runtime. The EvaluationContext implementation is ContainerEvaluationContext.

Remember to create the EvaluationContext on startup, not for each request.

//The context identifier normally the same within an application
public static String contextId = "applicationID";

//Create an EvaluationContext that gets data from the container.  The context
// should be created once and re-used.
private EvaluationContext _evalContext = new ContainerEvaluationContext();

public boolean isAllowed( String resource, String action ) {
        Permission perm = new ApplicationPermission( resource, action ) ;
        boolean retVal = ApplicationPolicy.getPolicy().implies( contextId, _evalContext, perm );
        return retVal;
}

Using an application-provided subject

If the application doesn't use WebSphere to authenticate the user, it can specify that information by using a different EvaluationContext information - ApplicationEvaluationContext.

The subject information is passed by creating an ApplicationSubject instance, calling the setUserPrincipal() and setGroupPrincipals() methods, and adding this ApplicationSubject to the HandlerData object of the EvaluationContext.

Remember to create the EvaluationContext on startup, not for each request.

//The context identifier normally the same within an application
public static String contextId = "applicationID";

//Create an EvaluationContext that gets data from the application.  The context
// should be created once and re-used.
private EvaluationContext _evalContext = new ApplicationEvaluationContext();

public boolean isAllowed( String user, String resource, String action ) {

        //Create our ApplicationSubject
        ApplicationSubject subject = new ApplicationSubject();

        //Specify the user identifier
        subject.setUserPrincipal( new ApplicationUserPrincipal( user ));

        //Set it in the HandlerData map
        _evalContext.getHandlerData().put( "java.security.auth.Subject.container", subject );

        Permission perm = new ApplicationPermission( resource, action ) ;
        boolean retVal = ApplicationPolicy.getPolicy().implies( contextId, _evalContext, perm );
        return retVal;
}

Providing additional subject attributes

An application can provide additional attributes that are included in the generated request, and therefore used by the policy to be considered when reachining a decision. In the TSPM console, these attributes are specified as being "in the request, in a standard location." Attributes are added by implementing the IAttributesHandler interface, then registering this implementation with the ApplicationAttributes object for Subject, Resource, Action or Environment.

The ApplicationAttributes object is already created for the Subject, as this is the most common use-case. To register a handler against it, use the following code.

ApplicationEvaluationContext context = new ApplicationEvaluationContext();

((ApplicationAttributes)context.getContext("com.ibm.sec.auth.subjectx.SubjectAttributes.container")).registerHandler(
    "[attributeIdentifier]", new IAttributesHandler() {

      public List getAttribute(String key, EvaluationContext evalCtx) throws PolicyContextException
      {
          ArrayList retVal = new ArrayList();
          retVal.add( "[attribute-value]" );
          return retVal;
      }

      public String[] getSupportedAttributes() {
          return new String[] { "[attributeIdentifier]" };
      }

      public boolean supports(String key) {
          return ( "[attributeIdentifier]".equals( key ));
      }
    });


Providing additional resource, action and environment attributes

You can provide attributes to the Resource, Action and Environment request sections as described in the "Providing additional subject attributes" section. However, you must manually create and register the ApplicationAttributes object with the appropriate key using EvaluationContext.registerHandler(String, com.ibm.sec.authz.jaccplus.IEvaluationContextHandler, boolean) method.

The following table shows the correct String keys to use:

Request sectionContext key
Resource"com.ibm.sec.auth.subjectx.ResourceAttributes.container"
Action"com.ibm.sec.auth.subjectx.ActionAttributes.container"
Environment"com.ibm.sec.auth.subjectx.EnvironmentAttributes.container"

These keys are also provided as constants of the ApplicationAttributes object as well.

ApplicationEvaluationContext context = new ApplicationEvaluationContext();

//The code for the AttributeContextHandler class is shown below.
IEvaluationContextHandler resourceContextHandler = new AttributeContextHandler(
    "com.ibm.sec.auth.subjectx.ResourceAttributes.container" );

//We could also use ApplicationAttributes.ATTR_RESOURCE_KEY as the first parameter here
// Passing "true" means to over-ride any existing handler for this key; if false and a handler
// already exists an exception is thrown.
context.registerHandler( "com.ibm.sec.auth.subjectx.ResourceAttributes.container", resourceContextHandler, true);

//Now register IAttributeHandler implementations against the resourceAttrs object as above.
((ApplicationAttributes)context.getContext("com.ibm.sec.auth.subjectx.ResourceAttributes.container"))
    .registerHandler( "[AttributeId]", handlerImpl );

//This is the code that returns an ApplicationAttributes object in response to the getContext() call.
private static class AttributeContextHandler implements IEvaluationContextHandler
{
        
    private final String _context;
    private final ApplicationAttributes _attrs = new ApplicationAttributes();
        
    public AttributeContextHandler( String context ) {
        this._context = context;
    }

    public Object getContext(String key, Map handlerData) {
        
        if ( _context.equals( key ))
        {
            return _attrs;
        }
        else
        {
            return null;
        }
    }

    public String[] getKeys() {
        return new String[] { _context };
    }

    public boolean supports(String key) {
        return _context.equals( key );
    }
}

Providing an XML fragment with the resource

You can provide an XML element with the resource at runtime so the policy can use XPath to extract data as part of the authorization decision. The ApplicationPermission object has the capability to hold an XML Node object, which is then automatically serialized at runtime.

//The context identifier normally the same within an application
public static String contextId = "applicationID";

//Create an EvaluationContext that gets data from the container.  The context
// should be created once and re-used.
private EvaluationContext _evalContext = new ContainerEvaluationContext();

public boolean isAllowed( String resource, String action, Node xmlContent ) {
        Permission perm = new ApplicationPermission( resource, action ) ;
        perm.setContent( xmlContent );

        boolean retVal = ApplicationPolicy.getPolicy().implies( contextId, _evalContext, perm );
        return retVal;
}

Providing a WS-Security authentication token with the subject

You can add a WS-Security token to the ApplicationSubject, which is serialized as part of the XACML Subject. TSPM can then send this token to a Security Token Service, such as that provided by Tivoli Federated Identity Manager (TFIM), for validation and/or exchange. One use case where this is valuable is when a WS-Security token is used to authenticate to the application that is encrypted or in a binary format. If the application cannot extract the user and group identifiers from this token directly, you may choose to use TFIM to extract this information.

//The context identifier normally the same within an application
public static String contextId = "applicationID";

//Create an EvaluationContext that gets data from the application.  The context
// should be created once and re-used.
private EvaluationContext _evalContext = new ApplicationEvaluationContext();

public boolean isAllowed( Element authnToken, String resource, String action ) {

        //Create our ApplicationSubject
        ApplicationSubject subject = new ApplicationSubject();

        //Add a WS-Security token
        subject.setAuthenticationToken( token );

        //Set it in the HandlerData map
        _evalContext.getHandlerData().put( "java.security.auth.Subject.container", subject );

        Permission perm = new ApplicationPermission( resource, action ) ;
        boolean retVal = ApplicationPolicy.getPolicy().implies( contextId, _evalContext, perm );
        return retVal;
}

Using getPermissions() for application entitlements

You can use the ApplicationPolicy.getPermissions(String, com.ibm.sec.authz.jaccplus.EvaluationContext, Class) method to retrieve a collection of Permissions that the currently authenticated Subject can access.

A Permission class must be passed in to this API in order to determine the type of Permissions extracted from the policy. The only supported class is ApplicationPermission.

//The context identifier normally the same within an application
public static String contextId = "applicationID";

//Create an EvaluationContext that gets data from the container.  The context
// should be created once and re-used.
private EvaluationContext _evalContext = new ContainerEvaluationContext();

public List getEntitlement( String action ) {
        //Get the list of resources that the current user can perform the specified action on
        List retVal = new ArrayList();

        //Call the getPermissions() API. Please note that only ApplicationPermission is supported at this time.
        PermissionCollection entitledPerms = ApplicationPolicy.getPolicy().getPermissions( contextId, _evalContext, ApplicationPermission.class );

        //You can loop over the returned Permissions using an Enumeration
        Enumeration e = entitledPerms.elements();
        while ( e.hasMoreElements() )
        {
                ApplicationPermission thisPerm = (ApplicationPermission)e.nextElement();
                if ( action.equals( thisPerm.getActions() ) ) {
                        retVal.add( thisPerm.getName() );
                }
        }

        return retVal;
}