Previous Topic: Perl Scripting OverviewNext Topic: CLI Agent API Methods


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:

Illustration showing some of the Agent API operations

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:

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:

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:

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:

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:

SiteMinder Support

The Command Line Interface supports:

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:

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