Sm_AgentApi_CreateSSOToken()

Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Agent API Function Declarations (C) › Sm_AgentApi_CreateSSOToken()

Sm_AgentApi_CreateSSOToken()

Produces an encrypted token of session and other information that can be shared between standard SiteMinder Web Agents and custom agents. The mutual access to this information allows a custom agent to participate in a single sign-on environment with a standard SiteMinder Web Agent.

Syntax

int SM_EXTERN Sm_AgentApi_CreateSSOToken (
   const void*                      pHandle,
   Sm_AgentApi_Session_t*           pSession,
   long                             nNumAttributes,
   Sm_AgentApi_Attribute_t*         pTokenAttributes,
   long*                            pNumSSOTokenLength, 
   char*                            lpszSSOToken
);

Parameter	I/O	Description
pHandle	I	Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().
pSession	I	Session information returned by the Sm_AgentApi_Login() call.
nNum Attributes	I	The number of attributes to include in the token. The attributes are specified in the parameter pTokenAttributes.
pToken Attributes	I	The user attributes to include in the token. Valid values: SM_AGENTAPI_ATTR_USERDN. The user’s distinguished name. SM_AGENTAPI_ATTR_USERNAME. The user’s name. SM_AGENTAPI_ATTR_CLIENTIP. The IP address of the machine where the user initiated a request for a protected resource. SM_AGENTAPI_ATTR_SSOZONE The designation of the SSO zone name. If you do not specify a zone name, the default is "SM." You read this value in the in the attribute list returned by the Sm_AgentApi_DecodeSSOToken method. Any other attribute is ignored. The fields in the Sm_AgentApi_Attribute_t structure that apply to this function are: nAttributeId (one of the above values) nAttributeLen lpszAttributeValue
pNumSSOToken Length	I, O	The length of the lpszSSOToken buffer passed in 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.
lpszSSOToken	O	The token returned from this function. Write this token to the SMSESSION cookie.

Return Values

SM_AGENTAPI_SUCCESS. The operation successful.
SM_AGENTAPI_FAILURE. The token was not created.
SM_AGENTAPI_NOCONNECTION. The initialization was not done.

Remarks

This function associates the user attribute information specified in the pTokenAttributes parameter with session and other attribute information returned from the call to Sm_AgentApi_Login(). The information in the resulting token can be shared between standard SiteMinder Web Agents and custom agents, allowing single sign-on operations between the standard and custom agents.

This call does not allocate any memory.

To decode token information, call Sm_AgentApi_DecodeSSOToken().