Programming Guides › Programming Guide for C › Agent API

Agent API

This section contains the following topics:

Agent API Overview

About the SiteMinder Agent

Agent Initialization

How to Access a Resource Using the Agent API

Compile and Link a Custom Agent

Central Host Configuration

Agent Call Sequence

Sample Custom Agent

Agent API Services

Response Attributes

Custom Agents and Single Sign-On

Memory Deallocation

Data Types and Structures

Function Declarations

Agent API Overview

The Agent API works with the Policy Server to simplify application development and make applications more scalable. Developers creating applications that are built using the Agent API either directly or indirectly (through another agent) are shielded from the following implementation-specific details:

• User namespaces such as LDAP directories, SQL databases, or NT domains
• Authentication methods as simple as user name and password, or as complex as PKI systems
• Authorizations based on group membership, or individual profile data

Additional benefits provided by the Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.

About the SiteMinder Agent

A SiteMinder Agent is a client of the Agent API. The agent enforces access control policies provided by the Policy Server. The Policy Server is a general-purpose policy engine with no information about resources. Agents establish resource semantics and act as gate keepers to protect resources from unauthorized users.

Different agent types protect different kinds of resources. Some agent types are pre-defined, standard agents that are shipped as part of the SiteMinder product—for example, the Web Agent, which provides HTTP access control for Web Servers. You can also use the Agent API to implement custom agents.

When you create an application using the Agent API, you can create a custom agent to authenticate and authorize users in a variety of ways, depending on the context. For example, you could create an agent for FTP transfers that implements the following functionality:

• Certificate-based authentication instead of basic name and password credentials
• Uploads and downloads based on an individual user’s authorization level

When you build a custom agent with the SDK, you must run the custom agent against the version of the SiteMinder Policy Server that corresponds to the version of the SDK.

Agent Initialization

Before an agent can perform work on behalf of its users, it must initialize connections to one or more Policy Servers by calling Sm_AgentApi_Init(). Calling Sm_AgentApi_Init() lets you specify connection parameters such as failover mode and connection pool size. This call creates TCP connections and typically does not need to be done more than once per agent instance.

It is possible to initialize more than one API instance (for example, when working with Policy Servers that use separate policy stores).

Immediately after initialization, the agent should communicate its version information to the Policy Server by calling Sm_AgentApi_DoManagement() with the command SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO set in the structure Sm_AgentApi_ManagementContext_t. The actual information can be any string containing enough information about the agent, such as the build number and version number. The string is recorded in the Policy Server logs.

How to Access a Resource Using the Agent API

After the Agent API has been initialized, the agent can start accepting requests from its users, such as receiving GET requests for URLs.

The following steps describe what is required for an agent to grant access to a resource. The outcome of most steps can be cached to improve agent performance. The agent can choose to cache as little as possible or as much as possible.

To grant user access to a resource

1. Accept a user request to access a resource. This is the application-specific request. For example, the Web Agent can accept a user’s GET request for a URL.
2. Determine if the requested resource is protected by calling Sm_AgentApi_IsProtected(). If the resource is protected, the Policy Server returns the required credentials that must be obtained from the user to validate the user’s identity. If the resource is not protected, access to the requested resource should be allowed. The outcome of this step can be cached.

   Collect the required credentials from the user and authenticate the user by calling Sm_AgentApi_Login(). After successful authentication, the Policy Server creates a session and returns response attributes including the unique session ID and session specification. These response attributes are policy driven and may include user profile data, static or dynamic privileges, a number of pre-defined authentication state attributes, or any other data that was designated by a policy administrator.
   The agent can now perform session management by caching user session information and keeping track of session expiration.

3. Validate that the user has access to the requested resource by calling Sm_AgentApi_Authorize(). After successful authorization, the Policy Server returns response attributes, including resource-specific privileges. These response attributes are policy driven and can include user profile data, static or dynamic privileges or any other data that was designated by a policy administrator. The user’s authorization information for the requested resource is available and can be cached to speed up future requests.
4. (Optional) Log the transactions for authentication and authorization by calling Sm_AgentApi_Audit() if the agent performs authorizations out of its cache.
5. Allow the user to access the resource when the user’s identity is known, authorization has been verified and the required entitlements obtained.
6. (Optional) Issue a management request by calling Sm_AgentApi_DoManagement(). This is an optional step that is used to poll the Policy Server for update commands. In response to a command, agents can update encryption keys or flush caches.
7. Release all API instances by calling Sm_AgentApi_UnInit() for each API instance. This closes TCP connections to all Policy Servers.

The Agent API does not provide a facility for caching in a manner that enforces session validity. By choosing to cache user sessions or resource-specific privileges, the agent becomes obligated to perform its own session management during each user request, because caching on the agent removes the need to contact the Policy Server to perform session validation or resource authorizations or both.

Compile and Link a Custom Agent

To enable your custom agent to interact with SiteMinder, compile your agent application with SmAgentAPI.h and link to the platform-specific library listed following. On UNIX platforms you must add the library to the environment variable that specifies the library search path. The variable takes a colon-separated list of directories and are also listed following.

Note: If you are building the agent API application using Microsoft Visual C++, make sure you link with ws2_32.lib.

Central Host Configuration

SiteMinder agents, including custom agents, connect to a Policy Server through the Agent API. SiteMinder recognizes two different types of agents, based on the way that connection parameters are provided:

• v4.x agents. Connection parameters required to connect to a Policy Server are agent-specific. They include the agent’s name, the name or IP address of the host machine where the agent resides, and the shared secret. These parameters are provided when you define an agent object on the Policy Server. Connection parameters defined for a v4.x agent apply to that agent only.
• v5.x and later agents. Connection parameters required to connect to the Policy Server can apply to multiple agents on the host machine where the agents reside. With v5.x and later agents, the host machine is called a trusted host.

  The information required to initialize the connection to a Policy Server is stored in an SmHost.conf file on the host machine. Additional information that determines how the Policy Server interacts with its agents is defined on the Policy Server in a host configuration object.

  Host configuration object parameters (such as failover and clustering instructions) apply to all agents associated with the host configuration object. They are centrally managed in the Administrative UI.

Custom v5.x and later agents support central host configuration (which determines the way a Policy Server and its agents interact), but not central agent configuration (which determines the way an agent operates). You cannot define an agent configuration object for a custom agent in the Policy Server. Configuration parameters for the operation of a custom agent are defined in the WebAgent.conf file (or in the case of IIS 6.0 agents, in the LocalConfig.conf file).

Configuration Requirements

To configure a custom agent through a host configuration object on the Policy Server, you must complete the following steps:

1. Register the client machine where the agent resides as a trusted host.

   You register a trusted host with the smreghost tool. This tool is installed in directory <install_path>/sdk/bin.

   Registering a trusted host creates the following items:

   • A host configuration object on the Policy Server. The host configuration object can be modified in the Administrative UI at any time.
   • The file SmHost.conf on the client. This file includes the parameter hostconfigobject, which references the host configuration object on the Policy Server.

     The information in SmHost.conf is used to initialize the connection between the Policy Server and its agents, through the Agent API. Once the connection is initialized, the information in the host configuration object determines how the Policy Server and its agents interact.

2. Define an agent object on the Policy Server.

   An agent object establishes a unique identity for your custom agent by defining a name and other information that is specific to your custom agent.

   The name assigned to the custom agent must match the name that the custom agent passes programmatically to SiteMinder.

