com.sun.identity.policy

The com.sun.identity.policy package contains the following classes for policy management and policy evaluation:

• Policy Management Classes

• Policy Evaluation Classes

Policy Management Classes

Policy management classes are used by privileged system administrators to programmatically add, look up, modify, replace and delete policies, and update the policy data store, if appropriate. Attempts by non-privileged users to manage policies will result in an exception and be logged. A valid session token is required to invoke any method provided by these classes. The key policy management classes are:

• PolicyManager

• Policy

PolicyManager

com.sun.identity.policy.PolicyManager is the top-level administrator class for policy management in a specific realm. This class provides methods that enable the administrator to add, look up, modify, replace and delete policies. Only a privileged user with access to the policy data store and a valid session token can create a PolicyManager object. Some of the more widely used methods include:

getPolicyNames()

Retrieves all named policies created in the realm for which the PolicyManager object was instantiated. This method can also take a pattern (filter) as an argument.

getPolicy()

Retrieves a policy when given the policy name.

addPolicy()

Adds a policy to the realm for which the PolicyManager object was instantiated. If a policy with the same name already exists, it will be overwritten.

removePolicy()

Removes a policy from the realm for which the PolicyManager object was instantiated.

replacePolicy()

Overwrites a policy already defined in the realm for which the PolicyManager object was instantiated.

Policy

com.sun.identity.policy.Policy represents a policy definition with all its intended parts, including Rule(s), Subject(s), Condition(s), Referral(s) and Response Provider(s). The Policy object can be saved in the policy data store if the addPolicy() or replacePolicy() methods from the PolicyManager class are invoked. This class contains methods for adding, removing, replacing or retrieving any of the parts of a policy definition.

Policy Evaluation Classes

Policy Decision APIs are used to evaluate policy decision when a principal attempts an action on a resource. This section covers some key classes that provide Policy Evaluation APIs. Some classes are also provided to be used only by privileged users to test policy decisions applicable to other users.

Policy evaluation classes are used to evaluate the applicable policy when a principal attempts an action on a resource and send a determination on whether the principal will be allowed or denied access. The key policy evaluation classes are:

• PolicyEvaluator

• ProxyPolicyEvaluator

• PolicyEvent

Policy evaluation classes from this package require a direct connection to the policy data store. These classes should be used with caution, and only when classes from com.sun.identity.policy.client cannot handle your use case. See com.sun.identity.policy.client.

PolicyEvaluator

com.sun.identity.policy.PolicyEvaluator evaluates policy privileges and provides policy decisions. It provides methods to evaluate access to one resource or a hierarchy of resources, and supports both boolean and non-boolean type policies. A valid session token of the principal attempting access is required to invoke any method of this class. A PolicyEvaluator class is created by calling the constructor with a service name. Key public methods of this class include:

isAllowed()

Evaluates a policy associated with the given resource and returns a boolean-type value indicating an allow or deny decision.

getPolicyDecision()

Evaluates policies and returns a decision as to whether the associated principal can perform the specified actions on the specified resource.

getResourceResults()

A ResourceResult contains policy decisions regarding a particular protected resource and its sub resources. getResourceResults() obtains these policy decisions. Possible values for the scope of objects retrieved are ResourceResult.SELF_SCOPE (returns an object that contains the policy decision for the specified resource only), ResourceResult.SUBTREE_SCOPE (includes policy decisions for the specified resource and its sub-resources), and ResourceResult.STRICT_SUBTREE_SCOPE (returns an object that contains one policy decision regarding the resourceName only). For example, the PolicyEvaluator class can be used to display links for a list of resources to which an authenticated user has access. The getResourceResults() method can be used to retrieve a list of resources to which the user has access from a defined resourceName parameter — a URL in the form http://host.domain:port. The resources are returned as a PolicyDecision object based on the user’s policies. If the user is allowed to access resources on different servers, this method needs to be called for each server.

Not all resources that have policy decisions are accessible to the user. Access depends on the ActionDecision() value contained in policy decisions.

ProxyPolicyEvaluator

com.sun.identity.policy.ProxyPolicyEvaluator allows a privileged user (top-level administrator, organization administrator, policy administrator, or organization policy administrator) to get policy privileges and evaluate policy decisions for any user in their scope of administration. com.sun.identity.policy.ProxyPolicyEvaluatorFactory is the singleton class used to get ProxyPolicyEvaluator instances. This is supported only within the OpenSSO Enterprise server process.

PolicyEvent

com.sun.identity.policy.PolicyEvent represents a policy event that could potentially change the current access status. A policy event is created and passed to registered policy listeners whenever there is a change in a policy rule. This class works with the PolicyListener class in the com.sun.identity.policy.interface package.