Programming Guides › Programming Guide for Perl › Agent API

Agent API

This section contains the following topics:

About Agents and the Agent API

Write a Script against the Agent API

Single Sign-on and the Agent API

Session Information

Objects and the Object Hierarchy

About Agents and the Agent API

A SiteMinder agent enforces access control policies provided by the Policy Server.

Agents act as gate keepers that protect resources from unauthorized users. When a user issues a request for a resource, the request is routed through the agent. The agent determines whether to accept or reject the request based on the information it receives from the Policy Server.

The Agent API (module Netegrity::AgentAPI) lets you write scripts that test the operation of your agents. The tasks you can perform with the Agent API include many of the tasks you can perform with the SiteMinder Test Tool. The Agent API also lets you view information about the user’s session.

The following illustration shows some of the operations you can perform with the Agent API:

Write a Script against the Agent API

All scripts require certain common basic steps.

To write a script against the Agent API

1. Reference the Agent API at the beginning of your script:
2. Use the New() method to create an Agent API object:

   $agentapi=Netegrity::AgentAPI‑>New("agtName","shrdScrt");
   

   Note: Specifying the shared secret in the second argument creates a v4.x agent. Omitting the shared secret creates a v5.x or 6.x agent.

3. Provide configuration information about the Policy Server. The IP address is required, but you can accept the defaults for other arguments:

   $serverconfig = $agentapi‑>AddServerConfig($ipAddr);
   

4. Connect to the Policy Server:
   • With v4.x agents:

     $agentapi‑>Connect();
     

   • With v5.x and later agents:

     $agentapi‑>Connect("../../../../Program Files/Netegrity/webagent/config/smhost.conf");
     

Example: Verify the protection on a resource

After you have completed these basic steps, you can perform various agent operations. For example, you can see whether a specified resource is protected by the agent, and if so, you can find out the credentials that are required to access the resource:

$resource = $agentapi‑>GetResource("/companyXYZ/private/");
if($resource‑>IsProtected() == SM_AGENTAPI_YES) {
   print "\nAuthentication Type: ".$resource‑>GetAuthType();
}
else {
   print "The resource is not protected.";
}

Single Sign-on and the Agent API

In a single sign-on environment, a user who successfully authenticates through a given agent does not need 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 cookie’s contents are retrieved from and written to the cookie in encrypted string form. The encrypted string is called a token.

The Agent API contains the following methods that allow custom agent scripts to share token information with standard SiteMinder Web Agents:

• CreateSSOToken(). After the user successfully logs in, the custom agent script passes information about the user to this method. The method creates a single sign-on token object from this user information and from session information returned from the login call.
• GetString(). After creating a token object, the custom agent script calls GetString() to retrieve the token as an encrypted string. The script then writes the token string to the SMSESSION cookie.
• Decode(). This method decrypts the token for the current token object and extracts the specified information. This method can also be used to update the last-access timestamp in the token.
• GetVersion(). Retrieves the SiteMinder version of the current token object.
• IsThirdParty(). Specifies whether the current token object was created by a custom (third-party) agent or a standard SiteMinder agent.

Single Sign-on Support for Custom Agents

You can create a single sign-on object when logging in through a custom agent, not when logging in through a standard SiteMinder Web Agent.

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

• User logs in through the custom agent script.
• Custom agent script calls Login() to authenticate the user. The user is challenged for credentials.
• Custom agent script 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 object along with session information returned from the login call. SiteMinder also encrypts the information in the token.
• Custom agent script calls GetString() to retrieve the token information in encrypted string form.
• Custom agent script creates the SMSESSION cookie in the user’s browser and writes the token string to the cookie.
• User requests a resource protected by a standard SiteMinder agent.
• 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.

Single Sign-on Support for Standard Agents

Custom agent scripts created with the Perl Agent API 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 SDK Release Notes.

To enable a SiteMinder agent with the appropriate QMR upgrade to accept SMSESSION cookies created by a custom agent, the 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"

Session Information

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 package AgentSession provides the following methods for setting, retrieving, and deleting session variables, and for defining the parameters list:

• SetVariables()
• GetVariables()
• DelVariables()
• AddParameter()

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 4 KB of data can be stored for each session variable value.
• The session information persists across multiple Policy Servers. Centralizing session information about the server allows features such as cross-domain session management, including enforcing logout and idle timeout across different domains.

SiteMinder Support

The Command Line Interface supports:

• SiteMinder v4.x and v5.x agents running against SiteMinder v5.x Policy Servers
• SiteMinder v4.x and later agents agents running against SiteMinder v6.x Policy Servers.

The Agent API can be accessed on the machine where a SiteMinder Policy Server is installed. The Agent API can access the local Policy Server or a remote Policy Server.

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, the session ends. In the case of a persistent session, SiteMinder removes all session information, including any session variables, from the session store.

Objects and the Object Hierarchy

The Agent API contains a set of objects that let you perform agent operations.

The objects in the Agent API are hierarchical. Before an object can be used, it must be created or retrieved by a method in another object.

The following hierarchy shows the objects in the Agent API. Use it to find the methods in higher-level objects that create or retrieve other objects. For example, if you need an AgentResource object, refer to the object directly above it (AgentAPI) and choose the appropriate method.

AgentAPI

AgentResource

AgentResponseAttr

AgentSvrCfg

AgentUser

AgentResponse

AgentResponseAttr

AgentSession

AgentResponseAttr

SSOToken