Code Requirements

For a custom agent to be configured through a central host configuration object on the Policy Server, the agent must do the following:

• Initialize agent configuration through Sm_AgentApi_GetConfig().

  This function lets you pass to SiteMinder the name and path of the SmHost.conf file that resides on the trusted host. This file references the host configuration object on the Policy Server.

  Alternatively, you can pass the name and path of the WebAgent.conf file if it contains a reference to SmHost.conf.

  After the trusted host connects to the Policy Server, the interaction between the Policy Server and the agents on the trusted host is determined by the host configuration object on the Policy Server.

  Note: When you call Sm_AgentApi_GetConfig(), SiteMinder populates the Sm_AgentApi_Init_t structure. With central host configuration, you do not populate the structure directly.

• Pass the agent’s name through Sm_AgentApi_SetDefaultAgentId().

  The name that the custom agent passes to SiteMinder in this function must match the name of the agent object that establishes a unique identity for your custom agent on the Policy Server.

  Call Sm_AgentApi_SetDefaultAgentId() after calling Sm_AgentApi_Init() and before making any other Agent API calls. This allows you to specify your custom agent name to SiteMinder without sending the name with each transaction.

Upgrade an Agent

To upgrade an existing v4.x agent

1. If the host machine where the v4.x agent resides is not currently registered with the Policy Server as a trusted host, run smreghost to register it.

   Registration creates an SmHost.conf file on the trusted host and a host configuration object on the Policy Server.

2. Call Sm_AgentApi_GetConfig() to initialize the structure Sm_AgentApi_Init_t with the information in SmHost.conf.
3. Call Sm_AgentApi_Init() to connect to the Policy Server.
4. Call Sm_AgentApi_SetDefaultAgentId() to set the default name of the custom agent.

Agent Call Sequence

A custom agent usually calls Agent API functions in the in the following order:

Sm_AgentApi_GetConfig() // Required with central host configuration
Sm_AgentApi_Init()
Sm_AgentApi_SetAgentInstanceInfo() For agent discovery (12.5 agents and later) 
Sm_AgentApi_SetDefaultAgentId() // Central host configuration only
Sm_AgentApi_DoManagement()
Sm_AgentApi_IsProtected()
Sm_AgentApi_Login()
Sm_AgentApi_Authorize()
// . . .

// Call other Agent API functions here, including
// periodic calling of Sm_AgentApi_DoManagement()

Sm_AgentApi_Logout()
Sm_AgentApi_Uninit()

Sample Custom Agent

Sample source code for the Agent API is provided in smagentexample.cpp. This file is installed in <install_path>/sdk/samples/smagentapi.

The Agent API sample can connect to the Policy Server as a v5.x or later agent (using central host configuration). When you run the sample, you are prompted to select the Agent Interface (v4.x-type or v5.x-type) before initializing the connection.

Agent API Services

The Agent API provides a rich set of services that let you develop sophisticated, secure, and robust agents. Building an agent involves using these services:

• Session Services
• Authorization Services
• Auditing Services
• Management Services (key encryption, cache updates)
• Tunnel Services

Session Services

A session is created after a successful user login. Once created, a user session persists until it is terminated. To maintain consistent user sessions in a multi-tiered application environment, a user session specification is maintained by the Web Agent (not the Policy Server). The session specification is also called the session ticket. The session specification represents a user session and is the key to SiteMinder Session Management. The environment in which the user session was created is responsible for persistent storage of the session specification. For example, the Web Agent (HTTP environment) stores the session specification in an HTTP cookie.

SiteMinder’s universal ID is integrated with the sessioning mechanism. A universal ID identifies the user to an application in a SiteMinder environment using a unique identifier, such as a customer account number. The universal ID facilitates identification of users between old and new applications by delivering the user’s identification automatically, regardless of the application. When configured on the Policy Server, a user’s universal id is part of the session specification and is made available to agents for the duration of the entire session.

Agents create sessions using Sm_AgentApi_Login(). This function authenticates the user credentials and returns the session specification and unique session id in Sm_AgentApi_Session_t. The session specification is updated on subsequent Agent API calls that also return the updated expiration times. Agents can use this information to perform custom session management and keep track of session timeouts.

If your Web server’s user tracking feature is enabled, SiteMinder issues an identity ticket in addition to the session specification. Identity tickets can be used for identity-based personalization when a user is accessing a resource protected by anonymous authentication schemes. Identity tickets never expire.

When an application’s logic flow crosses application tiers, sessions can be delegated by passing the session specification between two agents. Each agent can choose to have the session specification validated.

The session specification is validated to make sure that a user session has neither expired nor been terminated or revoked. This can occur at any time during the session’s lifetime. Agents call Sm_AgentApi_Login() to validate a session specification.

A session is terminated after a user logs out and the agent discards the session specification, when the session expires, or when the session is revoked. When a session is terminated, the user must log in again to establish a new session.

You should terminate a session if a user is disabled after a session has begun. To find a user's disabled state, call Sm_AgentApi_Login() to validate the session.

To terminate a session, the agent calls Sm_AgetnApi_Logout(). Note that any memory allocated for the session specification (Sm_AgentApi_Session_t) must be deallocated.

Application 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 Agent API provides the following functions for setting, retrieving, and deleting session variables:

• Sm_AgentApi_SetSessionVariables()
• Sm_AgentApi_GetSessionVariables()
• Sm_AgentApi_DelSessionVariables()

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

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

Timeouts

Agents can enforce session timeouts themselves or rely on the Policy Server to validate each request. Typically, caching of user sessions or privileges by the agent requires some form of timeout enforcement on the agent side. In this case, the agent is responsible for keeping track of the last access time and knowing when the session is going to expire.

Agents that do not cache can leverage the Policy Server’s enforcement of timeouts. The following Agent API methods return the updated timeout information after every call:

• Sm_AgentApi_Login()
• Sm_AgentApi_Authorize()
• Sm_AgentApi_Audit()

Authorization Services

Agents that perform access control functions use authorization services of the Agent API. These services enable clients to determine what access control is imposed on resources, verify users rights to access resources, and retrieve users privileges for specific resources.

Whether a resource is protected can be determined by calling the Sm_AgentApi_IsProtected() method. This method accepts a resource that is served by the requesting agent, and returns information about the credentials required for authentication.

After the user’s identity has been validated, agents call the Sm_AgentApi_Authorize() method to determine if the requesting user has access to the requested resource. Agents can perform fine-grained access control by testing the values of the response attributes returned by this method.

Transaction Tracking

A facility is provided for agents to keep track of all user activity during a session. Although much of the activity is logged by the Policy Server, there are times when it may be necessary to log authorizations done out of agent cache. Agents can call the Sm_AgentApi_Audit() method to log requests for resources.

By generating a unique transaction id, agents can correlate access control activity with application activity. The transaction id can be given to both the authorization and auditing methods so that the Policy Server would record the transaction-specific id associated with the application activity. This can be used for non-repudiation.

Management Services

A management protocol exists between agents and the Policy Server. This protocol helps agents manage its caches and encryption keys in a manner consistent with policies and administrative changes on the Policy Server.

Cache Commands

Agents issue the Sm_AgentApi_DoManagement() call with the SM_AGENTAPI_MANAGEMENT_GET_AGENT_COMMANDS command to request the latest agent commands. Typically, this is done every N seconds by a thread running in the background. The types of agent commands that can be received are cache commands and encryption commands.

