Sun OpenSSO Enterprise 8.0 Technical Overview

Chapter 8 Authorization and the Policy Service

The Sun OpenSSO Enterprise Policy Service determines if a user has been given permission by a recognized authority to access a protected resource. The process is referred to as authorization. This chapter describes how the various parts of the Policy Service work together to perform authorization. Topics covered include:

Authorization and Policy Service Overview

A policy is a rule that defines who is authorized to access a resource. A single policy can define authorization with either binary or non-binary decisions. (A binary decision is yes/no, true/false or allow/deny. A non-binary decision represents the value of an attribute; for example, a mail service might include a mailboxQuota attribute with a maximum storage value set for each user.) In general, the Policy Service allows administrators to configure, modify, and delete policies. The configured policies are then added to a realm and applied against the subjects in the realm. The Policy Service can be accessed using the Policy Service API: a privileged user can define access control policies using the administration API while a protected application or policy agent can obtain policy decisions using the evaluation API. The Policy Service relies on:

A Policy Administration Point (PAP) implements the functionality to define policies. The Policy Service is the PAP.
A Policy Enforcement Point (PEP) to protect an enterprise's resources by enforcing access control. The PEP uses the policy component of the Client SDK to retrieve policy decisions. The policy agent is the PEP.
A Policy Decision Point (PDP) to evaluate policy and make an access determination. The Policy Service is the PDP.
A data store in which configured policies are stored and from which they are retrieved. The Configuration Data Store is the data store.

Access to a resource is always preceded by a basic user session in which the requestor is authenticated, a session is created by the Authentication Service, and the session token identifier is validated. (See Chapter 6, Models of the User Session and Single Sign-On Processes.) The policy agent protecting the resource then provides the session token identifier, resource name, desired action, and additional context parameters to the Policy Service which uses configured policies to determine if the user has been given permission to access the protected resource by a recognized authority. When the policy agent gets the decision from the Policy Service, it allows or denies access to the user, enforcing the policy decision provided by Policy Service. This whole process is referred to as authorization. The Policy Service is defined by the amPolicy.xml and, generally speaking:

Provides a means for defining and managing access policies.
Provides a means for defining custom policy plug-ins by providing names and class locations.
Evaluates access policies.
Acts as a PDP to deliver the result of a policy evaluation.
Supports the delegation of policy management.
Provides an SPI for extensibility.
Provides access from remote clients using the Client SDK.
Caches and reuses policy decisions, where applicable, to improve performance.
Allows periodic polling of the Policy Service by a client to update locally cached policy decisions.
Dynamically recognizes changes to policies and provides policy decisions that reflect them.

Note –

The Policy Configuration Service provides a means to specify how policies are defined and evaluated. It enables you to specify, for example, which directory to use for subject lookup, the directory password, which search filters to use, and which subjects, conditions, and response providers to use. This configuration can be done within a realm or a subrealm and is accessible using the OpenSSO Enterprise console.

See Chapter 4, Managing Policies, in Sun OpenSSO Enterprise 8.0 Administration Guide and Chapter 2, Using the Policy Service API, in Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.

The Policy and the Referral

The Policy Service authorizes access to a user based on policies created and stored in the OpenSSO Enterprise configuration data store. The following sections contain information on the two configurations that can be created using the Policy Service.

For more information, see Chapter 4, Managing Policies, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Policy

A policy (referred to as a normal policy in previous releases) specifies a protected resource and who is allowed to access it. The protected resource can be anything hosted on a protected server. Examples of protected resources are applications, document files, images, or the server itself. A normal policy consists of rules, subjects, conditions, and response providers. The following sections contain information on these elements.

Rules

A rule defines the policy itself by specifying a resource, one or more sets of an action, and values for each action.

A resource defines the specific object that is being protected. Examples of protected objects are an HTML page on a web site, or a user’s salary information accessed using a human resources service.
An action is the name of an operation that can be performed on the resource. Examples of web page actions are POST and GET. An allowable action for a human resources service might be canChangeHomeTelephone.
A value defines the permission for the action. Examples are allow anddeny.

