Programming Guides › Programming Guide for Perl › CLI Agent API Methods

CLI Agent API Methods

This section contains the following topics:

Agent Administration Methods

Resource Methods

Response Methods

Response Attribute Methods

Server Configuration Method

Session Methods

Single Sign-on Token Methods

User Methods

Agent Administration Methods

The following methods act on AgentAPI objects:

• AddServerConfig Method—Adds Policy Server Configurations to Agent API Object
• Connect Method—Establishes Connection between Agent API and Policy Server
• CreateBootstrapFile Method—Generates Bootstrap File for Connecting to Agent
• CreateUser Method—Creates a User Object
• Disconnect Method—Closes Connection between Agent and Policy Server
• DoManagement Method—Requests Agent Commands from Policy Server
• GetResource Method—Retrieves the Specified Resource
• IncrementRefCount Method—Increment the Reference Count
• New Method—Constructs the Agent API
• PrintDebugTrace Method—Outputs Trace Information to Console
• SetErrorCallback Method—Registers Subroutine that Processes Error Messages
• SetTraceCallback Method—Registers Subroutine that Processes Trace Messages

AddServerConfig Method—Adds Policy Server Configurations to Agent API Object

The AddServerConfig method adds one or more Policy Server configurations to the Agent API object. Before you can establish a connection between the Policy Server and the Agent API, you must call this method at least once.

Syntax

The AddServerConfig method has the following format:

Netegrity::AgentAPI‑>AddServerConfig(IPAddress[, minConn]
[, maxConn][, stepConn][, timeout][, azPort][, auPort]
[, acPort])

Parameters

The AddServerConfig method accepts the following parameters:

IPAddress (string)

Specifies the IP address of the Policy Server.

minConn (int)

(Optional) Specifies the minimum number of connections allowed.

maxConn (int)

(Optional) Specifies the maximum number of connections allowed.

stepConn (int)

(Optional) Specifies the number of connections to add when all existing connections are being used.

timeout (int)

(Optional) Specifies the time in seconds before the Agent API stops trying to connect to the Policy Server.

azPort (int)

(Optional) Specifies the port number for the authorization service.

auPort (int)

(Optional) Specifies the port number for the authentication service.

acPort (int)

(Optional) Specifies the port number for the accounting service.

Return Value

The AddServerConfig method returns the following value:

• AgentSvrCfg (object)

Remarks

The single-process Policy Server introduced in SiteMinder v6.0 combines the previously separate authentication, authorization, and accounting processes into one combined process whose requests go through one TCP port. As a result, the parameters azPort, auPort, and acPort all reference the same port number. The three arguments are maintained for backward compatibility.

Connect Method—Establishes Connection between Agent API and Policy Server

The Connect method establishes a connection between the Agent API and the Policy Server.

Syntax

The Connect method has the following format:

Netegrity::AgentAPI‑>Connect([bootFile])

Parameters

The Connect method accepts the following parameter:

bootFile (string)

(Optional) Specifies the name of the configuration file to be used for connecting to a v5.x agent.

Note: You can use an existing file such as SmHost.conf or create a new file. For more information, see the method AgentAPI‑>CreateBootstrapFile.

Return Value

The Connect method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the connection was successful.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the Agent API could not reach the Policy Server.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization failed.

CreateBootstrapFile Method—Generates Bootstrap File for Connecting to Agent

The CreateBootstrapFile method generates a bootstrap file that the Policy Server can use for connecting to a v5.x agent. The bootstrap file contains the settings specified by the method's parameters. Once the connection is made, the Policy Server can provide the remaining settings. SmHost.conf is an example of a bootstrap file.

Syntax

The CreateBootstrapFile method has the following format:

Netegrity::AgentAPI‑>CreateBootstrapFile(trustedHostName, ipAddress,
hostConfigName, sharedSecret, registrationDataFileName)

Parameters

The CreateBootstrapFile method accepts the following parameters:

trustedHostName (string)

Specifies the name of the trusted host.

ipAddress (string)

Specifies the IP address of the Policy Server.

hostConfigName (string)

Specifies the name of the host configuration object.

sharedSecret (string)

Specifies the value of the shared secret used by the host.

registrationDataFileName (string)

Specifies the name of the bootstrap file generated by the method.

Return Value

The CreateBootstrapFile method returns one of the following values:

• file_name (string)

  Specifies the name of the newly-created file.

• empty_string (string)

  Specifies that the method failed.

Example

The following code fragment is an example of how to use the CreateBootstrapFile method:

# A shared secret is not specified in the context of a v5.x agent.
# A v5.x agent by the specified name needs to exist in the policy
# store. Use Netegrity::AgentAPI.

$agentapi = Netegrity::AgentAPI‑>New($agentname);

# Create the bootstrap file.

$agentapi‑>CreateBootstrapFile($thostname, $ipaddr, $hconfname, $secret, $fname);

# Notice that in the v5.x context, the connect() method takes a filename.

$agentapi‑>Connect($fname);

CreateUser Method—Creates a User Object

The CreateUser method creates a user object containing the information passed to the method in the parameters. Perl uses this object to perform user operations, such as login.

Note: This method does not create a new user in the user directory.

Syntax

The CreateUser method has the following format:

Netegrity::AgentAPI‑>CreateUser(Username, Password[, cert][, certLength])

Parameters

The CreateUser method accepts the following parameters:

Username (string)

Specifies the user's ID.

Password (string)

Specifies the user's password.

cert (string)

(Optional) Specifies an X.509 certificate for user authentication.

certLength (int)

(Optional) Specifies the length of the certificate.

Return Value

The CreateUser method returns one of the following values:

• AgentUser (object)
• undef

  Specifies that the method failed.

Disconnect Method—Closes Connection between Agent and Policy Server

The Disconnect method closes the connection between the Agent and the Policy Server.

Syntax

The Disconnect method has the following format:

Netegrity::AgentAPI‑>Disconnect()

Parameters

The Disconnect method accepts no parameters.

Return Value

The Disconnect method returns one of the following values:

