Previous Topic: API OverviewNext Topic: Configuring Custom Agent Types


Agent API

This section contains the following topics:

Agent API Overview

About the SiteMinder Agent

Agent Initialization

Agent Discovery

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:

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:

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.

Agent Discovery

Agent discovery lets CA SiteMinder® administrators track instances of different types of agents, including agents that have been deployed over a number of years. An agent instance can be any type of agent, for example, Web agent, custom agent, or ERP agent. To come under the purview of agent discovery, the agent must be active and in communication with the Policy Server.

Only 5.x agents and later can be tracked. For agents created before r12.5, the combination of the IP address and trusted host are used to identify the agent. Any change in this combination for the same agent results in multiple entries for the same agent.

A unique GUID identifies each r12.5 agent instance, which is stored in a configuration file. The Sm_AgentApi_SetAgentInstanceInfo() function plays a pivotal role in the process of agent discovery. The Sm_AgentApi_SetAgentInstanceInfo() function determines whether the configuration has a specified GUID for the agent instance. If a GUID is found, the agent has already been discovered and can be tracked. Otherwise, the function creates a GUID for the agent instance and writes it to the configuration file for subsequent invocations. Multiple agent instances cannot share a configuration file.

The Agent API provides the following for registering agent info:

	int SM_EXTERN Sm_AgentApi_SetAgentInstanceInfo (
	    const void* pHandle,
	    Sm_AgentApi_AgentDiscovery_t arrParams[], int nCount);

The following macros in SmAgentAPi.h define the supported named elements that can be passed in arrParams. These are all optional, and an agent provides as much, or as little, information as it relevant.

	#define SM_AGENT_INSTANCE_AGENTPRODUCTTYPE      "AGENTPRODUCTTYPE"

Example: WebAgent

	#define SM_AGENT_INSTANCE_AGENTPRODUCTVERSION   "AGENTPRODUCTVERSION"

Example: 1.0

	#define SM_AGENT_INSTANCE_AGENTPRODUCTSUBTYPE   "AGENTPRODUCTSUBTYPE"

Example: IIS

	#define SM_AGENT_INSTANCE_AGENTPRODUCTOSTYPE    "AGENTPRODUCTOSTYPE"

Example: Linux

	#define SM_AGENT_INSTANCE_AGENTIDFILE           "AGENTIDFILE"

Valid path to a text file with write permission, used to store a unique GUID. If a path to an empty file is passed, the agent API will generate a new GUID and write it to this file. In the future, this GUID can be read and used to uniquely identify the agent instance.

	#define SM_AGENT_INSTANCE_ACONAME               "ACONAME"

A value ACO name used by the agent.

#define SM_AGENT_INSTANCE_HCONAME               "HCONAME"

A valid HCO name used by the agent

	#define SM_AGENT_INSTANCE_FIPSMODE              "FIPSMODE"

The value store in SmHost.conf if host registration is used by the agent.

After Sm_AgentApi_SetAgentInstanceInfo is called successfully, the AgentAPI will make periodic calls to the Policy Server in the back ground like a heartbeat. Calling this API for the first time from an agent results in a new unique record created in the Agent Discovery table used by the policy server. If a GUID is available, this record is indexed by the GUID. It is best to provide an Agent ID file so that a valid GUID is used. Without this value, the agent instance cannot be tracked and maintained as a unique entity in the SiteMinder agent ecosystem.

The correct calling sequence is:

	Sm_AgentApi_Init
	Sm_AgentApi_SetAgentInstanceInfo
	..
	other calls to PS
	..
	Sm_AgentApi_Uninit 

