Programming Guides › Programming Guide for Perl › CLI Agent API Methods › Single Sign-on Token Methods

Single Sign-on Token Methods

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.