Custom Agents and Single Sign-On
Contents
casso10
Contents
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
CA Single Sign-On
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
CA Single Sign-On
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
CA Single Sign-On
SDK v5.5 SPx and later can accept SMSESSION cookies created by a standard CA Single Sign-On
Web Agent.However, standard
CA Single Sign-On
Web Agents can only accept cookies created by a custom agent if the standard agent has been upgraded with the appropriate CA Single Sign-On
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
CA Single Sign-On
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:
- User logs in through the custom agent.
- Custom agent calls Sm_AgentApi_Login() to authenticate the user. The user is challenged for credentials.
- Custom agent calls Sm_AgentApi_CreateSSOToken() and passes to it information about the user (user name, user DN, IP address of the requesting client).CA Single Sign-Onadds this information to a token along with session information returned from the login call.CA Single Sign-Onalso encrypts the information in the token.
- Custom agent creates the SMSESSION cookie in the user’s browser and writes the token to the cookie.
- User requests a resource protected by a standardCA Single Sign-Onagent.
- 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
CA Single Sign-On
Web Agent:- User logs in through the standard agent.
- Standard agent authenticates the user by challenging the user for credentials through the login call.
- CA Single Sign-Oncreates the SMSESSION cookie in the user’s browser and inserts the encrypted token containing session information.
- User requests a resource protected by a custom agent.
- The custom agent obtains the SMSESSION cookie from the user’s request and extracts the token.
- 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.
- 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.
- User requests a resource protected by a standardCA Single Sign-Onagent.
- 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.