This chapter explains how the Access Manager Session Service works with other core Access Manager components to process HTTP requests and to manage user session data. The chapter traces events in a basic user session, a single sign-on session (SSO), and a cross-domain single sign-on session (CDSSO) to give you an overview of Access Manager’s features and process flows. Topics covered include:

• User Sessions and the Session Service

• Sessions, Session Tokens, and Cookies

• Policy Agents

• Basic User Session

• Single Sign-On Session

• Cross-Domain Single Sign-On Session

• Session Termination

User Sessions and the Session Service

The Session Service in Sun Java System Access Manager tracks a user’s interaction with web applications. For example, the Session Service maintains information about how long a user has been logged in to Access Manager, and enforces time-out limits when necessary. Additionally, the Session Service performs the following actions:

• 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 (SSO) and cross-domain single sign-on (CDSSO) among applications external to Access Manager.

A user session is the interval between the moment a user logs in to Access Manager, and the moment the user logs out of Access Manager. In a typical user session, an employee attempts to access the corporate benefits administration application. The application is protected by Access Manager, and Access Manager prompts the user for a username and password. First, Access Manager authenticates, or verifies that the user is who he says he is. Following user authentication, Access Manager allows the user access to the application (providing the user has the appropriate permissions). For a more detailed explanation, see Basic User Session.

Oftentimes, in the same user session (without logging out of the corporate benefits application), the same employee attempts to access the corporate expense reporting application. Because the expense reporting application is also protected by Access Manager, the Session Service provides continued proof of the user’s authentication, and the employee is automatically allowed to access the expense reporting application. The employee has accessed more than one application in a single user session without having to re-authenticate. This functionality is called Single Sign-On (SSO). When SSO occurs among applications in more than one DNS domain, the functionality is called Cross-Domain Single Sign-On (CDSSO). For more detailed explanations, see Single Sign-On Session and Cross-Domain Single Sign-On Session, respectively.

Sessions, Session Tokens, and Cookies

The Access Manager Session Service creates a session data structure to store information about a user session and uses cookies to store a token that identifies the session data structure. When a user logs in and is successfully authenticated, the user is assigned a session, a session data structure that, minimally, stores the following information about a user session:

Maximum Idle Time

Maximum number of minutes without activity before the session will expire and the user must reauthenticate.

Maximum Session Time

Maximum number of minutes (activity or no activity) before the session expires and the user must reauthenticate.

Maximum Caching Time

Maximum number of minutes before the client contacts Access Manager to refresh cached session information.

Internally, these session attributes are used to enforce Access Manager timeout limits. But a session can also contain additional attributes and 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 Access Manager to include the following types of information in a session:

• Fixed session attributes

• Protected properties

• Custom properties

For a detailed summary of information that can be included in a session, see Configuring Access Manager Sessions in the Sun Java System Access Manager 7.1 Postinstallation Guide.

The Session Service also generates a session token for the new session data structure. The session token, also known as a sessionID, is an encrypted, unique string that identifies the specific session instance. If the session token is known to a protected resource such as an application, the application can access the session and all user information contained in it. In Access Manager, a session token is carried in a cookie. A cookie is an information packet generated by a web server and passed to a web browser. The fact that a web server generates a cookie for a user does not guarantee that the user is allowed access to protected resources. The cookie simply points to user information in a data store from which an access decision can be derived.

---

Note –

Cookies are domain-specific. For example, a cookie generated by a web server within Domain A cannot be used by a web server in Domain B. Cookies can be passed only between servers in the same domain in which the cookie was set. Similarly, servers can set cookies only on servers within in their own domain.

---

Policy Agents