Cache commands inform the agent of any changes to its caches that may need to be made as a result of administrative updates to the Policy Server. These agent commands are:

• SM_AGENTAPI_CACHE_FLUSH_ALL
• SM_AGENTAPI_CACHE_FLUSH_ALL_USERS
• SM_AGENTAPI_CACHE_FLUSH_THIS_USER
• SM_AGENTAPI_CACHE_FLUSH_ALL_REALMS
• SM_AGENTAPI_CACHE_FLUSH_THIS_REALM

Encryption commands

Encryption commands inform the agent of new encryption keys that are generated automatically by the Policy Server or administratively. Agents that need to save secure state can leverage this protocol to keep track of the latest encryption keys. These agent commands are:

• SM_AGENTAPI_AGENT_KEY_UPDATE_NEXT
• SM_AGENTAPI_AGENT_KEY_UPDATE_LAST
• SM_AGENTAPI_AGENT_KEY_UPDATE_CURRENT
• SM_AGENTAPI_AGENT_KEY_UPDATE_PERSISTENT

Tunnel Services

Tunnel services enable agents to establish secure communications with a callable service located on the Policy Server. This allows agents to perform custom actions over a secure, VPN-like channel without having to deal with issues such as encryption and key management.

Response Attributes

Response attributes enable the Policy Server to deliver information to agents. There are two types of attributes:

• Well-known attributes
• Policy-based attributes

Well-known attributes are always returned by the Policy Server after certain calls, such as Sm_AgentApi_Login(). These attributes represent static, fixed data such as the user DN and Universal ID.

Policy-based attributes are returned by Sm_AgentApi_Login() and Sm_AgentApi_Authorize(). These attributes are based on policies and are the vehicle for delivering static and dynamic data from the Policy Server to agents, so that the agents can distinguish between authentication and authorization attributes. The actual source of the data is defined on the Policy Server using the responses feature that can be configured to deliver data from a variety of sources. Data may include static information, information from a directory profile or a custom Policy Server plug-in. When the responses are properly configured, agents are capable of performing fine-grained access control as well as profile-driven personalization.

Based on a policy definition, response attributes can time out or be cached for the duration of the user session. The Policy Server delivers an attribute along with the TTL (Time-To-Live) value, calculated in seconds. If the agent is caching user sessions or authorizations or both, it is responsible for keeping the relevant attributes up to date. Agents issue the Sm_AgentApi_UpdateAttributes() call to update stale attributes.

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.

Memory Deallocation

You must explicitly deallocate any memory that you allocate for your custom agent. To release the response attributes in the Sm_AgentApi_Attribute_t structure, call Sm_AgentApi_FreeAttributes().

More Information:

Sm_AgentApi_FreeAttributes()

Data Types and Structures

The following C-language structures are used in the Agent API:

• Sm_AgentApi_Attribute_t
• Sm_AgentApi_Init_t
• Sm_AgentApi_ManagementContext_t
• Sm_AgentApi_Realm_t
• Sm_AgentApi_ResourceContext_t
• Sm_AgentApi_Server_t
• Sm_AgentApi_Session_t
• Sm_AgentApi_TunnelServiceRequest_t
• Sm_AgentApi_UserCredentials_t

Note: Before you use a structure, all unused fields should be set to zero. The best way to do this is to set the entire structure to zero.

Sm_AgentApi_Attribute_t

This structure defines information about a response attribute.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_Attribute_s
{
   long nAttributeId;
   long nAttributeTTL;
   long nAttributeFlags;
   char lpszAttributeOid[SM_AGENTAPI_SIZE_OID];
   long nAttributeLen;
   char* lpszAttributeValue;
} Sm_AgentApi_Attribute_t;

Parameters

This structure has the following parameters:

nAttributeId

ID of the response attribute.

nAttributeTTL

The time-to-live value (in seconds) for the response attribute. The attribute remains in cache for the duration of the TTL value.

nAttributeFlags

Response attribute flag. This flag is used in the following session store functions:

• Sm_AgentApi_DelSessionVariables()
• Sm_AgentApi_GetSessionVariables()
• Sm_AgentApi_SetSessionVariables()

See the ppRespAttributes parameter of these functions for more information.

lpszAttributeOid

The response attribute object identifier.

nAttributeLen

The length of the response attribute.

lpszAttributeValue

The null-terminated attribute value of a response attribute.

Remarks

The following well-known authentication attributes are returned by Sm_AgentApi_Login() and referenced in the nAttributeId field of the Sm_AgentApi_Attribute_t structure:

SM_AGENTAPI_ATTR_AUTH_DIR_OID

The Siteminder object id of the directory where the user was authenticated. This is the internal object id assigned to the SiteMinder user directory.

SM_AGENTAPI_ATTR_AUTH_DIR_NAME

The SiteMinder "name" specification of the directory where the user was authenticated. This is the directory name specified in the SiteMinder User Directory Dialog.

SM_AGENTAPI_ATTR_AUTH_DIR_SERVER

The SiteMinder "server" specification of the directory where the user was authenticated. This is the directory server specified in the SiteMinder User Directory Dialog.

SM_AGENTAPI_ATTR_AUTH_DIR_NAMESPACE

The SiteMinder "namespace" specification of the directory where the user was authenticated. This is the directory namespace (LDAP:, ODBC:, WinNT:, AD:) as specified in the SiteMinder User Directory Dialog.

SM_AGENTAPI_ATTR_USERMSG

The text presented to the user as a result of authentication. Some authentication schemes supply challenge text or a reason why an authentication has failed. A value for this attribute can be provided through the lpszUserMsg parameter of SmAuthenticate().

SM_AGENTAPI_ATTR_USERDN

The user’s distinguished name as recognized by SiteMinder.

This attribute is also used in single sign-on operations.

SM_AGENTAPI_ATTR_USERUNIVERSALID

The user’s universal id, as set in the user directory.

SM_AGENTAPI_ATTR_IDENTITYSPEC

The user’s identity ticket. SiteMinder returns this if the user tracking feature has been enabled.

The following well-known attributes are used in single sign-on operations and referenced in the nAttributeId field of the Sm_AgentApi_Attribute_t structure:

SM_AGENTAPI_ATTR_USERDN

The user’s distinguished name.

SM_AGENTAPI_ATTR_SESSIONSPEC

The session specification returned from the login call.

SM_AGENTAPI_ATTR_SESSIONID

The session ID returned from the login call.

SM_AGENTAPI_ATTR_USERNAME

The user’s name.

SM_AGENTAPI_ATTR_CLIENTIP

The IP address of the machine where the user initiated a request for a protected resource.

SM_AGENTAPI_ATTR_DEVICENAME

The name of the agent that is decoding the token.

SM_AGENTAPI_ATTR_InnnnnDLESESSIONTIMEOUT

Maximum idle time for a session.

SM_AGENTAPI_ATTR_STARTSESSIONTIME

The time the session started after a successful login.

SM_AGENTAPI_ATTR_LASTSESSIONTIME

The time that the Policy Server was last accessed within the session.

The following well-known management attributes are returned by Sm_AgentApi_DoManagement() and referenced in the nAttributeId field of the Sm_AgentApi_Attribute_t structure:

SM_AGENTAPI_AFFILIATE_KEY_UPDATE

Instructs the agent to update the name of the affiliate agent.