Here is a source example that assumes Sm_AgentApi_Init has been called previously to establish pAgentApiHandle:

    Sm_AgentApi_AgentDiscovery_t arrParams[8] = {
				{SM_AGENT_INSTANCE_AGENTPRODUCTTYPE, "CustomAgent"},
    				{SM_AGENT_INSTANCE_AGENTPRODUCTVERSION, "1.0"},
    				{SM_AGENT_INSTANCE_AGENTPRODUCTSUBTYPE, "IIS"},
    				{SM_AGENT_INSTANCE_AGENTPRODUCTOSTYPE, "Windows"},
    				{SM_AGENT_INSTANCE_AGENTIDFILE, "c:\idfile.txt"},
    				{SM_AGENT_INSTANCE_ACONAME, "MyACO"},
    				{SM_AGENT_INSTANCE_HCONAME, "MyHCO"},
    				{SM_AGENT_INSTANCE_FIPSMODE, "COMPAT"}};
    int nCount = 8;
    
    // Call the Agent API to send the data
    int nResult = Sm_AgentApi_SetAgentInstanceInfo(pAgentApiHandle, arrParams, nCount);

    switch (nResult)
    {
        case SM_AGENTAPI_NOCONNECTION:
        case SM_AGENTAPI_FAILURE:
        case SM_AGENTAPI_TIMEOUT:
        {
	    // put error handling here
            break;
        }
        case SM_AGENTAPI_NO:
        {
	    // The call was refused - probably not properly formatted. This return indicates
	    // that the call ran on the PS and returned an explicit NO response, as opposed to
	    // some other connection or protocol error that might generate the conditions above.
            break;
        }
	case SM_AGENTAPI_YES:
	{
	    // Success
	    break;
	}
    } // switch (nResult)

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.

Platform

Library

Directory

Variable Name

Windows

SmAgentAPI.lib

<install_path>\sdk\lib\win32\

 

Solaris

libsmagentapi.so

<install_path>/sdk/bin

LD_LIBRARY_PATH

HP-UX

libsmagentapi.so

<install_path>/sdk/bin

SHLIB_PATH

AIX

libsmagentapi.so

<install_path>/sdk/bin

LIBPATH

Linux

libsmagentapi.so

<install_path>/sdk/bin

LD_LIBRARY_PATH

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:

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:

  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:

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

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:

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:

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 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:

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:

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:

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 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:

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:

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:

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_AgentDiscovery_t

This structure defines information about agent instance parameters.

Syntax

This structure had the following format:

typedef struct Sm_AgentApi_AgentDiscovery_s
{
   char paramname[SM_AGENTAPI_SIZE_NAME];
   char paramvalue[SM_AGENTAPI_SIZE_NAME];
   } Sm_AgentApi_AgentDiscovery_t;

Parameters

This structure had the following parameters:

paramname

Use the following names to specify agent instance attributes:

paramvalue

The value of the specified attribute.

Remarks

All agent instance attributes are initialized to "unknown" value. The developer using the Agent API specifies the appropriate values by calling Sm_AgentApi_SetAgentInstanceInfo(). When this call is not made, the agent does not come under the purview of agent discovery.

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:

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.

SM_AGENTAPI_ATTR_SSOZONE

Specifies the designation of the SSO zone name, which you provide when you call the Sm_AgentApi_CreateSSOToken method. If you do not specify a zone name, the default is "SM." You can read this value in the in the attribute list returned by the Sm_AgentApi_DecodeSSOToken method.

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:

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:

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:

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.

Function

Description

Sm_AgentApi_Audit()

Audits a transaction.

Sm_AgentApi_Authorize()

Determines if a user has access to a resource.

Sm_AgentApi_ChangePassword()

Changes a user’s password.

Sm_AgentApi_CreateSSOToken()

Produces an encrypted single sign-on token that can be shared between standard SiteMinder Web Agents and custom agents.

Sm_AgentApi_DecodeSSOToken()

Decodes a single sign-on token.

Sm_AgentApi_DelSessionVariables()

Deletes the specified session variables from the session store.

Sm_AgentApi_DoManagement()

Requests agent commands.

Sm_AgentApi_FreeAttributes()

Frees the buffer of response attributes.

Sm_AgentApi_FreeServers()

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

