Sm_AgentApi_DecodeSSOToken()

Decodes a single sign-on token and returns a subset of its attributes. Optionally, you can update the last-access timestamp of the token, and then update the SMSESSION cookie with the new token.
casso10
Decodes a single sign-on token and returns a subset of its attributes. Optionally, you can update the last-access timestamp of the token, 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 one of the following locations:
  • If a custom agent generates the token, the token is returned in the output parameter
    lpszSSOToken
    from the call to Sm_AgentApi_CreateSSOToken(). The custom agent is responsible for extracting the contents of the cookie and assigning it to this parameter.
  • If a standard Web Agent generates the token, the token is in the SMSESSION cookie.
nTokenVersion
O
The 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 web 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 SSO_TOKEN_MAX_SIZE, parameter defines the maximum size. This parameter is 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 attributes.
You can update the last-access timestamp of the token. 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().