• SM_AGENT_SUCCESS (value = 0)

  Specifies that the connection was closed successfully.

• SM_AGENT_FAILURE (value = 1)

  Specifies that the connection was not successfully closed.

DoManagement Method—Requests Agent Commands from Policy Server

The DoManagement method requests the list of Agent commands pending from the Policy Server and returns them in an array. To access the commands in the array, call the AgentResponseAttr‑>GetID method.

Syntax

The DoManagement method has the following format:

Netegrity::AgentAPI‑>DoManagement()

Parameters

The DoManagement method accepts no parameters.

Return Value

The DoManagement method returns one of the following values:

• AgentResponseAttr (array)
• undef

  Specifies that there are no pending Agent commands.

GetResource Method—Retrieves the Specified Resource

The GetResource method retrieves the specified resource.

Syntax

The GetResource method has the following format:

Netegrity::AgentAPI‑>GetResource(resName[, action][, clientIP])

Parameters

The GetResource method accepts the following parameters:

resName (string)

Specifies the name of the resource to retrieve.

action (string)

(Optional) Specifies the HTTP action to perform (for example, GET, POST, or PUT).

clientIP (string)

(Optional) Specifies the client's IP address.

Return Value

The GetResource method returns the following value:

• AgentResource (object)

IncrementRefCount Method—Increment the Reference Count

You can call the IncrementRefCount method when the Agent API is operating in multi-threaded mode. After calling the Perl function fork, for example, you can call this method within the child process.

Syntax

The IncrementRefCount method has the following format:

Netegrity::AgentAPI‑>IncrementRefCount()

Parameters

The IncrementRefCount method accepts no parameters.

Return Value

The IncrementRefCount method does not return a value.

New Method—Constructs the Agent API

The New method constructs the Agent API object and must be called before the Agent API object can be used.

Syntax

The New method has the following format:

Netegrity::AgentAPI‑>New(agentName[, sharedSecret][, failover])

Parameters

The New method accepts the following parameters:

pagentName (string)

Specifies the name of the agent as it appears in the policy store.

Note: The agent name is not case-sensitive.

psharedSecret (string)

(Optional) Specifies the shared secret as it appears in the policy store.

Note: If you provide a value for the shared secret, a v4.x agent object is created. If you do not provide a value for the shared secret, a v5.x agent object is created. The shared secret is case-sensitive.

failover (int)

(Optional) Specifies whether to enable or disable failover operation:

• value = -1

  Specifies enabling failover operation.

• value = 0

  Specifies disabling failover operation.

Return Value

The New method returns the following value:

• AgentAPI (object)

PrintDebugTrace Method—Outputs Trace Information to Console

The PrintDebugTrace method enables or disables the output of error or trace information to the console and returns the value of 1 or 0, respectively.

Syntax

The PrintDebugTrace method has the following format:

Netegrity::AgentAPI‑>PrintDebugTrace([debugFlag])

Parameters

The PrintDebugTrace method accepts the following parameter:

debugFlag (int)

(Optional) Specifies enabling or disabling output of error or trace information to the console:

• value = 1

  Specifies enabling output.

• value = 0

  Specifies disabling output.

Return Value

The PrintDebugTrace method returns one of the following integer values:

• value = 1

  Specifies that output is enabled.

• value = 0

  Specifies that output is disabled.

ProcessAuthResponse Method--Extracts Information from a Login of Change Password

The ProcessAuthResponse method extracts pertinent information returned from a login or change password.

Syntax

The ProcessAuthResponse method has the following format:

Netegrity::AgentAPI‑>GetResource(UserCreds)

Parameters

The ProcessAuthResponse method accepts the following parameter:

UserCreds (UserCredentials)

Specifies the user credentials from a login or change password call

Return Value

The ProcessAuthResponse method returns the pertinent information as a string.

SetErrorCallback Method—Registers Subroutine that Processes Error Messages

The SetErrorCallback method registers a user-defined Perl subroutine that processes SiteMinder error messages. If multiple subroutines are registered, SiteMinder calls the most recently registered subroutine.

Syntax

The SetErrorCallback method has the following format:

Netegrity::AgentAPI‑>SetErrorCallback(subref)

Parameters

The SetErrorCallback method accepts the following parameter:

subref (string)

Specifies the name of the Perl subroutine or a reference to the subroutine:

• name

  Example:

  $agentapi‑>SetErrorCallback("CustomErrorHandler");
  

• reference

  Example:

  $agentapi‑>SetErrorCallback(\&CustomErrorHandler);
  

Return Value

The SetErrorCallback method returns one of the following integer values:

• value = 1

  Specifies that registration was successful.

• value = 0

  Specifies that registration failed.

SetTraceCallback Method—Registers Subroutine that Processes Trace Messages

The SetTraceCallback method registers a user-defined Perl subroutine that processes SiteMinder trace messages. If multiple subroutines are registered, SiteMinder calls the most recently registered subroutine.

Syntax

The SetTraceCallback method has the following format:

Netegrity::AgentAPI‑>SetTraceCallback(subref[, mode][, delim]
[, configFileName])

Parameters

The SetTraceCallback method accepts the following parameters:

subref (string)

Specifies the name of the Perl subroutine or a reference to the subroutine:

• name

  Example:

  $agentapi‑>SetErrorCallback("CustomTraceHandler");
  

• reference

  Example:

  $agentapi‑>SetErrorCallback(\&CustomTraceHandler);
  

  mode (string)

(Optional) Specifies an output format for the trace messages:

• default

  Specifies fields enclosed by square brackets.

• fixed

  Specifies fixed-width fields.

• delim

  Specifies using a character to delimit the fields.

• xml

  Specifies fields enclosed by XML-like tags.

  delim (string)

(Optional) Specifies the character to use as a delimiter when mode is set to delim.

configFileName (string)

(Optional) Specifies the name of the configuration file that specifies the data to be included in the trace.

Default: If no filename is specified, default settings are used.

Return Value

The SetTraceCallback method returns one of the following integer values:

• value = 1

  Specifies that registration was successful.

• value = 0

  Specifies that registration failed.

Resource Methods

