Sun Java System Access Manager 7.1 Developer's Guide

About the Policy APIs

The Policy Java APIs enable you to do the following:

This chapter describes Java Policy Service packages and classes, and provides instructions for using the Policy APIs and code samples. For a comprehensive listing of Policy Java methods and their usage, see the Sun Java System Access Manager 7.1 Java API Reference.

Access Manager also provides C APIs to enable external applications to connect to the Policy Service framework. For information about using the Policy C APIs, see Chapter 3, Policy Data Types and Functions, in Sun Java System Access Manager 7.1 C API Reference Chapter 3, Policy Data Types and Functions, in Sun Java System Access Manager 7.1 C API Reference.

Policy Java Packages

The following Java packages comprise the Policy APIs:

com.sun.identity.policy

Contains policy evaluation classes for policy administration and evaluation. 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.

com.sun.identity.policy.client

Contains classes used by remote Java applications to evaluate policies and to get policy decisions.

com.sun.identity.policy.interfaces

Contains interfaces for writing custom Policy plug-ins for conditions, subjects, referrals and resources.

Policy Management Classes

Policy Management classes are used by system administrators to manage policies in Access Manager. The interfaces for this functionality are contained in the com.sun.identity.policy package and including the following:

PolicyManager

com.sun.identity.policy.PolicyManager is the top-level administrator class for policy management. com.sun.identity.policy.PolicyManager provides methods that enable an administrator to create, modify, or delete realm policies. The PolicyManager can be obtained by passing a privileged user’s session token or by passing a privileged user’s session token with a realm name. Some of the more widely used methods of this class include the following:

getPolicyNames

Retrieves all named policies created for the realm for which the policy manager 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 specified realm. If a policy with the same name already exists, it will be overwritten.

removePolicy

Removes a policy from the specified realm.

replacePolicy

Replaces policy with a new policy.

Policy

com.sun.identity.policy.Policy represents a policy definition with all its intended parts (rules, subjects, referrals, conditions, and response providers). The policy object is saved in the data store if the addPolicy or replacePolicy methods from the PolicyManager class are invoked. This class contains methods for adding, removing, replacing or getting any of the parts of a policy definition.

Policy Evaluation Classes

Policy evaluation classes compute policy decisions which allow or deny access to a protected resource. Policy evaluation classes are contained com.sun.identity.policy package and include the following:

PolicyEvaluator Class

com.sun.identity.policy.PolicyEvaluator can be integrated into Java applications to evaluate policy privileges and provide policy decisions. This class provides support for both boolean and non-boolean type policies. Create a PolicyEvaluator by calling the constructor with a service name. Public methods of this class include the following:

isAllowed

Evaluates the policy associated with the given resource and returns a boolean value indicating whether the policy evaluation resulted in an allow or deny.

getPolicyDecision

Evaluates policies and returns decisions. Returns a decision that gives a user permission to perform specified actions on a specified resource.

getResourceResult

Obtains the policy and decisions for a hierarchy of resources. Possible values for the scope of this method are self, subtree, and strict-subtree. Use the self value to get the policy decision for the specified resource only. Use the subtree value to include the policy decisions for all resources defined in the policies which are sub-resources of the specified resource.

For example, the PolicyEvaluator class can be used to display the links for a list of resources to which an authenticated user has access. The getResourceResult method is used to get the list of resources. The resourceName parameter would be http://host.domain:port which returns all the resources to which the user has access on that server. These resources are returned as a PolicyDecision based on the user’s defined policies. If the user is allowed to access resources on different servers, this method needs to be called for each server.


Note –

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


ProxyPolicyEvaluator Class

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 respective scope of administration. com.sun.identity.policy.ProxyPolicyEvaluatorFactory is the singleton class used to get ProxyPolicyEvaluator instances.


Example 3–1 Public Methods For ProxyPolicyEvaluator


    /**
     * Evaluates a simple privilege of boolean type. The privilege
     * indicates if the user identified by the principalName
     * can perform specified action on the specified resource.
     *
     * @param principalName principal name for whom to
     * compute the privilege.
     * @param resourceName name of the resource
     * for which to compute policy result.
     * @param actionName name of the action the user is trying to
     * perform on the resource
     * @param env run time environment parameters
     *
     * @return the result of the evaluation as a boolean value
     *
     * @throws PolicyException exception form policy framework
     * @throws SSOException if sso token is invalid
     *
     */
    public boolean isAllowed(String principalName, String resourceName,
        String actionName, Map env) throws PolicyException, SSOException;

    /**
     * Gets policy decision for the user identified by the
     * principalName for the given resource
     *
     * @param principalName principal name for whom to compute the
     * policy decision
     * @param resourceName name of the resource for which to
     * compute policy decision
     * @param env run time environment parameters
     *
     * @return the policy decision for the principal for the given
     * resource
     * @throws PolicyException exception form policy framework
     * @throws SSOException if sso token is invalid
     *
     */
    public PolicyDecision getPolicyDecision(String principalName,
        String resourceName, Map env)
        throws PolicyException, SSOException;

    /**
     * Gets protected resources for a user identified by the
     * principalName. Conditions defined in the policies
     * are ignored while computing protected resources.
     * Only resources that are  subresources of the  given
     * rootResource or equal to the  given rootResource would
     * be returned.
     * If all policies applicable to a resource are
     * only referral policies, no ProtectedResource would be
     * returned for such a resource.
     * @param principalName principal name for whom
     * to compute the privilege.
     * @param rootResource  only resources that are subresources
     * of the given rootResource or equal to the  given
     * rootResource would be returned. If
     * <code>PolicyEvaluator.ALL_RESOURCES</code>
     * is passed as rootResource, resources under
     * all root  resources of the service
     * type are considered while computing protected
     * resources.
     *
     * @return set of protected resources. The set contains
     * ProtectedResource objects.
     *
     * @throws PolicyException exception form policy framework
     * @throws SSOException if sso token is invalid
     * @see ProtectedResource
     *
     */
    public Set getProtectedResourcesIgnoreConditions(String principalName,
        String rootResource)  throws PolicyException, SSOException
                  

Client PolicyEvaluator Class

com.sun.identity.policy.client.PolicyEvaluator evaluates policies and provides policy decisions for remote applications. This does not require direct access to a policy stores such as Directory Server (for example, if there is a firewall). com.sun.identity.policy.client.PolicyEvaluator get policy decision from Access Manager using XML over HTTP(s). It stores a cache of policy decisions for faster responses and maintains the cache in sync with the Policy Service on the instance of Access Manager using the notification and polling mechanism.

PolicyEvent Class

com.sun.identity.policy.PolicyEvent represents a policy event that could potentially change the current access status. For example, a policy event is created and passed to the 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.

Policy Plug-In APIs

The Policy plug-in classes are contained in the com.sun.identity.policy.interfaces package. The following classes are used by service developers and policy administrators who need to provide additional policy features as well as support for legacy policies.

ResourceName

Provides methods to determine the hierarchy of the resource names for a determined service type. For example, these methods can check to see if two resources names are the same or if one is a sub-resource of the other.

Subject

Defines methods that can determine if an authenticated user (possessing an SSOToken) is a member of the given subject.

Referral

Defines methods used to delegate the policy definition or evaluation of a selected resource (and its sub-resources) to another realm or policy server.

Condition

Provides methods used to constrain a policy to , for example, time-of-day or IP address. This interface allows the pluggable implementation of the conditions.

PolicyListener

Defines an interface for registering policy events when a policy is added, removed or changed. PolicyListener is used by the Policy Service to send notifications and by listeners to review policy change events.