Sm_AgentApi_DecodeSSOToken()

Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Agent API Function Declarations (C) › 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

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

Remarks

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

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

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

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