The following methods act on AgentResource objects:

• GetAuthType Method—Retrieves the Type of Credentials Required
• IsProtected Method—Checks whether SiteMinder Is Protecting Resource

GetAuthType Method—Retrieves the Type of Credentials Required

The GetAuthType method retrieves the type of credentials required for successful login to the resource or realm.

Syntax

The GetAuthType method has the following format:

Netegrity::AgentResource‑>GetAuthType()

Parameters

The GetAuthType method accepts no parameters.

Return Value

The GetAuthType method returns one of the following values:

• Sm_AuthApi_Cred_None (value = 0x00)

  Specifies that no credentials are required.

  Note: This authorization type is used for anonymous realms.

• Sm_AuthApi_Cred_Basic (value = 0x01)

  Specifies that a username and password are required.

• Sm_AuthApi_Cred_Digest (value = 0x02)

  Specifies that the username and password must be exchanged using the digest protocol.

• Sm_AuthApi_Cred_X509Cert (value = 0x04)

  Specifies that a full X.509 client certificate is required.

• Sm_AuthApi_Cred_X509CertUserDN (value = 0x08)

  Specifies that the user DN from an X.509 client certificate is required.

• Sm_AuthApi_Cred_X509CertIssuerDN (value = 0x10)

  Specifies that the issuer DN from an X.509 client certificate is required.

• Sm_AuthApi_Cred_CertOrBasic (value = 0x20)

  Specifies that a certificate is required, if available.

  Note: If a certificate is not available, a username and password are required.

• Sm_AuthApi_Cred_NTChalResp (value = 0x40)

  Specifies that the username and password must be exchanged using the NT challenge/response protocol.

• Sm_AuthApi_Cred_CertOrForm (value = 0x80)

  Specifies that either an X.509 certificate or a forms-based authentication scheme is required.

• Sm_AuthApi_Cred_SSLRequired (value = 0x01000000)

  Specifies that an SSL connection is required.

• Sm_AuthApi_Cred_FormRequired (value = 0x02000000)

  Specifies that the user must be redirected to an HTML form.

• Sm_AuthApi_Cred_AllowSaveCreds (value = 0x04000000)

  Specifies that the credentials can be saved for 30 days

  Note: When credentials are saved, users are not required to re-enter them each time they access a protected resource.

• Sm_AuthApi_Cred_PreserveSessionID (value = 0x08000000)

  Specifies that the Session ID be preserved for as long as the current session is valid.

• Sm_AuthApi_Cred_DoNotChallenge (value = 0x10000000)

  Specifies that the user not be challenged for credentials.

• undef

  Specifies that the resource is not protected.

IsProtected Method—Checks whether SiteMinder Is Protecting Resource

The IsProtected method checks whether SiteMinder is protecting the defined resource.

Syntax

The IsProtected method has the following format:

Netegrity::AgentResource‑>IsProtected()

Parameters

The IsProtected method accepts no parameters.

Return Value

The IsProtected method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the resource is protected.

• SM_AGENTAPI_NO (value = 2)

  Specifies that the resource is not protected.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the Policy Server could not be reached.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization failed.

Response Methods

The following methods act on AgentResponse objects:

• GetAttributes Method—Retrieves List of Available Response Attributes
• GetSession Method—Retrieves the Session from the Response

GetAttributes Method—Retrieves List of Available Response Attributes

The GetAttributes method retrieves the list of available response attributes and returns them in an array. Use this method after successful calls to AgentUser‑>Login or AgentUser‑>GetResponse. To identify the types of response attributes in the array, call the AgentResponseAttr‑>GetID method.

Syntax

The GetAttributes method has the following format:

Netegrity::AgentResponse‑>GetAttributes()

Parameters

The GetAttributes method accepts no parameters.

Return Value

The GetAttributes method returns one of the following values:

• AgentResponseAttr (array)
• undef

  Specifies that the method failed.

GetSession Method—Retrieves the Session from the Response

The GetSession method retrieves the session object from the response.

Syntax

The GetSession method has the following format:

Netegrity::AgentResponse‑>GetSession()

Parameters

The GetSession method accepts no parameters.

Return Value

The GetSession method returns one of the following values:

• AgentSession (object)
• undef

  Specifies that the method failed.

Response Attribute Methods

The following methods act on AgentResponseAttr objects:

• GetFlags Method—Retrieves Response Attribute's Flags
• GetID Method—Retrieves Response Attribute's ID or Agent Command's ID
• GetName Method—Retrieves Response Attribute's Name
• GetTTL Method—Retrieves Response Attribute's TTL Value
• GetValue Method—Retrieves Response Attribute's Value

GetFlags Method—Retrieves Response Attribute's Flags

The GetFlags method retrieves the response attribute's flags.

Syntax

The GetFlags method has the following format:

Netegrity::AgentResponseAttr‑>GetFlags()

Parameters

The GetFlags method accepts no parameters.

Return Value

The GetFlags method returns the following value:

• existing_response_attribute_flags

GetID Method—Retrieves Response Attribute's ID or Agent Command's ID

The GetID method retrieves a response attribute ID or an agent command ID.

Syntax

The GetID method has the following format:

Netegrity::AgentResponseAttr‑>GetID()

Parameters

The GetID method accepts no parameters.

Return Value

The GetID method returns a response attribute ID after AgentResponse‑>GetAttributes is called or an agent command ID after AgentAPI‑>DoManagement is called. In either case, the return value's type is long.

