Oracle® Access Manager Developer Guide 10g (10.1.4.0.1) Part Number B25346-01 |
|
|
View PDF |
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:
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.
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.
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.
The following sections describe the development environment for the plug-in API, including support file location and major components.
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
Under the samples directory, copy the content of the authn_api directory to a second directory, for example myplugin.
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.
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.
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.
This section describes the various types of constant and variable data that the API uses.
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. |
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. |
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.
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. |
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. |
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. |
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.
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 |
AccessServerAnPluginAPIVersion |
The lowest authentication plug-in API version the instance of the Access Server supports. |
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.
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)".
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.
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.
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 |
---|---|
|
Handle to a multivalued member of the ObAnPluginInfo structure passed to the plug-in. |
|
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.
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 |
---|---|
|
Handle to a writable, multivalued member of the ObAnPluginInfo structure passed to the plug-in. |
|
Name for the information whose value is to be set. |
|
The value to be inserted. |
|
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. |
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.
Output Parameters
There are no output parameters for this function.
The function returns the string value of an item.
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.
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.
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 |
---|---|
|
Handle for the credential information passed to the plug-in. |
|
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");
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 |
---|---|
|
Handle for the credential information passed to the plug-in. |
|
Key/name for the credential information to set. |
|
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");
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 |
---|---|
|
Handle to action information passed to the plug-in |
|
Key/name for the action information to retrieve. |
|
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.
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 |
---|---|
|
Handle for the action information passed to the plug-in. |
|
Key/name for the action information to set. |
|
The value to write to the action. |
|
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.
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.
Output Parameters
There are no output parameters for this function.
The function returns one of the values for ObAnASStatus_t.
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
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"
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 |
---|---|
|
Context information of the Access Server. |
Table 6-11 describes the output parameters for this function.
The function should return one of the ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.
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 |
---|---|
|
Context information from the Access Server. |
Table 6-13 describes the output parameters for this function.
The function should return one of two ObAnPluginStatus_t values, either ObAnPluginStatusContinue or ObAnPluginStatusAbort.
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 |
---|---|
|
Context information for the Access Server. |
|
Handle to a block of functions provided by the Access Server, that the plug-in needs to manipulate data. |
|
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 |
---|---|
|
Handle to data modified by the plug-in. |
|
Result message reported by the function. |
The function can return any one of the four ObAnPluginstatus_t values.
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.
Output Parameters
There are no output parameters from this function.
The function returns nothing
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.
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
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
Under the samples directory, copy the content of the authn_api directory to a second directory, for example myplugin.
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.
Modify the project to include and compile all of your source code.
Build the project.
The resulting *.dll is your new plug-in.
See "Managed Code API Plug-in Directory" for details about storing the plug-in and implementing an example.
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"
This section describes the various types of constant and variable data that the API uses.
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. |
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.
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. |
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.
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. |
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. |
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. |
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.
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. |
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. |
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. |
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.
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"
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.
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.
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.
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.)
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:
Credential Mapping—All methods
Validate Password—Basic, Form
Certificate Decode—X.509 Certificate
Selection Filter—All methods
NT/Windows 2000—Basic, Form
Secure ID—Form
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.
|
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
In the System Console, select Access System Configuration.
Click Authentication Schemes.
Select the Authentication Scheme you want to modify.
Click Modify.
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. |
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
|
Example Parameters | obCredentialPassword="password"obAnonUser="cn=anonymous, o=Company, c=US" |
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. |
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)" |
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.
|
Example Parameters | ntusername="userid"
|
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 " |