issrg.pba
Interface PBAAPI

All Known Implementing Classes:

ManagedPermisRBAC, PermisRBAC

public interface PBAAPI

This is a generic Privilege Based Access Control interface. It can be used for making decisions based on authorisation tokens.

The interface defines a two-staged decision mechanism. At the first stage the credentials for the user are retrieved, at the second stage a decision is made, based on the set of credentials, retrieved at the previous stage. The caller decides how many times to use the credential set for decisions, and when the credentials cannot be used anymore they must call getCreds again to retrieve the up-to-date set of credentials for the user. Note that the caller may specify an additional restriction on usage of the credentials by supplying an appropriate credentials service object. If the credentials service does not allow the use of the credentials, the decision fails, throwing a special kind of exception to signal the caller about that.

Note that Subject objects returned in the first stage for different users can be used simultaneously. Note also that they know their parent - the PBAAPI object that created them, and if the caller tried to reuse them with a different parent PBAAPI object the operation would fail.

The interface defines both push and pull modes of operation. When pushing, the sufficient set of authorisation tokens should be provided, including the delegation chain, if the delegation is supported. When pulling, the repository containing all the needed authorisation tokens should be configured in by implementation-specific means. Note that the format of the authorisation tokens is not defined and is implementation- specific.

Implementation objects would have their implementation-specific constructors for proper initialising of the object, and they should implement the finalize method for proper destruction of the object by the garbage collector.

Version:

1.0, 2.0

Author:

A Otenko

Method Summary

Response	authzDecision(Subject creds, Action action, Target target, java.util.Map contextualParams) This method generates a response regarding the the request of the user with the given set of credentials to perform the specified action on the specified target.
boolean	decision(Subject creds, Action action, Target target, java.util.Map contextualParams) This method decides if the user with the given set of credentials is allowed to perform the specified action on the specified target.
Subject	getCreds(java.security.Principal user, CredentialsService service) This method defines the pull mode for retrieving user's credentials.
Subject	getCreds(java.security.Principal user, java.lang.Object[] pushedCreds, CredentialsService service) This method defines the push mode for retrieving user's credentials.

Method Detail

getCreds

Subject getCreds(java.security.Principal user,
                 CredentialsService service)
                 throws PbaException

This method defines the pull mode for retrieving user's credentials.

Parameters:

user - is the name of the user

service - is an object that will perform some additional checks on the returned set of credentials each time the decision is made (for example, Session Time); if null, no additional service is provided for the resulting Subject object

Returns:

Subject object containing the Credential with all the necessary credentials in it

Throws:

PbaException

getCreds

Subject getCreds(java.security.Principal user,
                 java.lang.Object[] pushedCreds,
                 CredentialsService service)
                 throws PbaException

This method defines the push mode for retrieving user's credentials. Does the same as for pull mode, but the set of authorisation tokens must be provided as an array of objects.

Parameters:

user - is the name of the user

pushedCreds - is the array of authorisation tokens, containing all the credentials allocated to the user and its delegators

service - is an object that will perform some additional checks on the returned set of credentials each time the decision is made (for example, Session Time); if null, no additional service is provided for the resulting Subject object

Returns:

Subject object containing the Credential with all the necessary credentials in it

Throws:

PbaException

decision

boolean decision(Subject creds,
                 Action action,
                 Target target,
                 java.util.Map contextualParams)
                 throws PbaException

This method decides if the user with the given set of credentials is allowed to perform the specified action on the specified target.

Parameters:

creds - is a Subject object, containing the credentials and other parameters about the user (CredentialService object)

action - is the action the user is going to perform

target - is the target on which the action is being performed

contextualParams - is a collection of contextual ADI parameters

Returns:

true, if access should be granted; false, if access should be denied; note that exceptions may be thrown, specifying special conditions in decision-making

Throws:

PbaException, - if there was a problem during evaluation of the decision;

DecisionWithObligationException, - if the decision requires a set of obligations to be fulfilled with the decisions enforcement; it is suggested that either this exception is handled to retrieve the Obligations, or the response method is used to acquire authorisation response with Obligations. This method is deprecated in favor of the method authzDecision() because authzDecision() returns obligations and decision() cannot.

PbaException

See Also:

PbaException

authzDecision

Response authzDecision(Subject creds,
                       Action action,
                       Target target,
                       java.util.Map contextualParams)
                       throws PbaException

This method generates a response regarding the the request of the user with the given set of credentials to perform the specified action on the specified target.

Parameters:

creds - is a Subject object, containing the credentials and other parameters about the user (CredentialService object)

action - is the action the user is going to perform

target - is the target on which the action is being performed

contextualParams - is a collection of contextual ADI parameters

Returns:

response to the request. The response contains a decision and the associcated obligations if any.

Throws:

PbaException

See Also:

The method name is changed from response() to authzDecision()