Sm_AgentApi_GetAgentApiUpdateVersion()

Retrieves the current API update version.

Sm_AgentApi_GetAllowedTunnelBufSize()

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

Sm_AgentApi_GetConfig()

Retrieves agent configuration settings as defined either in the Registry (for Microsoft Windows only) or in an agent configuration file.

Sm_AgentApi_GetSessionVariables()

Retrieves the values of existing session variables.

Sm_AgentApi_Init()

Initializes the Agent API to set up connections to the Policy Servers.

Sm_AgentApi_IsProtected()

Determines if a resource is protected.

Sm_AgentApi_Login()

Performs session login and validation.

Sm_AgentApi_Logout()

Logs a user out of a session.

Sm_AgentApi_MakeCertificateHash()

Generates a hash of a certificate.

Sm_AgentApi_SetDefaultAgentId()

Sets the name of a custom agent that is configured through Central Host Configuration.

Sm_AgentApi_SetSessionVariables()

Creates new session variables or updates existing session variables.

Sm_AgentApi_Tunnel()

Transfers data between a remote service on the Policy Server side and your agent.

Sm_AgentApi_UnInit()

Uninitializes the Agent API.

Sm_AgentApi_UpdateAttributes()

Updates response attributes.

More Information:

Agent Call Sequence

Function Return Codes

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

Name

 

Value

 

SM_AGENTAPI_NOCONNECTION

-3

SM_AGENTAPI_TIMEOUT

-2

SM_AGENTAPI_FAILURE

-1

SM_AGENTAPI_SUCCESS

0

SM_AGENTAPI_YES

1

SM_AGENTAPI_NO

 

2

 

SM_AGENTAPI_CHALLENGE

3

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client where the user is logging in. This is an optional parameter.

If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

lpszTransactionId

I

The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID. This is an optional parameter.

pResourceContext

I

A defined resource definition structure.

pRealm

I

A realm definition structure.

pSession

I

A session definition structure.

 

ReturnValues

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client asking for the resource. This parameter is optional. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

lpszTransactionId

I

The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID. This is an optional parameter.

pResourceContext

I

A resource definition structure.

pRealm

I

A realm definition structure.

pSession

I

A session definition structure.

pNumAttributes

O

The number of returned attributes.

ppAttributes

O

A pointer to an array of response attribute definition structures.

Return Values

Example

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

Sm_AgentApi_AuthorizeDLP()

Determines if a defined user is authorized by SiteMinder DLP integration to access the resource and returns response attributes about the user with respect to the resource.

Syntax

