Sm_AgentApi_ChangePassword()

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

Sm_AgentApi_ChangePassword()

Changes a user’s password. The resulting attributes plus the reason code from the session object are used to construct the correct password services redirect.

Syntax

int SM_EXTERN Sm_AgentApi_ChangePassword (
   const void* pHandle,
   const char* lpszClientIpAddr,
   const char* lpszNewPassword,
   const char* pszTokenValue,
   const Sm_AgentApiResourceContext_t* pResourceContext,
   const Sm_AgentApi_Realm_t* pRealm,
   const Sm_AgentApi_UserCredentials_t* pUserCredentials,
   Sm_AgentApi_Session_t* pSession,
   long * numAttributes,
   Sm_AgentApi_Attribute_t** ppAttributes
);

Parameter	I/O	Description
pHandle	I	Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().
lpszClientIpAddr	I	The IP address of the client asking for the resource. This parameter is optional. If the client IP begins with a star (*), the Policy Server logs the IP address but does not validate it against a session specification.
lpszNewPassword	I	The new password (string) to which the user wants to change.
pszTokenValue	I	The token that is exchanged between the Policy Server and the Web Agent in the case of a Password Services redirect. Use this parameter to send to the Policy Server an extracted SMTOKEN from the ppAttributes (returned by Sm_AgentApi_ChangePassword()). This value can be NULL if the nChallengeReason value of the pUserCredentials parameter is set to Sm_Api_Reason_PWSelfChange (indicating a user-initiated password change).
pResourceContext	I	A pointer to a resource definition structure.
pRealm	I	A realm definition structure.
pUserCredentials	I	A user credentials definition structure.
pSession	O	A user session definition structure.
pNumAttributes	O	The number of attributes in ppAttributes.
ppAttributes	O	A pointer to an array of response attribute definition structures.

Return Values

SM_AGENTAPI_YES. The user’s password was changed.
SM_AGENTAPI_NO. The user’s password was not changed.
SM_AGENTAPI_NOCONNECTION. The initialization was not done.
SM_AGENTAPI_TIMEOUT. The function timed out.
SM_AGENTAPI_FAILURE. The password was not changed

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. 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().

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
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().