Skip Headers
Oracle® Access Manager Developer Guide
10g (10.1.4.0.1)

Part Number B25346-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

6 Authentication Plug-in API

The Access Server uses both authentication and authorization controls to limit access to resources that it protects. Authentication is governed by authentication rules. The authentication rules use authenticating schemes, and the schemes use one or more plug-ins to do tests on the credentials provided by a user when he or she tries to access a resource. The plug-ins can be taken from a set provided as part of the Access Server installation, or they can be custom plug-ins.

This chapter provides information on creating custom authentication plug-ins. It covers the following topics:

6.1 About the Authentication Plug-in API

When a browser requests a resource from a Access System-protected Web server, the Access Server checks to see if the resource is protected, and if it is, whether the user needs to authenticate. If the user has not already logged in, the Access Server requires a new login for the user and sends an authentication challenge to the browser. The challenge conforms to the challenge method defined in an Authentication Scheme. The authentication scheme is part of an Authentication Rule which is part of the access policy protecting the resource. When the scheme is carried out, it invokes an authentication plug-in, or two or more chained plug-ins that are performed in the order specified in the scheme.

All schemes follow the same general flow. In response to an authentication challenge, the browser obtains credentials from the user, such as a user name and password or a client certificate. In some cases, for example client certificate authentication, the browser generates credentials on behalf of the user. The browser sends the credentials to the server, in a format determined by the challenge. The Access Server re-formats the credentials as a set of name:value pairs for use during processing, and treats them as an authentication request.

The user's credentials are input to the single plug-in or to each plug-in in the scheme. Output is a status to accept, continue, deny or end the authentication, plus a set of credentials, possibly different from the originals.

If authentication fails, result messages are logged in the Access Server audit file, if it is provided by the plug-in. When the authentication scheme finishes, the result must have produced one and only one valid user DN, or no user DN.

If authentication succeeds, the Access Server creates a session cookie containing the user's profile DN, the IP address of the user's browser, the level of the authentication scheme, and the expiration time for the cookie. The Access Server can also set HTTP header variables based on the authentication actions defined for the authentication scheme. The cookie and HTTP information are returned to the browser, and access is granted.

If authentication does not succeed, the Access Server sets an HTTP return status of 401 (Not Authorized), the standard response for unauthenticated access, and access to the resource is denied.

Authentication schemes can be created which use only the predefined authentication plug-ins; see "Standard Plug-Ins". In addition, developers can create their own plug-ins and use them in schemes, alone or in combination with the standard plug-ins.

6.1.1 Globalization and Custom C Authentication Plug-ins and Interfaces -- reviewed/updated

With 10g (10.1.4.0.1) there are some changes and backward compatibility, as described here.

The 10g (10.1.4.0.1) Authentication Plug-In API for C uses UTF-8 encoding for plug-in processing. In earlier releases, the Authentication Plug-In API for C used Latin-1 encoding for data exchanged between the Access Server and the custom plug-ins.

6.1.1.1 Backward Compatibility

When you upgrade an older Access Server to 10g (10.1.4.0.1), ="IsBackwardCompatible" Value="false" is set in the Access Server globalparams.xml file automatically. A backward-compatible Access Server continues to send data to authentication plug-ins in Latin-1 encoding and expects that the plug-ins will set data in Latin-1 encoding. There is no change in plug-in data encoding.

When you add a new 10g (10.1.4.0.1) Access Server to an upgraded environment, you need manually set ="IsBackwardCompatible" Value="false" in the Access Server globalparams.xml to enable communication with older plug-ins and interfaces, as well as older WebGates and custom AccessGates.

6.2 C API Environment

The following sections describe the development environment for the plug-in API, including support file location and major components.

6.2.1 Support Files Location for the C API

When you install the Access Server component of the Access System, you put it into an installation directory, ASInstall_Dir, for example:

C:/COREid/access/oblix

Sample files for the authentication plug-in API are installed within this directory, at:

AccessServer_install_dir/access/oblix/sdk/authentication/samples

The samples directory contains an authn_api subdirectory.

The samples directory does not contain all of the files required to build and run the source code. For example, the header files, include files, and others are not provided.

Authn_api contains source code for a simple example authentication plug-in, an example make file and, one level down in the include directory, the header file authn_api.h.

The file authn_api.h contains two important sets of information:

  • Definitions of the set of utilities that the Access Server provides to all authentication plug-ins

  • Definitions of the API data and functions


Note:

Some of the definitions provided in this file are essential in order to correctly build and operate the API. When the plug-in is loaded by the Access Server, it expects to find the set of five functions in authn_api.h implemented within the plug-in. You may add information to the file, but do not remove any of the existing content.

To build

  1. Under the samples directory, copy the content of the authn_api directory to a second directory, for example myplugin.

  2. Within the new directory, change the content of the authn.c file, or create additional files, or both, to provide the desired functionality specific to your plug-in.

  3. Change the make file to show the actual path to your C compiler and to the authn_api.h file, and to include and compile all of your source code.

Run the make file. (The example supplied applies only to UNIX; you need to create your own for the Windows environment.)

The resulting *.so or *.dll is your new plug-in.

6.2.2 C API Plug-in Directory

The plug-in you created must be stored in the system where the Access Server is running, in the directory:

ASInstall_Dir/lib

The Access Administrator needs to know the filename of the plug-in, and its required and optional data names in order to properly configure the plug-in into an authentication scheme. See theOracle Access Manager Access Administration Guide for a more detailed discussion of authentication scheme configuration. Following the "C Authentication Plug-in Example" is a screen showing the authentication scheme configuration used to support the example.

6.3 C API Data

This section describes the various types of constant and variable data that the API uses.

6.3.1 Defines (C)

Authn_api.h predefines several values for use as fixed argument values when working with some functions.

#define OB_AN_PLUGIN_VERSION  "5.0"
#define ObAnPluginRequestResource  "Resource"
        #define ObAnPluginRequestOperation "Operation"
        #define ObAnPluginRequesterDN      "RequesterDn"

Value Name Meaning
OB_AN_PLUGIN_VERSION When ObAnPluginGetVersion is called, this value must be returned to the Access Server. The value in the header file may change with releases of the product.
ObAnPluginRequestResource The resource after the host name and port, for example: /basic/page.htm.
ObAnPluginRequestOperation The operation being performed on the resource.
ObAnPluginRequesterDN If an authentication plug-in has set the DN, this is where other plug-ins can access that DN. The plug-in named credential_mapping always sets the DN.

Custom authentication plug-ins can set the DN, once they have determined what it is, by calling SetCredFn.

ObAnPluginRequesterIP The IP address of the client that issued this request.

6.3.2 Handles (C)

The Access Server and API use pointers, also called handles, to allow manipulation of data structures that the Access Server maintains for use by the plug-in. These handles are named and described in the following table. The description of content for all structures begins at "C Structures". The terms list, name, value and item describe the data relationships within the ObAnPluginInfo structure, described on 526.

Data Type/Name Purpose
void const*ObAnPluginSVData_t A handle to a data structure containing names that are single valued. It is used to locate Creds and ActionInfo in the ObAnPluginInfo structure.
void*ObAnPluginMVData_t A handle to a data structure containing names that can be multivalued. They are used to locate Params and Context in the ObAnPluginInfo structure.
char**ObAnPluginStatusMsg_t A NULL-terminated string that a plug-in function returns to report on the result of the function.
void const*ObAnPluginList_t A handle pointing to a list of items for a multivalued name that is part of the data for the Params or Context members of the structure ObAnPluginInfo. This handle is obtained using the function GetData.
void const*ObAnPluginListItem_t A handle pointing to the current item in a list for a multivalued name. This handle is obtained using the functions GetFirstItem or GetNext.
struct ObAnPluginInfo*ObAnPluginInfo_t A handle pointing to the structure ObAnPluginInfo that contains information from the Access Server and data generated by the plug-in.
struct ObAnServerContext*ObAnServerContext_t A handle pointing to the structure ObAnServerContext. The structure provides general information about the Access Server.