int SM_EXTERN Sm_AgentApi_AuthorizeDLP (
   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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client asking for the resource. This parameter is optional. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

lpszTransactionId

I

The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID. This is an optional parameter.

pResourceContext

I

A resource definition structure.

pRealm

I

A realm definition structure.

pSession

I

A session definition structure.

pNumAttributes

O

The number of returned attributes.

ppAttributes

O

A pointer to an array of response attribute definition structures.

Return Values

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client asking for the resource. This parameter is optional. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

lpszNewPassword

I

The new password (string) to which the user wants to change.

pszTokenValue

I

The token that is exchanged between the Policy Server and the Web Agent in the case of a Password Services redirect. Use this parameter to send to the Policy Server an extracted SMTOKEN from the ppAttributes (returned by Sm_AgentApi_ChangePassword()).

This value can be NULL if the nChallengeReason value of the pUserCredentials parameter is set to Sm_Api_Reason_PWSelfChange (indicating a user-initiated password change).

pResourceContext

I

A pointer to a resource definition structure.

pRealm

I

A realm definition structure.

pUserCredentials

I

A user credentials definition structure.

pSession

O

A user session definition structure.

pNumAttributes

O

The number of attributes in ppAttributes.

ppAttributes

O

A pointer to an array of response attribute definition structures.

Return Values

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

pSession

I

Session information returned by the Sm_AgentApi_Login() call.

nNum
  Attributes

I

The number of attributes to include in the token. The attributes are specified in the parameter pTokenAttributes.

pToken
  Attributes

I

The user attributes to include in the token. Valid values:

  • SM_AGENTAPI_ATTR_USERDN. The user’s distinguished name.
  • 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_SSOZONE

    The designation of the SSO zone name. If you do not specify a zone name, the default is "SM." You read this value in the in the attribute list returned by the Sm_AgentApi_DecodeSSOToken method.

Any other attribute is ignored.

The fields in the Sm_AgentApi_Attribute_t structure that apply to this function are:

  • nAttributeId (one of the above values)
  • nAttributeLen
  • lpszAttributeValue

pNumSSOToken
  Length

I, O

The length of the lpszSSOToken buffer passed in to receive the token. The maximum size is specified by SSO_TOKEN_MAX_SIZE, defined in SmAgentAPI.h. Allow space for the null-terminator character.

On output, this parameter is set to the actual length of the returned token, including the null-terminator character.

lpszSSOToken

O

The token returned from this function. Write this token to the SMSESSION cookie.

Return Values

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszSSOToken

I

Null-terminated character array that contains the token to be decoded.

The custom agent finds the token in either of these locations:

  • If the token was created by a custom agent, the token is returned in the output parameter lpszSSOToken from the call to Sm_AgentApi_CreateSSOToken().
  • If the token was created by a standard SiteMinder Web Agent, the token is contained in the SMSESSION cookie. The custom agent is responsible for extracting the contents of the cookie and assigning it to this parameter.

nTokenVersion

O

The SiteMinder version of the token.

pThirdParty
  Token

O

A non-zero value indicates that the token was originally produced by a custom (third-party) agent and has not yet been updated by a standard SiteMinder agent.

pNumAttributes

O

The number of attributes retrieved from the token. The attributes are specified in the parameter ppTokenAttributes.

ppToken
  Attributes

O

The attributes extracted from the token. Valid values:

  • SM_AGENTAPI_ATTR_USERDN
  • SM_AGENTAPI_ATTR_SESSIONSPEC
  • SM_AGENTAPI_ATTR_SESSIONID
  • SM_AGENTAPI_ATTR_USERNAME
  • SM_AGENTAPI_ATTR_CLIENTIP
  • SM_AGENTAPI_ATTR_DEVICENAME
  • SM_AGENTAPI_ATTR_IDLESESSIONTIMEOUT
  • SM_AGENTAPI_ATTR_MAXSESSIONTIMEOUT
  • SM_AGENTAPI_ATTR_STARTSESSIONTIME
  • SM_AGENTAPI_ATTR_LASTSESSIONTIME
  • SM_AGENTAPI_ATTR_SSOZONE

nUpdateToken

I

A non-zero value indicates that an updated token is requested. The updated token is written to lpszUpdatedSSOToken.

Set the nUpdateToken flag to a non-zero value if you want to update the attribute SM_AGENTAPI_ATTR_LASTSESSIONTIME.

pNumUpdatedSSO
  TokenLength

I, O

The length of the lpszUpdatedSSOToken buffer to receive the token. The maximum size is specified by SSO_TOKEN_MAX_SIZE, defined in SmAgentAPI.h. Allow space for the null-terminator character.

On output, this parameter is set to the actual length of the returned token, including the null-terminator character.

lpszUpdated
  SSOToken

O

The updated token returned from this function. Write this token to the SMSESSION cookie.

A token is returned only if nUpdateToken is set to a non-zero value.

 

Returns

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

pResourceContext

I

Reserved for future use. Set all fields to 0.

lpszSessionId

I

A unique identifier of the session for which the variable is to be deleted. Variables can only be deleted for an active session.

After a successful login, the session ID is returned in the lpszSessionId field of the structure Sm_AgentApi_Session_t.

nNumReqAttributes

I

Size of the array of session variables in pReqAttributes.

pReqAttributes

I

An array of attributes representing the names of session variables to be deleted.

Set the variable name in the field lpszAttributeOid of structure Sm_AgentApi_Attribute_t.

Set the nAttributeFlags field of the Sm_AgentApi_Attribute_t structure to SM_AGENTAPI_REQATTR_FLAGS_NONE.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

pRespNumAttributes

O

Size of the array of responses, if any, in ppRespAttributes.

ppRespAttributes

O

If all the specified variables are deleted, no response attributes are returned in this parameter.

If this function returns SM_AGENTAPI_UNRESOLVED, the response attribute result set will contain variables that could not be deleted. Also, each response attribute will have the field nAttributeFlags of the structure Sm_AgentApi_Attribute_t set to SM_AGENTAPI_RESPATTR_FLAGS_UNRESOLVED.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

Return Values

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

pMananagement
  Context

I

A management definition structure. The agent uses this structure to define a management command.

pNumAttributes

I

The number of attributes in ppAttributes.

ppAttributes

O

A pointer to an array of requested attribute definition structures. One or more of the following attributes may be returned:

  • SM_AGENTAPI_AGENT_KEY_UPDATE_NEXT
  • SM_AGENTAPI_AGENT_KEY_UPDATE_LAST
  • SM_AGENTAPI_AGENT_KEY_UPDATE_CURRENT
  • SM_AGENTAPI_AGENT_KEY_UPDATE_PERSISTENT
  • 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

 

Return Values

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
);