• AgentResponse‑>GetAttributes retrieves a list of response attributes and returns them in an array. When GetID is called after AgentResponse‑>GetAttributes is called, GetID returns one of the following response attribute IDs (long):
  • SM_AGENTAPI_ATTR_AUTH_DIR_OID (value = 151)

    Specifies the internal SiteMinder object ID for the user directory where the user was authenticated.

  • SM_AGENTAPI_ATTR_USERUNIVERSALID (value = 152)

    Specifies the user's universal ID.

  • SM_AGENTAPI_ATTR_IDENTITYSPEC (value = 156)

    Specifies the user's identity ticket.

    Note: This value is returned if user tracking is enabled.

  • SM_AGENTAPI_ATTR_SESSIONDRIFT (value = 167)

    Specifies the maximum time in minutes, during which actual session data is validated against session data stored in a cookie.

  • SM_AGENTAPI_ATTR_AUTH_DIR_NAME (value = 213)

    Specifies the directory name as it appears in the Name field of the SiteMinder User Directory dialog.

  • SM_AGENTAPI_ATTR_AUTH_DIR_SERVER (value = 214)

    Specifies the server specification as it appears in the Server field of the SiteMinder User Directory dialog.

  • SM_AGENTAPI_ATTR_AUTH_DIR_NAMESPACE (value = 215)

    Specifies the user directory's namespace: LDAP, AD, WinNT, or ODBC.

  • SM_AGENTAPI_ATTR_USERMSG (value = 216)

    Specifies the text presented to the user following an authentication attempt.

    Note: This text could be an authentication challenge or a reason why authentication failed.

  • SM_AGENTAPI_ATTR_USERDN (value = 218)

    Specifies the user's distinguished name.

• AgentAPI‑>DoManagement retrieves a list of agent commands pending from the Policy Server and returns them in an array. When GetID is called after AgentAPI‑>DoManagement is called, GetID returns one of the following agent command IDs (long):
  • SM_AGENTAPI_AFFILIATE_KEY_UPDATE (value = 189)

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

  • SM_AGENTAPI_AGENT_KEY_UPDATE_NEXT (value = 190)

    Instructs the agent to update its "next" agent key.

    Note: The encrypted value contains 24 bytes of binary data.

  • SM_AGENTAPI_AGENT_KEY_UPDATE_LAST (value = 191)

    Instructs the agent to update its "last" agent key.

    Note: The encrypted value contains 24 bytes of binary data.

  • SM_AGENTAPI_AGENT_KEY_UPDATE_CURRENT (value = 192)

    Instructs the agent to update its "current" agent key.

    Note: The encrypted value contains 24 bytes of binary data.

  • SM_AGENTAPI_AGENT_KEY_UPDATE_PERSISTENT (value = 193)

    Instructs the agent to update its static (persistent) agent key.

    Note: The encrypted value contains 24 bytes of binary data.

  • SM_AGENTAPI_CACHE_FLUSH_ALL (value = 194)

    Instructs the agent to flush all information in its caches.

  • SM_AGENTAPI_CACHE_FLUSH_ALL_USERS (value = 195)

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

  • SM_AGENTAPI_CACHE_FLUSH_THIS_USER (value = 196)

    Instructs the agent to flush all cache information for a given user.

  • SM_AGENTAPI_CACHE_FLUSH_ALL_REALMS (value = 197)

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

  • SM_AGENTAPI_CACHE_FLUSH_THIS_REALM (value = 198)

    Instructs the agent to flush all resource information for a given realm.

GetName Method—Retrieves Response Attribute's Name

The GetName method retrieves the name of the response attribute.

Syntax

The GetName method has the following format:

Netegrity::AgentResponseAttr‑>GetName()

Parameters

The GetName method accepts no parameters.

Return Value

The GetName method returns the following value:

• response_attribute_name (string)

GetTTL Method—Retrieves Response Attribute's TTL Value

The GetTTL method retrieves the response attribute's Time To Live (TTL) value.

Syntax

The GetTTL method has the following format:

Netegrity::AgentResponseAttr‑>GetTTL()

Parameters

The GetTTL method accepts no parameters.

Return Value

The GetTTL method returns the following value:

• Time_To_Live_value (long)

GetValue Method—Retrieves Response Attribute's Value

The GetValue method retrieves the response attribute's value.

Syntax

The GetValue method has the following format:

Netegrity::AgentResponseAttr‑>GetValue()

Parameters

The GetValue method accepts no parameters.

Return Value

The GetValue method returns the following value:

• response_attribute_value (string)

Server Configuration Method

The following method acts on AgentSvrCfg objects:

• IPAddress Method—Sets or Retrieves Policy Server's IP Address

IPAddress Method—Sets or Retrieves Policy Server's IP Address

The IPAddress method sets or retrieves the IP address of the Policy Server.

Syntax

The IPAddress method has the following format:

Netegrity::AgentSvrCfg‑>IPAddress([IPAddress])

Parameters

The IPAddress method accepts the following parameter:

IPAddress (string)

(Optional) Specifies the IP address of the Policy Server.

Return Value

The IPAddress method returns the following value:

• IP_address (string)

  Specifies the IP address of the Policy Server.

Session Methods

The following methods act on AgentSession objects:

• AddParameter Method—Adds Session Variable Name-Value Pair to Parameters List
• DelVariables Method—Deletes Session Variables from Session Store
• GetID Method—Retrieves the Session ID
• GetReason Method—Retrieves the Session's Reason ID
• GetSpec Method—Retrieves the Encrypted Session Specification
• GetVariables Method—Retrieves Session Variables from Session Store
• IdleTimeout Method—Retrieves Session's Idle Timeout Value
• MaxTimeout Method—Retrieves Session's Maximum Timeout Value
• SetVariables Method—Writes Session Variables to Session Store

AddParameter Method—Adds Session Variable Name-Value Pair to Parameters List

The AddParameter method adds a session variable name-value pair to a parameters list. Session variables contain data about the client application, such as business logic, certificate information, and SAML assertions for Affiliate applications. This data is bound to a user session.

Syntax

The AddParameter method has the following format:

Netegrity::AgentSession‑>AddParameter(varName [,varValue][, varFlag])

Parameters

The AddParameter method accepts the following parameters:

varName (string)

Specifies the name of the variable to add to the parameter list.

Limit: Maximum length is 255 characters.

varValue (string)

(Optional) Specifies the value of the variable to be added to the parameter list.

Limit: Maximum length is determined by the target data store.

varFlag (int)

(Optional) Specifies whether the GetVariables method deletes the variable name-value pair from the session store:

• 0 (zero)

  Specifies that GetVariables retrieves the variable name-value pair from the session store, but does not delete it.