Subjects

A subject specifies the user or collection of users that the policy affects. The following list of subjects can be assigned to policies.

Access Manager Identity Subjects: The identities you create and manage under the Subjects tab in a configured realm can be added as a value of the subject.
Authenticated Users: Any user with a valid session (even if they have authenticated to a realm that is different from the realm in which the policy is defined) is a member of this subject. This is useful if the resource owner would like to allow access to users from other organizations. To restrict a resource's access to members of a specific organization, use the Organization subject.
Web Services Clients: This implies that a web service client (WSC) identified by a session token identifier is a member of this subject — as long as the distinguished name (DN) of any principal contained in the session token identifier matches any selected value of this subject.

The following list of subjects can only be specified after they are selected using the Policy Configuration Service of the appropriate realm.

OpenSSO Enterprise Roles

Any member of a OpenSSO Enterprise role is a member of this subject. A OpenSSO Enterprise role is created using OpenSSO Enterprise running in legacy mode. These roles have object classes mandated by OpenSSO Enterprise and can only be accessed through the hosting OpenSSO Enterprise Policy Service.

Note –

This subject can be used when connected to an AMSDK data store.

LDAP Groups

Any member of an LDAP group can be added as a value of this subject.

LDAP Roles

Any LDAP role can be added as a value of this subject. An LDAP Role is any role definition that uses the Sun Java System Directory Server role capability. These roles have object classes mandated by Directory Server role definition. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.

LDAP Users

Any LDAP user can be added as a value of this subject.

Organization

Any member of a realm is a member of this subject.

Conditions

A condition specifies additional constraints that must be satisfied for a policy be applicable. For example, you can define a condition to limit a user’s network access to a specific time period. The condition might state that the subject can access the network only between 7:00 in the morning and 10:00 at night. OpenSSO Enterprise allows for the following list of conditions.

Active Session Time: Sets a condition based on constraints configured for user session time such as maximum session time.
Authentication Chain: The policy is applicable if the user has successfully authenticated to the authentication chain in the specified realm. If the realm is not specified, authentication to any realm at the authentication chain will satisfy the condition.
Authentication Level: The Authentication Level attribute indicates the level of trust for authentication. The policy is applicable if the user's authentication level is greater than or equal to the Authentication Level set in the condition, or if the user's authentication level is less than or equal to the Authentication Level set in the condition, depending on the configuration.
Authentication Module Instance: The policy applies if the user has successfully authenticated to the authentication module in the specified realm. If the realm is not specified, authentication to any realm at the authentication module will satisfy the condition.
IP Address/DNS Names: Sets a condition based on a range of IP Addresses, or a DNS name.
Current Session Properties: Decides whether a policy is applicable to the request based on values set in the user's OpenSSO Enterprise session.
LDAP Filter Condition: The policy is applicable when the defined LDAP filter locates the user entry in the LDAP directory that was specified in the Policy Configuration service.
Realm Authentication: The policy applies if the user has authenticated to the specified realm.
Time: Sets the condition based on time constraints (time, day, date, time zone).

Response Providers

Response providers are plug-ins that provide policy response attributes. Policy response attributes typically provide values for attributes in the user profile. The attributes are sent with policy decisions to the PEP which, in turn, passes them in headers to an application. The application typically uses these attributes for customizing pages such as a portal page. OpenSSO Enterprise includes one implementation of the com.sun.identity.policy.interfaces.ResponseProvider class, the IDResponseProvider. See Chapter 2, Using the Policy Service API, in Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.

Referral

A user with the Top—level Realm Administrator or Policy Administrator roles can create policy. (A Realm Administrator or Policy Administrator configured for a specific realm have permission to create policies only for resources delegated to that realm.) A referral (referred to as a referral policy in previous releases) enables either administrator to delegate policy configuration tasks. A referral delegates both policy creation and policy evaluation, and consists of one or more rules and one or more referrals.

A rule defines the resource of which policy creation or evaluation is being referred.
A referral defines the identity to which the policy creation or evaluation is being referred.