Policy agents are an integral part of SSO and CDSSO sessions. They are programs that police the web server or application server that hosts protected resources. When a user requests access to a protected resource such as a server or an application, the policy agent intercepts the request and redirects it to the Access Manager Authentication Service for authentication. Following this, the policy agent will also enforce the authenticated user’s assigned policies. (A policy defines the rules that specify a user's access privileges to a protected resource.) Access Manager supports two types of policy agents:

• The web agent enforces URL-based policy for C applications.

• The J2EE/Java agent enforces URL-based policy and J2EE-based policy for Java applications on J2EE containers.

Both types of agents are available for you to install as programs separate from Access Manager. For an overview of the available policy agents and links to specific information on installation, see the Sun Java System Access Manager Policy Agent 2.2 User’s Guide.

---

Note –

When Access Manager policy agents are implemented, all HTTP requests are implicitly denied unless explicitly allowed by the presence of two things:

1. A valid session

2. A policy allowing access

You can modify this default configuration so that Access Manger implicitly allows access unless explicitly denied.

---

Basic User Session

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 Access Manager. In these examples, the server which hosts an application is protected by an Access Manager policy agent. The Basic User Session includes the following phases:

• Initial HTTP Request

• User Authentication

• Session Validation

• Policy Evaluation and Enforcement

• Logging Results

Initial HTTP Request

When a user initiates a user session by using a browser to log in to a web-based application, the events in the following illustration occur. The accompanying text describes the process.

Figure 2–1 Initial HTTP Request

1. The user’s browser sends an HTTP request to the protected resource.

2. The policy agent inspects the user’s request and finds no session token.

3. The policy agent contacts the configured authentication URL.

   In this example, the authentication URL it is set to the URL of the Distributed Authentication User Interface Service.

4. The browser sends a GET request to the Distributed Authentication User Interface.

5. The Session Service creates a new session (session data structure) and generates a session token. The session token is a randomly-generated string that represents the user.

6. The Authentication Service sets the session token in a cookie.

The next part of the user session is User Authentication.

User Authentication

When the browser sends a GET request to the Distributed Authentication User Interface, the events in the following illustration occur. The accompanying text describes the process.

1. Using the parameters in the GET request, the Distributed Authentication User Interface contacts the Authentication Service installed on the Access Manager server.

2. The Authentication Service determines the appropriate authentication module to use based upon Access Manager configuration and the request parameters passed by the Distributed Authentication User Interface using the Authentication client APIs.

   For example, if Access Manager is configured to use the LDAP Authentication type of module, the Authentication Service determines that the LDAP Authentication login page will be used.

3. The Authentication Service determines which presentation callbacks should be presented, and sends to the Distributed Authentication User Interface all necessary credentials, requirements, and callbacks for use by the presentation framework layer.

4. The Client Detection Service determines which protocol, such as HTML or WML, to use to display the login page.

5. The Distributed Authentication User Interface returns to the Web browser a dynamic presentation extraction page along with the session cookie.

   The presentation extraction page contains the appropriate credentials request and callbacks info obtained from the Access Manager server.

6. The user’s browser displays the login page.

   The user enters information in the Username and Password fields of the login page.

7. The browser replies to the Distributed Authentication User Interface with a POST that contains the required credentials.

8. The Distributed Authentication User Interface uses the Authentication client APIs to pass credentials to the Access Manager server.

9. The Authentication Service uses the appropriate authentication module type to validate the user’s credentials.

   For example, if the LDAP authentication module type is used, the Authentication Service verifies that the username and password provided exist in the LDAP directory. Other authentication module types have different requirements.

10. 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.

11. Once the session is activated, the Session Service changes the state of the session token to valid.

12. The Distributed Authentication User Interface replies to the protected resource with an SSOToken in a set-cookie header.

13. Now, the browser makes another request to the original resource protected by a policy agent.

    This time, the request includes a valid session token, created during the authentication process.

The next part of the user session is Session Validation.

Session Validation

After authentication, when the user’s browser redirects the initial HTTP request to the server for a second time, the events in the following illustration occur. The accompanying text describes the process.

Figure 2–2 Session Validation

1. The policy agent intercepts the second access request.

   The request now contains a session token in the same DNS domain as Access Manager.

2. The policy agent determines the validity of the session token.

   1. The policy agent contacts the Naming Service to learn where the session token originated.

      The Naming Service allows clients to find the service URL for the internal services used by Access Manager. This information can then be used for communication regarding a session.

   2. The Naming Service decrypts the session token and returns the corresponding URLs . The URLs will be used by other services to obtain information about the user session.

3. 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.

4. The Session Service receives the request and determines whether the session token is valid based on the following criteria:

   1. Has the user been authenticated?

   2. Does a session data structure associated with the session token exist?

5. 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.

6. The policy agent creates a Session Listener and registers the Session Listener with the Session Service. This enables notification 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.

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 it's defined policies. The following illustration and accompanying text describes the process.

Figure 2–3 Policy Evaluation

1. The policy agent sends a request to the Policy Service.

   The request asks for decisions regarding resources in the policy agent’s 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.

2. The Policy Service checks for policies that apply to the request.

   Policies are cached in Access Manager. If the policies have not been cached already, then the policies are loaded from the Access Manager information tree in the Identity Repository.

3. 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.

   1. If no policies that match the resource are found, the user is denied access. Skip to step 5.

   2. 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.

4. The Policy Service aggregates all policies that apply, encodes a final decision to grant or deny access, and responds to the policy agent with the appropriate decision.

The next part of the user session is logging the policy evaluation results.

Logging Results

When the policy agent receives an allow decision from the Policy Service, the events in the following illustration occur. The accompanying text describes the process.

Figure 2–4 Logging the Policy Evaluation Results

1. The allow decision is cached in the policy agent, along with the session token, so that subsequent requests can be checked using the cache.

   It is no longer necessary for the policy agent to contact Access Manager. The cache will expire after an interval has passed or upon an explicit notification of change in policy or session status. The interval is configurable.

2. The policy agent issues a logging request to the Logging Service.

3. 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.

4. The Logging Service notifies the policy agent of the new log.

5. The policy agent allows or denies the user access to the application.

   1. If the user is denied access, the policy agent displays an “access denied” page.

   2. 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.

While the user is still logged in, if he attempts to log into another protected resource, the Single Sign-On session begins.

Single Sign-On Session

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 example describes an SSO session by tracing 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. We will assume the application previously accessed was a corporate benefits administration application. For this SSO session, the user is attempting access to an expense reporting application.

Figure 2–5 Single Sign-On Session

1. The user attempts to access an expense reporting application.

   Both the expense reporting application and the corporate benefits administration application are hosted on servers in the same domain.

2. The user’s browser sends an HTTP request to the expense reporting application. The request includes the user’s session token.

3. The policy agent intercepts and inspects the request to determine whether a session token exists.

   A session token indicates the user is already authenticated. Since the user was authenticated when the user logged in to the corporate benefits administration application, the Authentication Service is not required at this time. The SSO APIs retrieve the session data structure using the session token imbedded in the cookie. The session data structure is referred to as the SSOToken by the SSO APIs. The session token is referred to as the SSOTokenID.

4. The policy agent determines the validity of the session.

   For detailed steps, see Session Validation.

5. The Session Service sends a reply to the policy agent indicating whether the SSOToken is valid.

   • If the SSOToken is not valid, the user is redirected to the Authentication page.

   • If the SSOToken is valid, the Session Service creates a Session Listener.

     A Session Listener allows notification to the policy agent when a change in the SSOToken state or validity occurs.

6. The policy agent sends a request to the Policy Service.

   The request asks for a decision regarding resources in the policy agent’s portion of the HTTP namespace.

7. The Policy Service checks for policies that apply to the request.

   • If Policy Service does not find policy allowing access to the protected resource, the user is denied access and the following events occur:

     1. The Logging Service logs a denial of access.

     2. The policy agent issues a Forbidden message to the user.

        The user can then be redirected to an administrator-specified page indicating the user was denied access.

   • If the Policy Service finds policy allowing access to the protected resource, the user is granted access to the protected resource and the SSO session is valid until it is terminated. See Session Termination.

While still logged in, if the user decides to attempt to log in to another protected resource located in a different DNS domain, Cross-Domain Single Sign-On takes place.

Cross-Domain Single Sign-On Session

CDSSO occurs when an authenticated user requests a protected resource on a different 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 his company’s DNS domain. In the following example, the same user will log in to a travel administration application supplied to his company by an external company. The travel administration application is hosted on the external company’s DNS domain. In this scenario, the CDSSO Controller Service within Access Manager transfers the user’s session information from the initial domain, making the it available to applications in this second domain.

When the user logs in to the travel administration application in the external DNS domain, the events in the following illustration occur. The process is described in the accompanying text.

1. The user’s browser sends an HTTP request to the travel administration application.

2. The policy agent intercepts the request and inspects it to determine if a session token exists for the domain in which the travel administration 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) redirects the HTTP request to the CDSSO Controller Service.

     ---

     Note –

     The CDSSO Controller Service 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.

