Programming Guides › Programming Guide for C › Authentication API › Create a Custom Authentication Scheme Library › SmAuthenticate()

Previous Topic: Create a Custom Authentication Scheme Library

Next Topic: SmAuthInit()
SmAuthenticate()

Authenticates user credentials.

Syntax

Sm_AuthApi_Status_t SM_EXTERN SmAuthenticate (
   const Sm_Api_Context_t*             lpApiContext,
   const Sm_Api_UserContext_t*         lpUserContext,
   const Sm_AuthApi_UserCredentials_t* lpUserCredentials,
   const Sm_Api_Reason_t               nChallengeReason,
   const char*                         lpszParam,
   const char*                         lpszSharedSecret,
   const int                           nBytesUserMsg,
   char*                               lpszUserMsg,
   const int                           nBytesErrMsg,
   char*                               lpszErrMsg
);

Parameter

I/O

Description

lpApiContext

I

Pointer to the API context structure.

lpUserContext

I

Pointer to the user context structure.

lpUserCredentials

I

Pointer to the user credentials context structure.

nChallengeReason

I

The reason for the original challenge, otherwise 0.

lpszParam

I

Pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.

lpszSharedSecret

I

Pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.

nBytesUserMsg

I

Maximum size of the lpszUserMsg buffer to receive the user message—4097 bytes, including the string termination character.

lpszUserMsg

O

Output buffer to receive the user message. This message can be the challenge text or any other message that the scheme developer wants to present to the user through a mechanism external to SiteMinder. The Agent stores this message in the HTTP_SM_USERMSG HTTP variable. For RADIUS authentication, the user message is returned in the REPLY-MESSAGE response attribute.

nBytesErrMsg

I

Maximum size of the lpszErrMsg error buffer—4097 bytes, including the string termination character.

lpszErrMsg

O

Output buffer to receive the error text. Use this buffer to return an error message to SiteMinder.

Returns

Use the SM_MAKEAUTH_STATUSVALUE macro to construct the return value. This macro is defined in SmApi.h.

The syntax of the macro is as follows:

SM_MAKEAUTH_STATUSVALUE(status, reason)

The macro's parameters are:

Sm_AuthApi_NoUserContext

During the authentication phase (for descriptions, see the description in User Authentication, which follows):

Remarks

The authentication process includes two phases—user disambiguation and user authentication. During each phase, SmAuthenticate() is called at least once:

The basic steps are as follows:

  1. User login. The user supplies a login ID (such as jsmith) for authentication purposes.
  2. Disambiguation phase. User disambiguation is the process of locating a user in the user store, such as an LDAP user directory or an ODBC database. Either SiteMinder or the custom authentication scheme can look up the user in the user store.

    Before the lookup operation can begin, a complete DN or a search expression must be constructed based upon the supplied login ID. For example, if the login ID is jsmith, the DN used to search the user store might be constructed as follows:

    uid=jsmith,ou=marketing,o=myorg.org

    An LDAP search expression can also be used to search an LDAP user directory, and a SQL query is used to search an ODBC database—for example:

    (&(objectclass=inetOrgPerson)(uid=jsmith))

    select Name from SmUser where Name = 'jsmith'

    Multiple results are possible, given that the LDAP DN or the ID stored in the ODBC database might apply to different users who have different passwords.

  3. Authentication phase. The custom authentication scheme compares the known credentials of each disambiguated user with the credentials supplied during login—for example, by comparing the hash of the supplied password against the hash in the user store.

User Disambiguation

SiteMinder first calls SmAuthenticate() at the beginning of the user disambiguation phase.

Either SiteMinder or the custom authentication scheme can disambiguate the user. The authentication scheme indicates whether it has performed the disambiguation through one of the following return codes:

Note: If the authentication scheme leaves lpszUserMsg empty, SiteMinder uses the login ID provided by the Agent (the same behavior as with return code SmAuthApi_NoUserContext).

User Authentication

During this phase, SiteMinder calls SmAuthenticate() again to verify the supplied credentials after the user context has been established during disambiguation. The function returns one of the following return codes:

Example

Sm_AuthApi_Status_t SM_EXTERN SmAuthenticate (
const Sm_Api_Context_t*lpApiContext, 
// The structure that provides API context
const Sm_Api_UserContext_t*lpUserContext, 
// The structure that allows access to user properties
const Sm_AuthApi_UserCredentials_t* lpUserCredentials, 
// The user credentials
unsigned char  bChallengeResponse, 
// Boolean indicating whether this is the response to a challenge
const char*  lpszServerParam,  
// The parameter to be passed to the server
const char* lpszSharedSecret, 
// The shared secret to be passed to the server
const int  nBytesUserMsg,               
// Maximum size of the user message buffer
char*   lpszUserMsg, 
// Output buffer to hold the null-terminated user message
const int  nBytesErrMsg, 
// Maximum size of the error buffer
char*   lpszErrMsg) 
// Output buffer to hold the null-terminated error message
{
if (!lpUserContext->bIsUserContext)
   return Sm_AuthApi_NoUserContext;
return (0 == lpUserContext->fAuthenticate (
             lpUserContext->lpParam,
             lpUserCredentials->lpszPassword,
             nBytesUserMsg,
             lpszUserMsg,
             nBytesErrMsg,
             lpszErrMsg) ? Sm_AuthApi_Accept : Sm_AuthApi_Reject);
}

Copyright © 2010 CA. All rights reserved. Email CA about this topic