Programming Guides › Programming Guide for C › Authentication API

Authentication API

This section contains the following topics:

Create a Custom Authentication Scheme Library

Authentication API Overview

Each SiteMinder Authentication Scheme is an instance of a shared library that supports the Authentication API provider interface.

Typically, when you define an authentication scheme in the Administrative UI, you accept the default library for the authentication scheme type you want to use. For example, if you want to use an authentication scheme based on the HTML Form Template, you would accept its default library, smauthhtml.

But if you want your authentication scheme to support custom authentication functionality, you must build a new library for the authentication scheme. You build an authentication scheme library using the Authentication API.

The following figure shows how the authentication scheme library is used in the authentication process:

Graphic showing authentication scheme usage in the authentication process

Install an Authentication Scheme Library

Install your custom-built library in one of the following default locations:

On UNIX platforms, in the SiteMinder lib directory
On Windows platforms, in the SiteMinder bin directory

Load an Authentication Scheme

The authentication scheme library is loaded by both the authentication server and the authorization server. Both servers use the scheme to retrieve the required credentials.

Immediately after the scheme is loaded, the following operations occur:

The SmAuthQuery() function is called to get the Authentication API version number and description.
After SmAuthQuery() is called, SmAuthInit() is called by the authentication server. The SmAuthInit() function is not called by the authorization server.

User Context

An authentication scheme verifies the user credentials passed to it by SiteMinder and returns the authentication result. An authentication scheme operates in these modes:

User context is unknown—The user has yet to be located in the user store. Either SiteMinder or the authentication scheme looks up the user so that the user’s stored credentials can be compared with the credentials supplied at login.
Looking up the user in the user store is called user disambiguation.
User context is known—The user has been located in the user store. The custom authentication scheme can now verify the user’s credentials.

Authentication Events

Authentication results are tied to SiteMinder events. If authentication events are enabled in the realm where the user is being authenticated, SiteMinder evaluates optional policies tied to OnAuthAccept, OnAuthReject, OnAuthAttempt, and OnAuthChallenge rules. You can configure these policies to return custom responses based on a user’s identity, redirect the user to another location based on the result of the authentication, or update the user data in an external database.

Redirection

The authentication scheme can tell the Policy Server to instruct the agent to perform a redirect. To build an authentication scheme that provides redirection capabilities, place the URL in the lpszErrMsg parameter and return a status code that includes reason code Sm_Api_Reason_ErrorMessageIsRedirect.

For example:

strcpy (lpszErrMsg, "https://12.12.1.1/display/user.cgi?dn=");
strcat (lpszErrMsg, lpUserContext->lpszUserName);
return SM_MAKEAUTH_STATUSVALUE (Sm_AuthApi_Accept,
                          Sm_Api_Reason_ErrorMessageIsRedirect);

This functionality is useful when customizing the workflow of a Web application using a standard Agent. However, configuring redirection is also useful when using custom agents.

Supported Credentials

The Authentication API supports user authentication based on the following types of credentials:

Username/Password
X.509 Certificate
Custom user attributes

More Information:

SmAuthQuery()

Create a Custom Authentication Scheme Library

To create a custom authentication scheme library:

Include the SmApi.h file, as follows:

#include "SmApi.h"

Make the following functions externally visible:

Function	Description
SmAuthenticate()	Performs user authentications. The scheme authenticates user credentials and returns the result.
SmAuthInit()	Initializes the scheme. The scheme should initialize whatever resources it needs at this time.
SmAuthQuery()	Requests scheme information.
SmAuthRelease()	Releases the scheme only when SiteMinder is shutting down. The scheme should release its resources at this time.

Each entry point in the shared library must be defined according to specified syntax.

Note: If you are using Microsoft Visual Studio, export the function addresses to a modular definition file (.DEF) file. To export the function addresses, create a .DEF file, and in the export section of the .DEF file, list all of the authentication scheme functions, described in the previous table. Once you have created the .DEF file, add it to the Microsoft Visual Studio project.

Compile the code into a DLL or shared library. When you define the authentication scheme in the Administrative UI, you will specify this library name in the Authentication Scheme Properties dialog box.

After you have written and compiled a custom authentication scheme library, you define the authentication scheme that will use the custom library. You do so using the Administrative UI.