Referrals delegate policy management privileges to another entity such as a peer realm, a sub realm, or even a third-party product. (You can implement custom referrals by using the Policy API.) For example, assume a top-level realm exists named ISP. It contains two sub realms: company1 and company2. The Top-Level Realm Administrator for ISP can delegate policy management privileges so that a Realm Administrator in company1 can create and manage policies only within thecompany1 realm, and a Realm Administrator in company2 can create and manage policies only within the company2 realm. To do this, the Top-Level Realm Administrator creates two referrales, defining the appropriate realm in the rule and the appropriate administrator in the referral. See Chapter 4, Managing Policies, in Sun OpenSSO Enterprise 8.0 Administration Guide for more information.

Realms and Access Control

When a user logs into an application, OpenSSO Enterprise plug-ins retrieve all user information, authentication properties, and authorization policies that the OpenSSO Enterprise framework needs to form a temporary, virtual user identity. The Authentication Service and the Policy Service use this virtual user identity to authenticate the user and enforce the authorization policies, respectively. All user information, authentication properties, and authorization policies is contained within a realm. You create a realm when you want to apply policies to a group of related subjects, services or servers. The Policy Configuration Service within the realm provides a means to specify how policies are defined and evaluated. It enables you to specify, for example, which directory to use for subject lookup, the directory password, which search filters to use, and which subjects, conditions, and response providers to use. For example, you can create a realm that groups all servers and services that are accessed regularly by employees in one region. And, within that regional grouping realm, you can group all servers and services accessed regularly by employees in a specific division such as Human Resources. A configured policy might state that all Human Resources administrators can access the URL http://HR.example.com/HRadmins/index.html. You might also add constraints to this policy: it is applicable only Monday through Friday from 9:00 a.m. through 5:00 p.m. Realms facilitate the delegation of policy management privileges. These configurations can be done within a realm or a sub realm and is accessible using the OpenSSO Enterprise console.

Note –

Access control realms can be configured to use any supported user database.

Policy Service Programming Interfaces

OpenSSO Enterprise provides both Java API and C API for writing clients that remote applications can use to administer policies and evaluate policy decisions. They are used to add, lookup, modify or replace policies, and to evaluate policy decisions when a principal attempts an action on a protected resource. Communication between the API and the Policy Service occurs by sending XML messages over HTTP(S). Additionally, you can extend and customize the Policy Service using the SPI. The classes are used by service developers and policy administrators who need to provide additional policy features as well as support for legacy policies. For example, you can develop customized plug-ins for creating custom policy subjects, referrals, conditions, and response providers. Lastly, the Client SDK is provided to implement policy evaluation logic on a remote web server or application server. For information, see Chapter 14, Using the Client SDK, in Sun OpenSSO Enterprise 8.0 Developer’s Guide, Chapter 2, Using the Policy Service API, in Sun OpenSSO Enterprise 8.0 Developer’s Guide, the Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers, and the Sun OpenSSO Enterprise 8.0 Java API Reference.

XACML Service

eXtensible Access Control Markup Language (XACML) is a markup language that provides an XML syntax for defining policies (who can do what, where can it be done, and when), for querying whether access to a protected resource can be allowed (requests), and for receiving responses to those queries (decisions). XACML is built around the standard access control separation of the Policy Enforcement Point (PEP) and the Policy Decision Point (PDP) as discussed in Authorization and Policy Service Overview except you use XACML formatted queries and responses. The XACML PEP is responsible for intercepting all access requests, collecting the appropriate information (such as who is making the request, which resource is being accessed, and what action is to be taken), and sending a request for a decision to the XACML PDP. The XACML PDP (OpenSSO Enterprise) evaluates configured policies against the information in the decision request. It uses a Context Handler to request the appropriate policies and attributes in order to render one of the following decisions.

Permit
Deny
Not Applicable (no policy created by this PDP applies to the access request)
Indeterminate (an error occurred that prevents the PDP from knowing the correct response)