Parameter

I/O

Description

nNumAttributes

I

The number of attributes in pAttributes.

pAttributes

I

A pointer to an array of response attribute definition structures.

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
);

Parameter

I/O

Description

pServers

I

The server structures to free.

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

nServer

I

The server that will process the request at the time of the tunnel call. One of these values, defined in smAgentAPI.h:

/* server ports */

/* authorization server */
#define SM_AGENTAPI_AZ_SERVER 0

/* authentication server */
#define SM_AGENTAPI_AUTH_SERVER 1

/* accounting server */
#define SM_AGENTAPI_ACCT_SERVER 2

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
);

Parameter

I/O

Description

pInit

O

A pointer to an Sm_AgentApi_Init_t structure. Sm_AgentApi_GetConfig() retrieves agent configuration information and copies each setting to a field of pInit.

To free the array of server structures that may be placed in Sm_AgentApi_Init_t, call Sm_AgentApi_FreeServers().

lpszAgentName

I

Name of the target agent. The function Sm_AgentApi_GetConfig() searches the agentname list for the agent name specified in lpszAgentName. If lpszAgentName is empty, Sm_AgentApi_GetConfig() searches for the default agent name.

In the case of a v5.x or v6.x custom agent that is configured through central host configuration, this parameter is ignored.

lpszPath

I

Full path and name of the configuration file that contains the agent configuration information. Set this parameter as an empty string ("") only for the 4QMRx web agent on IIS.

If lpszPath is an empty string, Sm_AgentApi_GetConfig() checks whether the agent is written for a WIN32 platform. If it is, the function searches the Windows Registry for configuration information. If it is not, the function returns SM_AGENTAPI_FAILURE.

Return Values

Remarks

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

With v5.x or later agent connectivity:

With 4.x agent connectivity:

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

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

pResourceContext

I

Reserved for future use. Set all fields to 0.

lpszSessionId

I

A unique identifier of the session for which the variable is to be retrieved. Variables can only be retrieved for an active session.

After a successful login, the session ID is returned in the lpszSessionId field of the structure Sm_AgentApi_Session_t.

nNumReqAttributes

I

Size of the array of attributes in pReqAttributes.

pReqAttributes

 

An array of attributes representing the names of session variables to be retrieved.

Set the variable name in the field lpszAttributeOid of structure Sm_AgentApi_Attribute_t.

