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

User Methods

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.