The following sections contain more information.

XACML in OpenSSO Enterprise

OpenSSO Enterprise implements the SAML v2 Profile of XACML version 2.0 thus supporting XACMLAuthzDecisionQuery and XACMLAuthzDecisionStatement. In a OpenSSO Enterprise XACML interaction, after receiving a request for access, the XACML PEP makes a XACMLAuthzDecisionQuery request and receives a XACMLAuthzDecisionStatement response that contains the decision. (The policies themselves are not returned.) The XACML components on the client side include Client SDK interfaces for passing XACML requests and receiving XACML responses as well as an interface to construct the communications.

Note –

The framework relies internally on the Client SDK SAML v2 interfaces for communication between the PEP and PDP, and includes an implementation of the SAML v2 request handler called the XACML2AuthzDecisionQueryHandler that plugs into the SAML v2 Service framework.

The XACML components on the OpenSSO Enterprise side include out-of-the-box implementations of XACML mappers for subjects, resources, actions and environment. These implementations use the Policy Service to compute authorization decisions. Figure 8–1illustrates how XACML and OpenSSO Enterprise interact with each other. The communications are explained in the procedure following the image.

Figure 8–1 XACML Process Flow

Illustration of the XACML process flow in OpenSSO Enterprise

The policy agent protecting a resource constructs a XACML access request using the Client SDK.
The Client SDK wraps the request in a XACMLAuthzDecisionQuery element and sends it to the SAML v2 query processor on the local machine (also part of the Client SDK).
The SAML v2 query processor consults the metadata for the PEP and the PDP, sets additional elements or attributes in the query, signs it (if necessary) and sends a SOAP request containing the query to the PDP.
The SAML v2 request handler on the PDP side receives the request, consults the metadata for the PEP and the PDP, verifies the trust relationships, enforces any signing or encryption requirements, verifies the signature and forwards the query to the XACMLAuthzDecisionQueryHandler.
The XACMLAuthzDecisionQueryHandler consults the appropriate metadata using the entityID values of the PEP and PDP (included in the request) to find the correct mapper implementations to use.
XACMLAuthzDecisionQueryHandler uses the Resource mapper to map the given Resource to a resource and service configured with OpenSSO Enterprise.
XACMLAuthzDecisionQueryHandler uses the Action mapper to map the given Action to an action name configured with OpenSSO Enterprise.
XACMLAuthzDecisionQueryHandler uses the Environment mapper to map the given Environment to conditions configured with OpenSSO Enterprise.
XACMLAuthzDecisionQueryHandler uses the OpenSSO Enterprise policy evaluator to get the policy decision.
XACMLAuthzDecisionQueryHandler uses the Result mapper to map the decision to an XACML Result element.

Note –
OpenSSO Enterprise is not an XACML policy engine. It has no support for XACML policies themselves and thus no support for retrieving the policies, only the decision.
XACMLAuthzDecisionQueryHandler wraps the XACML Result in an XACML Response, the XACML Response in an XACMLAuthzDecisionStatement, the XACMLAuthzDecisionStatement in a SAML Assertion, the Assertion in a SAML Response, and hands over the SAML Response to the SAML v2 request handler.
The SAML v2 request handler sets additional attributes and elements (based on the SAML v2 protocol), signs it as required and returns it in a SOAP message to the PEP side.
The SAML v2 query processor verifies the trust relationships, the signing requirements, and the signature as necessary. It then extracts the SAML Response from the SOAP message and returns it to the XACML portion of the Client SDK.
The Client SDK extracts the XACML Response from the SAML v2 Response and returns it (and the decision) to the client application.

XACML Programming Interfaces

OpenSSO Enterprise provides Java API for using, and interacting with, the XACML Service. For information, see Chapter 14, Using the Client SDK, in Sun OpenSSO Enterprise 8.0 Developer’s Guide, Chapter 2, Using the Policy Service API, in Sun OpenSSO Enterprise 8.0 Developer’s Guide, and the Sun OpenSSO Enterprise 8.0 Java API Reference.