Set the nAttributeFlags field of the Sm_AgentApi_Attribute_t structure to one of these values:

  • SM_AGENTAPI_REQATTR_FLAGS_NONE

Retrieve the named variable, but don’t delete it.

  • SM_AGENTAPI_REQATTR_FLAGS_DELETE

Delete the variable from the session store after retrieving it.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

Set the nAttributeFlags field of the Sm_AgentApi_Attribute_t structure to one of these values:

  • SM_AGENTAPI_REQATTR_FLAGS_NONE

Retrieve the named variable, but don’t delete it.

  • SM_AGENTAPI_REQATTR_FLAGS_DELETE

Delete the variable from the session store after retrieving it.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

pRespNumAttributes

O

Size of the array of responses in ppRespAttributes.

ppRespAttributes

O

An array of response attributes representing session variables and their values.

The value returned from this function indicates the contents of the response attribute result set, as follows:

  • SM_AGENTAPI_UNRESOLVED

Some variables could not be fetched. If a given variable can’t be fetched, the associated nAttributeFlags field of the Sm_AgentApi_Attribute_t structure is set to SM_AGENTAPI_ RESPATTR_FLAGS_UNRESOLVED.

For the variables that are fetched, the nAttributeFlags field is set to SM_AGENTAPI_RESPATTR_FLAGS_NONE.

  • SM_AGENTAPI_YES

All requested variables and their values were fetched from the session store and returned in ppRespAttributes.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

Return Values

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
);

Parameter

I/O

Description

pInitStruct

I

A pointer to information about the server.

ppHandle

O

The address of a pointer to hold the returned handle for this API session. This is an opaque type.

Returns

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:

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client asking for the resource. This is an optional parameter.

pResourceContext

I

A resource definition structure.

pRealm

O

A realm definition structure. The resource is protected by the returned realm.

Return Values

Example

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

Sm_AgentApi_IsProtectedDLP()

Checks if the defined resource is protected by SiteMinder DLP integration.

Syntax

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

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client asking for the resource. This is an optional parameter.

pResourceContext

I

A resource definition structure.

pRealm

O

A realm definition structure. The resource is protected by the returned realm.

Return Values

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:

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client that the user is logging from. This is an optional parameter. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

pResourceContext

I

A pointer to a resource definition structure.

pRealm

I

A realm definition structure.

pUserCredentials

I

A user credentials definition structure.

pSession

O

A User Session definition structure.

pNumAttributes

O

The number of attributes in ppAttributes.

ppAttributes

O

A pointer to an array of response attribute definition structures.

This function returns the following attributes, when available:

  • SM_AGENTAPI_ATTR_AUTH_DIR_OID
  • SM_AGENTAPI_ATTR_AUTH_DIR_NAME
  • SM_AGENTAPI_ATTR_AUTH_DIR_SERVER
  • SM_AGENTAPI_ATTR_AUTH_DIR_NAMESPACE
  • SM_AGENTAPI_ATTR_USERMSG
  • SM_AGENTAPI_ATTR_USERDN
  • SM_AGENTAPI_ATTR_USERUNIVERSALID
  • SM_AGENTAPI_ATTR_IDENTITYSPEC

See Remarks for information about the attributes that are set when a resource is protected by an anonymous authentication scheme.

Return Values

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:

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter pHandle of Sm_AgentApi_Init().

lpszClientIpAddr

 

I

The IP address of the client that the user is logging out from. This is an optional parameter. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

pSession

I

A session definition structure (Sm_AgentApi_Session_t) for the user’s session. The nreason field will be passed in the event issued by the Policy Server. See Sm_Api_Reason_t.

Return Values

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
);

Parameter

I/O

Description

pCertificateData

I

A pointer to a buffer.

nCertLen

I

The length in bytes of the buffer.

pCertHash

O

The buffer into which the hash is placed.

nCertHashLen

I

The size of the hash buffer in bytes. The size must be at least 20.

 

Return Values

Sm_AgentApi_SetAgentInstanceInfo()

