Package com.ibm.sec.authz.jaccplus
This document is the API specification for JACCPlus.
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:
-
ApplicationPolicy
- is the primary object used to invoke the API. It has a method with the signature implies( String, EvaluationContext, Permission) that returns a boolean decision. - Context Identifier - is string value that uniquely identifies an application or service. It is a way to partition a policy space such that only policy relevant to a particular application is considered. The user enters this value when creating a Custom Application in TSPM.
-
EvaluationContext
- is the object that contains the logic for extracting context information from the running environment and passing it to the decision engine. Context information includes the currently authenticated user, the groups they are in, the application-level roles they are in (optional), and other application-specific attributes. There are two implementations: one automatically extracts the Subject data from WebSphere Application Server; the other implementation allows you to specify this information yourself. Whatever implementation is used, you should create it once on initialization and re-use it. -
EvaluationContext.getHandlerData()
- a thread-scoped map of values inside the evaluation context. It is used to pass down subject information, attributes and so on. -
ApplicationPermission
- A Permission implementation that acts as the mechanism to pass the resource identifier and action to the decision engine.
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
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 section | Context 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, MaphandlerData) { 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 ListgetEntitlement( 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; }