• 1 (one)

  Specifies that GetVariables retrieves the variable name-value pair from the session store and then deletes it.

Return Value

The AddParameter method does not return a value.

Remarks

You can manage the name-value pairs in the parameters list by calling these session variable methods:

• AgentSession‑>DelVariables
• AgentSession‑>GetVariables
• AgentSession‑>SetVariables

To manage multiple variables, call AddParameter once for each variable before calling the AgentSession‑>DelVariables, AgentSession‑>GetVariables, and AgentSession‑>SetVariables methods. While AddParameter adds variables to the parameters list, AgentSession‑>DelVariables, AgentSession‑>GetVariables, and AgentSession‑>SetVariables clear the parameters list.

Before you can use the session variable methods, the following conditions must be met:

• A persistent session must be created in at least one realm.
• The SiteMinder session store must be enabled.

Note: For more information, see the Policy Server Administration Guide and the Policy Server Configuration Guide.

DelVariables Method—Deletes Session Variables from Session Store

The DelVariables method deletes the session variables in the parameters list from the session store. Call AgentSession‑>AddParameter first to specify the variables in the parameters list.

Syntax

The DelVariables method has the following format:

Netegrity::AgentSession‑>DelVariables()

Parameters

The DelVariables method accepts no parameters.

Return Value

The DelVariables method does not return a value.

Remarks

The DelVariables method clears the parameters list.

GetID Method—Retrieves the Session ID

The GetID method retrieves the session ID.

Syntax

The GetID method has the following format:

Netegrity::AgentSession‑>GetID()

Parameters

The GetID method accepts no parameters.

Return Value

The GetID method returns the following value:

• session_ID (string)

GetReason Method—Retrieves the Session's Reason ID

The GetReason method retrieves the session's reason ID. The reason ID specifies a reason for a failed authentication or authorization.

Syntax

The GetReason method has the following format:

Netegrity::AgentSession‑>GetReason()

Parameters

The GetReason method accepts no parameters.

Return Value

The GetReason method returns one of the following values (long):

• Sm_Api_Reason_None (value = 0)
• Sm_Api_Reason_PwMustChange (value = 1)
• Sm_Api_Reason_InvalidSession (value = 2)
• Sm_Api_Reason_RevokedSession (value = 3)
• Sm_Api_Reason_ExpiredSession (value = 4)
• Sm_Api_Reason_AuthLevelTooLow (value = 5)
• Sm_Api_Reason_UnknownUser (value = 6)
• Sm_Api_Reason_UserDisabled (value = 7)
• Sm_Api_Reason_InvalidSessionId (value = 8)
• Sm_Api_Reason_InvalidSessionIp (value = 9)
• Sm_Api_Reason_CertificateRevoked (value = 10)
• Sm_Api_Reason_CRLOutOfDate (value = 11)
• Sm_Api_Reason_CertRevokedKeyCompromised (value = 12)
• Sm_Api_Reason_CertRevokedAffiliationChange (value = 13)
• Sm_Api_Reason_CertOnHold (value = 14)
• Sm_Api_Reason_TokenCardChallenge (value = 15)
• Sm_Api_Reason_ImpersonatedUserNotInDir (value = 16)
• Sm_Api_Reason_Anonymous (value = 17)
• Sm_Api_Reason_PwWillExpire (value = 18)
• Sm_Api_Reason_PwExpired (value = 19)
• Sm_Api_Reason_ImmedPWChangeRequired (value = 20)
• Sm_Api_Reason_PWChangeFailed (value = 21)
• Sm_Api_Reason_BadPWChange (value = 22)
• Sm_Api_Reason_PWChangeAccepted (value = 23)
• Sm_Api_Reason_ExcessiveFailedLoginAttempts (value = 24)
• Sm_Api_Reason_AccountInactivity (value = 25)
• Sm_Api_Reason_NoRedirectConfigured (value = 26)
• Sm_Api_Reason_ErrorMessageIsRedirect (value = 27)
• Sm_Api_Reason_Next_Tokencode (value = 28)
• Sm_Api_Reason_New_PIN_Select (value = 29)
• Sm_Api_Reason_New_PIN_Sys_Tokencode (value = 30)
• Sm_Api_Reason_New_User_PIN_Tokencode (value = 31)
• Sm_Api_Reason_New_PIN_Accepted (value = 32)
• Sm_Api_Reason_Guest (value = 33)
• Sm_Api_Reason_PWSelfChange (value = 34)
• Sm_Api_Reason_ServerException (value = 35)
• Sm_Api_Reason_UnknownScheme (value = 36)
• Sm_Api_Reason_UnsupportedScheme (value = 37)
• Sm_Api_Reason_Misconfigured (value = 38)
• Sm_Api_Reason_BufferOverflow (value = 39)
• Sm_Api_Reason_SetPersistentSessionFailed (value = 40)

GetSpec Method—Retrieves the Encrypted Session Specification

The GetSpec method retrieves the encrypted session specification. The session specification includes information about the user session, such as the session start time, timeout parameters, and the user's distinguished name. You can use the session specification to identify a session across multiple Web sites, as you would for single sign-on applications.

Syntax

The GetSpec method has the following format:

Netegrity::AgentSession‑>GetSpec()

Parameters

The GetSpec method accepts no parameters.

Return Value

The GetSpec method returns the following value:

• encrypted_session_specification (string)

Remarks

Where the session specification is stored depends on the type of session:

• Non-persistent Sessions

  The session specification is stored in a cookie.

• Persistent Sessions

  The session specification is stored in a session store database and optionally in a cookie on the client.

  Note: The session ticket is used as an index to the actual user session data stored in the Web agent's cache.

GetVariables Method—Retrieves Session Variables from Session Store

The GetVariables method retrieves the session variables in the parameters list from the session store. Call AgentSession‑>AddParameter first to specify the variables in the parameters list. To delete a variable from the session store after it is retrieved, call AgentSession‑>AddParameter with varFlag set to 1 (one).

Syntax

The GetVariables method has the following format:

Netegrity::AgentSession‑>GetVariables()

