Programming Guides › Programming Guide for C › Agent API › 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.