6.3.3 C Return Values

Many of the functions the Access Server and API use to communicate are expected to return a status value. These are all predefined in several categories as described in this section.

6.3.3.1 ObAnActionType_t

These are action flags that the API returns to the Access Server, to tell it what actions to take.

typedef enum {
ObAnSuccessRedirect = 0,
ObAnFailRedirect = 1,
        ObAnSuccessProfileAttrs = 2,
        ObAnFailProfileAttrs = 3,
        ObAnSuccessFixedVals = 4,
        ObAnFailFixedVals = 5
} ObAnActionType_t;

Name Description
ObAnSuccessRedirect For successful authentication, tells the Access Server to set the redirection URL, as defined in the authentication rule.
ObAnFailRedirect For failed authentication, tells the Access Server to set the redirection URL, as defined in the authentication rule.
ObAnSuccessProfileAttrs For successful authentication, tells the Access Server to set the profile attributes for the action using values provided by the authentication rule, which may have been added to by the plug-in.
ObAnSuccessProfileAttrs For failed authentication, tells the Access Server to set the profile attributes for the action using values provided by the authentication rule, which may have been added to by the plug-in.
ObAnSuccessFixedVals For successful authentication, tells the Access Server to set the fixed values defined in the authentication rule, which may have been added to by the plug-in.
ObAnFailFixedVals For failed authentication, tells the Access Server to set the fixed values defined in the authentication rule, which may have been added to by the plug-in.

6.3.3.2 ObAnPluginstatus_t

Plug-ins must return one of these values to the Access Server to show the result of the attempt to authenticate.

typedef enum { 
ObAnPluginstatusContinue = 0,
ObAnPluginstatusAllowed = 1,
ObAnPluginstatusDenied = 2, 
        ObAnPluginstatusAbort = 3 
        }ObAnPluginstatus_t; 
Value Name Meaning
ObAnPluginStatusContinue Your plug-in returns this code if it completed execution successfully.

The Access Server interprets a return code of Continue as indication that the current plug-in succeeded, and that it should continue processing the plug-ins of the steps of the authentication scheme.

If all of the plug-ins of an authentication scheme return this result code, authentication is successful.

ObAnPluginStatusAllowed Your plug-in returns this code if authentication is successful.

The Access Server interprets a return code of Allowed as indication that credentials were processed and authentication succeeded.

The Access Server performs no further processing of authentication plug-ins in any of the steps of the authentication scheme.

ObAnPluginStatusDenied Your plug-in returns this code if authentication failed.

The Access Server interprets a return code of Denied as indication that credentials were processed and authentication failed.

The Access Server performs no further processing of authentication plug-ins of any steps of the authentication scheme because authentication failed.

ObAnPluginStatusAbort Your plug-in returns this code if a fatal error occurs during its processing.

The Access Server interprets a return code of Abort as a direction to end the authentication process specified by the authentication scheme, not just the step containing the plug-in.

If Abort is returned during initialization, the Access Server will log the condition, but it will not end the process.


6.3.3.3 ObAnASStatus_t

When a plug-in calls upon the Access Server to perform one of its built-in functions, the Access Server attempts to execute the function, and returns one of these values.

typedef enum {
ObAnASStatusSuccess = 0,
ObAnASStatusFailed
        }ObAnASStatus_t;
Value Name Meaning
ObAnASStatusSuccess The Access Server successfully performed the operation.
ObAnASStatusFailed The Access Server did not perform the operation. The most likely cause of this error is that the plug-in tried to change values that it is not allowed to change. An example is an attempt to add a second value for a name, to an array member which permits only single values.

6.3.4 C Structures

The Access Server groups related data items into named structures, allocates the memory for them, and carries the data for them. Structures are opaque to the developer, meaning that they can be used to transfer information to and from the Access Server, but the developer cannot change the way the structure is organized or the format of the data that it contains. The content of the structure can be changed in some instances.

Here are the structures used in the Authentication Plug-in API.

6.3.4.1 ObAnServerContext

This structure carries information about the Access Server that the plug-in may need.

struct ObAnServerContext {
char                    *AccessServerInstallDir;
char                    *AccessServerAnPluginAPIVersion; 
        };

ObAnServerContext_t is the handle that works with this structure.

Data held in this structure is read only.

Data Type/Name Purpose
AccessServerInstallDir Path to the Installation directory for the Access Server, for example COREid/Access.

Note: this does not include the /oblix directory.

AccessServerAnPluginAPIVersion The lowest authentication plug-in API version the instance of the Access Server supports.

6.3.4.2 ObAnPluginInfo

The Access Server fills this structure with data determined by the Authentication Rule to be used, and provides the filled structure to the plug-in. The plug-in modifies data within the structure and may append new data to it as work progresses through the plug-in. When there are multiple plug-ins being carried out as part of an authentication scheme, it also provides a means to set variable information for the first plug-in in the rule, and pass information from one plug-in to another within the scheme.

struct ObAnPluginInfo {
ObAnPluginsVData_t                                                 Creds;
ObAnPluginMVData_t                                                 Params;
        ObAnPluginMVData_t                                                 Context;
        ObAnPluginsVData_t                                                 ActionInfo;
        };

ObAnPluginInfo_t is the handle pointing to this structure.

Data is extracted from structures and stored to them using the functions described under "Functions Provided by the Access Server (C API)".

Data Type/Name Purpose
Creds Creds is all information submitted by the entity (user or application) trying to access a resource. The plug-in may add to or replace this data. The data is passed to the next plug-in in sequence and hence can be used by the plug-in to communicate with the plug-in following it in an authentication scheme. The Access Server provides four predefined names within this list: Resource, Operation, RequesterDN, and RequesterIP.
Params The parameters specified in the plug-in configuration. The plug-in may add to or replace this data, within the plug-in. However, this data is not passed to the next plug-in.
Context Data created by the plug-in. The plug-in may add to or replace this data. The data is passed to the next plug-in in sequence.
ActionInfo Action information specified in the plug-in configuration. The plug-in may add to or replace this data. Actions can also be set and passed to the next plug-in, keeping in mind that the final user of the action information is the Access Server.

Understanding the organization of the ObAnPluginInfo structure in is key to understanding how the Authentication Plug-in API works. This structure can be thought of as an array of four nested arrays, the structure members. Each member holds one or more names.

For structure members that are of type ObAnPluginSVData_t, the array consists of a set of names and the single value associated with each one. For example, the creds member can be thought of this way:

Name Value
"Resource" 1 value
"Operation" 1 value
"RequesterDN" 1 value
"RequesterIP" 1 value
User Created Credential Name 1 value

To get the value, you use GetCredFn and provide the name of the credential for which you want the value. The function returns the single value. GetActionFn operates the same way, with actions.

For structure members that are of type ObAnPluginMVData_t, each name has an associated handle that points to a list of one or more items. Each item contains a value and a handle to the next item in the list. A handle for the next item set to NULL indicates the end of the list.

The params member can be thought of according to the following diagram. You use GetDataFn to get the pointer to the list, for a specified parameter name within the params array.You then use GetFirstFn to get a handle to the information for the first item in the list. GetValueFn at this point returns the value for item 1, GetNextFn returns the handle to the information for item 2, and so on.

Illustration of GetDataFn.

6.3.4.3 ObAnPluginFns

This structure provides handles to a block of functions available in the Access Server, which the plug-in uses to manipulate data in the ObAnPluginInfo structure.

