Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Custom Agents and Single Sign-On

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

The Agent API contains two functions that allow custom agents to participate in a single sign-on environment with standard SiteMinder Web Agents:

• Sm_AgentApi_DecodeSSOToken(). The custom agent extracts the cookie’s contents, called a token, from an existing SMSESSION cookie and passes the token to this function. The function decrypts the token and extracts the specified information. This function can also be used to update the last-access timestamp in the token.
• Sm_AgentApi_CreateSSOToken(). After the user successfully logs in through the custom agent, the custom agent passes information about the user to this function. The function 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 functions and parsing the results. The sample custom agent code is located in the smagentapi directory of <install_path>\sdk\samples.

Standard Agent Support

Custom agents created with SiteMinder SDK v5.5 SPx and later can accept SMSESSION cookies created by a standard SiteMinder Web Agent.

However, standard SiteMinder 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.

In addition, to enable a SiteMinder 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 later) 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 later, 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.

Login 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 Sm_AgentApi_Login() to authenticate the user. The user is challenged for credentials.
3. Custom agent calls Sm_AgentApi_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.

Login Through a Standard Agent

Here is the typical sequence of events in a single sign-on environment when the initial login is 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 function Sm_AgentApi_DecodeSSOToken(). The function 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 Sm_AgentApi_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.