Programming Guides › Programming Guide for Java › Agent API Guidance for C › Single Sign-on

Single Sign-on

In a single sign-on environment, a user who successfully authenticates through a given agent does not have to re-authenticate when accessing a realm protected by a different agent. When a custom agent is involved in a single sign-on environment, the two agents must be in the same cookie domain—for example, xxx.domainname.com.

Single sign-on is made possible through a single sign-on cookie named SMSESSION. This cookie is created and written to the user’s browser either by SiteMinder or by the custom agent.

Class AgentAPI contains two methods that allow custom agents to participate in a single sign-on environment with standard SiteMinder Web Agents:

decodeSSOToken()

The custom agent extracts the cookie’s contents, called a token, from an existing SMSESSION cookie and passes the token to this method. The method decrypts the token and extracts the specified information. This method can also be used to update the last-access timestamp in the token.

createSSOToken()

After the user successfully logs in through the custom agent, the custom agent passes information about the user to this method. The method creates an encrypted token from this user information and from session information returned from the login call. The custom agent writes the token to the SMSESSION cookie.

See the sample custom agent code for an example of setting up the parameters for the single sign-on methods and parsing the results. The sample custom agent code is located in the smjavaagentapi directory of <install_path>\sdk\samples.

Log on through a Custom Agent

Here is the typical sequence of events in a single sign-on environment when the initial login is through the custom agent:

1. User logs in through the custom agent.
2. Custom agent calls login() to authenticate the user. The user is challenged for credentials.
3. Custom agent calls createSSOToken() and passes to it information about the user (user name, user DN, IP address of the requesting client). SiteMinder adds this information to a token along with session information returned from the login call. SiteMinder also encrypts the information in the token.
4. Custom agent creates the SMSESSION cookie in the user’s browser and writes the token to the cookie.
5. User requests a resource protected by a standard SiteMinder agent.
6. The standard agent performs a login operation, which validates the user based on the information in the single sign-on cookie. The user is not challenged for credentials.

Log on through a Standard Agent

Here is the typical sequence of events that occurs in a single sign-on environment when the initial login is performed through the standard SiteMinder Web Agent:

1. User logs in through the standard agent.
2. Standard agent authenticates the user by challenging the user for credentials through the login call.
3. SiteMinder creates the SMSESSION cookie in the user’s browser and inserts the encrypted token containing session information.
4. User requests a resource protected by a custom agent.
5. The custom agent obtains the SMSESSION cookie from the user’s request and extracts the token.
6. The custom agent passes the token to the method decodeSSOToken(). The method decodes the token and returns a subset of the token’s attributes to the custom agent.
7. The custom agent obtains the session specification from the token and passes the session specification to login(). The login call validates the user without challenging the user for credentials.
8. User requests a resource protected by a standard SiteMinder agent.
9. The standard agent performs a login operation, which validates the user based on the contents of the SMSESSION cookie. The user is not challenged for credentials.

Standard Agent Support

Custom agents created with the SiteMinder SDK v6.x can accept SMSESSION cookies created by a standard SiteMinder v4.x, v5.x, or v6.x Web Agent. However, standard SiteMinder v4.x or v5.x Web Agents can only accept cookies created by a custom agent if the standard agent has been upgraded with the appropriate Siteminder Agent Quarterly Maintenance Release (QMR). For information about the QMR version required for each standard agent version, see the accompanying SDK release notes.

To enable a SiteMinder v4.x or v5.x agent with the appropriate QMR upgrade to accept SMSESSION cookies created by a custom agent, the standard agent’s Agent configuration file (LocalConfig.conf with IIS servers or WebAgent.conf with other servers) or central configuration object (for v5.x or higher) must contain the following entry:

AcceptTPCookie="yes"

Set AcceptTPCookie as follows:

• With 4.xQMR4 agents and above, add AcceptTPCookie="yes" directly in the standard agent’s Agent configuration file.
• With 5.xQMR1 agents and above, add the entry to the standard agent’s Agent Configuration Object if the AllowLocalConfig parameter for that object is set to no. If AllowLocalConfig is set to yes, you can set AcceptTPCookie in the standard agent’s Agent configuration file.

How Information Is Bound to a Session

Session information can consist of more than the session specification. Session information can include any information that the client application wants to associate with the user’s session.

Application-defined session information consists of name/value pairs called session variables. For example, business logic, certificate information, and SAML assertions for affiliate operations can all be stored as session variables and bound to the session ID.

The class AgentAPI provides the following methods for setting, retrieving, and deleting session variables:

• setSessionVariables()
• getSessionVariables()
• delSessionVariables()

Session variables are stored in a server-side database called the session store. The session store is managed by the Policy Server.

Advantages of Session Variables

When a client application uses session variables:

• Up to 4K of data can be stored for each session variable value.
• The session information persists across multiple Policy Servers. Centralizing session information on the server allows features such as cross-domain session management, including enforcing logout and idle timeout across different domains.

Requirements for Using Session Variables

For a client application to use session variables, both of the following prerequisites must be met:

• The session store must be enabled in the Policy Server Management Console.
• During realm configuration in the Policy Server UI, Persistent Session must be selected for at least one of the realms to be accessed during the session. As soon as the user accesses a realm configured for persistent sessions, session variables can be used throughout the remainder of the session.

End of Session Cleanup

When the user logs out and the agent discards the session specification, the session ends. In the case of a persistent session, SiteMinder removes all session information, including any session variables, from the session store.