Sm_AgentApi_CreateSSOToken()

Produces an encrypted token of session and other information that standard Web Agents and custom agents can share. This shared information allows a custom agent to operate in a single sign-on environment with a standard Web Agent.
casso127
Produces an encrypted token of session and other information that standard Web Agents and custom agents can share. This shared information allows a custom agent to operate in a single sign-on environment with a standard 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 SSO token. Valid values:
  • SM_AGENTAPI_ATTR_USERDN—The distinguished name of the user.
  • SM_AGENTAPI_ATTR_USERNAME—The user name.
  • SM_AGENTAPI_ATTR_CLIENTIP—The IP address of the system from 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." This value is in the attribute list that is returned by the Sm_AgentApi_DecodeSSOToken method. Any other attribute is ignored.
  • SM_AGENTAPI_ATTR_SESSION_DOMAIN—The host domain stored in the SSO token. This function lets a custom agent generate SSO tokens for use as HTTP session cookies that can support the TrackSessionDomain agent setting. This setting enables the Web Agent to validate the domain of a session cookie.
The fields in the Sm_AgentApi_Attribute_t structure that apply to this function are:
  • nAttributeId (one of the listed attribute values)
  • nAttributeLen
  • lpszAttributeValue
pNumSSOToken Length
I,O
The length of the
lpszSSOToken
buffer that is 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 that is 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 that is specified in the
pTokenAttributes
parameter with session and other attribute information that is returned from the call to Sm_AgentApi_Login(). The information in the resulting token can be shared between standard Web Agents and custom agents, allowing single sign-on operations between the two agents. This call does not allocate any memory.
To decode token information, call Sm_AgentApi_DecodeSSOToken().