Parameters

The GetVariables method accepts no parameters.

Return Value

The GetVariables method returns the following value:

• AgentResponseAttr (array)

Note: Some session variables cannot be retrieved. To check for these, call AgentResponseAttr‑>GetFlags for the associated AgentResponseAttr object and test for the following return value:

SM_AGENTAPI_RESPATTR_FLAGS_UNRESOLVED (value = 2)

Remarks

The GetVariables method clears the parameters list.

IdleTimeout Method—Retrieves Session's Idle Timeout Value

The IdleTimeout method retrieves the session's idle timeout value in seconds. The idle timeout value is the maximum length of time a user session can be inactive. When this time is exceeded, the session is no longer valid and the user must re-authenticate.

Syntax

The IdleTimeout method has the following format:

Netegrity::AgentSession‑>IdleTimeout()

Parameters

The IdleTimeout method accepts no parameters.

Return Value

The IdleTimeout method returns the following value:

• idle_timeout_value (long)

MaxTimeout Method—Retrieves Session's Maximum Timeout Value

The MaxTimeout method retrieves the session's maximum timeout value in seconds. The maximum timeout value is the length of time a user session can be active. When this time is exceeded, the user must re-authenticate.

Syntax

The MaxTimeout method has the following format:

Netegrity::AgentSession‑>MaxTimeout()

Parameters

The MaxTimeout method accepts no parameters.

Return Value

The MaxTimeout method returns the following value:

• maximum_timeout_value (long)

SetVariables Method—Writes Session Variables to Session Store

The SetVariables method writes the session variables in the parameters list to the session store. Call AgentSession‑>AddParameter first to specify the variables in the list. If a variable exists in the session store, its value is updated to the new value. If the variable does not exist, a new variable is created.

Syntax

The SetVariables method has the following format:

Netegrity::AgentSession‑>SetVariables()

Parameters

The SetVariables method accepts no parameters.

Return Value

The SetVariables method does not return a value.

Remarks

The SetVariables method clears the parameters list.

Single Sign-on Token Methods

The following methods act on SSOToken objects:

• Decode Method—Decodes a Single Sign-on Token
• GetString Method—Retrieves String Representation of SSO Token Object
• GetVersion Method—Retrieves SiteMinder Version of SSO Token
• IsThirdParty Method—Determines Whether the Token Is Custom

Decode Method—Decodes a Single Sign-on Token

The Decode method decodes a single sign-on token and returns a subset of its attributes. In addition, you have the option of updating the token's last-accessed timestamp by passing a non-zero value to this method. To retrieve the updated token in string format, call SSOToken‑>GetString and write the token string to the SMSESSION cookie.

Syntax

The Decode method has the following format:

Netegrity::SSOToken‑>Decode([update])

Parameters

The Decode method accepts the following parameter:

update (int)

(Optional) Specifies whether an updated token is requested:

• value = non-zero

  Specifies that an updated token is requested.

• value = 0 (default)

  Specifies that an updated token is not requested.

Return Value

The Decode method returns one of the following values:

• an array of attributes containing a subset of the following:
  • ATTR_CLIENTIP

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

  • ATTR_DEVICENAME

    Specifies the name of the agent that is decoding the token.

  • ATTR_IDLESESSIONTIMEOUT

    Specifies the maximum idle time for a session.

  • ATTR_LASTSESSIONTIME

    Specifies the time when the Policy Server was last accessed within the session.

  • ATTR_MAXSESSIONTIMEOUT

    Specifies the maximum time that a session can be active.

  • ATTR_SESSIONID

    Specifies the session ID returned from the login call.

  • ATTR_SESSIONSPEC

    Specifies the session specification returned from the login call.

  • ATTR_STARTSESSIONTIME

    Specifies when the session started after a successful login.

  • ATTR_USERDN

    Specifies the user's distinguished name.

  • ATTR_USERNAME

    Specifies the user's name.

• undef

  Specifies that the method failed.

Remarks

To create a single sign-on object, call AgentUser‑>CreateSSOToken.

GetString Method—Retrieves String Representation of SSO Token Object

The GetString method retrieves the string representation of a single sign-on token object. After calling GetString, you can write the token string to the SMSESSION cookie.

Syntax

The GetString method has the following format:

Netegrity::SSOToken‑>GetString()

Parameters

The GetString method accepts no parameters.

Return Value

The GetString method returns the following value:

• SSO_token (string)

Remarks

You can call GetString after creating a single sign-on token object with CreateSSOToken. You can also call GetString after updating the token's last-accessed timestamp with Decode.

GetVersion Method—Retrieves SiteMinder Version of SSO Token

The GetVersion method retrieves the SiteMinder version of the single sign-on token.

Syntax

The GetVersion method has the following format:

Netegrity::SSOToken‑>GetVersion()

Parameters

The GetVersion method accepts no parameters.

Return Value

The GetVersion method returns the following value:

• version (int)

  Specifies the SiteMinder version of the single sign-on token.

IsThirdParty Method—Determines Whether the Token Is Custom

The IsThirdParty method determines whether the token was originally produced by a custom (or third-party) agent and has not yet been updated by a standard SiteMinder agent.

Syntax

The IsThirdParty method has the following format:

Netegrity::SSOToken‑>IsThirdParty()

Parameters

The IsThirdParty method accepts no parameters.

Return Value

The IsThirdParty method returns one of the following integer values:

• value = non-zero

  Specifies that the token was originally produced by a custom agent and has not yet been updated by a standard SiteMinder agent.

• value = 0

  Specifies that the token was not produced by a custom agent or has been updated by a standard SiteMinder agent.

User Methods

The following methods act on AgentUser objects:

• Audit Method—Audits Authorizations Performed out of Agent Cache
• Certificate Method—Sets or Retrieves User's X.509 Certificate
• CertificateFile Method—Sets or Retrieves User's X.509 Certificate Using File
• CreateSSOToken Method—Creates Single Sign-on Token Object
• CustomData Method—Sets or Retrieves Custom Authentication Data
• FormData Method—Sets or Retrieves HTML Forms-based Authentication Data
• GetResponse Method—Returns Response After IsAuthorized or Login
• Impersonate Method—Allows One User to Impersonate Another
• IsAuthorized Method—Determines Whether User Is Authorized
• Login Method—Performs Session Login and Validation
• Logout Method—Logs the User out of the Session
• Name Method—Sets or Retrieves the User's Username
• Password Method—Sets or Retrieves the User's Password
• Validate Method—Validates a Session Specification

Audit Method—Audits Authorizations Performed out of Agent Cache

The Audit method audits authorizations performed out of the agent cache.

Syntax

The Audit method has the following format:

Netegrity::AgentUser‑>Audit()

Parameters

The Audit method accepts no parameters.

Return Value

The Audit method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the audit was successful.

• SM_AGENTAPI_NO (value = 2)

  Specifies that the audit was not successful.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the Policy Server could not be reached.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization failed.

Certificate Method—Sets or Retrieves User's X.509 Cerficate

The Certificate method sets or retrieves the user's X.509 certificate. This method only affects the certificate data associated with the current instance of the user object.

Syntax

The Certificate method has the following format:

Netegrity::AgentUser‑>Certificate([cert, certBinaryLen])

Parameters

The Certificate method accepts the following parameters:

cert (string)

(Optional) Specifies the certificate data to set.

certBinaryLen (int)

(Optional) Specifies the length of the certificate.

Return Value

The Certificate method returns one of the following values:

• ($String, $Length)

  Specifies the new or existing certificate's data and length.

• undef

  Specifies that the method failed.

CertificateFile Method—Sets or Retrieves User's X.509 Certificate Using File

The CertificateFile method sets or retrieves the user's X.509 certificate using the specified certificate file.

Syntax

The CertificateFile method has the following format:

Netegrity::AgentUser‑>CertificateFile([certFile[, format]])

Parameters

The CertificateFile method accepts the following parameters:

certFile (string)

(Optional) Specifies the full path and file name of the certificate file.

format (string)

(Optional) Specifies the format of the certificate file.

Default: base64 encoded X.509 (value = 1)

Note: The default is the only supported file format.

Return Value

The CertificateFile method returns the following value:

• ($String, $Length)

  Specifies the new or existing certificate's data and length.

CreateSSOToken Method—Creates Single Sign-on Token Object

The CreateSSOToken method creates a single sign-on token object from a valid user session. The token contains encrypted session and other information that a custom agent can share with a standard SiteMinder Web agent. Creating single sign-on between standard and custom agents requires that the agents be in the same domain. To create the single sign-on object, the user must be logged in to the custom agent, not the SiteMinder agent.

Syntax

The CreateSSOToken method has the following format:

Netegrity::AgentUser‑>CreateSSOToken(szDn, szName, szIP)

Parameters

The CreateSSOToken method accepts the following parameters:

szDn (string)

Specifies the user's distinguished name.

szName (string)

Specifies the user's name.

szIP (string)

Specifies the IP address of the machine, where the user initiates the request for a protected resource.

Return Value

The CreateSSOToken method returns the following value:

• SSOToken (object)

Remarks

To retrieve the token object in string format, use the GetString method and write the token string to the SMSESSION cookie. To decode the token and retrieve a subset of its attributes, use the Decode method.

CustomData Method—Sets or Retrieves Custom Authentication Data

The CustomData method sets or retrieves custom authentication data. This method is used to test authentication schemes that are based on the Custom Template. The format and content of custom authentication data are customer-defined according to the requirements of each Web site.

Syntax

The CustomData method has the following format:

Netegrity::AgentUser‑>CustomData([customData, length])

Parameters

The CustomData method accepts the following parameters:

customData (string)

(Optional) Specifies the custom authentication data to set.

length (int)

(Optional) Specifies the length of the custom authentication data.

Return Value

The CustomData method returns one of the following values:

• ($String, $Length)

  Specifies the new or existing custom authentication data and length.

• undef

  Specifies that the method failed.

FormData Method—Sets or Retrieves HTML Forms-based Authentication Data

The FormData method sets or retrieves HTML forms-based authentication data. This method is used to test authentication schemes that are based on the HTML Forms Template. The formData string consists of attribute name-value pairs separated by the ampersand (&) character.

Example:

"PASSWORD=$password1&email=$username1@mycompany.com"

Syntax

The FormData method has the following format:

Netegrity::AgentUser‑>FormData([formData])

Parameters

The FormData method accepts the following parameter:

formData (string)

(Optional) Specifies the HTML forms-based authentication data to set.

Return Value

The FormData method returns one of the following values:

• authentication_data

  Specifies the new or existing HTML forms-based authentication data.

• undef

  Specifies that the method failed.

GetResponse Method—Returns Response After IsAuthorized or Login

The GetResponse method returns a response after AgentUser‑>IsAuthorized or AgentUser‑>Login is called regardless of whether the user is authorized.

Syntax

The GetResponse method has the following format:

Netegrity::AgentUser‑>GetResponse()

Parameters

The GetResponse method accepts no parameters.

Return Value

The GetResponse method returns one of the following values:

• AgentResponse (object)
• undef

  Specifies that the method failed, because neither AgentUser‑>IsAuthorized or AgentUser‑>Login was called before calling GetResponse.

Impersonate Method—Allows One User to Impersonate Another

The Impersonate method allows one user to impersonate another user by logging in as that user. For example, a customer service representative can impersonate a customer to better understand a software problem that the customer is having.

Syntax

The Impersonate method has the following format:

Netegrity::AgentUser‑>Impersonate(username, resource)

Parameters

The Impersonate method accepts the following parameters:

username (string)

Specifies the ID of the user to impersonate.

resource (AgentResource object)

Specifies the resource to log in to.

Return Value

The Impersonate method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the impersonation was successful.

• SM_AGENTAPI_NO (value = 2)

  Specifies that impersonation failed.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the operation failed.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization failed.

Remarks

The Impersonate method creates a new session without destroying the impersonator's original session. To end the impersonation session and restore the impersonator's original session, call AgentUser‑>Logout.

