Previous Topic: SmDirAddMemberToRole()Next Topic: SmDirChangeUserPassword()

Programming Guides › Programming Guide for C › Directory API Guidance › Directory API Reference › SmDirAuthenticateUser()

SmDirAuthenticateUser()

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.