struct ObAnPluginFns {
ObASPluginGetFirstItem_t     GetFirstItemFn;
ObASPluginGetValue_t             GetValueFn;
ObASPluginGetNext_t              GetNextFn;
        ObAnPluginGetData_t              GetDataFn; 
ObAnPluginsetData_t              SetDataFn;
        ObAnPluginGetCred_t              GetCredFn;
ObAnPluginsetCred_t              SetCredFn;
ObAnPluginGetAction_t            GetActionFn;
        ObAnPluginSetAuthnUid_t          SetAuthnUidFn
        }; 

ObAnPluginFns_t is the handle pointing to this structure.

You refer to this structure when implementing ObAnPluginFn. The functions are described separately under "Functions Provided by the Access Server (C API)".

6.4 C API Functions

Functions used by the API to talk to the Access Server are of two types. They can be provided by the Access Server, in which case they are called by reference to it. Otherwise, they must be implemented in the plug-in, following the prototypes in authn_api.h.

6.4.1 Functions Provided by the Access Server (C API)

To use these functions you must call them out as members of the structure of type ObAnPluginFns that you named in your code. For example, if you implemented ObAnPluginFn and set the variable name of type ObAnPluginFns to pFnBlock, then you call GetCredFn by reference to its place in the structure, as pFnBlock->GetCredFn.

6.4.1.1 GetDataFn

This function returns a handle to a list of multivalued data for either the Params or the Context members of the ObAnPluginInfo structure. Given the handle, the plug-in must then use the list manipulation functions—GetFirstItemFns, GetValueFn, GetNextFn, GetValueFn and so on—to extract information from the list.

The function takes the form:

ObAnPluginList_t GetDataFn(
        ObAnPluginMVData_t                                                 prequesterinfo,
                const char*                                                         pName
); 

Table 6-1 describes the input parameters for this function.

Table 6-1 Input Parameters

Variable Name Purpose

prequesterInfo

Handle to a multivalued member of the ObAnPluginInfo structure passed to the plug-in.

pName

Retrieves the list of items for this name.


Output Parameters

There are no output parameters for this function.

The function returns a handle to a list of values for the given name. If the handle value is NULL, the name is not present for the structure member.

6.4.1.2 SetDataFn

This function sets a value for a name in the Params or Context members of the ObAnPluginInfo structure. The Access Server checks to see if the name already exists, and appends or overwrites the value, depending on the value of the replace flag.

The function takes the form:

ObAnASStatus_t SetDataFn(
ObAnPluginMVData_t  pRequesterContext,
const char*         pName,
const char*         pValue,
const int           replace
); 

Table 6-2 describes the input parameters for this function.

Table 6-2 Input Parameters

Variable Name Purpose

pRequesterContext

Handle to a writable, multivalued member of the ObAnPluginInfo structure passed to the plug-in.

pName

Name for the information whose value is to be set.

pValue

The value to be inserted.

replace

Specifies whether to replace or append to existing values for the name. An integer value of 0 indicates append, all other values are a request to replace the current first value for pName.


Output Parameters

There are no output parameters from this function.

The function returns one of the values for ObAnASStatus_t.


Note:

The replace option applies only to the first item in the list.

6.4.1.3 GetFirstItemFn

This function returns the handle to the first item in a list of multivalued data, once a handle to the full list has been obtained using GetDataFn. You must do at least this first step before asking for a value using GetValueFn. The handle to the full list is not the handle to the first item in the list.

The function takes the form:

ObAnPluginListItem_t GetFirstItemFn(
                ObAnPluginList_t plist
);

Table 6-3 describes the input parameters for this function.

Table 6-3 Input Parameters

Variable Name Purpose

pItem

Handle to an item.


Output Parameters

There are no output parameters for this function.

The function returns the string value of an item.

6.4.1.4 GetNextFn

This function gets a handle to the next item in a multivalued list, given the handle to the current item, which you get either with GetFirstItemFn or an earlier use of GetNextFn.

The function takes the form:

ObAnPluginListItem_t GetNextFn(
ObAnPluginListItem_t pItem
                );

Table 6-4 describes the input parameters for this function.

Table 6-4 Input Parameters

Variable Name Purpose

pItem

Handle to the current item in the list.


Output Parameters

There are no output parameters for this function.

The function returns a handle to the next item in the list. If the value returned is NULL, then you have reached the end of the list.

6.4.1.5 GetCredFn

This function retrieves the value corresponding to a credential name, given the handle to the credential information and the name. A user's authentication level can be tied to a scheme or to a resource where the user has logged in. For example, you can set the authentication level based on whether the user has logged in through Active Directory or a reverse proxy. The custom plug-in extracts this information by querying the Access Server for an ObAuthentSchemeLevel variable that is maintained in a credential list.

Only one value is allowed for a credential name.

The function takes the form:

const char *GetCredFn(
ObAnPluginSVData_t pCreds,
const char* pName
);

Table 6-5 describes the input parameters for this function.

Table 6-5 Input Parameters

Variable Name Purpose

pCreds

Handle for the credential information passed to the plug-in.

pName

Name of the credential information to retrieve.


Output Parameters

There are no output parameters for this function.

The function returns the value for the credential, or NULL if no value is found

schemeLevel = pFnBlock->GetCredFn(pInfo->Creds, "ObAuthentSchemeLevel");

6.4.1.6 SetCredFn

This function sets a value for a specified name in the credential information passed to the plug-in, given the handle to the credential information, the name of the credential to modify, and the value to store. If the name already exists, its current value is overwritten. If not, the name and value are added.

The function takes the form:

ObAnASStatus_t SetCredFn(
                ObAnPluginSVData_t pCreds,
const char*   pName,
const char*   pValue
);

Table 6-6 describes the input parameters for this function.

Table 6-6 Input Parameters

Variable Name Purpose

pCreds

Handle for the credential information passed to the plug-in.

pName

Key/name for the credential information to set.

pValue

The value to write to the credentials


Output Parameters

There are no output parameters for this function.

The following function returns one of the values for ObAnASStatus_t.