Only one user at a time can be impersonated. You cannot chain impersonation sessions.

Impersonation begins in a realm that is protected by the Impersonation Authorization Scheme. The impersonator must be authorized to impersonate users in the realm, and the user must be allowed to be impersonated in the realm.

For more information about user impersonation, see the Policy Server Configuration Guide.

IsAuthorized Method—Determines Whether User Is Authorized

The IsAuthorized method determines whether the user is authorized to perform the specified action on the specified resource. This method calls AgentUser‑>Login, if AgentUser‑>Login has not been called. After calling this method, call AgentUser‑>GetResponse.

Syntax

The IsAuthorized method has the following format:

Netegrity::AgentUser‑>IsAuthorized(resource[, clientIP][, transID])

Parameters

The IsAuthorized method accepts the following parameters:

resource (AgentResource object)

Specifies the resource to check.

clientIP (string)

(Optional) Specifies the client's IP address.

transID (string)

(Optional) Specifies the user-defined transaction ID that the agent uses to associate application activity with security activity.

Return Value

The IsAuthorized method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the user is authorized.

• SM_AGENTAPI_NO (value = 2)

  Specifies that the user is not authorized.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the Policy Server could not be reached.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization was not done.

IsAuthorizedEx Method--Determines Whether User Is Authorized

The IsAuthorizedEx method determines whether the user is authorized to perform the specified action on the specified resource. This method calls AgentUser‑>Login if AgentUser‑>Login has not been called. After calling this method, call AgentUser‑>GetResponse.

Syntax

The IsAuthorizedEx method has the following format:

Netegrity::AgentUser‑>IsAuthorizedEx(resource[, clientIP][, transID])

Parameters

The IsAuthorizedEx method accepts the following parameters:

resource (AgentResource object)

Specifies the resource to check.

clientIP (string)

(Optional) Specifies the client's IP address.

transID (string)

(Optional) Specifies the user-defined transaction ID that the agent uses to associate application activity with security activity.

Return Value

The IsAuthorizedEx method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the user is authorized.

• SM_AGENTAPI_NO (value = 2)

  Specifies that the user is not authorized.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the Policy Server could not be reached.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that initialization was not done.

Login Method—Performs Session Login and Validation

The Login method performs session login and validation. Before calling this method, call AgentResource‑>IsProtected for the target resource.

Syntax

The Login method has the following format:

Netegrity::AgentUser‑>Login(resource[, clientIP])

Parameters

The Login method accepts the following parameters:

resource (AgentResource object)

Specifies the resource to log in to.

clientIP (string)

(Optional) Specifies the client's IP address.

Return Value

The Login method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that user login was successful.

• SM_AGENTAPI_NO (value = 2)

  Specifies that user login failed.

• SM_AGENTAPI_CHALLENGE (value = 3)

  Specifies that a challenge is required for authentication.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the operation failed.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that the object was not connected.

Remarks

To allow one user, who is already logged in, to log in again as another user, call AgentUser‑>Impersonate.

Logout Method—Logs the User out of the Session

The Logout method logs the user out of the session. Calling this method is optional, because the user is automatically logged out when the user object exceeds its scope in the Perl script.

Syntax

The Logout method has the following format:

Netegrity::AgentUser‑>Logout()

Parameters

The Logout method accepts no parameters.

Return Value

The Logout method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the user logged out successfully.

• SM_AGENTAPI_NO (value = 2)

  Specifies that user logout failed.

• SM_AGENTAPI_CHALLENGE (value = 3)

  Specifies that a challenge is required for authentication.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the operation failed.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that the object was not connected.

Remarks

Calling Logout while one user is impersonating another user ends the impersonation session and restores the impersonator's original session. Calling AgentUser‑>Impersonate allows one user to impersonate or log in as another user.

Name Method—Sets or Retrieves the User's Username

The Name method sets or retrieves the user's username.

Syntax

The Name method has the following format:

Netegrity::AgentUser‑>Name([username])

Parameters

The Name method accepts the following parameter:

username (string)

(Optional) Specifies the username to set.

Return Value

The Name method returns the following value:

• username (string)

  Specifies the new or existing username.

Remarks

Setting the username only affects the current instance of the user object. It does not affect the user's entry in the directory.

Password Method—Sets or Retrieves the User's Password

The Password method sets or retrieves the user's password.

Syntax

The Password method has the following format:

Netegrity::AgentUser‑>Password([password])

Parameters

The Password method accepts the following parameter:

password (string)

(Optional) Specifies the password to set.

Return Value

The Password method returns the following value:

• password (string)

  Specifies the new or existing password.

Remarks

Setting the password only affects the current instance of the user object. It does not affect the user's entry in the directory.

Validate Method—Validates a Session Specification

The Validate method validates a session specification, checking that a user session has neither expired nor been terminated or revoked. This check can occur at any time during the life of a session.

Syntax

The Validate method has the following format:

Netegrity::AgentUser‑>Validate(resource[, clientIP][, transID])

Parameters

The Validate method accepts the following parameters:

resource (AgentResource object)

Specifies the resource to log in to.

clientIP (string)

(Optional) Specifies the client's IP address.

transID (string)

(Optional) Specifies a user-defined transaction ID.

Return Value

The Validate method returns one of the following values:

• SM_AGENTAPI_YES (value = 1)

  Specifies that the operation was successful.

• SM_AGENTAPI_NO (value = 2)

  Specifies that the user was not logged in.

• SM_AGENTAPI_FAILURE (value = -1)

  Specifies that the operation failed.

• SM_AGENTAPI_TIMEOUT (value = -2)

  Specifies that the method timed out.

• SM_AGENTAPI_NOCONNECTION (value = -3)

  Specifies that the object was not connected.

Remarks

The Policy Server validates a session specification or session ID, as follows:

• If the session ID is specified without a session specification, the Policy Server uses the session ID for validation.
• If the session ID is specified with a session specification, the Policy Server validates the session ID against the session specification.
• If the client's IP address is specified with a session specification, the Policy Server validates the IP address against the session specification.