SM_AGENTAPI_AGENT_KEY_UPDATE_NEXT

Instructs the agent to update its "next" Agent key. The value contains 24 bytes of binary data.

SM_AGENTAPI_AGENT_KEY_UPDATE_LAST

Instructs the agent to update its "last" Agent key. The value contains 24 bytes of binary data.

SM_AGENTAPI_AGENT_KEY_UPDATE_CURRENT

Instructs the agent to update its "current" Agent key. The value contains 24 bytes of binary data.

SM_AGENTAPI_AGENT_KEY_UPDATE_ PERSISTENT

Instructs the agent to update its static (persistent) Agent key. The value contains 24 bytes of binary data.

SM_AGENTAPI_CACHE_FLUSH_ALL

Instructs the agent to flush all information in its caches.

SM_AGENTAPI_CACHE_FLUSH_ALL_USERS

Instructs the agent to flush all user information stored in its caches.

SM_AGENTAPI_CACHE_FLUSH_THIS_USER

Instructs the agent to flush all cache information pertaining to a given user. The value contains the following: <user dir oid> / <user dn>.

SM_AGENTAPI_CACHE_FLUSH_ALL_REALMS

Instructs the agent to flush all resource information stored in its caches.

SM_AGENTAPI_CACHE_FLUSH_THIS_REALM

Instructs the agent to flush all resource information pertaining to a given realm. The value is a realm OID.

Sm_AgentApi_Init_t

This structure defines agent initialization, including its server information, and also specifies the failover threshold.

Syntax

This structure had the following format:

typedef struct Sm_AgentApi_Init_s
{
   long nVersion;
   char lpszHostName[SM_AGENTAPI_SIZE_NAME];
   char lpszSharedSecret[SM_AGENTAPI_SIZE_NAME];
   long nFailover;
   long nNumServers;
   Sm_AgentApi_Server_t* pServers;
} Sm_AgentApi_Init_t;

Parameters

This structure had the following parameters:

nVersion

The version of the Agent API. Set to SM_AGENTAPI_VERSION.

lpszHostName

The agent name. This name must match the agent name provided to the Policy Server. The agent name is not case sensitive.

lpszSharedSecret

Each agent has a shared secret registered with the Policy Server. Enter that secret here. This is a case sensitive field.

nFailover

Setting this to 0 enables the agent to access the specified Policy Servers in a round-robin configuration. Setting this to 1 disables the round-robin configuration, in which case the agent will operate in the failover mode.

nNumServers

The number of Policy Servers defined in the next parameter.

pServers

An array of nNumServers structures of type Sm_AgentApi_Server_t. This structure defines each identically configured Policy Server with which the agent will communicate. The servers must share a common policy store. Depending on the specified Agent API version the array contains either clustered or non-clustered servers.

Remarks

This structure is populated by calling Sm_AgentApi_GetConfig().

More Information:

Sm_AgentApi_GetConfig()

Central Host Configuration

Sm_AgentApi_ManagementContext_t

This structure defines Information about the management command.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_ManagementContext_t
{
   long nCommand;
   char lpszData[SM_AGENTAPI_SIZE_NAME];
} Sm_AgentApi_ManagementContext_t;

Parameters

This structure has the following parameters:

nCommand

One of these management commands:

• SM_AGENTAPI_MANAGEMENT_GET_AGENT_COMMANDS
  Requests the latest agent commands. With this command, lpszData should be left blank.
• SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO
  Provides information about the agent to the Policy Server. The information is contained in lpszData.

lpszData

When SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO is set, contains the following null-terminated string of information about the agent:

"Product=XXX,Platform=XXX,Version=XXX,Label=XXX"

Unknown clauses can be omitted.

This information is recorded by the Policy Server for logging and troubleshooting purposes.

Example:

"Product=WebAgent,Platform=NT/ISAPI,
         Version=5.0,Update=SP1,Label=C134"

The Agent API adds the crypto strength and agent time (in GMT) and time zone to this string.

If you want to log information about a custom agent, add the following lines of code to your custom agent definition:

ManagementContext.nCommand = SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO;
strncpy (ManagementContext.lpszData, version info goes here, 255);

Sm_AgentApi_Realm_t

This structure defines Information about the realm in which a resource is protected.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_Realm_s
{
   char lpszDomainOid[SM_AGENTAPI_SIZE_OID];
   char lpszRealmOid[SM_AGENTAPI_SIZE_OID];
   char lpszRealmName[SM_AGENTAPI_SIZE_NAME];
   long nRealmCredentials;
   char lpszFormLocation[SM_AGENTAPI_SIZE_URL];
} Sm_AgentApi_Realm_t;

Parameters

This structure has the following parameters:

lpszDomainOid

Unique identifier for the domain.

lpszRealmOid

Unique identifier for the realm.

lpszRealmName

Name of the realm in which the resource is protected.

nRealmCredentials

A bit mask of values indicating the required credentials. The values are defined in the Sm_Api_Credentials_t enumerated type (as defined in SmApi.h). The value 0 means that no credentials are required. The types are as follows:

• Sm_AuthApi_Cred_None
  No credential required.
• Sm_AuthApi_Cred_Basic
  Username and password required.
• Sm_AuthApi_Cred_Digest
  Digest required.
• Sm_AuthApi_Cred_X509Cert
  X.509 certificate required.
• Sm_AuthApi_Cred_X509CertUserDN
  X.509 certificate and user DN required.
• Sm_AuthApi_Cred_X509CertIssuerDN
  X.509 certificate issuer DN required.
• Sm_AuthApi_Cred_CertOrBasic
  Either an X.509 certificate or username/password is required.
• Sm_AuthApi_Cred_CertOrForm
  Either an X.509 certificate or a forms-based authentication scheme is required.
• Sm_AuthApi_Cred_NTChalResp
  Use the NT challenge/response protocol.
• Sm_AuthApi_Cred_SSLRequired
  SSL required.
• Sm_AuthApi_Cred_FormRequired
  A redirect to an HTML form is required.
• Sm_AuthApi_Cred_AllowSaveCreds
  Save credentials hint.
• Sm_AuthApi_Cred_PreserveSessionId
  Session id should be preserved if the current session is still valid.
• Sm_AuthApi_Cred_DoNotChallenge
  Do not challenge for credentials.

lpszFormLocation

