SmDirAuthenticateUser()

Use the SmDirAuthenticateUser() function to check the directory for the provided user name and password.
casso1283
Use the SmDirAuthenticateUser() function to check the directory for the provided user name and password.
After the call to SmDirAuthenticateUser(),
SiteMinder
calls SmDirFreeString() to free the
lpszUserMsg
buffer, then calls SmDirFreeString() again to free the
lpszErrMsg
buffer.
Syntax
int SM_EXTERN SmDirAuthenticateUser (
   const Sm_Api_Context_t*  lpApiContext,
   void*                    pHandle,
   void*                    pInstanceHandle,
   const char*              lpszUserDN,
   const char*              lpszPassword,
   Sm_Api_Reason_t*         pnReason,
   char**                   lpszUserMsg,
   char**                   lpszErrMsg
);
Parameter
I/O
Description
lpApiContext
I
Pointer to the API context structure.
Handle
I
The address of the pointer returned by SmDirInit().
pInstanceHandle
I
The address of a pointer to the user instance handle.
lpszUserDN
I
Buffer containing the user DN that has to be authenticated.
If SmDirValidateUsername() is not implemented, the user-supplied username is passed into
lpszUserDN
.
If SmDirValidateUsername() is implemented, SmDirValidateUsername() should return the user’s ID in the
lpszNewUsername
parameter. The value returned by
lpszNewUsername
becomes the
lpszUserDN
parameter value.
lpszPassword
I
Buffer containing the password that has to be authenticated.
pnReason
O
Pointer to the resulting reason of the authentication event, using the reasons enumerated in Sm_Api_Reason_t.
lpszUserMsg
O
Output buffer to receive a message for the user. This message can be the challenge text or any other message an authentication scheme developer wants to present to the user through a mechanism external to
SiteMinder
. In the sample, if a bogus username is presented, authentication fails and the string Failed to authenticate is copied to
lpszUserMsg
.
The Web Agent stores this message in the HTTP variable HTTP_SM_USERMSG. For RADIUS authentication, the user message is returned in the REPLY-MESSAGE response attribute.
The
SiteMinder
Policy Server writes the error message in
lpszUserMsg
to the
SiteMinder
Authentication log.
lpszErrMsg
O
Output buffer to receive the error message. Use this buffer to return an error message to
SiteMinder
. In the sample, if a bogus username is presented, authentication fails and the string Failed to authenticate is copied to
lpszErrMsg
.
The
SiteMinder
Policy Server writes the error message in
lpszErrMsg
to the
SiteMinder
Authentication log. The string in
lpszErrMsg
follows Not Authenticated in the log. The string in
lpszUserMsg
follows the string in
lpszErrMsg
. For example, if the challenged user presents the bogus username impostor, the
SiteMinder
Policy Server writes the following status message to the log:‘impostor’ Not Authenticated. ErrMsg. UserMsg
Returns
Returns 0 if authentication succeeds, or -1 if there is an error in processing or if the user-supplied credentials are invalid.
If authentication fails, convey the reason through the output parameter
pnReason
and return -1.
Remarks
This function is called when you use the
SiteMinder
Test Tool to run IsAuthenticated for a user in the custom directory.