schemeLevel = pFnBlock->GetCredFn(pInfo->Creds, "ObAuthentSchemeLevel");
if(schemeLevel != NULL){
schemeLevelAsInt = atoi(schemeLevel);
schemeLevelAsInt +=10;
itoa(schemeLevelAsInt, buff, 10);
pFnBlock->SetCredFn(pInfo->Creds, "ObAuthentSchemeLevel", buff);

Example 6–1 illustrates setting the UID.

Example 6-1 To set the UID

This function sets the uid that is internal to authentication for the current user. If the uid has already been set, its value is overwritten. If not the value is added. The following example illustrates setting the UID for the user:

pFnBlock->SetCredFn(pInfo->Creds, ObAnPluginRequesterDN, "cn=Halley Starks, 
ou=LHuman Resource, ou=Los Angles, ou=Dealer1k1, ou=Latin America, ou=Ford,
o=Company,c=US");

6.4.1.7 GetActionFn

This function retrieves action information, given the handle to the action information, the name of the action to retrieve, and its type. Only one value is allowed for an action name/type combination.

The function takes the form:

const char *AnGetAction(
ObAnPluginSVData_t  pActionInfo,
const char* pName,
ObAnActionType_t pActionType);

Table 6-7 describes the input parameters for this function.

Table 6-7 Input Parameters

Variable Name Purpose

pActionInfo

Handle to action information passed to the plug-in

pName

Key/name for the action information to retrieve.

pActionType

Type of action information to get.


Output Parameters

There are no output parameters for this function.

The function returns the value for the action/type combination, or NULL if no value is found.

6.4.1.8 SetActionFn

This function sets a value in the action information passed to the plug-in, using the handle to the action information, the name of the action to modify, the value to store, and the action type. If the name and type combination already exists, its value is overwritten. If not, the name and value are added.

The function takes the form:

ObAnASStatus_t SetActionFn(
                ObAnPluginSVData_t  Creds,
const char*  pName,
const char*  pValue
ObAnActionType  pActionType);

Table 6-8 describes the input parameters for this function.

Table 6-8 Input Parameters

Variable Name Purpose

pActions

Handle for the action information passed to the plug-in.

pName

Key/name for the action information to set.

pValue

The value to write to the action.

pActionType

Type of action information to set.


Output Parameters

There are no output parameters for this function.

The function returns one of the values for ObAnASStatus_t.

6.4.1.9 SetAuthnUidFn

This function sets the uid that is internal to authentication for the current user. If the uid has already been set, its value is overwritten. If not the value is added.


WARNING:

This function is obsolete. Use SetCredFn instead.


The function takes the form:

ObAnASStatus_t SetAuthnUidFn(
char* pUid
);

Table 6-9 describes the input parameters for this function.

Table 6-9 Input Parameters

Variable Name Purpose

pUid

The new uid to be set.


Output Parameters

There are no output parameters for this function.

The function returns one of the values for ObAnASStatus_t.

6.4.2 C Functions Implemented in the Plug-in

All of the functions described in this section must be implemented by the developer in the plug-in, following the prototype provided in authn_api.h. The Access Server expects them all to be present and refuses to execute the plug-in if they are not.

The OBDLLEXPORT entry for each function is required. It provides a means for the Access Server to locate and call these functions from within the plug-in.

The Access Server calls the functions in this order:

  • GetVersion: The first time the plug-in is loaded.

  • Init: The first time the plug-in is loaded.

  • DeAllocStatusMessage: Automatically, following any of the other functions which returns a status message.

  • Fn: Each time the plug-in is used.

  • Terminate: When the Access Server shuts down, or the plug-in is unloaded

6.4.2.1 ObAnPluginGetVersion

The Access Server calls this function immediately after the plug-in is loaded. The plug-in returns the version number of the library with which it was built. The Access Server uses this version to determine if it can support the plug-in. That is, it would catch a situation in which an older version of the Access Server was being asked to support a newer version of the API, or a newer version of the Access Server was being asked to work with a plug-in version no longer supported.

The function takes the form:

OBDLLEXPORT

const char* ObAnPluginGetVersion(void);

There are no input parameters to this function.

Output parameters

There are no output parameters from this function.

The function returns the version of the authentication plug-in. This is the value set by the following line in the authn_api.h file:

#define OB_AN_PLUGIN_VERSION "X.X"

6.4.2.2 ObAnPluginInit

The Access Server calls this function immediately after making the version check. The function initializes the work space for the plug-in, which could include tasks such as connecting to a database and initializing global data for the plug-in. This function, and the two others where a presult string might be built, must allocate memory in order to return the presult string. The Access Server automatically calls the ObAnPluginDeallocStatusMsg function to deallocate this memory.

The function takes the form:

OBDLLEXPORT
ObAnPluginStatus_t ObAnPluginInit(
ObAnServerContext_t pServerContext,
ObAnPluginStatusMsg_t  pResult
);

Table 6-10 describes the input parameters for this function.

Table 6-10 Input Parameters

Variable Purpose

pServerContext

Context information of the Access Server.


Table 6-11 describes the output parameters for this function.

Table 6-11 Output Parameters

Variable Purpose

pResult

Result message reported by the function.


The function should return one of the ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.

6.4.2.3 ObAnPluginTerminate

The Access Server calls this function when it is about to terminate. The function should be written to clear whatever work space the plug-in set for itself and disconnect from any other applications, such as a database, that the plug-in might have opened.

The function takes the form:

OBDLLEXPORT
ObAnPluginStatus_t ObAnPluginTerminate(
ObAnServerContext_t  pServerContext,
ObAnPluginstatusMsg_t pResult);

Table 6-12 describes the input parameters for this function.

Table 6-12 Input Parameters

Variable Purpose

pServerContext

Context information from the Access Server.


Table 6-13 describes the output parameters for this function.

Table 6-13 Output Parameters

Variable Purpose

pResult

Result message reported by the function.


The function should return one of two ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.

6.4.2.4 ObAnPluginFn

The Access Server calls this function to request the plug-in to do the actual custom authentication work using the plug-in information and the server context. This function can also modify some of the plug-in information for use by subsequent authentication plug-ins in a scheme.

The function takes the form:

OBDLLEXPORT
ObAnPluginStatus_t ObAnPluginFn(
ObAnServerContext_t  pServerContext,
ObAnPluginFns_t   pFuncBlock,
ObAnPluginInfo_t pData
ObAnPluginstatusMsg  pResult
        );

Table 6-14 describes the input parameters for this function.

Table 6-14 Input Parameters

Variable Purpose

pServerContext

Context information for the Access Server.

pFuncBlock

Handle to a block of functions provided by the Access Server, that the plug-in needs to manipulate data.

pData

Handle to data passed to the plug-in.


Table 6-15 describes the output parameters for this function.

Table 6-15 Output Parameters

Variable Purpose

pData

Handle to data modified by the plug-in.

pResult

Result message reported by the function.


The function can return any one of the four ObAnPluginstatus_t values.

6.4.2.5 ObAnPluginDeallocStatusMsg

If another of these implemented functions sent a pResult string, the Access Server automatically calls this function to delete the memory that was assigned by the plug-in to build the message. You should ensure that it does so.

The function takes the form:

OBDLLEXPORT
void ObAnPluginDeallocStatusMsg(
ObAnPluginstatusMsg_t pStatusMsg
        );

Table 6-16 describes the input parameters for this function.

Table 6-16 Input Parameters

Variable Purpose

pStatusMsg

Status Message to be deallocated.


Output Parameters

There are no output parameters from this function.

The function returns nothing

6.5 C Authentication Plug-in Example

Example 6–2 shows some basic uses of the plug-in functions.

Example 6-2 Authentication Plug-in Example.

/*
* Copyright (c) 2005, Oracle Inc. All Rights Reserved.
*
* authn_api.c

* Custom Authentication plugin.
*
* This implementation of the 5 authentication functions is built
* into a DLL named SimpleAPI, and then, in a slightly modified
* form, into a DLL called SimpleAPI2.
* The differences between the two forms of the plugin are these:
* 1) the second form writes the number 2 into all of its
* log messages
* 2) the second form does not make a check on the param
* values or write context data back to the info structure.
*
* It shows:
*
* 1. Example implementations of all 5 functions.
* 2. Examples for extracting data from many of the structures.
* 3. An example of writing new data to the info structure.
* 3. A simple way to log results for testing.
*/


#include "authn_api.h"
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <iostream.h>
#include <malloc.h>
#include <fstream.h>

#ifdef _WIN32
#undef strcasecmp
#define strcasecmp stricmp
#endif
/*
* Implementation of ObAnPluginGetVersion
*
* The data logged by this function appears only once, when the
* Plugin is first loaded.
*
*/
OBDLLEXPORT const char* ObAnPluginGetVersion(void)
{
FILE *file = fopen("d:\\ANtestfile.txt", "a+");
fprintf (file, "\n%s%s\n", "sending Authn version,
which is ",OB_AN_PLUGIN_VERSION);
fclose(file);
return OB_AN_PLUGIN_VERSION;
}
/*
* Implementation of ObAnPluginInit
*
* The logged data appears only once, when the Plugin is first loaded.
*
*/
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginInit(
ObAnServerContext_t pContext,
ObAnpluginStatusMsg_t pResult)
{
//      Values to be read in by this function are initialized.
        ObAnpluginStatus_t rtval;
const char* pASPluginVersion = NULL;
const char* pASInstallDir    = NULL;
FILE *file = fopen("d:\\ANtestfile.txt", "a+");
fprintf (file, "\n%s\n", "initializing");        
if(pContext != NULL) {
pASPluginVersion = pContext->AccessServerAnPluginAPIVersion;
pASInstallDir    = pContext->AccessServerInstallDir;
fprintf (file, "\n%s%s\n", "  version is ",pASPluginVersion);
fprintf (file, "\n%s%s\n", "  AS directory is ",
pASInstallDir);
}
if((pASPluginVersion != NULL) &&
         (strcmp(pASPluginVersion, OB_AN_PLUGIN_VERSION) == 0)) {
rtval = ObAnPluginStatusContinue;
*pResult = strdup("Success version check");
}
else {
/*
* return failure, because the version provided by the AS
* is not what was expected.
*/
rtval = ObAnPluginStatusAbort;
}
fclose(file);
return rtval;
}
/*
* Implementation of ObAnPluginTerminate
* The logged data appears only when the Access Server terminates.
*/
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginTerminate(
ObAnServerContext_t pContext,
ObAnPluginStatusMsg_t pResult)
{
FILE *file = fopen("d:\\ANtestfile.txt", "a+");
fprintf (file, "\n%s\n", "terminating gracefully");
*pResult = strdup("Success, terminated");
fclose(file);
return ObAnPluginStatusContinue;
}
/*
* Implementation of ObAnPluginDeallocStatusMsg
* The logged data appears following each other function
* that provides a presult.
*/
OBDLLEXPORT void ObAnPluginDeallocStatusMsg(
ObAnPluginStatusMsg_t pResult)
{ 
FILE *file = fopen("d:\\ANtestfile.txt", "a+");
fprintf (file, "\n%s\n", "deallocating");

if(pResult != NULL && *pResult != NULL) {
free(*pResult);
*pResult = NULL;
}
fclose(file);
}
/*
* Implementation of ObAnPluginFn
*/
OBDLLEXPORT ObAnpluginstatus_t ObAnPluginFn(
ObAnServerContext_t pContext,
ObAnPluginFns_t pFnBlock,
ObAnPluginInfo_t pInfo,
        ObAnPluginStatusMsg_t pResult)
{
// rtval is initialized to allow continuing to the next 
// plugin
ObAnPluginStatus_t rtval = ObAnPluginStatusContinue;

ObAnPluginList_t list;
ObAnPluginListItem_t item;
ObAnASStatus_t writeres=100;

// These are initialized, and get overwritten with real data
// if any is found below
const char* Resource;
const char* Operation;
const char* UserDN;
const char* con1   = "cdummy1";
const char* con2   = "cdummy2";
const char* con3   = "cdummy3";
const char* param1 = "pdummy1";
/* this initialization is key to the example*/
const char* param2 = NULL; 
const char* param3 = "pdummy3";
FILE *file = fopen("d:\\testfilen_fn.txt", "a+");
fprintf (file, "\n%s\n", "Starting Fn");
// This is an example of getting data from the Creds member
// of Info, using the predefined names
Resource =pFnBlock->GetCredFn
(pInfo->Creds,ObAnPluginRequestResource);
Operation=pFnBlock->GetCredFn
(pInfo->Creds,ObAnPluginRequestOperation);
UserDN   =pFnBlock->GetCredFn
(pInfo->Creds,ObAnPluginRequesterDN);
fprintf (file, "\n%s%s\n", "resource is ",Resource);
fprintf (file, "\n%s%s\n", "operation is ",Operation);
fprintf (file, "\n%s%s\n", "user DN   is ",UserDN);
// This set of code tries to extract the context information.
//
list   = pFnBlock->GetDataFn(pInfo->Context,"isthereany");
// For the first use of the plugin, none has been set.
// There is no context data, and no context name called isthereany.
//
// For the second use of the plugin, context data may be present
// and if so will be read in.
if (list != NULL){
fprintf(file, "\n%s\n","found context data!!");
item   = pFnBlock->GetFirstItemFn(list);
if (item != NULL){
con1 = pFnBlock->GetValueFn(item);
item   = pFnBlock->GetNextFn(item);
if (item != NULL){
con2 = pFnBlock->GetValueFn(item);
item   = pFnBlock->GetNextFn(item);
if (item != NULL){
param3 = pFnBlock->GetValueFn(item);
}
}
}
}
fprintf (file, "\n%s%s\n", "first context   is ",con1);
fprintf (file, "\n%s%s\n", "second context  is ",con2);
fprintf (file, "\n%s%s\n", "third context   is ",con3);
//      This set of code extracts the param information.
// The value of param2, which is set, or not, in the Authentication
// Scheme, controls the test. 
list   = pFnBlock->GetDataFn(pInfo->Params,"myparam");
if (list != NULL){
item   = pFnBlock->GetFirstItemFn(list);
if (item != NULL){
param1 = pFnBlock->GetValueFn(item);
item   = pFnBlock->GetNextFn(item);
if (item != NULL){
param2 = pFnBlock->GetValueFn(item);
item   = pFnBlock->GetNextFn(item);
if  (item != NULL){
param3 = pFnBlock->GetValueFn(item);
}
}
}
}

fprintf (file, "\n%s%s\n", "first param   is ",param1);
fprintf (file, "\n%s%s\n", "second param  is ",param2);
fprintf (file, "\n%s%s\n", "third param   is ",param3);
*pResult = strdup("Success");
// -----> The second form of the plugin omits the code from here
//      If there is a value set for param2 under the myparam 
// name in the authentication scheme, then the logic here
// returns allowed to the Access Server, and the next plugin
// will not be used.
// If there is no value set for param2, then the logic here
// sets a value in the context data, which will be seen by the
// next plugin.
if (param2 != NULL){
rtval = ObAnPluginStatusAllowed;
fprintf (file, "\n%s\n", "second param is not NULL");
}
else {
fprintf (file, "\n%s\n", "second param was NULL");
writeres=pFnBlock->SetDataFn
(pInfo->Context, "isthereany", "context1", 0);
fprintf (file, "\n%s%i\n", "AS returned", writeres);
}
// -----> to here
fclose(file);   
return rtval;
}

The following are screens shot that show the authentication scheme that uses the example plug-in. Note that no second value is entered for the myparam parameter name.

Setup for the Authentication Scheme
The plugins page.

Given this version of the authentication scheme, the corresponding trace information from the example code is:

sending Authn version, which is 5.0
initializing
version is 5.0
AS directory is
d:\netscape\server4\ws41sp6\docs\techpubs_fcs88\as\access

deallocating
in 2, sending Authn version, which is 5.0

in 2, initializing
version is 5.0

AS directory is
d:\netscape\server4\ws41sp6\docs\techpubs_fcs88\as\access

Starting Fn
resource  is /test3
operation is GET
user DN   is cn=Rohit Valiveti,ou=Sales,ou=Dealer1k1,ou=Latin
America,ou=Ford,o=Company,c=US
first context   is cdummy1
second context  is cdummy2
third context   is cdummy3
first param   is thedata1
second param  is (null)
third param   is pdummy3
second param was NULL

AS returned 0

in 2, Starting Fn
resource  is /test3
operation is GET
user DN   is cn=Rohit Valiveti,ou=Sales,ou=Dealer1k1,ou=Latin
America,ou=Ford,o=Company,c=US
found context data!!
first context   is context1
second context  is cdummy2
third context   is cdummy3
first param   is pdummy1
second param  is (null)
third param   is pdummy3


6.6 Managed Code API Environment

The following sections describe the development environment for the managed plug-in API, including support file location and major components.

Support Files Location for the Managed Code API

When you install the Access Server component of the Access System, you put it into an installation directory, ASInstall_Dir, for example:

C:/COREid/access/oblix

Sample files for the authentication plug-in API are installed within this directory, at:

ASInstall_Dir/sdk/managed/authn++

Authn_api contains source code for a simple example authentication plug-in, an example project file. Some of the definitions in this file are essential for building and operating the API. When the plug-in is loaded by the Access Server, it expects to find the set of four functions in authn_api.h implemented within the plug-in.

To build

  1. Under the samples directory, copy the content of the authn_api directory to a second directory, for example myplugin.

  2. Within the new directory, change the content of the authn.c file, create additional files, or both to provide the desired functionality specific to your plug-in.

  3. Modify the project to include and compile all of your source code.

  4. Build the project.

    The resulting *.dll is your new plug-in.

  5. See "Managed Code API Plug-in Directory" for details about storing the plug-in and implementing an example.

6.6.1 Managed Code API Plug-in Directory

The plug-in you created must be stored in the system where the Access Server is running, in the directory:

ASInstall_Dir/lib

The Access Administrator needs to know the filename of the plug-in, and its required and optional data names in order to properly configure the plug-in into an authentication scheme. See the Oracle Access Manager Access Administration Guide for a more detailed discussion of authentication scheme configuration.

Following the "C Authentication Plug-in Example" is a screen showing the authentication scheme configuration used to support the example. To use the example with managed code, be sure to add the following in the parameters text box for the authn_api plug-in:

obtype="managed", obnamespace="sample"

6.7 Managed Code API Data

This section describes the various types of constant and variable data that the API uses.

6.7.1 Defines (Managed Code)

The managed_plugin_interface.h predefines several values for use as fixed argument values when working with some functions.

pubic_value class AnDefines {
static string *ObAnPluginResourceRequest                                                                                                                   = S"Resource";
static string *ObAnPluginRequestOperation                                                                                                                  = S"Operation";
static string *ObAnPluginRequesterIP                                                                                                                       = S"RequesterIP";
static string *ObAnPluginRequesterDN                                                                                                                       = S"RequesterDN";
static string *OB_AN_PLUGIN_VERSION                                                                                                                 = S"5.0";
};

Value Name Meaning
OB_AN_PLUGIN_VERSION When ObAnPluginGetVersion is called, this value must be returned to the Access Server. The value in the header file may change with releases of the product.
ObAnPluginRequestResource The resource after the host name and port, for example: /basic/page.htm.
ObAnPluginRequestOperation The operation being performed on the resource.
ObAnPluginRequesterDN If an authentication plug-in has set the DN, this is where other plug-ins can access that DN. The plug-in named credential_mapping always sets the DN.

Custom authentication plug-ins can set the DN, once they have determined what it is, by calling SetCredFn.

ObAnPluginRequesterIP The IP address of the client that issued this request.

6.7.2 Interfaces (Managed Code)

The Access Server and API use interfaces to allow manipulation of data structures that the Access Server maintains for use by the plug-in. These interfaces are named and described in the following paragraphs.

Interface Purpose
IObAnPluginSVData An interface that provides functions to get singe-valued data. It is used to locate Creds and ActionInfo in the ObAnPluginInfo interface.
IObAnPluginMVData An interface that provide functions to multivalued data. They are used to locate Params and Context in the ObAnPluginInfo interface.
IObASPluginListItem An interface pointing to an item in a list.
IObAnPluginInfo An interface providing functions that contain information from the Access Server and data generated by the plug-in.
IObAnServerContext An interface that provides functions that contain general information about the Access Server.

The Access Server groups related data items into named structures, allocates the memory for them, and carries the data for them. Structures are opaque to the developer, meaning that they can be used to transfer information to and from the Access Server, but you cannot change the way the structure is organized or the format of the data that it contains. The content of the structure can be changed in some instances.

The following are the interfaces that are used in the Authentication Plug-in API.

6.7.2.1 IObAnServerContext

This interface provides information about the Access Server that the plug-ins may need.

public _gc _interface IObAnServerContext {
_property String* get_AccessServerInstallDir();
_property String* get_AccessServerAnPluginAPIVersion();
};

Data Type/Name Purpose
get_AccessServer InstallDir Path to the installation directory for the Access Server, for example, COREid/Access. Note: this does not include the /oblix directory.
get_AcessServerAn PluginAPIVersion The lowest authentication plug-in API version that the instance of the Access Server supports.

6.7.2.2 IObAnPluginInfo

The Access Server creates an object with data determined by an authentication rule, and provides the interface to the plug-in. The plug-in modifies data within the structure and may append new data to it as work progresses through the plug-in. When there are multiple plug-ins being carried out as part of an authentication scheme, it also provides a means to set variable information for the first plug-in in the rule, and passes information from one plug-in to another within the scheme.

public _gc _interface IObAnPluginInfo {
IObAnPluginSVData* get_Creds();
IObAnPluginMVData* get_Params();
IObAnPluginMVData* get_Context();
IObAnPluginSVData* get_ActionInfo();
};

Function Purpose
get_Creds The creds function consists of all information submitted by the user or application that is trying to access a resource. The plug-in may add to or replace this data. The data is passed to the next plug-in in sequence. As a result, the data can be used by the plug-in to communicate with the plug-in following it in an authentication scheme. The Access Server provides four predefined names within this list: Resource, Operation, RequesterDN, and RequesterIP.
get_Params The parameters specified in the plug-in configuration. The plug-in may add to or replace this data within the plug-in. This data is not passed to the next plug-in.
get_Context Data created by the plug-in. The plug-in may add to or replace this data. The data is passed to the next plug-in in sequence.
get_ActionInfo Action information that is specified in the plug-in configuration. The plug-in may add to or replace this data. Actions can also be set and passed to the next plug-in, but the final user of the action information is the Access Server.

This interface can be thought of as an array of four nested arrays, the structure members. Each member holds one or more names.

6.7.2.3 IObAnPluginSVData

To get the value, you use the GetCred function in the IObAnPluginSVData interface, and provide the name of the credential for which you want the value. The function returns a single value. GetAction operates in the same actions.

For structure members that are of type IObAnPluginSVData, the array consists of a set of names and a single value associated with each one. For example, the creds member can be though of this way:

Name value
"Resource" 1 value
"Operation" 1 value
"RequesterDN" 1 value
"RequesterIP" 1 value
User Created Credential Name 1 value

Function Purpose
GetCred This function retrieves the value corresponding to a credential name, given the handle to the credential information and the name. A user's authentication level can be tied to a scheme or to a resource where the user has logged in. For example, you can set the authentication level based on whether the user has logged in through Active Directory or a reverse proxy. The custom plug-in extracts the information by querying the Access Server for an ObAuthntSchemeLevel variable that is maintained in a credential list.
SetCred This function sets a value for a specified name in the credential information passed to the plug-in, given the handle to the credential information, the name of the credential to notify, and the value to store. If the name already exists, its current value is overwritten. If not, the name and value are added.
GetAction This function retrieves action information, given the handle to the action information, the name of the action to retrieve, and its type. Only one value is allowed for an action name/type combination.
SetAction This function sets a value in the action information passed to the plug-in, using the handle to the action information, the name of the action to modify, the value to store, and the action type. If the name and type combination already exists, its value if overwritten. If not, the name and value are added.

6.7.2.4 IObAnPluginMVData

The IObAnPluginMVData interface provides functions to work on objects that contain a list of one or more items. Each item contains a value.

Function Purpose
get_Data This function returns a handle to a list of multivalued data for either the Params or the Context members of the IObAnPluginInfo interface. Given the handle, the plug-in must then use the list manipulation functions—GetFirstItemFns, GetValueFn, GetValueFn, and so on—to extract information from the list.
set_Data This function sets a value for a specified name in the credential information passed to the plug-in, given the handle to the credential information, the name of the credential to modify, and the value to store. If the name already exists, its current value is overwritten. If not, the name and value are added.

6.7.2.5 IObAsPluginListItem

The list returned by the get_Data function can be traversed using standard Enumerator functions. Each item in the list is returned whose value can be obtained by using this interface.

Function Purpose
get_Value This interface provides the function to get the value of an item.

6.7.3 Managed Code Return Values

Many of the functions the Access Server and API use to communicate are expected to return a status value. These are all predefined in several categories as described here.

6.7.3.1 ObAnActionType

These are action flags that the API returns to the Access Server, to tell it what actions to take.

_value enum ActionType {
ObAnSuccessRedirect = 0,
ObAnFailRedirect = 1,
ObAnSuccessProfileAttrs = 2,
ObAnFailProfileAttrs = 3,
ObAnSuccessFixedVals = 4,
ObAnFailFixedVals = 5
};

Name Description
ObAnSuccessRedirect For successful authentication, tells the Access Server to set the redirection URL, as defined in the authentication rule.
ObAnFailRedirect For failed authentication, tells the Access Server to set the redirection URL, as defined in the authentication rule.
ObAnSuccessProfileAttrs For successful authentication, tells the Access Server to set the profile attributes for the action using values provided by the authentication rule, which may have been added to by the plug-in.
ObAnFailProfileAttrs For failed authentication, tells the Access Server to set the profile attributes for the action using values provided by the authentication rule, which may have been added to by the plug-in.
ObAnSuccessFixedVals For successful authentication, tells the Access Server to set the fixed values defined in the authentication rule, which may have been added to by the plug-in.
ObAnFailFixedVals For failed authentication, tells the Access Server to set the fixed values defined in the authentication rule, which may have been added to by the plug-in.

6.7.3.2 ObAnPluginstatus

Plug-ins must return one of these values to the Access Server to show the result of the attempt to authenticate.

_value enum ObAnPluginStatus { 
ObAnPluginstatusContinue = 0,
ObAnPluginstatusAllowed = 1,
ObAnPluginstatusDenied = 2, 
ObAnPluginstatusAbort = 3 
};

Value Name Meaning
ObAnPluginStatusAbort You set this value to show that a fatal error occurred while processing authentication.Processing for this authentication request does not continue after this plug-in.
ObAnPluginStatusAllowed Credentials were processed and authentication succeeded. No further authentication plug-ins are processed.
ObAnPluginStatusDenied Credentials were processed and authentication failed. Processing does not continue after the function. Authentication fails.
ObAnPluginStatusContinue Authentication processing continues after the function. If all plug-ins in an authentication scheme return continue, authentication is implicitly allowed.

6.7.3.3 ObAnASStatus

When a plug-in calls upon the Access Server to perform one of its built-in functions, the Access Server attempts to execute the function, and returns one of these values.

_value enum ASStatus{
  bAnASStatusSuccess = 0,
  bAnASStatusFailed
};

Value Name Meaning
ObAnASStatusSuccess The Access Server successfully performed the operation.
ObAnASStatusFailed The Access Server did not perform the operation. The most likely cause of this error is that the plug-in tried to change values that it is not allowed to change. An example is an attempt to add a second value for a name, to an array member which permits only single values.

6.7.4 Managed Code Functions Implemented in the Plug-in

All of the functions described in this section must be implemented by the developer in the plug-in, following the prototype provided in managed_plugin_interface.h.

For Authentication plug-ins, you must define a class with the following functions:

public _gc class ObAuthzPlugin
{
public:
  ObAuthnPlugin();
  String* ObAnPluginGetVersion();
  IObAuthnPlugin::Status ObAnPluginInit
Oblix::IObAnServerContext* context, String* msg);
        ObAuthnPlugin::Status
ObAnPluginFN(Oblix::IObAnServerContext* context, Oblix::IObAnPluginInfo* info);
        IObAuthnPlugin::Status ObAnPluginTerminate
(Oblix::IObAnServerContext* context, String* msg);
};

The Access Server calls the functions in this order:

  • ObAnPluginGetVersion—The first time the plug-in is loaded.

  • ObAnPluginInit—The first time the plug-in is loaded.

  • ObAnPluginFn—Each time the plug-in is used.

  • ObAnPluginTerminate—When the Access Server shuts down, or the plug-in is unloaded.

6.7.4.1 ObAnPluginGetVersion

The Access Server calls this function immediately after the plug-in is loaded. The plug-in returns the version number of the library with which it was built. The Access Server uses this version to determine if it can support the plug-in. That is, it would catch a situation in which an older version of the Access Server was being asked to support a newer version of the API, or a newer version of the Access Server was being asked to work with a plug-in version no longer supported.

The function takes the form:

OBDLLEXPORT
const char* ObAnPluginGetVersion(void);

Input Parameters

There are no input parameters to this function.

Output Parameters

There are no input parameters to this function.

The function returns the version of the authentication plug-in. This is the value set by the following line in the authn_api.h file:

#define OB_AN_PLUGIN_VERSION                                                                          "X.X"

6.7.4.2 ObAnPluginInit

The Access Server calls this function immediately after making the version check. The function initializes the work space for the plug-in, which could include tasks such as connecting to a database and initializing global data for the plug-in. This function, and the two others where a presult string might be built, must allocate memory in order to return the presult string. The Access Server automatically calls the ObAnPluginDeallocStatusMsg function to deallocate this memory.

The function takes the form:

OBDLLEXPORT
ObAnPluginStatus_t ObAnPluginInit(
ObAnServerContext_t                                                                pServerContext,
ObAnPluginStatusMsg_t                                                              pResult
};

Input Parameters

Variable Purpose
pServerContext Context information of the Access Server.

Output Parameters

Variable Purpose
pResult Result message reported by the function.

The function should return one of the ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.

6.7.4.3 ObAnPluginTerminate

The Access Server calls this function when it is about to terminate. The function should be written to clear whatever work space the plug-in set for itself and disconnect from any other applications, such as a database, that the plug-in might have opened.

Input Parameters

Variable Purpose
pServerContext Context information from the Access Server.

Output Parameters

Variable Purpose
pResult Result message reported by the function

The function should return one of two ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.

6.7.4.4 ObAnPluginFn

The Access Server calls this function to request the plug-in to do the actual custom authentication work using the plug-in information and the server context. This function can also modify some of the plug-in information for use by subsequent authentication plug-ins in a scheme.

Input Parameters

Variable Purpose
pServerContext Context information for the Access Server.
pFuncBlock Handle to a block of functions provided by the Access Server, that the plug-in needs to manipulate data.
pData Handle to data passed to the plug-in.

Output Parameters

Variable Purpose
pData Handle to data modified by the plug-in.
pResult Result message reported by the function.

The function can return any one of the four ObAnPluginstatus_t values.

6.8 Troubleshooting

For unit testing of plug-ins, writing the results to a file as the example here does is the best approach. The pResult text is captured by the Access Server audit log only if authentication fails, and then only for Solaris. If you write to a file, be sure you have the correct permissions for writing into the directory holding the file.

Performance is a developer responsibility and should be considered when designing a plug-in. The total time required to process one authentication request depends on the performance of all the plug-ins that are invoked while processing that request.

Plug-ins are trusted by the Access Server. No access check is performed when giving pre-configured information to the plug-in.

A coding problem in a plug-in, such as a memory or access violation or segmentation, or bus error fault, can cause the Access Server to fail.

Plug-ins allow optional parameters, which would usually be filled in by an Access Administrator when schemes are created. Plug-ins should be able to gracefully handle the situation in which values for these parameters are not supplied.

If requests seem to fail without reason, check the path of the shared library to be sure it is correct; it must be available at ASInstall_Dir/lib. Also check to be sure that the Authentication Scheme refers to the correctly spelled shared library name.

Be sure that the ObAuthnplug-inInit function gets called and does not return abort (turn auditing on for authentication failure and see if anything appears in the audit logs.)

6.9 Standard Plug-Ins

The Access System provides several authentication plug-ins as part of a standard installation. They are described in this section. You can use these plug-ins in combination with your own custom plug-ins to create Authentication Schemes.

The Access System supports several challenge methods (Basic, X.509 Certificate, and Form), as described in the Oracle Access Manager Access Administration Guide. The plug-ins described here can be used with challenge methods as follows:

6.9.1 Credential Mapping Plug-In

The following are the details for the plug-in.

Characteristic Description
Name credential_mapping
Purpose Maps user-entered information to match a valid Distinguished Name (DN) in the directory
Result If one, and only one, DN matches the specified criteria, execution of the authentication scheme continues. The obMappingBase and obMappingFilter are added to the list of credentials and the uid carried in the credentials is set to the value of the DN. Authentication fails if zero or more than one DN is returned.
Dependency This plug-in should be present in the scheme, if you are going to need a DN.

obMappingBase - Base DN for the LDAP search. If omitted or empty, the directory base is used

obMapping Filter - Filter for the LDAP search. This parameter is required.
Parameters ObDomain - Used only when authentication is being done against a specific directory in an Active Directory Forest and the authentication method is basic. Value for this parameter is one of the configured Directory Server profile names.

obEnable Credential Cache - Turns off the credential mapping cache in the credential_mapping plugin. Using this parameter, a deactivation takes effect the next time the user authenticates. If you deactivate a user while they are logged in, the user will still have access to resources based on policy information. However, if the obEnableCredentialCache parameter is set to false, once the user's session token expires or the user logs out, the next time the user is authenticated, they are not allowed into a protected site

Example Parameters obMappingBase="o=Company,c=US",obMappingFilter="(&(objectclass=inetOrgPerson)(uid=%userid%))"

By default, the credential mapping cache is turned on. The following table shows the values for obEnableCredentialCache:

obEnableCredentialCache

Value Interpretation
no value Credential mapping cache turned on
true Credential mapping cache turned on
false Credential mapping cache turned off

An example of the credential_mapping Authentication plug-in with credential mapping cache turned off:

credential_mapping
obMappingBase="%domain%",obMappingFilter="(&(&(objectclass=user)(samaccountname=
%userid%))(|(!(obuseraccountcontrol=*))(obuseraccountcontrol=ACTIVATED)))",obdom
ain="domain",obEnableCredentialCache="false"

