User authentication, authorization for access to protected resources, and programmatically defining user sessions are all aspects of access management, one of the core functions of Sun OpenSSO Enterprise. OpenSSO Enterprise offers access management features programmatically using the Client SDK, over the wire using HTTP and the OpenSSO Enterprise console, and using an integrated development environment (IDE) application to incorporate Representational State Transfer (REST) calls and Web Services Definition Language (WSDL) files. The chapters in this part contain information on these aspects of access management.
The Session Service in Sun OpenSSO Enterprise tracks a user’s interaction with web applications through the use of session data structures, session tokens, cookies, and other objects. This chapter explains these concepts and other components of a user's session and contains the following sections:
The Session Service in Sun OpenSSO Enterprise tracks a user’s interaction with protected web applications. For example, the Session Service maintains information about how long a user has been logged in to a protected application, and enforces timeout limits when necessary. Additionally, the Session Service:
Generates session identifiers.
Maintains a master copy of session state information.
Implements time-dependent behavior of sessions.
Implements session life cycle events such as logout and session destruction.
Generates session life cycle event notifications.
Generates session property change notifications.
Implements session quota constraints.
Implements session failover.
Enables single sign-on and cross-domain single sign-on among applications external to OpenSSO Enterprise.
Offers remote access to the Session Service through the Client SDK with which user sessions can be validated, updated, and destroyed.
The state of a particular session can be changed by user action or timeout. Figure 5–1 illustrates how a session is created as invalid before authentication, how it is activated following a successful authentication, and how it can be invalidated (and destroyed) based on timeout values.
A user session is the interval between the moment a user attempts to log in to a resource protected by OpenSSO Enterprise, and the moment the session expires, is terminated by an administrator, or the user logs out. As an example of a user session, an employee attempts to access the corporate benefits administration application protected by OpenSSO Enterprise. A new invalid session is created, and the Authentication Service prompts the user for a username and password to verify the user's identity. Following a successful authentication, the Policy Service and policy agent work together to check that the user has the appropriate permissions to access the protected application and allows or denies access based on the outcome.
Oftentimes, in the same user session (without logging out of the corporate benefits application), the same employee might attempt to access a corporate expense reporting application. Because the expense reporting application is also protected by OpenSSO Enterprise, the Session Service provides proof of the user’s authentication, and the employee is allowed to access the expense reporting application (based on the outcome of a second authorization check with the Policy Service). If access is granted, the employee has accessed more than one application in a single user session without having to reauthenticate. This is called single sign-on (SSO). When SSO occurs among applications in more than one DNS domain, it is called cross-domain single sign-on (CDSSO). For a more detailed overview of a basic user session, an SSO session, and a CDSSO session, see Chapter 6, Models of the User Session and Single Sign-On Processes.
The Session Service programmatically creates a session data structure to store information about a user session. The result of a successful authentication results in the validation of a session data structure for the user or entity and the creation of a session token identifier. The session data structure minimally stores the following information.
A unique, universal identifier for the session data structure.
The location from which the client (browser) is making the request.
Set to the user's distinguished name (DN) or the application's principal name.
USER or APPLICATION
Defines whether the session is valid or invalid.
Maximum number of minutes without activity before the session will expire and the user must reauthenticate.
Maximum number of minutes (activity or no activity) before the session expires and the user must reauthenticate.
Maximum number of minutes before the client contacts OpenSSO Enterprise to refresh cached session information.
The value for Maximum Caching Time should be smaller than the value for Maximum Idle Time. If not, the user session idle time won't be updated if the resource is accessed again within the maximum caching time period.
A session can also contain additional properties which can be used by other applications. For example, a session data structure can store information about a user’s identity, or about a user’s browser preferences. You can configure OpenSSO Enterprise to include the following types of data in a session:
Protected properties are only modifiable by the server-side modules (primarily the Authentication Service).
Custom properties are modifiable remotely by any application which possesses the session identifier.
For a detailed summary of information that can be included in a session, see Chapter 14, Configuring OpenSSO Enterprise Sessions, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
The session token, also referred to as a sessionID and programmatically as an SSOToken, is an encrypted, unique string that identifies the session data structure. As the user visits different protected resources using the browser, the session token is propagated to these resources and is used to retrieve the user's credentials. These credentials are then validated by sending a back-end request (using the Client SDK or a policy agent) to OpenSSO Enterprise which then returns an error or the session's prior authentication data. Sessions (and hence the SSOToken) are invalidated when a user logs out, the session expires, or a user in an administrative role invalidates it. With OpenSSO Enterprise, a session token is carried in a cookie, an information packet generated by a web server and passed to a web browser. (The generation of a cookie for a user by a web server does not guarantee that the user is allowed access to protected resources. The cookie simply points to information in a data store from which an access decision can be made.)
Access to some OpenSSO Enterprise services, such as the Policy Service and the Logging Service, require presentation of both the SSOToken of the application as well as the SSOToken of the user, allowing only designated applications to access these services.
This chapter traces events in a basic user session, a single sign-on session (SSO), a cross-domain single sign-on session (CDSSO), and session termination to give you an overview of the features and processes being invoked by OpenSSO Enterprise. It contains the following sections:
The following sections describe the process behind a basic user session by tracing what happens when a user logs in to a resource protected by OpenSSO Enterprise. In these examples, the server which hosts an application is protected by a policy agent. The Basic User Session includes the following phases:
When a user initiates a user session by using a browser to access and log in to a protected web-based application, the events illustrated in Figure 6–1 occur. The accompanying text describes the model.
The user’s browser sends an HTTP request to the protected resource.
The policy agent that protects the resource intercepts and inspects the user's request and finds no session token.
The policy agent issues a redirect to its configured authentication URL to begin the authentication process.
In this example, the authentication URL it is set to the URL of the Distributed Authentication User Interface.
The browser, following the redirect, sends an HTTP request for authentication credentials to the Distributed Authentication User Interface.
The Session Service creates a new session (session data structure) and generates a session token (a randomly-generated string that identifies the session).
The Authentication Service sets the session token in a cookie.
The next part of the user session is User Authentication.
When the browser sends the HTTP request to the Distributed Authentication User Interface, the events illustrated in Figure 6–2 occur.
Using the parameters in the HTTP request from the browser (which includes the URL of the requested application), the Distributed Authentication User Interface contacts the OpenSSO Enterprise Authentication Service (which, in turn, communicates with the Session Service).
The Authentication Service determines what should be presented to the user based upon configuration data and retrieves the appropriate authentication module(s) and callback(s) information.
For example, if configured to use LDAP Authentication, the Authentication Service determines that the LDAP Authentication login page should be displayed.
The collected information is passed to the Distributed Authentication User Interface using the Client SDK.
The Client Detection Service determines which protocol, such as HTML or WML, to use to display the login page.
The Distributed Authentication User Interface generates a dynamic presentation extraction page that contains the appropriate credentials request and callbacks information obtained from OpenSSO Enterprise.
The session cookie will be included in this communication.
The user’s browser displays the login page.
The user enters information in the fields of the login page.
The browser sends the credentials in an HTTP POST to the Distributed Authentication User Interface.
The Distributed Authentication User Interface uses the Client SDK to pass the credentials to the Authentication Service.
The Authentication Service uses the appropriate authentication module to validate the user’s credentials.
For example, if LDAP authentication is used, the LDAP authentication module verifies that the username and password provided exist in the LDAP directory.
Assuming authentication is successful, the Authentication Service activates the session by calling the appropriate methods in the Session Service.
The Authentication Service stores information such as login time, Authentication Scheme, and Authentication Level in the session data structure.
Once the session is activated, the Session Service changes the state of the session token to valid.
The Distributed Authentication User Interface sends an HTTP response back to the browser with a validated SSOToken and location change.
The browser follows the redirect by sending another HTTP request to the original resource protected by a policy agent. This time, the request includes the valid session token created during the authentication process.
The next part of the user session is Session Validation.
After successful authentication, the user’s browser redirects the initial HTTP request to the server a second time for validation. The request now contains a session token in the same DNS domain as OpenSSO Enterprise. The events in Figure 6–3 illustrate this process.
The policy agent intercepts the second access request.
To determine the validity of the session token, the policy agent contacts the Naming Service to learn where the session token originated.
The Naming Service allows clients to find the URL for internal OpenSSO Enterprise services. When contacted, the Naming Service decrypts the session token and returns the corresponding URL which can be used by other services to obtain information about the user session.
The policy agent, using the information provided by the Naming Service, makes a POST request to the Session Service to validate the included session token.
The Session Service receives the request and determines whether the session token is valid based on the following criteria:
Has the user been authenticated?
Does a session data structure associated with the session token exist?
If all criteria are met, the Session Service responds that the session token is valid.
This assertion is coupled with supporting information about the user session itself.
The policy agent creates a Session Listener and registers it with the Session Service, enabling notification to be sent to the policy agent when a change in the session token state or validity occurs.
The next part of the user session is Policy Evaluation and Enforcement.
After a session token has been validated, the policy agent determines if the user can be granted access to the server by evaluating its defined policies. Figure 6–4 illustrates this process.
The policy agent sends a request to the Policy Service, asking for decisions regarding resources in its portion of the HTTP namespace.
The request also includes additional environmental information. For example, IP address or DNS name could be included in the request because they might impact conditions set on a configuration policy.
The Policy Service checks for policies that apply to the request.
Policies are cached in OpenSSO Enterprise. If the policies have not been cached already, they are loaded from OpenSSO Enterprise.
If policies that apply to the request are found, the Policy Service checks if the user identified by the session token is a member of any of the Policy Subjects.
If no policies that match the resource are found, the user will be denied access.
If policies are found that match the resource, and the user is a valid subject, the Policy Service evaluates the conditions of each policy. For example, Is it the right time of day? or Are requests coming from the correct network?
If the conditions are met, the policy applies.
If the conditions are not met, the policy is skipped.
The Policy Service aggregates all policies that apply, encodes a final decision to grant or deny access, and responds to the policy agent.
The next part of the basic user session is Logging the Results.
When the policy agent receives a decision from the Policy Service, the events illustrated in Figure 6–5 occur.
The decision and session token are cached by the policy agent so subsequent requests can be checked using the cache (without contacting OpenSSO Enterprise).
The cache will expire after a (configurable) interval has passed or upon explicit notification of a change in policy or session status.
The policy agent issues a logging request to the Logging Service.
The Logging Service logs the policy evaluation results to a flat file (which can be signed) or to a JDBC store, depending upon the log configuration.
The Logging Service notifies the policy agent of the new log.
The policy agent allows or denies the user access to the application.
If the user is denied access, the policy agent displays an “access denied” page.
If the user is granted access, the resource displays its access page.
Assuming the browser displays the application interface, this basic user session is valid until it is terminated. See Session Termination for more information. While logged in, if the user attempts to log into another protected resource, the Single Sign-On Session begins.
SSO is always preceded by a basic user session in which a session is created, its session token is validated, the user is authenticated, and access is allowed. SSO begins when the authenticated user requests a protected resource on a second server in the same DNS domain. The following process describes an SSO session by tracking what happens when an authenticated user accesses a second application in the same DNS domain as the first application. Because the Session Service maintains user session information with input from all applications participating in an SSO session, in this example, it maintains information from the application the user was granted access to in Basic User Session.
The user attempts to access a second application hosted on a server in the same domain as the first application to which authentication was successful.
The user’s browser sends an HTTP request to the second application that includes the user’s session token.
The policy agent intercepts the request and inspects it to determine whether a session token exists.
A session token indicates the user is already authenticated. Since the user was authenticated, the Authentication Service is not required at this time. The Session Service API retrieve the session data using the session token identifier imbedded in the cookie.
The policy agent sends the session token identifier to the OpenSSO Enterprise Session Service to determine whether the session is valid or not.
For detailed steps, see Session Validation.
The Session Service sends a reply to the policy agent indicating whether the session is valid.
If the session is not valid, the user is redirected to the Authentication page.
If the session is valid, the Session Service creates a Session Listener.
As the session is valid, the Session Service creates a Session Listener.
A Session Listener sends notification to the policy agent when a change in the session state occurs.
The policy agent sends a request for a decision regarding resources in it’s portion of the HTTP namespace to the Policy Service.
The Policy Service checks for policies that apply to the request.
The Policy Service sends the policy evaluation response (either Access Denied or Access Granted.) to the policy agent.
If Policy Service does not find policy allowing access to the protected resource, the user is denied access and the Logging Service logs a denial of access. The user may be redirected to a specified page indicating that access was denied if configured as such by the administrator.
If the Policy Service finds policy allowing access to the protected resource, the user is granted access and the session is valid until terminated.
The policy agent sends a reply to the user indicating whether the user is granted the access.
If the user is denied access, the policy agent displays an Access Denied page.
If the user is granted access, the protected resource displays its access page.
Assuming the Policy Service finds policy allowing access to the protected resource, the user is granted access and the SSO session is valid until terminated. See Session Termination. While still logged in, if the user attempts to log in to another protected resource located in a different DNS domain, the Cross-Domain Single Sign-On Session begins.
CDSSO occurs when an authenticated user requests a protected resource on a server in a different DNS domain. The user in the previous sections, Basic User Session and Single Sign-On Session, for example, accessed applications in one DNS domain. In this scenario, the CDSSO Controller within OpenSSO Enterprise transfers the user’s session information from the initial domain, making it available to applications in a second domain.
The basic difference between the proprietary CDSSO and SAML v2 (as described in Federation Options) is that CDSSO uses a single authentication authority, a mechanism to move a cookie between multiple DNS domains. SAML v2, on the other hand, gives you the option of using multiple authentication authorities, with one authority asserting the identity of the user to the other.
The authenticated user’s browser sends an HTTP request to the application in a different DNS domain.
The policy agent intercepts the request and inspects it to determine if a session token exists for the domain in which the requested application exists. One of the following occurs:
If a session token is present, the policy agent validates the session.
If no session token is present, the policy agent (which is configured for CDSSO) will redirect the HTTP request to the CDSSO Controller.
The CDSSO Controller uses Liberty Alliance Project protocols to transfer sessions so the relevant parameters are included in the redirect.
In this example, no session token for the second domain is found.
The policy agent redirects the HTTP request to the CDSSO Controller.
The user’s browser allows the redirect to the CDSSO Controller.
Recall that earlier in the user session the session token was set in a cookie in the first domain which is now part of the redirect.
The CDC Servlet (in the CDSSO Controller) receives the session token from the first domain, extracts the user's session information, formulates a Liberty POST profile response containing the information, and returns a response to the browser.
The user’s browser automatically submits the response to the policy agent in the second domain.
The policy agent in the second domain receives the response, extracts the session information, validates the session, and sets a session token in the cookie for the new DNS domain.
If the user is denied access, the policy agent displays an “access denied” page.
If the user is granted access, the protected resource displays its access page. The new cookie can now be used by all agents in the new domain, and the session is valid until it is terminated.
A user session can be terminated in any of following ways:
When a user explicitly logs out of OpenSSO Enterprise by clicking on a link to the Logout Service the following events occur:
The Logout Service receives the Logout request, and:
Marks the user’s session as destroyed.
Destroys the session.
Returns a successful logout page to the user.
The Session Service notifies applications which are configured to interact with the session. In this case, each of the policy agents was configured for Session Notification, and each is sent a document instructing the agent that the session is now invalid.
The policy agents flush the session from the cache and the user session ends.
OpenSSO Enterprise administrators with appropriate permissions can terminate a user session at any time. When an administrator uses the Sessions tab in the OpenSSO Enterprise console to end a user’s session, the following events occur:
The Logout Service receives the Logout request, and:
Marks the user’s session as destroyed.
Destroys the session.
The Session Service notifies applications which are configured to interact with the session. In this case, each of the policy agents was configured for Session Notification, and each is sent a document instructing the agent that the session is now invalid.
The policy agents flush the session from cache and the user session ends.
When a session timeout limit is reached, the Session Service:
Changes the session status to invalid.
Displays a time out message to the user.
Starts the timer for purge operation delay. (The default is 60 minutes.)
Purges or destroys the session when the purge operation delay time is reached.
Displays login page to the user if a session validation request comes in after the purge delay time is reached.
OpenSSO Enterprise allows administrators to constrain the amount of sessions one user can have. If the user has more sessions than the administrator will allow, one (or more) of the existing sessions can be destroyed.
The Sun OpenSSO Enterprise Authentication Service determines whether a user is the person he claims to be. User authentication is the first step in controlling access to web resources within an enterprise. This chapter explains how the Authentication Service works with other components to prove that the user’s identity is genuine. Topics covered in this chapter include:
The function of the Authentication Service is to request information from an authenticating party, and validate it against the configured identity repository using the specified authentication module. After successful authentication, the user session is activated and can be validated across all web applications participating in an SSO environment. For example, when a user or application attempts to access a protected resource, credentials are requested by one (or more) authentication modules. Gaining access to the resource requires that the user or application be allowed based on the submitted credentials. From the user perspective, a company employee wants to look up a colleague’s phone number. The employee uses a browser to access the company’s online phone book. To log in to the phone book service, the employee provides a user name and password. OpenSSO Enterprise compares the user’s input with data stored in the appropriate identity repository. If OpenSSO Enterprise finds a match for the user name, and if the given password matches the stored password, the user’s identity is authenticated.
The Basic User Session section in the previous chapter contains a detailed description of the authentication process itself.
The Authentication Service can be accessed by a user with a web browser, by an application using the Client SDK, or by any other client that correctly implements the Authentication Service messaging interfaces. The Authentication Service framework has a pluggable architecture for authentication modules that have different user credential requirements. Together with the Session Service, the Authentication Service establishes the fundamental infrastructure for SSO. Generally speaking, the Authentication Service:
Identifies a requester's credential requirements.
Generates a dynamic user interface based on the requirements of the authentication module being called.
Supports custom, pluggable authentication modules.
Provides pre- and post-processing SPI.
Populates and manages system domain cookies.
Generates time dependent alerts and session termination notifications.
Provides a remote user interface application for distributed deployments.
Implements a clean logout interface which destroys the session.
Every time a request is used to access the Authentication Service, the session token identifier is retrieved and used to get the associated session data structure from the Session Service. Additionally, the Authentication Service interfaces with the Session Service to:
Initiate or create user sessions.
Maintain session state information.
Activate sessions after successful authentication.
Populate the valid session data structure with all user-authenticated identity data and properties.
Destroy sessions after logout.
The following diagram illustrates how the two services work together.
The Authentication Service also interfaces with other OpenSSO Enterprise services including the Naming Service, the Identity Repository Service, the Logging Service, and the Monitoring Service. It also interfaces with the configuration data store and policy agents protecting system resources. (A policy agent must authenticate itself using the Client SDK authentication interfaces, and users with no valid session must be authenticated.)
The following sections explain some of the features of the Authentication Service.
The Authentication Service provides account locking to prevent a user from completing the authentication process after a specified number of failures. OpenSSO Enterprise sends email notifications to administrators when account lockouts occur. OpenSSO Enterprise supports:
By default, user accounts are physically unlocked. You can initiate physical locking by typing inactive as the value of the Lockout Attribute Name attribute in the Core Authentication Service. Additionally, the value of the Login Failure Lockout Duration attribute should be set to 0.
physical lock attr name is: inetuserstatus value active/inactive
You can configure Memory Locking so that a user account is locked in memory after a specified number of authentication attempts. By changing the Login Failure Lockout Duration attribute to a value greater then 0, the user’s account is then locked in memory for the number of minutes specified and the account is unlocked after the time period elapses.
To figure out the amount of time the lockout will be in effect, the value of the Lockout Duration Multiplier attribute is multiplied by the value of the Login Failure Lockout Duration attribute for subsequent lockout. For example, if the value of Login Failure Lockout Duration is 5 minutes and the value of the Lockout Duration Multiplier is 2, the first time a user is locked out in memory will be 5 minutes. The second time this same user gets locked out in memory the lockout duration will be 10 minutes (5 minutes x 2). The third time this same user gets locked out in memory the lockout duration will be 20 minutes (5 minutes x 2 x 2).
The account locking feature is disabled by default. Account locking activities are also logged. For information on how to enable it, see Enabling Account Lockout in Sun OpenSSO Enterprise 8.0 Administration Guide.
Only authentication modules that throw an Invalid Password Exception can leverage the Account Locking feature. Out of the box, these include Active Directory, Data Store, HTTP Basic, LDAP, and Membership.
OpenSSO Enterprise allows the configuration of an authentication process in which a user must pass credentials to one or more authentication modules before session validation is accomplished. This is called authentication chaining. OpenSSO Enterprise uses the Java Authentication and Authorization Service (JAAS) framework (integrated with the Authentication Service) to implement authentication chaining. The JAAS framework validates all user identifiers used during the authentication process, and maps them to one principal. (The mapping is based on the configuration of the User Alias List attribute in the user's profile.) If all the maps are correct, the session token is validated. If all the maps are not correct, the user is denied a valid session token. Once authentication to all modules in the chain succeeds or fails, control is returned to the Authentication Service from the JAAS framework.
You configure an authentication chain by realm, user, role, or service. Determining validation is based upon the control flag configured for each authentication module instance defined in the chain. The flags are:
Authentication to this module instance is required to succeed. If it succeeds, authentication continues down the module instance list. If it fails, control immediately returns to the application.
Authentication to this module instance is required to succeed. If any of the required module instances defined in the chain fails, the whole authentication chain will fail.
The module instance is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the module instance list). If it fails, authentication continues down the list.
The module instance is not required to succeed. Whether it succeeds or fails, authentication still continues to proceed down the module instance list.
Role based authentication is only supported for use with the AM SDK data store. This data store would come from an existing Sun Java System Access Manager 7.x installation or would have been manually created.
For more information, see Chapter 3, Configuring Authentication, in Sun OpenSSO Enterprise 8.0 Administration Guide. For an overview of the authentication module instances, see Authentication Modules.
Fully Qualified Domain Name (FQDN) mapping enables the Authentication Service to take corrective action in the case where a user may have typed in an incorrect URL. This is necessary, for example, when a user specifies a partial host name or IP address to access protected resources. This feature can also be used to allow access to one instance of OpenSSO Enterprise using many different aliases. For example, you might configure one instance of OpenSSO Enterprise as intranet.example.com for employees and extranet.example.com for partners. For more information, see Mapping Fully Qualified Domain Names in Sun OpenSSO Enterprise 8.0 Administration Guide.
A persistent cookie is an information packet that is written to the user's hard drive and, therefore, continues to exist after the web browser is closed. The persistent cookie enables a user to log into a new browser session without having to reauthenticate. The Authentication Service can be enabled to write persistent cookies rather than cookies that are written to a web browser's memory. For more information, see Using Persistent Cookies in Sun OpenSSO Enterprise 8.0 Administration Guide.
The Authentication Service allows for the upgrade of a valid session based on a second, successful authentication performed by the same user. If a user with a valid session attempts to authenticate to a second resource secured under the realm to which he is currently authenticated, and this second authentication request is successful, the Authentication Service updates the session with the new properties based on the new authentication. If the authentication fails, the current user session is returned without an upgrade. If the user with a valid session attempts to authenticate to a resource secured in a different realm, the user will receive a message asking whether the user would like to authenticate to the new realm. The user can choose to maintain the current session, or can attempt to authenticate to the new realm. Successful authentication will result in the old session being destroyed and a new one being created. For more information, see Upgrading Sessions in Sun OpenSSO Enterprise 8.0 Administration Guide.
Successful authentication for session upgrade does not necessarily destroy the previous session. If the subsequent AuthContext object is created with the constructor AuthContext(SSOToken ssoToken, boolean forceAuth) when forceAuth is set to true, the existing session will be used and a new session will not be created.
The JAAS shared state enables sharing of both a user identifier and a password between authentication module instances. Options are defined for each authentication module type by realm, user, service and role. If an authentication fails with the credentials from the shared state, the authentication module restarts the authentication process by prompting for its required credentials. If it fails again, the module is marked failed. After a commit, an abort, or a logout, the shared state will be cleared. For more information, see Sharing User Credentials Among Authentication Modules (Shared State) in Sun OpenSSO Enterprise 8.0 Administration Guide.
From a security point of view, here are some general practices implemented in the Authentication Service.
SSL is strongly recommended to prevent the user credentials from being stolen through passive network snooping.
The signing and encryption of some user data is to prevent other software applications, sharing the same system resources, from subverting it.
The main user entry points of the Authentication Service (Distributed Authentication User Interface, Authentication XML Handler Interface for remote clients, the Authentication Service User Interface) are protected by entry level validation of the size of the requested data.
Creation and modification of authentication configuration information is only allowed by privileged OpenSSO Enterprise administrators.
An authentication module is a plug-in that collects user information such as a user ID and password, and compares the information against entries in a database. If a user provides information that meets the authentication criteria, the user is validated and, assuming the appropriate policy configuration, granted access to the requested resource. If the user provides information that does not meet the authentication criteria, the user is not validated and denied access to the requested resource. OpenSSO Enterprise is deployed with a number of authentication modules. Table 7–1 provides a brief description of each.Table 7–1 Authentication Service Modules
Authentication Module Name
Uses an Active Directory operation to associate a user identifier and password with a particular Active Directory entry. You can define multiple Active Directory authentication configurations for a realm. Allows both LDAP and Active Directory to coexist under the same realm.
Enables a user to log in without specifying credentials. You can create an Anonymous user so that anyone can log in as Anonymous without having to provide a password. Anonymous connections are usually customized by the OpenSSO Enterprise administrator so that Anonymous users have limited access to the server.
Enables a user to log in through a personal digital certificate (PDC). The user is granted or denied access to a resource based on whether or not the certificate is valid. The module can optionally require the use of the Online Certificate Status Protocol (OCSP) to determine the state of a certificate.
Enables authentication against one or more configuration data stores within a realm.
Used by the service provider during federation (using SAML v1.x, SAML v2, WS-Federation, Liberty ID-FF) to create a session after validating the assertion. This authentication module can not be invoked like the other modules as it is invoked directly by the SAMLAwareServlet.
Enables authentication to occur with no data encryption. Credentials are validated internally using either the LDAP or Data Store authentication module.
Enables authentication through any Structured Query Language (SQL) databases that provide JDBC-enabled drivers. The SQL database connects either directly through a JDBC driver or through a JNDI connection pool.
Enables authentication using LDAP bind, a directory server operation which associates a user identifier and password with a particular LDAP entry. You can define multiple LDAP authentication configurations for a realm.
Enables user to self-register a user entry. The user creates an account, personalizes it, and accesses it as a registered user without the help of an administrator. Implemented similarly to personalized sites such as my.site.comor mysun.sun.com.
The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables authentication using a mobile subscriber ISDN associated with a device such as a cellular telephone. It is a non-interactive module. The module retrieves the subscriber ISDN and validates it against the user repository to find a user that matches the number.
Uses an external Remote Authentication Dial-In User Service (RADIUS) server to verify identities.
Security Assertion Markup Language (SAML)
Receives and validates SAML assertions on a target server by using either a web artifact or a POST response.
Uses Secure Computing’s SafeWord PremierAccessTM server software and SafeWord tokens to verify identities.
Uses RSA ACE/Server software and RSA SecurID authenticators to verify identities.
Solaris and Linux modules use a user’s UNIX identification and password to verify identities.
Windows Desktop Single Sign-On (SSO)
Allows a user who has already authenticated with a key distribution center to be authenticated by OpenSSO Enterprise without having to provide the login information again. Leverages Kerberos authentication and is supported wherever Kerberos is supported (including Windows, Solaris, Linux, and Macintosh).
Uses a Microsoft Windows NTTM server to verify identities.
You can use the OpenSSO Enterprise console to enable and configure the authentication modules. You can also create and configure multiple instances of a particular authentication module. (An authentication module instance is a child entity that extends the schema of a parent authentication module and adds its own subschema.) Finally, you can write your own custom authentication module (or plug-in) to connect to the OpenSSO Enterprise authentication framework. See Chapter 3, Configuring Authentication, in Sun OpenSSO Enterprise 8.0 Administration Guide for detailed information about enabling and configuring default authentication modules and authentication module instances. See Chapter 1, Using the Authentication Service API and SPI, in Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information about writing custom authentication modules.
After granting or denying access to a resource, OpenSSO Enterprise checks for information about where to redirect the user. A specific order of precedence is used when checking for this information. The order is based on whether the user was granted or denied access to the protected resource, and on the type of authentication specified. When you install OpenSSO Enterprise, a number of authentication types are automatically configured.
User authenticates to a configured realm or sub-realm.
This authentication type is equivalent to organization—based authentication. The query parameters org and realm would both lead to realm-based authentication in realm mode, and organization-based authentication in legacy mode.
User authenticates to a configured role within a realm or sub-realm. The user must possess the role. A static role is possessed when an attribute is assigned to a specific user or container. A filtered role is dynamically generated based on an attribute contained in the user’s or container’s entry. For example, all users that contain a value for the employee attribute can be included in a role named employees when the filtered role is created.
Role based authentication is only supported for use with the AM SDK data store schema plug-in. This data store would come from an existing Sun Java System Access Manager 7.x installation or would have been manually created. If a user installs OpenSSO Enterprise with any other user datastore, role-based authentication will not be supported.
User authenticates to a specific service or application registered to a realm or sub-realm.
User authenticates using an authentication process configured specifically for him or her.
An administrator specifies the security level of the authentication modules by defining each with an authentication level. Successful authentication to a higher authentication level defines a higher level of trust for the user. If a user attempts to access a service, the service can determine if the user is allowed access by checking the authentication level in the user's session data. If the authentication level is not high enough, the service redirects the user to go through an authentication process with a set authentication level.
Allows a user to specify the module to which they will authenticate.
User authenticates to an organization or sub-organization.
This authentication type is equivalent to realm-based authentication. The query parameters org and realm would both lead to realm-based authentication in realm mode, and organization-based authentication in legacy mode.
For more information, see Chapter 3, Configuring Authentication, in Sun OpenSSO Enterprise 8.0 Administration Guide.
The authentication framework includes the following places where you can configure for authentication:
Explanations of the authentication attributes can be found in the Online Help and the Sun OpenSSO Enterprise 8.0 Administration Reference.
The Core Authentication Module contains general authentication properties that can be defined globally using the OpenSSO Enterprise console (under the Configuration tab) or more specifically for each configured realm (under the Access Control tab). Core authentication properties are added and enabled for the top-level realm during installation. As new realms are configured under the top-level realm, these properties (and the values defined globally for them) are dynamically added to each new realm when it is created. Once added, new values can be defined and configured values can be modified by the realm's administrator. The values are then used if no overriding value is defined in the specified authentication module instance or authentication chain. The default values for the Core Authentication Module are defined in the amAuth.xml file and stored in the configuration data store. For more information, see Chapter 3, Configuring Authentication, in Sun OpenSSO Enterprise 8.0 Administration Guide and the Sun OpenSSO Enterprise 8.0 Administration Reference.
The Authentication Configuration Service describes all the dynamic attributes for service-based authentication. This service is used for configuring roles. When you assign a service to a role, you can also assign other attributes such as a success URL or an authentication post-processing class to the role.
In the last phase of the authentication process, OpenSSO Enterprise either grants or denies access to the user. If access is granted, OpenSSO Enterprise uses a login URL to display a page in the browser. If access is denied, OpenSSO Enterprise uses a redirection URL to display an alternate page in the browser. A typical alternate page contains a brief message indicating the user has been denied access.
Each authentication type (as discussed in Authentication Types) uses a login URL or redirection URL based on a specific order of precedence, and on whether the authentication succeeded or failed. For a detailed description of how OpenSSO Enterprise proceeds through the order of precedence, see Chapter 3, Configuring Authentication, in Sun OpenSSO Enterprise 8.0 Administration Guide.
The OpenSSO Enterprise Authentication Service has two separate graphical user interfaces that can be used. The following sections contain information on them.
The Authentication Service implements a user interface that is separate from the OpenSSO Enterprise administration console. The Authentication Service user interface provides a dynamic and customizable means for gathering authentication credentials. When a user requests access to a protected resource, the Authentication Service presents a web-based login page and prompts the user for the appropriate credentials based on the configured authentication module or chain. Once the credentials have been passed back to OpenSSO Enterprise and authentication is deemed successful, the user may gain access to the protected resource if authorized to do so. The Authentication Service user interface can be used for the following:
Administrators can access the administration portion of the OpenSSO Enterprise console to manage their realm’s identity data.
Users can access their own profiles to modify personal data.
A user can access a resource defined as a redirection URL parameter appended to the login URL.
A user can access the resource protected by a policy agent.
Below is a screen capture of the default Authentication Service user interface.
OpenSSO Enterprise provides customization support for the Authentication Service user interface. You can customize JavaServer Pages™ (JSP™) and the file directory level by organization, service, locale, or client type. See Chapter 13, Customizing the Authentication User Interface, in Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.
OpenSSO Enterprise also provides a remote authentication user interface component to enable secure, distributed authentication across two firewalls. A web browser communicates an HTTP request to the remote authentication user interface which, in turn, presents the appropriate module login page to the user. The web browser then sends the user login information through a firewall to the remote authentication user interface which, in turn, communicates through the second firewall with OpenSSO Enterprise. The Distributed Authentication User Interface enables a policy agent or an application that is deployed in a non-secured area to communicate with the OpenSSO Enterprise Authentication Service installed in a secured area of the deployment. Figure 7–3 illustrates this scenario.
The Distributed Authentication User Interface uses a JATO presentation framework and is customizable. (See screen capture in Authentication Service User Interface.) You can install the Distributed Authentication User Interface on any servlet-compliant web container within the non-secure layer of a OpenSSO Enterprise deployment. The remote component then works with the Authentication client APIs and authentication utility classes to authenticate web users. For a more detailed process, see User Authentication. For detailed installation and configuration instructions, see Chapter 9, Deploying a Distributed Authentication UI Server, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
OpenSSO Enterprise provides both Java APIs and C APIs for writing authentication clients that remote applications can use to gain access to the Authenticate Service. Communication between the APIs and the Authentication Service occurs by sending XML messages over HTTP(S). The Java and C APIs support all authentication types supported by the browser-based user interface. Clients other than Java and C clients can use the XML/HTTP interface directly to initiate an authentication request. Additionally, you can add custom authentication modules to OpenSSO Enterprise by using the service provider interface (SPI) package, com.iplanet.authentication.spi. This SPI implements the JAAS LoginModule, and provides additional methods to access the Authentication Service and module configuration properties files. Because of this architecture, any custom JAAS authentication module will work within the Authentication Service. For more information, see Chapter 1, Using the Authentication Service API and SPI, in Sun OpenSSO Enterprise 8.0 Developer’s Guide and Sun OpenSSO Enterprise 8.0 Java API Reference.
OpenSSO Enterprise also provides a Client SDK that can implement authentication 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.
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:
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.
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.
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.
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.
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.
A subject specifies the user or collection of users that the policy affects. The following list of subjects can be assigned to policies.
The identities you create and manage under the Subjects tab in a configured realm can be added as a value of the subject.
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.
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.
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.
This subject can be used when connected to an AMSDK data store.
Any member of an LDAP group can be added as a value of this subject.
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.
Any LDAP user can be added as a value of this subject.
Any member of a realm is a member of this subject.
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.
Sets a condition based on constraints configured for user session time such as maximum session time.
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.
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.
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.
Sets a condition based on a range of IP Addresses, or a DNS name.
Decides whether a policy is applicable to the request based on values set in the user's OpenSSO Enterprise session.
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.
The policy applies if the user has authenticated to the specified realm.
Sets the condition based on time constraints (time, day, date, time zone).
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.
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.
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.
Access control realms can be configured to use any supported user database.
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.
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.
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.
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.
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.
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.
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.
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.