3. The policy agent redirects the HTTP request to the CDSSO Controller Service.

4. The user’s browser allows the redirect to the CDSSO Controller Service.

   Recall that earlier in the user session the session token was set in a cookie in the initial domain which is now part of the redirect.

5. The CDSSO Controller Service's CDC Servlet receives the session token from the initial domain, extracts the user's session information, and formulates a Liberty POST profile response containing the information. The response is returned to the browser.

6. The user’s browser automatically submits the form containing the Liberty document to the policy agent.

   The form is based upon the Action and the Javascript included in the Body tags onLoad.

7. The policy agent receives the document, extracts the session information, validates the session, and sets a session token in the cookie for the new DNS domain.

   For detailed information, see Session Validation.

8. The process continues with policy evaluation and results logging.

   See the following sections for detailed information.

   • Policy Evaluation and Enforcement

   • Logging Results

9. The policy agent allows or denies the user access to the application.

   1. If the user is denied access, the policy agent displays an “access denied” page.

   2. If the user is granted access, the resource displays its access page.

Assuming proper authorization, the policy agent responds to the user by presenting the travel administration application screen. This new cookie can now be used by all agents in the new domain, and the session is valid until it is terminated. (See Session Termination.)

Session Termination

A user session can be terminated in any of following ways:

• User Ends Session

• Administrator Ends Session

• Access Manager Enforces Timeout Rules

• Session Quota Constraints

User Ends Session

When a user explicitly logs out of Access Manager by clicking on a link to the Logout Service the following events occur:

1. The Logout Service receives the Logout request, and performs the following steps:

   1. Marks user’s session as destroyed.

   2. Destroys session.

   3. Returns a successful logout page to the user.

2. 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.

3. The policy agents flush the session from cache and the user session ends.

Administrator Ends Session

Access Manager administrators with appropriate permissions can terminate a user session at any time. When an administrator uses the Sessions tab in the Access Manager console to end a user’s session, the following events occur:

1. The Logout Service receives the Logout request, and performs the following steps:

   1. Marks user’s session as destroyed.

   2. Destroys session.

2. 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.

3. The policy agents flush the session from cache and the user session ends.

Access Manager Enforces Timeout Rules

When a session timeout limit is reached, the Session Service completes the following steps:

1. Changes session status to invalid.

2. Displays time-out message to user.

3. Starts timer for purge operation delay (default is 60 minutes).

4. When purge operation delay time is reached, purges or destroys the session.

5. If a session validation request comes in after the purge delay time is reached, displays login page to user.

Session Quota Constraints

Access Manager 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.