To set the obEnableCredentialCache parameter

  1. In the System Console, select Access System Configuration.

  2. Click Authentication Schemes.

  3. Select the Authentication Scheme you want to modify.

  4. Click Modify.

  5. Add the obEnableCredentialCache="false" parameter to the credential_mapping plug-in


Note:

For details about context-specific data for an authentication request and form-based authentication to pass the originally requested URL to a change password servlet, see the Oracle Access Manager Access Administration Guide.

6.9.2 Validate Password Plug-In

The following are details for this plug-in.

Characteristic Description
Name validate_ password
Purpose Validates the password entered at the browser against the user's password in the directory.
Result If the user-entered password matches the password in that user's directory entry, execution of the authentication scheme continues. If not, it fails. Nothing is added to the list of credentials.
Dependency This plug-in requires a valid Distinguished Name (DN) therefore it is best to call the credential_mapping plug-in before calling this plug-in.
Parameters obCredentialPassword -Specifies the name of the password field. This parameter must be listed first

obAnonUser - (optional) Specifies a user ID that is considered authenticated with any password, for example, guest or anonymous. This user ID must map to a user profile in the directory, preferably one with restricted access. Multiple obAnonUser parameter values are allowed for a single plug-in

Example Parameters obCredentialPassword="password"obAnonUser="cn=anonymous, o=Company, c=US"