Sets the agent instance information specified in the agent discovery data structure. All values in the Sm_AgentApi_AgentDiscovery_t are initialized to "unknown". Call this function after Sm_AgentApi_Init() to set the values of these attributes when you want the agent to come under the purview of agent discovery.

Syntax

int SM_EXTERN Sm_AgentApi_SetAgentInstnaceInfo (
   const void*                            pHandle,
   Sm_AgentApi_AgentDiscovery_t*          arrParams[]
   int						 nCount			 
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

arrParams[]

I

Array containing name/value pairs of attributes for the agent instance.

nCount

I

Number of elements in the array of attributes.

Return Values

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
);

Parameter

I/O

Description

pszAgentIdentity

I

Specifies the name to set as the default agent name. This name must match the name of the corresponding agent object on the Policy Server.

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

Return Values

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

pResourceContext

I

Reserved for future use. Set all fields to 0.

lpszSessionId

I

A unique identifier of the session for which the variable is to be set. Variables can only be set for an active session.

After a successful login, the session ID is returned in the lpszSessionId field of the structure Sm_AgentApi_Session_t.

nNumReqAttributes

I

Size of the array of session variables in pReqAttributes.

pReqAttributes

I

An array of attributes representing session variable values.

Set the variable name in the field lpszAttributeOid of structure Sm_AgentApi_Attribute_t:

  • If a variable name already exists, the associated variable value is overwritten by the value of pReqAttributes.
  • If a variable name doesn’t exist, a new variable is created.

Set the nAttributeFlags field of the Sm_AgentApi_Attribute_t structure to SM_AGENTAPI_REQATTR_FLAGS_NONE.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

pRespNumAttributes

O

Size of the array of responses in ppRespAttributes.

ppRespAttributes

O

An array of response attributes representing variables that could not be set.

If this function returns SM_AGENTAPI_UNRESOLVED, the response attribute result set will contain unresolved variables. Also, for each unresolved variable returned, the field nAttributeFlags of the structure Sm_AgentApi_Attribute_t will be set to SM_AGENTAPI_RESPATTR_UNRESOLVED.

The structure’s nAttributeId and nAttributeTTL fields are ignored.

Returns

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

nServer

I

The server that will process the request at the time of the tunnel call. One of these values, defined in smAgentAPI.h:

/* server ports */

/* authorization server */
#define SM_AGENTAPI_AZ_SERVER 0

/* authentication server */
#define SM_AGENTAPI_AUTH_SERVER 1

/* accounting server */
#define SM_AGENTAPI_ACCT_SERVER 2

lpszClientIpAddr

I

(Optional) The IP address of the client from which the user is logging.

lpszTransactionId

I

(Optional) The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID.

pResourceContext

I

A resource definition structure.

pServiceRequest

I

A service request definition structure.

pRespNumAttributes

O

The number of attributes in ppRespAttributes.

ppRespAttributes

O

A pointer to an array of response attribute definition structures. The attribute identifier SM_AGENTAPI_ATTR_SERVICE_DATA indicates that the response structure contains the data returned by the remote service. The attribute identifier SM_AGENTAPI_ATTR_STATUS_MESSAGE has the status message from the remote service.

 

Returns

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
);

Parameter

I/O

Description

ppHandle

I

The address of a pointer to the handle for this API session. This is an opaque type.

Returns

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
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

lpszClientIpAddr

I

The IP address of the client that the user is logging from. This is an optional parameter. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.

lpszTransactionId

I

The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID. This is an optional parameter.

pResourceContext

I

A resource definition structure.

pRealm

O

A realm definition structure.

pSession

I

A session definition structure.

nNumReqAttributes

I

The number of attributes in pReqAttributes.

pReqAttributes

I

An array of requested attribute definition structures.

pRespNumAttributes

O

The number of attributes in ppRespAttributes.

ppRespAttributes

O

An array of response attribute definition structures.

Returns