Creating Your Own Authentication Plugin

enables you to write a plugin to authenticate users. This section describes the API for writing your own plugin.

Note:

The can use only one authentication plugin at a time.

An authentication plugin uses a plugin pointer and an authentication context. The plugin pointer is passed to the plugin each time the initialize(), authenticate(), or shutdown() function is called. You then pass this pointer to other library functions when calling them. The data structure that the plugin pointer points to is opaque, meaning you do not need to read or change it.

The authentication context holds information about the user, such as their username, ID, and the names of the groups that they are a member of. The authentication content also holds information about the authentication results.

The following is an example of an authentication plugin:

/**
 * The plugin pointer
 */
typedef struct C8AuthPluginImp C8AuthPlugin;
/**
 * Authentication result codes
 */
#define C8_AUTH_SUCCESS 0
#define C8_AUTH_FAILURE 1
#define C8_AUTH_ERROR   2
#define C8_AUTH_UNAVAIL 3
/**
 * The authenticationg context
 */
typedef struct C8AuthContextImp C8AuthContext;

The following functions allow you to get and set information in the authentication context variable.

const char * C8AuthContextGetUsername (C8AuthContext *ctxt); – Purpose: Returns the user name from an existing authorization context.
Parameters:
- ctxt: A pointer to the authorization context you want to retrieve the user name from.
Returns: A string containing the username.
const char * C8AuthContextGetpassword (C8AuthContext *ctxt); – Purpose: Returns the user password from an existing authorization context.
Parameters:
- ctxt: A pointer to the authorization context you want to retrieve the user password from.
Returns: A string containing the password.
void C8AuthContextSetResult (C8AuthContext *ctxt, C8Int res); – Purpose: Sets a value that indicates the result of the authentication.
Parameters:
- ctxt: A pointer to the authorization context you want to set the result from.
- res: The result. C8_AUTH_SUCCESS indicates that the user was authenticated.
Returns: Nothing.
void C8AuthContextAddGroup (C8AuthContext *ctxt, const char *groupName); – Purpose: Adds a group to the list of groups that the user is a member of. A single user may be a member of multiple groups, so you can call this function more than once for a single user. Each time you call, the group name that you specify will be added to the list of group names for user.
Parameters:
- ctxt: A pointer to the authorization context for which you want to set the result.
- groupName: The name of a group this user is a member of.
Returns: Nothing.

Note:
Add the groups after you have authenticated the user. Only users who have been successfully authenticated should have the list of groups.

As with any plugin, an authentication plugin contains "initialize()", "execute()" and "shutdown()" functions. Below we show some examples with the correct input parameter types and return types. The names for these functions can be different, but you can specify the actual names of the function in the "AccessControl/Authentication/plugin" section of your server configuration file.

C8Status c8authplugin_demo_initialize(C8AuthPlugin *plugptr); – Purpose: Performs any initialization that the plugin needs. This may involve allocating memory, opening a file, or connecting to an authentication servic.
Parameters:
- plugPtr: A pointer to a C8AuthPlugin object.
Returns: C8_OK if successful, C8_FAIL otherwise.
C8Status c8authplugin_demo_authenticate(C8AuthPlugin *plugPtr, C8AuthContext *); – Purpose: Authenticates a user.
Parameters:
- plugPtr: A pointer to a C8AuthPlugin object.
- i_credentials: A pointer to the credentials to of the user.
Returns: C8_OK if successful, C8_FAIL otherwise.
C8Status c8authplugin_demo_shutdown(C8AuthPlugin *plugPtr); – Purpose: Performs any cleanup that the plugin needs. This may involve de-allocating memory, or closing a file.
Parameters:
- plugPtr: A pointer to a C8AuthPlugin object.
Returns: C8_OK if successful; C8_FAIL otherwise.

If you want to preserve information across calls to the execute/authenticate function, you can store information by using the following:

void* C8AuthPluginGetSessionState (C8AuthPlugin *plugPtr); – Purpose: Gets plugin's state. Returns NULL if no state was set. The pointer points to a user-defined structure that holds information that the user needs each time the execute function is called.
Parameters:
- plugPtr: A pointer to a C8AuthPlugin object.
Returns: C8_OK if successful, C8_FAIL otherwise.
void C8AuthPluginSetSessionState (C8AuthPlugin *plugPtr, void *statePtr); – Purpose: Sets the plugin's state. The pointer points to a user-defined structure that holds information that the user needs each time the execute/authenticate function is called. The plugin is responsible for destroying private data during the "shutdown" callback
Parameters:
- plugPtr: A pointer to a C8AuthPlugin object.
- statePtr: A pointer to the "state" information that the user wants to preserve.
Returns: C8_OK if successful; C8_FAIL otherwise.

The state information is not retained if the server restarts.

The instructions for compiling a C/C++ plugin are virtually identical to the instructions for compiling an in-process adapter. See Step-by-Step Instructions for Creating an In-process Adapter for more information. Note that you will need to include the c8auth_plugin.h file