URL of the form credential provider (http://...).

Sm_AgentApi_ResourceContext_t

This structure defines a resource for protection and authorization.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_ResourceContext_s
{
   char lpszAgent[SM_AGENTAPI_SIZE_NAME];
   char lpszServer[SM_AGENTAPI_SIZE_NAME];
   char lpszAction[SM_AGENTAPI_SIZE_NAME];
   char lpszResource[SM_AGENTAPI_SIZE_URL];
} Sm_AgentApi_ResourceContext_t;

Parameters

This structure has the following parameters:

lpszAgent

Name of the Affiliate Agent holding the resource. This flag is reserved for working with Affiliate Agents. Leave this field blank.

lpszServer

Optional field, used to specify the name of the Web server hosting the Web resource—for example, www.myorg.org.

lpszResoure

Name of the Web resource being requested—for example, /inventory/ .

lpszAction

Type of action to be performed on the resource—for example, GET.

Sm_AgentApi_Server_t

This structure defines the connection configuration for each server.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_Server_s
{
   char lpszIpAddr[SM_AGENTAPI_SIZE_NAME];
   long nConnMin; 
   long nConnMax;
   long nConnStep; 
   long nTimeout;
   long nPort[3];
   void* pHandle[3];
   long nClusterSeq;
} Sm_AgentApi_Server_t;

Parameters

This structure has the following parameters:

pszIpAddr

The IP address of the Policy Server. A pipe of TCP connections is formed for each of the three services within the Policy Server (Authorization, Authentication, and Accounting).

nConnMin

Describing the pipe of TCP connections, this is the initial number of connections.

nConnMax

Describing the pipe of TCP connections, this is the maximum number of allowed connections within the pipe.

nConnStep

As necessary, the number of connections in the pipe of TCP connections will be increased by this increment.

nTimeout

The number of seconds until it is determined that the agent can not reach the Policy Server. This parameter is configurable based on the overall throughput and latency conditions of the entire SiteMinder installation.

nPort

When the Policy Server is configured for a single Access Control TCP port, use the constant SM_AGENTAPI_POLICYSERVER to point to the combined port. The constants below are maintained for backward compatibility:

• SM_AGENTAPI_AZ_SERVER
• SM_AGENTAPI_AUTH_SERVER
• SM_AGENTAPI_ACCT_SERVER

pHandle

Reserved; set to null.

nClusterSeq

The cluster sequence number. Sequence numbers begin at 1. Omit this parameter for a non-cluster server.

Sm_AgentApi_Session_t

This structure defines information about the user's session.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_Session_s
{
   long nReason;
   long nIdleTimeout;
   long nMaxTimeout;
   long nCurrentServerTime;
   long nSessionStartTime;
   long nSessionLastTime;
   char lpszSessionId[SM_AGENTAPI_SIZE_OID];
   char lpszSessionSpec[SM_AGENTAPI_SIZE_SESSIONSPEC];
} Sm_AgentApi_Session_t;

Parameters

This structure has the following parameters:

nReason

Additional status code: explains the reason for failed authentication or authorization, or is passed in the event that results from a successful invocation of Sm_AgentApi_Logout(). Defined in SmApi.h.

nIdleTimeout

Maximum amount of time a session can be valid without the user accessing a resource before the agent should challenge the user to re-authenticate, defined in seconds.

nMaxTimeout

Maximum amount of time a user session can be active before the agent challenges the user to re-authenticate, defined in seconds.

nCurrentServerTime

Current time (in GMT) set on the Policy Server.

nSessionStartTime

Server time (in GMT) when the session started.

nSessionLastTime

Server time (in GMT) when the session was last seen by the Policy Server.

lpszSessionId

An opaque value returned to identify the session.

lpszSessionSpec

An opaque value returned to identify the session, which represents the session specification.

Sm_AgentApi_TunnelServiceRequest_t

This structure defines information about the remote service library.

Syntax

This structure has the following syntax:

typedef struct Sm_AgentApi_TunnelServiceRequest_s
{
   char lpszLibrary[SM_AGENTAPI_SIZE_NAME];
   char lpszFunction[SM_AGENTAPI_SIZE_NAME];
   char lpszParameter[SM_AGENTAPI_SIZE_USERINFO];
   long nLength;
   void* pData;
} Sm_AgentApi_TunnelServiceRequest_t;

Parameters

This structure has the following parameters:

lpszLibrary

The name of the service to be invoked by the Policy Server.

lpszFunction

The name of a method to call within the service.

lpszParameter

Arbitrary string parameter to be passed to the method.

nLength

The length of the data passed to the method. The maximum length can be determined by calling Sm_AgentApi_GetMaxTunnelBufSize().

pData

A pointer to the data.

Sm_AgentApi_UserCredentials_t

This structure is used for passing credentials to the server.

Note: The agent supplies only the relevant information as requested by the Policy Server.

Syntax

This structure has the following format:

typedef struct Sm_AgentApi_UserCredentials_s
{
   long nChallengeReason;
   char lpszUsername[SM_AGENTAPI_SIZE_USERINFO];
   char lpszPassword[SM_AGENTAPI_SIZE_USERINFO];
   char lszCertUserDN[SM_AGENTAPI_SIZE_USERINFO];
   char lpszCertIssuerDN[SM_AGENTAPI_SIZE_USERINFO];
   long nCertBinaryLen;
   char* lpszCertBinary;
} Sm_AgentApi_UserCredentials_t;

Parameters

This structure has the following parameters:

nChallengeReason

The original reason code from a previous authentication that has failed or been challenged.

lpszUsername

Name of the user being authenticated.

lpszPassword

Password of the user being authenticated.

lpszCertUserDN

This field should be set to null. Specify the complete certificate data, including the user DN, in lpszCertBinary.Existing agent applications that specify a user DN in this field are not required to change the value to null. A user DN value is supported for backward compatibility.

lpszCertIssuerDN

This field should be set to null. Specify the complete certificate data, including the issuer DN, in lpszCertBinary.Existnnnnning agent applications that specify an issuer DN in this field are not required to change the value to null. An issuer DN value is supported for backward compatibility. If lpszCertUserDN is null, lpszCertIssuerDN is ignored.

nCertBinaryLen

Number of characters in the Binary Certificate.

lpszCertBinary

Pointer to the certificate data.

Function Declarations

The following table summarizes the C language functions that are used in the Agent API. The functions appear alphabetically.

More Information:

Agent Call Sequence

Function Return Codes

The Agent API functions can use some or all of the following return codes:

Sm_AgentApi_Audit()

Call this function if the authorizations are to be done out of agent cache.

Syntax

int Sm_AgentApi_Audit (
   const void*                            pHandle,
   const char*                            lpszClientIpAddr,
   const char*                            lpszTransactionId,
   const Sm_AgentApi_ResourceContext_t*   pResourceContext,
   const Sm_AgentApi_Realm_t*             pRealm,
   Sm_AgentApi_Session_t*                 pSession
);

ReturnValues

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The operation failed.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Sm_AgentApi_Authorize()

Determines if a defined user is authorized by SiteMinder to perform a defined action on a defined resource and returns response attributes about the user with respect to the resource.

Syntax

int SM_EXTERN Sm_AgentApi_Authorize (
   const void*                            pHandle,
   const char*                            lpszClientIpAddr,
   const char*                            lpszTransactionId,
   const Sm_AgentApi_ResourceContext_t*   pResourceContext,
   const Sm_AgentApi_Realm_t*             pRealm,
   Sm_AgentApi_Session_t*                 pSession,
   long*                                  pNumAttributes,
   Sm_AgentApi_Attribute_t**              ppAttributes
);

Return Values

• SM_AGENTAPI_YES. The user is authorized.
• SM_AGENTAPI_NO. The user is not authorized.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Example

See the sample smagentexample.cpp for an example of this function.

Sm_AgentApi_ChangePassword()

Changes a user’s password. The resulting attributes plus the reason code from the session object are used to construct the correct password services redirect.

Syntax

int SM_EXTERN Sm_AgentApi_ChangePassword (
   const void* pHandle,
   const char* lpszClientIpAddr,
   const char* lpszNewPassword,
   const char* pszTokenValue,
   const Sm_AgentApiResourceContext_t* pResourceContext,
   const Sm_AgentApi_Realm_t* pRealm,
   const Sm_AgentApi_UserCredentials_t* pUserCredentials,
   Sm_AgentApi_Session_t* pSession,
   long * numAttributes,
   Sm_AgentApi_Attribute_t** ppAttributes
);

Return Values

• SM_AGENTAPI_YES. The user’s password was changed.
• SM_AGENTAPI_NO. The user’s password was not changed.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_TIMEOUT. The function timed out.
• SM_AGENTAPI_FAILURE. The password was not changed

Sm_AgentApi_CreateSSOToken()

Produces an encrypted token of session and other information that can be shared between standard SiteMinder Web Agents and custom agents. The mutual access to this information allows a custom agent to participate in a single sign-on environment with a standard SiteMinder Web Agent.

Syntax

int SM_EXTERN Sm_AgentApi_CreateSSOToken (
   const void*                      pHandle,
   Sm_AgentApi_Session_t*           pSession,
   long                             nNumAttributes,
   Sm_AgentApi_Attribute_t*         pTokenAttributes,
   long*                            pNumSSOTokenLength, 
   char*                            lpszSSOToken
);

Return Values

• SM_AGENTAPI_SUCCESS. The operation successful.
• SM_AGENTAPI_FAILURE. The token was not created.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.

Remarks

This function associates the user attribute information specified in the pTokenAttributes parameter with session and other attribute information returned from the call to Sm_AgentApi_Login(). The information in the resulting token can be shared between standard SiteMinder Web Agents and custom agents, allowing single sign-on operations between the standard and custom agents.

This call does not allocate any memory.

To decode token information, call Sm_AgentApi_DecodeSSOToken().

Sm_AgentApi_DecodeSSOToken()

Decodes a single sign-on token and returns a subset of its attributes. Optionally, you can update the token’s last-access timestamp, and then update the SMSESSION cookie with the new token.

Syntax

int SM_EXTERN Sm_AgentApi_DecodeSSOToken (
   const void*                  pHandle,
   const char*                  lpszSSOToken,
   long*                        nTokenVersion,
   long*                        pThirdPartyToken,
   long*                        pNumAttributes,
   Sm_AgentApi_Attribute_t**    ppTokenAttributes,
   long                         nUpdateToken,
   long*                        pNumUpdatedSSOTokenLength,
   char*                        lpszUpdatedSSOToken
);

Returns

• SM_AGENTAPI_SUCCESS. The operation succeeded.
• SM_AGENTAPI_FAILURE. The token was not decoded.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.

Remarks

This function accepts a single sign-on token as input and returns a subset of the token’s attributes.

You can update the token’s last-access timestamp. To do so, assign a non-zero value to the parameter nUpdateToken. The token that includes the updated timestamp is returned in lpszUpdatedSSOToken. Write the updated token to the SMSESSION cookie.

This function allocates memory for the attribute list. To deallocate this memory, call Sm_AgentApi_FreeAttributes().

To create a single sign-on token, call Sm_AgentApi_CreateSSOToken().

Sm_AgentApi_DelSessionVariables()

Deletes the specified session variables from the session store.

Syntax

int Sm_AgentApi_DelSessionVariables (
   const void*                           pHandle,
   const Sm_AgentApi_ResourceContext_t*  pResourceContext,
   const char*                           lpszSessionId,
   long                                  nNumReqAttributes,
   Sm_AgentApi_Attribute_t*              pReqAttributes,
   long*                                 pRespNumAttributes,
   Sm_AgentApi_Attribute_t**             ppRespAttributes
);

Return Values

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The call was refused.
• SM_AGENTAPI_UNRESOLVED. Some variables could not be deleted. See the description of the ppRespAttributes parameter.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Remarks

This function fails if the session referenced by lpszSessionId is not active, or the connection to the session store is lost.

To release the memory allocated for any variables returned in the ppRespAttributes parameter, call Sm_AgentApi_FreeAttributes().

More Information:

Sm_AgentApi_FreeAttributes()

Sm_AgentApi_DoManagement()

Requests agent commands from the Policy Server. Agent commands indicate work to be performed by agents.

Syntax

int SM_EXTERN Sm_AgentApi_DoManagement (
   const void*                         pHandle,
   Sm_AgentApi_ManagementContext_t*    pManagementContext,
   long*                               pNumAttributes,
   Sm_AgentApi_Attribute_t**           ppAttributes
);

Return Values

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Example

See the function SmAgentExample::Sm_DoManagement() in the example application smagentexample.cpp.

Sm_AgentApi_FreeAttributes()

Frees the buffer of response attributes.

Syntax

void Sm_AgentApi_FreeAttributes (
   const long                       nNumAttributes, 
   const Sm_AgentApi_Attribute_t*   pAttributes
);

Example

See the function SmAgentExample::Sm_Login() in the example application smagentexample.cpp.

Sm_AgentApi_FreeServers()

Frees an array of server structures after a call to Sm_AgentApi_GetConfig().

Syntax

void SM_EXTERN Sm_AgentApi_FreeServers (
	Sm_AgentApi_Server_t* pServers
);

Sm_AgentApi_GetAgentApiUpdateVersion()

Retrieves the current API update version in SM_AGENTAPI_UPDATE_VERSION.

For example, if the current version of the Agent API is v6.0 SP3, you can call Sm_AgentApi_GetAgentApiUpdateVersion() to verify that the custom program was compiled against Agent API v6.0 SP3.

Syntax

int SM_EXTERN Sm_AgentApi_GetAgentApiUpdateVersion();

Sm_AgentApi_GetAllowedTunnelBufSize()

Retrieves the maximum data buffer size that can be transferred in the Sm_AgentApi_Tunnel() function call.

Syntax

long SM_EXTERN Sm_AgentApi_GetAllowedTunnelBufSize (
   void* pHandle,
   int nServer
);

Returns

The maximum size of the buffer.

Remarks

This function was introduced in SDK v5.5. Beginning with that release, maximum allowable buffer sizes are larger than in previous releases.

Sm_AgentApi_GetConfig()

Retrieves configuration information for an agent.

This function requires an Agent API version of v5.0 or later.

This function can read configuration information either from a configuration file or, on a Microsoft Windows platform, from the Windows Registry.

Syntax

int SM_EXTERN Sm_AgentApi_GetConfig (
   Sm_AgentApi_Init_t*   pInit, 
   const char*           lpszAgentName, 
   const char*           lpszPath
);

Return Values

• SM_AGENTAPI_SUCCESS. Configuration retrieval succeeded.
• SM_AGENTAPI_FAILURE. Configuration retrieval failed.
• SM_AGENTAPI_FAILURE is returned under any of these conditions:
  • No agent name is specified in lpszAgentName, and Sm_AgentApi_GetConfig() cannot get the default agent name
  • An agent name is specified in lpszAgentName, but Sm_AgentApi_GetConfig() cannot find that agent name
  • Sm_AgentApi_GetConfig() cannot find at least one SiteMinder Policy Server configuration
  • There is no path specified in lpszPath, and one of the following occurs:
    • The platform is not WIN32, so there are no Registry settings to retrieve.
    • Sm_AgentApi_GetConfig() cannot retrieve one of the required settings from the Registry. For example, it cannot open the Registry key that holds the shared secret.
    • There is a path specified in lpszPath, but Sm_AgentApi_GetConfig() cannot open and read the configuration file named in lpszPath.

Remarks

This function must be called by custom agents that are configured through central host configuration.

With v5.x or later agent connectivity:

• The function’s lpszPath parameter references the SmHost.conf file created when the trusted host was registered with the Policy Server, or a WebAgent.conf file that references SmHost.conf.
• The lpszAgentName parameter is ignored.

With 4.x agent connectivity:

• The agent name is specified in the lpszAgentName parameter.
• A v4.x WebAgent.conf file is referenced in lpszPath.

Sm_AgentApi_GetConfig() checks the value of lpszPath to find the path and name of a configuration file:

• If lpszPath is empty and the agent is written for a Microsoft Windows platform, Sm_AgentApi_GetConfig() searches the Windows Registry for the configuration information.
• If lpszPath is empty and the agent is running on a UNIX system, Sm_AgentApi_GetConfig() returns SM_AGENTAPI_FAILURE.

If Sm_AgentApi_GetConfig() cannot find the agent name, it uses the default agent name. If the default agent name cannot be retrieved, the function returns SM_AGENTAPI_FAILURE.

When Sm_AgentApi_GetConfig() locates the configuration information for the correct agent, it copies the information into the fields of an initialization structure (Sm_AgentApi_Init_t). The parameter pInit points to this initialization structure. For example, suppose the agent name parameter contains the string Agent1 and the agentname list of the configuration file is set as follows:

agentname="Agent1,123.112.12.12"

In this circumstance, Sm_AgentApi_GetConfig() sets the lpszHostName field of initialization structure pInit to Agent1. The IP Address is ignored. Sm_AgentApi_GetConfig() then retrieves the information for the other fields of the initialization structure.

Sm_AgentApi_GetMaxTunnelBufSize()

Deprecated in SDK v5.5. Replaced by Sm_AgentApi_GetAllowedTunnelBufSize().

Sm_AgentApi_GetSessionVariables()

Retrieves the values of existing session variables.

Syntax

int Sm_AgentApi_GetSessionVariables (
   const void*                           pHandle,
   const Sm_AgentApi_ResourceContext_t*  pResourceContext,
   const char*                           lpszSessionId,
   long                                  nNumReqAttributes,
   Sm_AgentApi_Attribute_t*              pReqAttributes,
   long*                                 pRespNumAttributes,
   Sm_AgentApi_Attribute_t**             ppRespAttributes
);

Return Values

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The call was refused.
• SM_AGENTAPI_UNRESOLVED. Some variables could not be fetched. See the description of the ppRespAttributes parameter.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.
• SM_AGENTAPI_SUCCESS. The operation succeeded.

Remarks

This function fails if the session referenced by lpszSessionId is not active, if no variables are found, or if the connection to the session store is lost.

To delete a variable from the session store after fetching it, set the SM_AGENTAPI_REQATTR_FLAGS_DELETE flag in the pReqAttributes parameter. To delete a variable without fetching it, call the function Sm_AgentApi_DelSessionVariables().

To release the memory allocated for any variables returned in the ppRespAttributes parameter, call Sm_AgentApi_FreeAttributes().

Sm_AgentApi_Init()

Initializes the Agent API and sets up connections to the Policy Server. This function is called once per agent.

Note: This call succeeds even if a connection to the Policy Server cannot be established immediately. The Agent API will keep trying to reconnect. See the Remarks for more information.

Syntax

int SM_EXTERN Sm_AgentApi_Init (
   const Sm_AgentApi_Init_t*  pInitStruct, 
   void**                     ppHandle
);

Returns

• SM_AGENTAPI_SUCCESS. Initialization succeeded.
• SM_AGENTAPI_FAILURE. Initialization failed.

Remarks

All agents should issue the DoManagement() call and specify the SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO command once at startup.

This function is designed to fail only when a connection to the Policy Server is established, but the shared secret and/or agent name are incorrect. In all other circumstances, this function returns SM_AGENTAPI_SUCCESS, such as in the following circumstances:

• An incorrect Policy Server IP address and/or port number are provided during the initialization operation
• A correct Policy Server IP address and port number are provided, but the Policy Server is down

In these cases, the Agent API returns a status of success and continues to try to establish the connection to the Policy Server (the connection layer does not know if the information provided is correct or incorrect). You should not assume that a connection to the Policy Server is established if the Sm_AgentApi_Init() function succeeds.

You are responsible for deallocating memory for your custom agent. When you initialize the Agent API with Sm_AgentAPI_Init(), all information in the Sm_AgentApi_Init_t structure is copied, allowing you to deallocate the structure’s memory after initialization.

Example

See the function SmAgentExample::Sm_Init() in the example application smagentexample.cpp.

Sm_AgentApi_IsProtected()

Checks if the defined resource is protected by SiteMinder.

Syntax

int SM_EXTERN Sm_AgentApi_IsProtected (
   const void                             pHandle,
   const char*                            lpszClientIpAddr,
   const Sm_AgentApi_ResourceContext_t*   pResourceContext,
   Sm_AgentApi_Realm_t*                   pRealm
);

Return Values

• SM_AGENTAPI_YES. The resource is protected.
• SM_AGENTAPI_NO. The resource is not protected.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Example

See the function SmAgentExample::Sm_IsProtected() in the example application smagentexample.cpp.

Sm_AgentApi_Login()

This function performs session login and session validation.

The Policy Server authenticates user credentials during session login and validates the session specification during session validation. Whether the Policy Server performs session login or session validation depends on whether a session specification is defined in the field lpszSessionSpec of the structure Sm_AgentApi_Session_t, as follows:

• If the session specification exists, the Policy Server performs session validation. During session validation, if the lpszSessionSpec field has a length, the Policy Server takes the following actions:
  • Verifies that the session has not expired based on the nMaxTimeout field of Sm_AgentApi_Session_t.
  • Checks the IP address.
  • Verifies that the user is in the user directory and has not been disabled.
• If the session specification does not exist, the Policy Server performs session login. During session login, if the session ID is specified, it will be used as the session ID upon successful authentication.

Syntax

int SM_EXTERN Sm_AgentApi_Login (
   const void*                            pHandle,
   const char*                            lpszClientIpAddr,
   const Sm_AgentApi_ResourceContext_t*   pResourceContext,
   const Sm_AgentApi_Realm_t*             pRealm,
   const Sm_AgentApi_UserCredentials_t*   pUserCredentials,
   Sm_AgentApi_Session_t*                 pSession,
   long*                                  pNumAttributes,
   Sm_AgentApi_Attribute_t**              ppAttributes
);

Return Values

• SM_AGENTAPI_YES. The user was authenticated.
• SM_AGENTAPI_NO. The user was not authenticated.
• SM_AGENTAPI_CHALLENGE. A challenge is required for authentication.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Remarks

Response attributes can be returned when authentication events occur. Both well-known and policy-based attributes can be returned, as described in Response Attributes. For example, upon successful authentication, a response could return the user’s DN.

When a resource is protected by an anonymous authentication scheme, only the following attributes are set:

• SM_AGENTAPI_ATTR_USERDN. Set with the SessionID for the anonymous session.
• SM_AGENTAPI_ATTR_IDENTITYSPEC. Set with the globally unique identity ticket for the anonymous session.

Supply only the required credentials (as determined by a call to Sm_AgentApi_IsProtected(), which should be called before Sm_AgentApi_Login()). Unused fields in the user credentials structure must be zero-initialized.

Sm_AgentApi_Login() returns attributes in the Sm_AgentApi_Attribute_t structure. Call Sm_AgentApi_FreeAttributes() to release the attributes.

On successful login, the Sm_AgentApi_Session_t structure is populated with the session specification. If you allocated memory for this structure, it is your responsibility to deallocate it.

Example

See the example application smagentexample.cpp for an example of this function.

Sm_AgentApi_Logout()

Logs a user out of a user session and issues an event. No database is updated.

When a user logs out, you must explicitly terminate the session by discarding the session specification.

This function does not deallocate memory. It is your responsibility to deallocate any memory you allocated for your custom agent.

Syntax

int SM_EXTERN Sm_AgentApi_Logout (
   const void*                   pHandle,
   const char*                   lpszClientIpAddr,
   const Sm_AgentApi_Session_t*  pSession
);

Return Values

• SM_AGENTAPI_YES. The user logged out successfully.
• SM_AGENTAPI_NO. The user was not logged out.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Remarks

To terminate a user’s session when a user logs out, you must discard the session specification. You can do so by re-initializing the session specification in the Sm_AgentApi_Session_t structure, as illustrated in the following code:

iResult = Sm_AgentApi_Logout (
                pHandle,
                SMAPI_SAMPLE_AGENTIP,
                &pSession);

if (SM_AGENTAPI_YES==iResult)
      memset(&pSession,0,sizeof(Sm_AgentApi_Session_t));

Sm_AgentApi_MakeCertificateHash()

Use this function to generate an SHA1 hash of a binary certificate. The hash should be placed in the binary certificate in the user credentials structure. For this function to work properly, the iCertHashLen parameter must be greater than or equal to 20 bytes. This function can be used to generate SHA1 hashes of an arbitrary buffer.

Syntax

int Sm_AgentApi_MakeCertificateHash (
   const unsigned char*   pCertificateData, 
   const int              nCertLen,
   unsigned char*         pCertHash, 
   const int              nCertHashLen
);

Return Values

• SM_AGENTAPI_SUCCESS. The operation succeeded.
• SM_AGENTAPI_FAILURE. The size is too small.

Sm_AgentApi_SetDefaultAgentId()

Sets the name of a v5.x or later agent that is configured through Central Host Configuration.

Syntax

int SM_EXTERN Sm_AgentApi_SetDefaultAgentId(
   const char *pszAgentIdentity,
   void* pHandle
);

Return Values

• SM_AGENTAPI_SUCCESS. The default agent name was set successfully.
• SM_AGENTAPI_FAILURE. Parameter pszAgentIdentity was NULL or exceeded SM_AGENTAPI_SIZE_NAME.
• SM_AGENTAPI_NOCONNECTION. Parameter pHandle was NULL.

Remarks

Call this function after calling Sm_AgentApi_Init() and before calling any other function in the Agent API. Doing so avoids having to pass the name of the agent with each Agent API request.

This function is only used with v5 or later custom agents that are configured through central host configuration.

Sm_AgentApi_SetSessionVariables()

Creates new session variables or updates existing session variables.

Syntax

int Sm_AgentApi_SetSessionVariables (
   const void*                           pHandle,
   const Sm_AgentApi_ResourceContext_t*  pResourceContext,
   const char*                           lpszSessionId,
   long                                  nNumReqAttributes,
   Sm_AgentApi_Attribute_t*              pReqAttributes,
   long*                                 pRespNumAttributes,
   Sm_AgentApi_Attribute_t**             ppRespAttributes
);

Returns

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The operation failed.
• SM_AGENTAPI_UNRESOLVED. Some variables could not be set. The list of unresolved variables is returned in the ppRespAttributes parameter.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.
• SM_AGENTAPI_SUCCESS. The operation succeeded.

Remarks

This function fails if the session referenced by lpszSessionId is not active or the connection to the session store is lost.

To release the memory allocated for any unresolved variable values returned in the ppRespAttributes parameter, call Sm_AgentApi_FreeAttributes().

Sm_AgentApi_Tunnel()

Call this function to transfer data between a remote service on the Policy Server side and your agent. The Sm_AgentApi_GetMaxTunnelBufSize() function call gives you the maximum data size that can be transferred. At this time this function supports only one buffer for each call. pServiceRequest holds the information about the remote service that will be invoked by the Policy Server.

Note: SMTUNNEL is a predefined tunnel agent name whose shared secret is also SMTUNNEL. You can initialize a tunnel agent using these names without specifically creating the agent ahead of time. The predefined SMTUNNEL agent can only call Sm_AgentApi_Tunnel().

If you explicitly create a tunnel agent that has the name and shared secret SMTUNNEL, it is also limited to calling Sm_AgentApi_Tunnel().

If an agent named SMTUNNEL makes a call to a function other than Sm_AgentApi_Tunnel(), the Policy Server returns an error.

Syntax

int SM_EXTERN Sm_AgentApi_Tunnel (
  const void*                            pHandle,
  const int                              nServer,
  const char*                            lpszClientIpAddr,
  const char*                            lpszTransactionId,
  const Sm_AgentApi_ResourceContext_t*   pResourceContext,
  const Sm_AgentApi_TunnelServiceRequest_t* pServiceRequest,
  long*                                  pRespNumAttributes,
  Sm_AgentApi_Attribute_t**              ppRespAttributes
);

Returns

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The operation failed.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.

Example

For an example of Sm_AgentApi_Tunnel(), see:

<install_path>\sdk\samples\smtunnelagent\smtunnelexample.cpp

Sm_AgentApi_UnInit()

Once the agent is no longer needed, uninitialize all API instances by issuing the Sm_AgentApi_UnInit() call for each API instance. This closes TCP connections to all Policy Servers.

This function does not deallocate memory. It is your responsibility to deallocate any memory you allocated for your custom agent.

Syntax

int SM_EXTERN Sm_AgentApi_UnInit (
   void** ppHandle
);

Returns

• SM_AGENTAPI_SUCCESS. Uninitialization succeeded.
• SM_AGENTAPI_NOCONNECTION. Uninitialization was not done.

Example

See the function SmAgentExample::Sm_UnInit() in the example application smagentexample.cpp.

Sm_AgentApi_UpdateAttributes()

Call this function to update response attributes when the time-to-live (TTL) value has expired. When specifying request attributes, each attribute structure should be zero-initialized, then set the lpszAttributeOid fields in the Sm_AgentApi_Attribute_t structure. Use the same field to map the response attributes to requested attributes. Not all attributes may be updated.

This function will recalculate an active response that originally held no data. An active response attribute is considered valid if its return value has a non-zero length or its TTL value is set.

Syntax

int SM_EXTERN Sm_AgentApi_UpdateAttributes (
   const void*                          pHandle,
   const char*                          lpszClientIpAddr,
   const char*                          lpszTransactionId,
   const Sm_AgentApi_ResourceContext_t* pResourceContext,
   const Sm_AgentApi_Realm_t*           pRealm,
   const Sm_AgentApi_Session_t*         pSession,
   long                                 nNumReqAttributes,
   Sm_AgentApi_Attribute_t*             pReqAttributes,
   long*                                pRespNumAttributes,
   Sm_AgentApi_Attribute_t**            ppRespAttributes
);

Returns

• SM_AGENTAPI_YES. The operation succeeded.
• SM_AGENTAPI_NO. The operation failed.
• SM_AGENTAPI_NOCONNECTION. The initialization was not done.
• SM_AGENTAPI_FAILURE. The server could not be reached.
• SM_AGENTAPI_TIMEOUT. The function timed out.