6.9.3 Certificate Decode Plug-In

The following are details for this plug-in.

Characteristic Description
Name cert_decode
Purpose Decodes an X.509 certificate and extracts the components of the certificate's subject and issuer DNs.
Result If the decoding of the certificate is successful, for each component the plug-in inserts a credential with a certSubject or certIssuer prefix. For instance, if your certificates have a subject name such as givenName=somename, the plug-in will add the credential certSubject.givenName=somename to the credential list. If not, authentication fails.
Dependency The browser must supply an X.509 certificate as part of the credentials.
Parameters None
Notes For additional information on this plug-in, see the Oracle Access Manager Access Administration Guide.

6.9.4 Selection Filter Plug-In

The following are details for this plug-in.

Characteristic Description
Name Selection Filter Plug-In
Purpose Applies a filter to a user's credentials.
Result If the credentials meet the criteria specified by the filter, the credentials are accepted and authentication continues. If not, authentication fails.
Dependency The data to be substituted in ObSelectionfilter must be in credentials before this plug-in runs. For the example parameters provided in this table, cert-decode must run before selection-filter, in order to provide the certissuer information.
Parameters obSelectionFilter - Filter to apply to the user credentials.
Example Parameters obSelectionFilter="(%certIssuer.CN%=Verisign Class I CA)"