SmAuthenticate()

The SmAuthenticate() function authenticates user credentials.

Syntax

This function has the following format:

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
);

Parameters

This function has the following parameters:

lpApiContext: [in] Indicates a pointer to the API context structure.
lpUserContext: [in] Indicates a pointer to the user context structure.
lpUserCredentials: [in] Indicates a pointer to the user credentials context structure.
nChallengeReason: [in] Indicates the reason for the original challenge; otherwise, set to zero.
lpszParam: [in] Indicates a pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.
lpszSharedSecret: [in] Indicates a pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.
nBytesUserMsg: [in] Indicates the maximum size of the lpszUserMsg buffer to receive the user message—4097 bytes, including the string termination character.
lpszUserMsg: [out] Indicates a pointer to an 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: [in] Indicates the maximum size of the lpszErrMsg error buffer—4097 bytes, including the string termination character.
lpszErrMsg: [out] Indicates a pointer to an output buffer to receive the error text. Use this buffer to return an error message to SiteMinder.

Returns

This function uses 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)

This macro ha sthe following two parameters::

status—An Sm_AuthApi_Status_t enumeration. Different status codes can be returned when SmAuthenticate() is called during disambiguation and when it is called during authentication, as follows:
During the disambiguation phase:
- Sm_AuthApi_NoUserContext
- Sm_AuthApi_Success
- Sm_AuthApi_SuccessUserDN
- Sm_AuthApi_SuccessUserFilter
- Sm_AuthApi_Attempt
- Sm_AuthApi_Failure
During the authentication phase:
- Sm_AuthApi_Accept
- Sm_AuthApi_Reject
- Sm_AuthApi_Challenge
- Sm_AuthApi_Failure
reason—An Sm_Api_Reason_t enumeration:
- Values 0 - 31999 are reserved for use by SiteMinder.
- Values 32000 - 32767 are available for user-defined reasons.

SmAuthInit()

The SmAuthInit() function lets the authentication scheme perform its own initialization procedure. This call is made once, when the scheme is first loaded.

Syntax

This function has the following format:

Sm_AuthApi_Status_t SM_EXTERN SmAuthInit (
   const char*   lpszParam, 
   const char*   lpszSharedSecret
);

Parameters

This function has the following parameters:

lpszParam: [in] Indicates a pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.
lpszSharedSecret: [in] Indicates a pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.

Returns

This function returns one of the following values:

Sm_AuthApi_Success.: Indicates the function completed successfully.
Sm_AuthApi_Failure.: Indicates the function was unsuccessful. The scheme is not loaded.

SmAuthQuery()

The SmAuthQuery() function returns information about an authentication scheme.

Syntax

This function has the following format:

Sm_AuthApi_Status_t SM_EXTERN SmAuthQuery (
   const char*                   lpszParam,
   const char*                   lpszSharedSecret,
   const Sm_AuthApi_QueryCode_t  code,
   char*                         lpszStatusBuffer,
   int*                          lpnStatusCode
);

Parameters

This function has the following parameters:

lpszParam

[in] Indicates a pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.

lpszSharedSecret

[in] Indicates a pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.

code

[in] Request code as defined by an enum type Sm_AuthApi_QueryCode_t, which contains the following values:

Sm_AuthApi_QueryDescription. Requests the scheme’s description. The scheme returns a description through lpszStatusBuffer and the Authentication API version number through lpnStatusCode.
Sm_AuthApi_QueryCredentialsReq.
Requests the credentials required by the scheme and where to obtain them. The scheme should return a bit mask through lpnStatusCode, which represents the credentials needed for authentication.

Individual flags are defined by the enum type Sm_Api_Credentials_t. The scheme may return the location where the credentials can be obtained (that is, an HTTP URL) using the lpszStatusBuffer parameter.

lpszStatusBuffer

Receives a character string response. Up to Sm_AuthApi_StatusBufSize characters can be returned.

lpnStatusCode

If the call requests the scheme’s description, receives a numeric response indicating the version number of the Authentication API. Supported versions are Sm_Api_Version_V4 and Sm_Api_Version_V4_1.

If the call requests the credentials required by the scheme, the scheme returns one or more credentials. See Remarks. These constants are defined in SmApi.h.

Returns

This function returns one of the following values:

Sm_AuthApi_Success: Indicates the function completed successfully.
Sm_AuthApi_Failure: Indicates the caller has specified an invalid request code.

Remarks

The scheme supports request codes as specified by enumeration type Sm_AuthApi_QueryCode_t. The caller queries the scheme to find out what kind of credentials are required for authentication and where to obtain them.

The credentials are defined by the enum type Sm_Api_Credentials_t and can be combined to request multiple credentials. The caller collects the requested credentials, places them into the Sm_AuthApi_UserCredentials_t context structure, and calls the SmAuthenticate() function.

The individual flags in Sm_Api_Credentials_t are as follows:

Sm_AuthApi_Cred_None—No credentials are required.
Sm_AuthApi_Cred_Basic—Username and password are required.
Sm_AuthApi_Cred_Digest—Required user name and password are exchanged using the digest protocol.
Sm_AuthApi_Cred_X509Cert—Full X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_X509CertUserDN—User DN from an X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_X509CertIssuerDN—Issuer DN from an X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_CertOrBasic—Either a certificate is required or a user name and password is required.
Sm_AuthApi_Cred_CertOrForm—Either a certificate is required or a form-based username and password are required.
Sm_AuthApi_Cred_SSLRequired—An SSL connection is required. A redirect to an https URL must be specified.
Sm_AuthApi_Cred_NTChalResp—Required user name and password are exchanged using the NT Challenge Response protocol.
Sm_AuthApi_Cred_AllowSaveCreds—Signifies whether the credentials can be saved for 30 days by the user. If a user saves their credentials, they do not need to enter their credentials, such as user name and password, each time they access the protected resource.
Sm_AuthApi_Cred_FormRequired—A form-based username and password are required. A redirect to a URL containing a form must be specified.
Sm_AuthApi_Cred_PreserveSessionId—The session ID should be preserved if the current session is still valid.
Sm_AuthApi_Cred_DoNotChallenge—Do not challenge for credentials
Sm_AuthAPI_Cred_AllowAnonymous—Allow validation of anonymous identity.

Examples: Setting status codes

An Anonymous scheme combines these credential flags:

*lpnStatusCode = Sm_AuthApi_Cred_None|Sm_AuthApi_Cred_AllowAnonymous;

Collect username and password. The Agent uses HTTP basic authentication to challenge the user:
```
*lpnStatusCode = Sm_AuthApi_Cred_Basic;
```

Collect username and password. The Agent challenges the user over SSL using HTTP basic authentication:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                           Sm_AuthApi_Cred_SSLRequired;
strcpy(lpszStatusBuffer,
                "https://xxx.yyy.zzz/secure.ssc?basic")

Collect username and password. The Agent challenges the user over SSL using an HTML form:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                          Sm_AuthApi_Cred_FormRequired;
strcpy(lpszStatusBuffer,
               "https://xxx.yyy.zzz/getcredentials.fcc")

Collect an X.509 Certificate. The Agent challenges the user for a certificate:

*lpnStatusCode = Sm_AuthApi_Cred_SSLRequired |
                               Sm_AuthApi_Cred_X509Cert;
strcpy(lpszStatusBuffer,
                 "https://xxx.yyy.zzz/getcert.scc?cert")

Collect an X.509 Certificate, username, and password. The Agent challenges the user over SSL using HTTP basic authentication:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                         Sm_AuthApi_Cred_SSLRequired |
                         Sm_AuthApi_Cred_X509Cert;
strcpy(lpszStatusBuffer,
           "https://xxx.yyy.zzz/getcert.scc?cert+basic")

SmAuthRelease()

The SmAuthRelease() function lets an authentication scheme perform its own rundown procedure.The caller makes this call once when SiteMinder is shutting down.

Syntax

This function has the following format:

Sm_AuthApi_Status_t SM_EXTERN SmAuthRelease (
   const char*    lpszParam
   const char*    lpszSharedSecret
);

Parameters

This function has the following parameters:

lpszParam: [in] Indicates a pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.
lpszSharedSecret: [in] Indicates a pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.

Returns

This function returns one of the following values:

Sm_AuthApi_Success.: Indicates the function completed successfully.
Sm_AuthApi_Failure.: Indicates the function was unsuccessful. The scheme is not loaded.