Chapter 2 User Session Management and Single Sign-On

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.

This chapter contains the following sections:

• Overview of Access Manager User Sessions

• Cookies and Session Objects

• Policy Agents

• Basic User Session

• Single Sign-On Session

• Cross-Domain Single Sign-On Session

• Session Termination

Overview of Access Manager User Sessions

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.

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. Access Manager then allows the user access to the application.

In the same user session (without logging out of the health benefits application), the same employee attempts to access the corporate expense reporting application. The expense reporting application is also protected by Access Manager. In this second transaction, the Access Manager 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 service 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).

Cookies and Session Objects

The Session Service uses cookies and creates session objects to store information about a user session. In an Access Manager user session, session service is most commonly used to enforce timeout limits. For example, you can use session service to configure the Access Manager application so that the user is automatically logged out after x minutes of Access Manager inactivity. The session service can also be used to store additional information to be used by other applications.

Cookies Store User Information

A cookie is an information packet generated by a web server and passed to a web browser. The cookie maintains information about the user’s interactions with the web server that generated the cookie. For example, a web server can generate a cookie containing information a web browser needs to display a page according to the user’s preferences for language or layout.

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 stores information about the user.

Cookies are domain-specific. For example, a cookie generated by a web server within DomainA cannot be used by a web server in DomainB. 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.

Objects in the Session Data Structure

When a user logs in and is successfully authenticated, or verified to be who the user says he is, the user is assigned a session. A session is a data structure that contains maximum timeout limits and information about caching time limits. 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 sessionID is known to a protected resource such as an application, the application can access the session and all user information contained in it.

Minimally, an Access Manager session data structure 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.

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 the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.

Policy Agents

Policy agents 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 the request to Access Manager authentication service. The policy agent also enforces the user’s assigned policies. Policy agents are an integral part of SSO and CDSSO sessions.

Access Manager supports two types of policy agents:

• Web agent– Enforces URL-based policy for C applications.

• 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 comprehensive information about policy agents and how to install them, see the Web Policy Agent GuideSun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Web Server 6.1 and J2EE Policy Agent GuideSun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Application Server 8.1.

Basic User Session

When Access Manager policy agents are implemented, by default all HTTP requests are implicitly denied unless explicitly allowed by the presence of two things: 1) a valid session, and 2) policy allowing access. You can modify the default configuration so that Access Manger implicitly allows access unless explicitly denied. For detailed information on configuring Session Service, see The Current Sessions Interface in Sun Java System Access Manager 7 2005Q4 Administration Guide.

The following sections describe 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

• Results Logging

• Session Termination

Initial HTTP Request

A user initiates a user session by using a browser to log in to a web—based application.

Figure 2–1 Initial HTTP Request

The following events occur:

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

2. The policy agent inspects the user’s request, and no session token is found.

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, or data structure, and generates a session token. The session token is a randomly-generated string that represents the user.

6. Authentication Service sets the session data structure 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 following events occur.

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

2. 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 through 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. Authentication Service determines which presentation callbacks should be presented, and sends to the Distributed Authentication User Interface all necessary credentials, requirements, and callbacks to be in used the presentation framework layer.

4. 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, Authentication Service verifies that the username and password provided exist in the LDAP directory. Other authentication module types have different requirements.

10. When authentication is successful, Authentication Service activates the session by calling the appropriate methods in the Session Service.

    Authentication Service stores information such as Login time, Authentication Scheme, and Authentication Level in the session data structure.

11. Once the session is activated, 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. The browser makes a request to the originally requested resource protected by an Agent.

This time, the request includes the valid session data structure and session token that were 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 mail server for a second time, the following events occur.

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

Figure 2–2 Session Validation

Policy Evaluation

Once a session token has been validated, the policy agent determines if the user can be granted access to the mail server. The following events occur.

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, then Policy Service evaluates conditions of each policy. For example, Is it the right time of day? Are requests coming from the correct network?

      • If conditions are met, the policy applies.

      • If conditions are not met, the policy is skipped.

4. Policy service aggregates all policies that apply, and encodes a final decision to grant or deny access.

5. Policy Services responds to the policy agent with the appropriate decision.

   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.

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

Results Logging

When the policy agent receives an allow decision from the Policy Service, the following events occur.

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 the user access to the application.

   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, then 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 and its session token is validated, and in which the user is authenticated. For detailed information, see Basic User Session.

SSO begins occurs 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 (from Basic User Session) accesses a second application, an expense reporting application. Session Service maintains user session information with input from all applications participating in the single sign-on. In this example, session service maintains information from the benefits administration and the expense reporting application. The following events occur.

Figure 2–5 Single Sign-On Session

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

   Both the expense reporting application and the benefits administration application from section Basic User Session are hosted by 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. The user was authenticated when the user logged in to the benefits administration application, so authentication service is not required at this time. The SSO APIs retrieve the session data structure, which is known to SSO APIs as the SSOToken. The session token, or session ID, is known to SSO APIs 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.

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

7. If the SSOToken is valid, 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.

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

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

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

    1. The Logging Service logs this 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.

11. If Policy Service finds policy allowing access to the protected resource, the user is granted access to the protected resource.

    The SSO session is valid until it is terminated. Session Termination.

    While the user is still logged in, if the user decides to attempt to log in to another protected resource located in a different DNS domain, then CDSSO 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 benefits administration application supplied to his company by an external company. The benefits administration application is hosted on the external company’s DNS domain.

The CDSSO servlet within Access Manager transfers the user’s SSOToken into the external DNS domain, making the SSOToken usable for applications in this second domain. The CDSSO Controller Service uses Liberty Protocols to transfer sessions between domains.

When the user logs in to the benefits administration application in the external DNS domain, the following events occur.

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

2. The policy agent intercepts the request and inspects it to determine if a session token or SSOToken exists.

3. If a session token or SSOToken is present, the policy agent validates the session.

   In this example, the SSOToken is present. See Session Validation, then skip to Cross-Domain Single Sign-On Session.

4. If no session token or SSO token is present, the policy agent sends the HTTP request to the CDSSO Controller Service.

   The send includes the relevant Liberty parameters.

   

5. The user’s browser allows the redirect.

   This time the request contains the SSOToken. Recall that earlier in the user session (see Single Sign-On Session), the SSOToken was set in a cookie in the primary domain.

6. The CDC Servlet receives the SSOToken, and replies to the browser with a Liberty Post Profile response that includes user session information.

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

   2. The policy agent receives the Liberty document and extracts the user session information.

7. The policy agent validates the SSOtoken.

   For detailed information, see Session Validation.

8. The policy service examines policies.

   For detailed information, see Policy Evaluation.

9. The policy agent allows or denies access to the requested resource.

   For detailed steps, see Results Logging. In this case, the session token was determined to be valid, and the user is allowed access.

10. The policy agent responds to the user by presenting the benefits administration application screen.

11. The policy agent sets the SSOToken in a cookie for the new DNS domain.

    The cookie can now be used by all agents in the new domain.

    The CDSSO session is valid until it is terminated.

Session Termination

A user session can be terminated in one of three ways:

• User ends the session.

• Administrator ends the session.

• Access Manager enforces timeout rules.

User Ends Session

When a user explicitly logs out of Access Manager the following events occur:

1. The user logs out by clicking on a link to the Logout Service.

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

   1. Marks user’s session as destroyed.

   2. Destroys session.

   3. Returns a successful logout page to the user.

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

4. 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 ends a session, the following events occur:

1. The administrator uses Sessions tab in the Access Manager console to end the user’s session.

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

   1. Marks user’s session as destroyed.

   2. Destroys session.

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

4. 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, 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.