6.9.5 NT/Win2000 Plug-In

The following are details for this plug-in.

Characteristic Description
Name authn_windows
Purpose Given a user name, password, and domain in the credentials, authenticates these against an NT domain, Windows 2000 domain, or Windows 2000 Kerberos. When using the Basic challenge method, the domain should be entered in the user name field. However, when using the Forms challenge method you may want to provide a field in the form for the user to type in a distinct domain name.
Dependency When using the Basic Challenge method, the domain name should be entered in the user name field in the form Domain\Name.When using the Forms Challenge method, the form can be designed to include a field specifically for domain.
Parameters ntusername - Name of the parameter containing the user name.

ntpwd - Name of the parameter containing the password.

ntdomain - (optional) Name of the parameter containing the domain

Example Parameters ntusername="userid"

ntpwd="password"

ntdomain="domain"


6.9.6 SecurID Plug-In

The following are details for this plug-in.

Characteristic Description


Name authn_securid


Purpose Authenticates credentials from a user's SecurID token against a SecurID ACE Server. Supports SecurID Next Tokencode Mode and New PIN Mode operations.


Result If the ACE Server returns success, authentication continues. If not, authentication fails.


Dependency None


Parameters Name Default REQ/OPT Comments
fullformdir none REQ Full path to the SecurID forms.
machine none REQ Name of the Web server doing the SecurID authentication. If you are redirecting all SecurID authentications, this is the Web server name that you are redirecting to. Example: securid.abc.com:8888.
username login OPT If you are using the sample forms, set this value to login. Enter the value as a creds challenge parameter for the plug-in, and in the ObMappingFilter parameter for the Credential Mapping plug-in.
passcode password OPT If you are using the sample forms, set this value to password. If you want to specify a different value, you must provide it as a creds challenge parameter for the plug-in.
formdir <WebGate_install_ dir>/ securid-forms/ OPT The path, relative to where the WebGate is installed, to the SecurID forms. It requires a trailing slash(/). To use a different path, use the new value here and for fullformdir, and change the value for the form challenge parameter when configuring the plug-in.
httpType http:// OPT Type of Web server that is handling SecurID authentications. The two valid values are http:// and https://.
choiceLabel choice OPT Name of the field in the HTML form corresponding to the user's choice of how a PIN is generated. Set this using the creds challenge parameter.
newpinLabel newpin OPT Name of the field in the HTML form corresponding to the new PIN entered by the user. Set this using the creds challenge parameter.
newpinLabel2 newpin2 OPT Name of the field in the HTML form corresponding to the user's re-entered new PIN. Set this using the creds challenge parameter.
Example Parameters fullformdir="<WebGate_install_dir>/access/oblix/securid-forms/"machine="securid.abc.com:8888"