Sun OpenSSO Enterprise 8.0 Developer's Guide

About the Policy Service Interfaces

The Policy Service provides the functionality to control access to web services and applications by providing authorization decisions based on defined and applicable policies or rules that define who or what is authorized to access a resource. In a single sign-on (SSO) environment, the Policy Service acts as authorization authority, providing authorization decisions that are enforced by a policy agent. The Policy Service acts as a Policy Administration Point (PAP) and a Policy Decision Point (PDP). As a PAP, it allows privileged users to create, modify, and delete access control policies. As a PDP, it provides access control decisions (after evaluating applicable policies) to a Policy Enforcement Point (PEP) which, in a OpenSSO Enterprise environment, is a policy agent.

Note –

For information on how the Policy Service works within a user session, see Chapter 6, Models of the User Session and Single Sign-On Processes, in Sun OpenSSO Enterprise 8.0 Technical Overview. Additional information is in Chapter 8, Authorization and the Policy Service, in Sun OpenSSO Enterprise 8.0 Technical Overview. More information on policy agents can be found in Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

The Policy Service provides an application programming interface (API) to manage policies and provide authorization decisions. It also provides a service provider interface (SPI) to extend the Policy Service functionality. These interfaces include the following packages:

`com.sun.identity.policy`

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

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`

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:

Caution –

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.

`com.sun.identity.policy.client`

The com.sun.identity.policy.client package contains classes that can be used by remote Java applications to evaluate policies and communicate with the Policy Service to get policy decisions. This package does not communicate with the policy data store therefore, use it when, for example, there is an intervening firewall. The package also maintains a local cache of policy decisions kept current either by a configurable time to live and/or notifications from the Policy Service.

`com.sun.identity.policy.interfaces`

The com.sun.identity.policy.interfaces package contains SPI for writing custom plug-ins to extend the Policy Service. The classes are used by service developers and policy administrators who need to provide additional policy features as well as support for legacy policies.

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.
Referral: Provides methods used to delegate the policy definition or evaluation of a selected resource (and its sub-resources) to another realm or policy server.
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.
ResponseProvider: Defines an interface to allow pluggable response providers into the OpenSSO Enterprise framework. Response providers are used to provide policy response attributes which typically provide attribute values from the user profile.
Subject: Provides methods to determine if an authenticated user is a member of the given subject.

Policy Service Provider Interfaces and Plug-Ins

OpenSSO Enterprise includes SPIs that work with the Policy Service framework to create and manage policies. You can develop customized plug-ins for creating custom policy subjects, referrals, conditions, and response providers. For information on creating custom policy plug-ins, see Sample Code for Custom Subjects, Conditions, Referrals, and Response Providers. The following table summarizes the Policy Service SPI, and lists the specialized Policy Service plug-ins that come bundled with OpenSSO Enterprise.

Table 2–1 Policy Service Service Provider Interfaces


Interface	Description
Subject	Defines a set of authenticated users for whom the policy applies. The following Subject plug-ins come bundled with OpenSSO Enterprise: Access Manager Identity Subject, Access Manager Roles, Authenticated Users, LDAP Groups, LDAP Roles, LDAP Users, Organization Web, and Services Clients.
Referral	Delegates management of policy definitions to another access control realm.
Condition	Specifies applicability of policy based on conditions such as IP address, time of day, authentication level. The following Condition plug-ins come bundled with OpenSSO Enterprise: Authentication Level, Authentication Scheme, IP Address, LE Authentication Level, Session, SessionProperty, and Time.
Resource Name	Allows a pluggable resource.
Response Provider	Gets attributes that are sent along with policy decision to the policy agent, and used by the policy agent to customize the client applications. Custom implementations of this interface are now supported in OpenSSO Enterprise.

`com.sun.identity.policy.jaas`

The com.sun.identity.policy.jaas package provides classes for performing policy evaluation against OpenSSO Enterprise using the Java Authentication and Authorization Service (JAAS) framework. JAAS is a set of APIs that enable services to authenticate and enforce access controls upon users. This package provides support for authorization only, making it possible to use JAAS interfaces to access the Policy Service. It contains the following implementations of JAAS classes:

For more information see Enabling Authorization Using the Java Authentication and Authorization Service (JAAS).

`ISPermission`

com.sun.identity.policy.jaas.ISPermission extends java.security.Permission, an abstract class for representing access to a resource. It represents the control of a sensitive operation, such as opening of a socket or accessing a file for a read or write operation. It does not grant permission for that operation, leaving that responsibility to the JAAS AccessController class which evaluates OpenSSO Enterprise policy against the Policy Service.

ISPermission covers the case when additional policy services are defined and imported provided they only have boolean action values as a JAAS permission only has a boolean result.

`ISPolicy`

com.sun.identity.policy.jaas.ISPolicy is an implementation of the JAAS abstract class java.security.Policy which represents the system policy for a Java application environment. It performs policy evaluation against the Policy Service instead of against the default file-based PolicyFile.