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

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

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

7 Authorization Plug-in API

The Access Server controls access to resources by requiring requestors to be both authenticated and authorized. Authentication is the processes by which users establish and prove their identities in order to gain access. Authorization determines what operations users are permitted to perform after they have been authenticated. See Oracle Access Manager Access Administration Guide for details on configuring authentication and authorization using the administration console.

This chapter describes support for authorization.

This chapter discusses the following topics:

7.1 About the Authorization Plug-In API

The Authorization plug-in API provides a way for developers to create modules, called plug-ins, that are used within an authorization scheme. Schemes are included in authorization rules, and one or more authorization rules, along with one authentication rule and one audit rule, make up a policy that controls access to resources within a domain, such as URLs within a Web site or a set of methods within an application. Oracle Access Manager provides two standard resource types, HTTP and EJB, but others can be easily added and defined by administrators. See the Oracle Access Manager Access Administration Guide for instructions on creating resource types, domains, policies, rules and schemes.

Plug-ins within authorization schemes are used for two purposes:

Execution of an authorization plug-in delivers one of the following results, which are described in more detail in the sections that follow, at "ObAzplug-instatus_t"

Custom action plug-ins can be directed to execute if the authorization plug-in has allowed access or if access has been denied. They are used to return data to the AccessGate or to perform a service, such as to notify some person or log a transaction.

To use a plug-in created by the Authorization Plug-in API, two types of information need to be configured by an administrator.

To create the plug-in itself, refer to the other sections in this chapter:

7.1.1 Support for C and Managed Code

You can now write plug-ins using any language supported by the Microsoft .NET framework, including C, MC++, and Visual Basic. If you are using the plug-in in a Windows environment, managed code enables you to select from a variety of implementation languages and provides the other benefits of managed code.

7.1.2 Globalization and Custom C Authorization Plug-in Interfaces -- reviewed/updated

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

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

7.1.2.1 Backward Compatibility

When you upgrade an older Access Server to 10g (10.1.4.0.1), the value ="IsBackwardCompatible" Value="false" is set in the Access Server globalparams.xml file automatically. A backward-compatible Access Server continues to send data to authorization 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.

7.2 API Environment

The following sections describe the API environment.

7.2.1 C Code Location

The authorization plug-in SDK is installed as a standard component when the Access Server is installed, at

ASInstall_dir /sdk/authorization/samples

where ASInstall_dir is the location where you have installed the Access Server, for example

COREid/access/oblix

The samples directory contains an example of plug-in code, and one or more make files, as well as an include subdirectory. The include subdirectory contains two header files, to be included in the plug-ins to be written. The file as_plugin_utils.h defines a set of utilities that the Access Server provides to all authorization plug-ins. authz_plugin_api.h defines the API data and functions, and includes the other header file.

Note:

The header file contains definitions for the API data and functions. Content provided for this file as part of the installation is 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 functions implemented in authz_plugin_api.h available 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, create a new directory named, for example, myplugin. Copy the make files and sample code to this new directory.

    Within the new directory, the authz_api.c file provides a good example of the structure and operation of a plug-in. You probably want to create your own file to add some functionality specific to your site.

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

  3. Run the make file.

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

7.2.2 Managed C++ Code Location

The authorization plug-in SDK is installed as a standard component when the Access Server is installed, at

ASInstall_dir/sdk/authorization/managed/authz_c++

where ASInstall_dir is the location where you have installed the Access Server, for example,

COREid/access/oblix

The directory contains an example of plug-in code in C++. The file managed_plugin_interface in the following location:

ASInstall_dir/apps/common/bin

defines a set of interfaces that the Access Server provides to all managed authorization plug-ins. Managed_plugin_interface.h defines and documents the interfaces that can be used by the plug-in writer.

Note that the header file contains definitions for the API data and functions. Content provided for this file as part of the installation is 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 functions implemented in managed_plugin_interface.h available within the plug-in.

Important:

Do not remove any of the existing content.

To build

  1. Under the samples directory, create a new directory.

    This directory can have any name, for example, mydirectory.

    You will probably want to create a new file and add functionality specific to your site.

  2. In the new directory, the file cplusplus.cpp provides an example of the structure and operation of a plug-in.

  3. Use the cplusplus.vcproj project file to load and build the plug-in.

    The resulting .dll is your new plug-in.

7.2.3 Plug-in Location

The plug-in you create (in C or in managed code), as either a *.so or *.dll file, can be stored anywhere on the system where the Access Server is running. To be consistent with Authentication Plug-in APIs, you can copy Authorization plug-ins to:

<$ASInstall_dir >/lib

This is not a requirement, however; the file can be stored anywhere on the machine running the Access Server. For this reason, the Access Administrator needs to know the full path to the file, to be able to refer to the plug-in when configuring an authorization scheme. The Access Administrator also needs to know the required and optional input parameters needed by the plug-in. See the Oracle Access Manager Access Administration Guide for a full discussion of authorization scheme configuration. Following the "C Example" is a screen showing the authorization scheme configuration used to support the example.

Note:

When you migrate your system, custom plug-ins are not carried forward. This is another good reason to put all of these in one place, to make the manual migration task easier.

7.3 C API Data

The following sections describe the C API.

7.3.1 C Constant Definitions

The authz_plugin_api.h file includes several defined values to aid in programming.

One provides the value that is returned to the Access Server when ObAzPluginGetVersion is called:

#define OB_AZ_PLUGIN_VERSION "10.1.3"

Note:

The value provided for the version may differ for later versions.

Other defined values map to names for data that is provided by the Access Server in either the RequestorInfo or RequestContext members of the ObAzPluginInfo structure:

#define ObAzPluginRequesterDn "RequesterDn"
#define ObAzPluginRequesterIP "RequesterIP"
#define ObAzPluginRequestResourceType "ResourceType"
#define ObAzPluginRequestResource "Resource"
#define ObAzPluginRequestOperation "Operation"
#define ObAzPluginRequesterDn "RequesterDn" #define ObAzPluginRequesterIP "RequesterIP" #define ObAzPluginRequestResourceType "ResourceType" #define ObAzPluginRequestResource "Resource" #define ObAzPluginRequestOperation "Operation"

As described in the Oracle Access Manager Access Administration Guide, an authorization scheme can obtain data from an external source. This data is passed to a custom authorization plug-in. By obtaining external data (usually in the form of information about the user) authorization decisions can be made dynamically, based on user input.

For example, if a user goes to a form to purchase an item for $1000, this $1000 amount can be dynamically evaluated against a limit—perhaps stored in a database—to determine if the purchase is authorized.

The process of retrieving authorization data from an external source is sometimes known as a reverse action.

Note that when creating an authorization plug-in that uses a reverse action, the calls to retrieve reverse actions will not fail if no reverse actions are present. For example, the following returns NULL for a list if there is no user-agent value in RequestContext:

ObASPluginList_t list = pFnBlock->GetDataFn(pInfo->RequestContext, "user-agent");

Plug-ins should check if the data list returned for a reverse action (or anything else) is NULL before using it to retrieve individual data values. This situation can occur if the client did not specify a value for a reverse action.

7.3.2 C Handles

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 ObAzPluginInfo structure, described on"ObAzPluginInfo".

Data Type and Name Description
void const*ObASPluginList_t A handle pointing to a list of values for a named member of the structure ObAzPluginInfo. This handle is obtained using the function GetDataFn.
void const*ObASPluginListItem_t A handle pointing to one of the items within a list of values. This handle is obtained using GetFirstItemFn or GetNextFn.
ObASPluginListItem_t*ObASPluginGetFirstItem_t A handle pointing to an Access Server function that gets the handle to the head of a list for a name.
const char* *ObASPluginGetValue_t A handle pointing to an Access Server function that gets the value for the current item.
ObASPluginListItem_t*ObASPluginGetNext_t A handle pointing to an Access Server function that gets the handle to the next item in a list.
ObASPluginList_t *ObAzPluginGetData_t A handle pointing to an Access Server function that gets the handle to the head of a list for a name.
ObAzASStatus_t *ObAzplug-insetData_t A handle pointing to an Access Server function that stores a value to a list.
void const*

ObAzPluginData_t

A handle to the head of the list of names for any of the read-only members of the opaque data structure, ObAzPluginInfo.
struct ObAzPluginFns

ObAzPluginFns_t

A handle pointing to the structure ObAzPluginFns that contains handles to functions provided by the Access Server, used to manipulate data in the ObAzPluginInfo structure.
struct ObAzPluginInfo*

ObAzPluginInfo_t

A handle pointing to the head of the structure ObAzPluginInfo.
char**

ObAzplug-instatusMsg_t

A handle to a NULL-terminated string that a plug-in function returns to the Access Server to report on the result of the function.
void*

ObAzPluginWritableData_t

A handle to the head of the list of names for any of the read and write members of the opaque data structure ObAzPluginInfo.
struct ObAzServerContext*

ObAzServerContext_t

A handle pointing to the head of the structure ObAzServerContext.

7.3.3 C Return Values

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

7.3.3.1 ObAzplug-instatus_t

These are the possible values that plug-ins can return to show the result of the attempt to authorize.

typedef enum {
ObAzplug-instatusContinue = 0,
ObAzplug-instatusAccessDenied = 2,
ObAzplug-instatusAccessAllowed = 1,
ObAzplug-instatusAbort = 3

Name Description
ObAzplug-instatusAbort You indicate that a fatal error occurred within the plug-in. Processing is not passed to the following plug-in (if any). If this error is returned by an authorization plug-in, authorization fails and access is denied. If the error is returned by a custom action plug-in, an error message is logged, but authorization status is not affected. If returned during initialization, the Access Server logs an error message.
ObAzplug-instatusAccessAllowed The plug-in authorizes access to the target by the requester. If the plug-in is an authorization plug-in, authorization processing stops and the Access Server moves on to success action processing. If the plug-in is a custom action plug-in, this response is ignored.
ObAzplug-instatusAccessDenied The plug-in denies access to the target by the requester. If the plug-in is an authorization plug-in, authorization processing stops and the Access Server moves on to denied action processing. If the plug-in is a custom action plug-in, this response is ignored.
ObAzplug-instatusContinue Authorization or custom action processing continues after the plug-in ends.

7.3.3.2 ObAzASStatus_t

When the plug-in calls SetDataFn to write data to the ObAzPluginInfo structure, the Access Server tries to do so, and returns one of these values.

typedef enum {
ObAzASStatusSuccess = 0,
ObAzASStatusWriteNotAllowed = 1
}ObAzASStatus_t;

Name Purpose
ObAzASStatusSuccess The Access Server successfully performed the operation.
ObAzASStatusWriteNotAllowed The Access Server did not perform the operation; specifically, the plug-in tried to change values it is not allowed modify.

7.3.4 C Structures

The Access Server groups related data items into named structures, allocates the memory for them, and holds the data that is in the structures. The API uses handles to read from and write data into these structures. Structures are opaque to the user, meaning that they can be used to transfer information to and from the Access Server, but the user cannot change the way the structure is organized or the format of the data that it contains. Following are the structures used in the Authorization Plug-in API.

7.3.4.1 ObAzServerContext

This structure carries information about the Access Server that the plug-in may need. It has two members.

const *ObAzserverContext{
                                                char            *AccessServerInstallDir;
                                                char            *AccessServerAzPluginAPIVersion; 
                                        };

The constant *ObAzServerContext_t is a handle pointing to the head of this structure.

Data held in the structure is read only.

The following table describes the structure members.

Name Description
AccessServerInstallDir Path to the installation directory for the Access Server.
AccessServerAzPluginAPI Version The lowest Authorization Plug-in API version the Access Server currently supports.

7.3.4.2 ObAzPluginInfo

The Access Server fills this structure with data determined by the Authorization Scheme using the plug-in, in combination with the Authorization Rule that uses the scheme. 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 authorization rules being carried out as part of a policy, the structure also provides a means to pass information from one plug-in to another within the rules.

struct ObAzPluginInfo{
ObAzPluginData_tRequesterInfo;
ObAzPluginData_tRequestContext; 
ObAzPluginData_tParams; 
ObAzPluginWritableData_tContext;
ObAzPluginWritableData_tActionInfo; 
}; 

The constant *ObAzPluginInfo_t is a handle pointing to this structure.

Data of type ObAzPluginWritableData_t can be both read and written. Data of type ObAzPluginData_t is read only.

Data is extracted from the structure and stored to it using the functions described under"ObAzPluginFns".

The following table describes the information provided by the members of this structure.

Data Type and Name Description
RequesterInfo Data describing the user or application trying to access a resource. The plug-in cannot change this data. The Access Server provides two predefined names within this list: RequesterDn and RequesterIP. Users can add other names as a User Parameter when the Authorization Scheme is configured. The parameter entered is the name of an attribute that can be found in the directory. The Access Server provides the name of the attribute and the value(s) of the entry for that attribute.
RequestContext Request-specific information that is passed to the plug-in, such as a resource type. The plug-in cannot change this data. The Access Server provides three predefined names within this list: ResourceType, Resource, and Operation. Users cannot add others.
Params Names and values for all required, optional, and additional parameters specified in the plug-in configuration. The plug-in cannot change this data. Names are created when an Authorization scheme is first created by the System or Master Access Administrator. Values can be provided when the scheme is first created, or added later by a Delegated Access Administrator when the scheme is used in an Authorization Rule.
Context The plug-in uses this data to temporarily store or transfer information, for example to keep track of its own state when moving between logical modules, or to pass information to another plug-in. The plug-in may add new data or replace existing data. The Access Server maintains this data until the authorization request completes.
ActionInfo The plug-in uses this data to return information, such as the authorization result, to the AccessGate. The plug-in may add new data or replace existing data. The Access Server maintains this data until the authorization request completes, when it is provided to the Client.

Understanding the organization of the ObAzPluginInfo structure is key to understanding how the Authorization Plug-in API works.

In the Authorization Plug-in API, all structure members are multivalued, meaning that the names held within each structure may each have more than one value. 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 GetFirstItemFn 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.

Figure 7-1 illustrates the process flow for the authorization plug-in API.

Figure 7-1 Flow for Authorization Plug-in API

Authz plug-in API flow.

7.3.4.3 ObAzPluginFns

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

struct ObAzPluginFns
ObAzPluginFns_t{
ObASPluginGetFirstItem_tGetFirstItemFn;
ObASPluginGetValue_tGetValueFn;
ObASPluginGetNext_tGetNextFn;
ObAzPluginGetData_tGetDataFn;
ObAzPluginsetData_tSetDataFn; 
}; 

The following table describes the members of this structure. You may want to refer to"ObAzPluginInfo" to understand how data is organized.

Note:

The constant ObAzPluginFns_t is a handle pointing to this structure.
Name Description
GetFirstItemFn A function to get a handle for the first item in a list associated with a name.
GetValueFn A function to read the value of an item, once the item's handle has been defined using either GetFirstItemFn or GetNextFn.
GetNextFn A function to get the handle for the next item in a list associated with a name. A returned handle value NULL means there are no more items in the list.
GetDataFn A function to get a handle to a name in a specified member of the ObAzPluginInfo structure, given the text value for the name. A returned handle value NULL means that name is not present in that member of the structure.
SetDataFn A function to store a value to a name in a specified member of the ObAzPluginInfo structure, given the text value for the name.

7.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 authz_plugin_api.h.

7.4.1 C Functions Provided by the Access Server

These functions get and set data in the structures that have been passed. To use these functions you must call them as members of the structure of type ObAzPluginFns that you named in your code. For example, if you implemented ObAzPluginFn and set the variable name of type ObAzPluginFns to pFnBlock, then you call GetDataFn by reference to its place in the structure, as pFnBlock->GetDataFn.

7.4.1.1 GetDataFn

The plug-in uses this function to get a handle to the head of a list of values associated with a name in one of the members of the ObAzPluginInfo structure. The plug-in must then use the list manipulation functions GetFirstItemFn, GetValueFn, GetNextFn, GetValueFn, and so on, to extract information from the list. The function takes the form:

ObASPluginList_t GetDataFn(
                  ObAzPluginData_tpmember,
                  const char*pName);

Input Parameters

Name Description
pmember The member of the ObAzPluginInfo structure in which the name is expected to be found.
pName The name for which values are to be retrieved.

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.

7.4.1.2 SetDataFn

The plug-in uses this function to store a single value for a name in one of the members of the ObAzPluginInfo structure. The function takes the form:

ObAzASStatus_t SetDataFn(
ObAzPluginData_t pMember,
const char*     pName,
const char*    Value,
const int      replace);  

Input Parameters

Name Description
pMember The name of a writable member of the ObAzPluginInfo structure.
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. A value of 0 indicates append, all other values are a request to replace the current first value for pName.

There are no output parameters from this function.

Output Parameters

The function returns one of the ObAzASStatus_t values.

Note:

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

7.4.1.3 GetFirstItemFn

The plug-in uses this function to get a handle to the first item in a list of values, once the handle to the head of the list has been obtained using GetDataFn. You must then use the GetValueFn to extract the value or GetNextFn to get a handle to the next item in the list.

The function takes this form:

ObASPluginListItem_t GetFirstItemFn(
                 ObASPluginList_tplist);

Input Parameters

Name Description
pList Handle to the head of a list of values, returned by GetDataFn.

Output Parameters

There are no output parameters for this function.

The function returns a handle to the first item in a list of values. If the handle value is NULL, there is no first item.

7.4.1.4 GetValueFn

The plug-in uses this function to get the value for an item, once a handle to the item has been obtained.

The function takes this form:

const char* GetValueFn(
 ObASPluginListItem_tPItem);

Input Parameters

Name Description
pItem Handle to the current item in a list, returned by GetFirstItemFn or GetNextFn.

Output Parameters

There are no output parameters for this function.

The function returns the value of an item.

7.4.1.5 GetNextFn

The plug-in uses this function to get a handle to the next item in a list, given the handle to the current item.

The function takes this form:

ObASPluginListItem_t GetNextFn(
ObASPluginListItem_tpItem);

Input Parameters

Name Description
pItem Handle to the current item in a list, returned by GetFirstItemFn or GetNextFn.

Output Parameters

There are no output parameters for this function.

The function returns a handle to the next item in the list.

7.4.2 C Functions Implemented in the Plug-In

These functions describe the entry points that need to be in the .dll. Prototypes for these five functions are provided in authz_plugin_api.h. They must all be implemented in the plug-in.

The OBDLLEXPORT entry for each method is required. It provides a means for the Access Server to locate and call these methods 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.

7.4.2.1 ObAzPluginGetVersion

The Access Server calls this function once when the plug-in is first loaded. The plug-in returns its version number, as defined in the authz_plugin_api.h file 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 support an obsolete version of the plug-in.

The function takes the form:

OBDLLEXPORT
         const char* ObAzPluginGetVersion(void)

Input parameters

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 authorization plug-in.

7.4.2.2 ObAzPluginInit

The Access Server calls this function after making the version check. You use ObAzPluginInit to initialize 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 allocates memory in order to return the presult string, which must later be de-allocated using ObAzPluginDeallocStatusMsg.

The function takes the form:

OBDLLEXPORT
                  ObAzplug-instatus_t ObAzPluginInit(
                  ObAzServerContext_tpServerContext,
                  ObAzplug-instatusMsg_tpResult)

Input Parameters

Name Description
pServerContext The name assigned by the plug-in to the Context information structure provided by the Access Server.

Output Parameters

Name Description
pResult Result message reported by the function.

The function must return one of two ObAzASStatus_t values, whose meaning is described in the following table.

Name Description
ObAzplug-instatusContinue The work space is successfully initialized. Processing of other plug-ins, of either type, if any, continues.
ObAzplug-instatusAbort Initialization has failed. No additional plug-ins, of either type, are processed.

7.4.2.3 ObAzPluginTerminate

The Access Server calls this function when the Access Server terminates or the plug-in is unloaded. You use this function to clear the plug-in work area, for example to disconnect from a database or to free memory.

The function takes the form:

OBDLLEXPORT
                  ObAzplug-instatus_t ObAzPluginTerminate(
                  ObAzServerContext_tpServerContext,
                  ObAzplug-instatusMsg_tpResult);

Input Parameters

Name Description
pServerContext The name assigned by the plug-in to the Context information structure provided by the Access Server.

Output Parameters

Name Description
pResult The result message reported by the function.

The function must return one of two ObAzASStatus_t values, whose meaning is described in the following table.

Name Description
ObAzplug-instatusContinue The work space is successfully cleared. Processing of other plug-ins, of either type, if any, continues.
ObAzplug-instatusAbort The work space could not be cleared. For example, a database connection could not be closed because the database was down. Processing of plug-ins ends.

7.4.2.4 ObAzPluginFn

The Access Server calls this function whenever a protected resource calls for authorization covered by a policy of which the plug-in is a part. You use this function to make the detailed decision or chain of decisions that determines whether access is denied or granted. The function defines either a custom authorization or a custom action process.

The function takes the form:

BDLLEXPORT
                     ObAzplug-instatus_t ObAzPluginFn(
                     ObAzServerContext_tpServerContext,
                     ObAzPluginFns_tpFuncBlock,
                     ObAzPluginInfo_tpData)

Input Parameters

Name Description
pServerContext The name you want to assign to the Context information structure provided by the Access Server.
pFuncBlock Handle to the block of functions provided by the Access Server that the plug-in needs to manipulate data. You specify the name of this block.
pData Handle to the ObAzPluginInfo structure in the Access Server. You specify the name of this structure.

Output Parameters

Name Description
pData Handle to data modified by the plug-in.

The function returns one of the ObAzplug-instatus_t values, whose meaning is described in the following table:

Name Description
ObAzplug-instatusContinue Regardless of the plug-in type, this signals the Access Server to move on to the next plug-in in the sequence. For an authorization plug-in, this means that the plug-in did not explicitly allow or deny access to the requester.
ObAzplug-instatusAccessAllowed If this results from an authorization plug-in, the requester is allowed access to the target. The Access Server stops evaluating authorization plug-ins and moves on to success action plug-ins, if any. For a custom action plug-in this status is ignored.
ObAzplug-instatusAccessDenied If this results from an authorization plug-in, the requester is denied access to the target. The Access Server stops evaluating authorization plug-ins and moves on to denied action plug-ins, if any. For a custom action plug-in this status is ignored.
ObAzplug-instatusAbort Regardless of the plug-in type, processing does not continue after the function. If this results from an authorization plug-in, authorization fails.

7.4.2.5 ObAzPluginDeallocStatusMsg

The Access Server calls this function automatically when the plug-in terminates. You use it to delete the memory allocated by other plug-ins which returned a status message.

The function takes the form:

OBDLLEXPORT
                     void ObAzPluginDeallocStatusMsg(
                     ObAzplug-instatusMsg_tpStatusMsg);

Input Parameters

Name Description
pStatusMsg Status Message to be deallocated.

Output Parameters

There are no output parameters from this function.

The function returns nothing

7.4.2.6 C Example

Example 7–1 shows some basic uses of the plug-in functions. It is a modification of the authz_api.c sample function provided as part of the Access System Installation.

Example 7-1 Authorization Plug-in Example.

OBDLLEXPORT const char* ObAzPluginGetVersion(void)
{
   FILE *file = fopen("d:\\AZtestfile.txt", "a+");
   fprintf (file, "\n%s %s\n", "getting version, it is",
      OB_AZ_PLUGIN_VERSION);
   fclose(file);
   return OB_AZ_PLUGIN_VERSION;
}
 
/*
* -----------------------------------------------
* Implementation of ObAnPluginInit
*
* The logged data appears only once, when the Plugin is first loaded.
*
*/
 
OBDLLEXPORT ObAzplug-instatus_t ObAzPluginInit(ObAzServerContext_t pContext, ObAzplug-instatusMsg_t pResult)
{
 
//   Values to be read in by this function are initialized.
 
   ObAzplug-instatus_t rtval;
   const char* pASPluginVersion = NULL;
 
   FILE *file = fopen("d:\\AZtestfile.txt", "a+");
   fprintf (file, "\n%s\n", "initializing");
 
   if(pContext != NULL) {
      pASPluginVersion = pContext->AccessServerAzPluginAPIVersion;
   }
 
   if((pASPluginVersion != NULL) &&
         (strcmp(pASPluginVersion, OB_AZ_PLUGIN_VERSION) == 0)) {
      rtval = ObAzplug-instatusContinue;
      *pResult = strdup("Success version check");
   } else {
/*
* return failure, because the version provided by the AS 
* is not what was expected.
*/
      rtval = ObAzplug-instatusAbort;
   }
 
   fclose(file);
   return rtval;
}
/*
* -----------------------------------------------
* Implementation of ObAnPluginTerminate
*
* The logged data appears only when the Access Server terminates.
*
*/
OBDLLEXPORT ObAzplug-instatus_t ObAzPluginTerminate
      (ObAzServerContext_t pContext,
      ObAzplug-instatusMsg_t pResult)
{
   FILE *file = fopen("d:\\AZtestfile.txt", "a+");
   fprintf (file, "\n%s\n", "terminating gracefully");
   *pResult = strdup("Success, terminated");
   fclose(file);
   return ObAzplug-instatusContinue;
}
/*
* -----------------------------------------------
* Implementation of ObAnPluginDeallocStatusMsg
* The logged data appears following each other function
* that provides a presult.
*/
OBDLLEXPORT void ObAzPluginDeallocStatusMsg
      (ObAzplug-instatusMsg_t pResult)
{
   FILE *file = fopen("d:\\AZtestfile.txt", "a+");
   fprintf (file, "\n%s\n", "deallocating");
   
   if(pResult != NULL && *pResult != NULL) {
      free(*pResult);
      *pResult = NULL;
   }
   fclose(file);
}
/*
* -----------------------------------------------
* Implementation of ObAnPluginFn
*/
OBDLLEXPORT ObAzplug-instatus_t ObAzPluginFn
      (ObAzServerContext_t pContext,
      ObAzPluginFns_t pFnBlock,
      ObAzPluginInfo_t pInfo)
{
/*
* Default will be to continue without granting or denying
* authorization.
*/
   ObAzplug-instatus_t rtval = ObAzplug-instatusContinue;
* Pointers are defined.
*/
   ObASPluginList_t list;
   ObASPluginListItem_t item;
/*
* Data that might be read in is initialized.
*/
   const char* ou = NULL;
   const char* deny1 = NULL;
   const char* deny2 = NULL;
   const char* allow1 = NULL;
   const char* allow2 = NULL;
   const char* allow3 = NULL;
   const char* allow4 = NULL;
   int i = 0;
   FILE *file = fopen("d:\\AZtestfile.txt", "a+");
   fprintf (file, "\n%s\n", "doing real work");
   if((pFnBlock != NULL) && (pInfo != NULL)){
      fprintf (file, "%s\n", "first test okay, getting ou");
/*
* get user's "ou" from pInfo.
*/
      list = pFnBlock->GetDataFn(pInfo->RequesterInfo, "ou");
      item = pFnBlock->GetFirstItemFn(list);
      ou = pFnBlock->GetValueFn(item);
   }
/*
* show the ou value.
*/
   if(ou != NULL){
      fprintf (file, "%s\n", "ou was not null");
      fprintf (file,"%s %s \n", "ou is", ou);
   } else {
      fprintf (file, "%s\n", "ou was not found");
      rtval = ObAzplug-instatusAccessDenied;
      pFnBlock->SetDataFn
            (pInfo->ActionInfo, "access_status", "deny", 1);
      fclose(file);    
      return rtval;
   )
/*
* now get two deny_organization values.
* This is risky coding, since it could be that "deny_organization"
* does not exist, or only has one value. In either case, the code 
* will be generating NULL pointers, which could be misused elsewhere
*/
   list = pFnBlock->GetDataFn(pInfo->Params, "deny_organization");
if(list == NULL){
      fprintf (file, "%s\n", "missing deny org");
      rtval = ObAzplug-instatusAccessDenied;
      pFnBlock->SetDataFn
            (pInfo->ActionInfo, "access_status", "deny", 1);
      fclose(file);    
      return rtval;
   }
   item = pFnBlock->GetFirstItemFn(list);
   deny1 = pFnBlock->GetValueFn(item);
   fprintf (file,"%s %s \n", "deny1 is", deny1);
   item = pFnBlock->GetNextFn(item);
   deny2 = pFnBlock->GetValueFn(item);
   fprintf (file,"%s %s \n", "deny2 is", deny2);
/*
* now get up to 4 allow_organization values.
*/
   list = pFnBlock->GetDataFn(pInfo->Params,"allow_organization");
   if(list == NULL){
      fprintf (file, "%s\n", "missing allow org");
      rtval = ObAzplug-instatusAccessDenied;
      pFnBlock->SetDataFn
            (pInfo->ActionInfo, "access_status", "deny", 1);
      fclose(file);    
      return rtval;   }   
/*
* This is a better approach; it avoids generating null pointers.
*/
   for(i = 0, item = pFnBlock->GetFirstItemFn(list);
         item != NULL; i++, item = pFnBlock->GetNextFn(item)) {
      switch(i) {
         case 0:
            allow1 = pFnBlock->GetValueFn(item);
            fprintf (file,"%s %s \n", "allow1 is", allow1);
         break;
         case 1:
            allow2 = pFnBlock->GetValueFn(item);
            fprintf (file,"%s %s \n", "allow2 is", allow2);
         break;
         case 2:
            allow3 = pFnBlock->GetValueFn(item);
            fprintf (file,"%s %s \n", "allow3 is", allow3);
         break;
         case 3:
            allow4 = pFnBlock->GetValueFn(item);
            fprintf (file,"%s %s \n", "allow4 is", allow4);
         break;   }}

The following screen shows the initial setup for the Authorization Scheme, as set by the Access Administrator. Note that space has been left for a required parameter, but no value has been entered.

Initial setup for the Authorization Scheme.

Later, when a policy is defined to cover a resource that uses this Authorization scheme, the Delegated Access Administrator provides the missing required parameter value. In the following example, an additional value is also added.

A policy is defined for this scheme.

Given this version of the authorization scheme, the corresponding trace information given by the sample code is:

initializing
 
               deallocating
 
               doing real work
               first test okay, getting ou
               ou was not null
               ou is Sales 
               deny1 is nosuch 
               deny2 is reqdenparam 
               allow1 is sales 
               allow2 is addallowparam 
               allow3 is optallowparam 
               access was allowed 

7.5 Managed Code API Interfaces

The following sections detail the managed code API interfaces.

7.5.1 Defines

The managed_plugin_interface.h file includes several defined values to aid in programming. One provides the value that is returned to the Access Server when ObAZPluginGetVersion is called:

#define OB-AZ_PLUGIN_VERSION "10.1.3"

Note:

The value provided for the version may differ for later versions.

7.5.2 Interfaces

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 table.

Name Description
IObASPluginListItem An interface that provides functions to access one of the items in a list of values.
IObAzPluginData An interfaces that provides functions to access the list of read-only values.
IObAzPluginInfo An interface that provides functions to access various data items that the plug-in can use.
IObAzPluginWritableData An interface that provides functions to access and modify the list of values.
IObAzServerContext An interface that provides functions to access server context information.

7.5.3 Return Values

Many of the functions that the Access Server and the API use to communicate return a status value. These are described in the following section.

7.5.3.1 Status

The following are the possible values that plug-ins can return to show the result of the authorization attempt.

IObAuthzPlugin::Status {
                     ObAzpluginstatusContinue = 0,
                        ObAzpluginstatusAccessAllowed = 1,
                        ObAzpluginstatusAccessDenied = 2,
                        ObAzpluginstatusAbort = 3

Name Meaning
ObAzpluginStatus Abort enables you to indicate that a fatal error occurred in the plug-in. Processing is not passed to the next plug-in (if there is any). If this error is returned by an authorization plug-in, authorization fails and access is denied. If the error is returned by a custom action plug-in, an error message is logged, but authorization status is not affected. If returned during initialization, the Access Server logs an error message.
ObAzpluginStatus AccessAllowed The plug-in authorizes access to the target by the requester. If the plug-in is an authorization plug-in, authorization processing stops and the Access Server moves on to success action processing. If the plug-in is a custom action plug-in, this response is ignored.
ObAzpluginStatus AccessDenied The plug-in denies access to the target by the requester. If the plug-in is an authorization plug-in, authorization processing stops and the Access Server moves on to denied action processing. If the plug-in is a custom action plug-in, this response is ignored.
ObAzpluginStatus Continue Authorization or custom action processing continues after the plug-in ends.

7.5.3.2 ASStatus

When the plug-in calls set_Data to write data to the ObAzPluginInfo structure, the Access Server tries to do this, and returns one of these values:

IObAuthzPlugin::ASStatus {
                        ObAzASStatusSuccess = 0,
                        ObAzASStatusWriteNotAllowed = 1
               };

Name Meaning
ObAzASStatusSuccess The Access Server successfully performed this operation.
ObAzASStatusWrite NotAllowed The Access Server did not perform the operation. Specifically, the plug-in tried to change values that it is not allowed to modify.

7.5.4 Managed Code Interfaces

The Access Server groups related data items into structures and provides interfaces to access various members. The following are the interfaces used in the Authorization Plug-in API.

7.5.4.1 IObAzServerContext

This structure carries information about the Access Server that the plug-in may need. It has two members:

public _gc _interface IObAzServerContext
          {
                _property String* get_AccessServerInstallDir();
                _property String* get_AccessServerAzPluginAPIVersion();
          };

Name Description
get_AccessServer InstallDir Path to the installation directory for the Access Server.
get_AccessServerAz PluginAPIVersion The lowest Authorization Plug-in API version the Access Server currently supports.

7.5.4.2 IObAZPluginInfo

The Access Server fills this structure with data that is determined by the authorization scheme that uses the plug-in, along with the authorization rule that uses the scheme. The plug-in can modify data within the structure and may append new data to it as work progresses through the plug-in. When there are multiple authorization rules being carried out as part of a policy, the structure also provides a means to pass information from one plug-in to another within the rules.

public _gc _interface IObAzPluginInfo
               {
                     IObAzPluginData* GetRequesterInfo();
                     IObAzPluginData* GetRequestContext ();
                     IObAzPluginData* GetParams ();
 
                     IObAzPluginWritableData* GetContext ();
                     IObAzPluginWritableData* GetActionInfo ();

Data of type IObAzPluginWritableData can be both read and written. Data of type IObAzPluginData is read only.

The following table describes the information provided by the members of this structure

Name Description
GetRequestInfo Returns data that describes the user or application that is trying to access a resource. The plug-in cannot change this data. The Access Server provides two predefined names in this list: RequesterDN and RequesterIP. Users can add other names as a User Parameter when the authorization scheme is configured. The parameter entered is the name of an attribute that can be found in the directory. The Access Server provides the name of the attribute and the value(s) of the entry for that attribute.
GetRequestContext Returns request-specific information that is passed to the plug-in, such as a resource type. The plug-in cannot change this data. The Access Server provides three predefined names in this list: ResourceType, Resource, and Operation. Users cannot add others. See "C Constant Definitions" for details on a "request context" operation.
GetParams Returns names and values for all required, optional, and additional parameters specified in the plug-in configuration. The plug-in cannot change this data. Names are created when an authorization scheme is first created by the System or Master Access Administrator. Values can be provided when the scheme is first created, or added later by a Delegated Access Administrator when the scheme is used in an authorization rule.
GetContext The plug-in uses this data to temporarily store or transfer information, for example to keep track of its own state when moving between logical modules, or to pass information to another plug-in. The plug-in may add new data or replace existing data. The Access Server maintains this data until the authorization request completes.
GetActionInfo The plug-in uses this data to return information, such as the authorization result, to the AccessGate. The plug-in may add new data or replace existing data. The Access Server maintains this data until the authorization request completes, when it is provided to the client.

In the authorization plug-in API, all structure members are multi-valued, meaning that the names help within each structure may each have more than one value. Each name has an associated list of one or more items. Each item contains a value.

7.5.4.3 IObAzPluginData

This interface provides the functions to get the list of items.

public _gc _interface IObAzPluginData
               {
                     _property IEnumerator* get_Data(String* pName);
               };

7.5.4.3.1 get_Data

The plug-in uses this function to get a list of values associated with a name in one of the members of the ObAzPluginInfo structure. The plug-in must then use the enumeration functions Current, MoveNext, and Reset to obtain items from the list.

Name Purpose
pName The name for which values are to be retrieved.

The function returns an object which implements the interface IEnumerator.

7.5.4.4 IObAzPluginWriteableData

This interface provides the functions to get and set the list of items.

public _gc _interface IObAzPluginWritableData
               {
                     IEnumerator* get_Data(String* pName);
                     IObAuthzPlugin::ASStatus set_Data(String* key, String* val, Oblix::ObListOper operation);
               };
7.5.4.4.1 get_Data

The plug-in uses this function to get a list of values associated with a name in one of the members of the ObAzPluginInfo structure. The plug-in must then use the enumeration functions Current, MoveNext, and Reset to obtain items from the list.

Name Purpose
pName The name for which values are to be retrieved.

The function returns an object which implements the interface IEnumerator.

7.5.4.4.2 set_Data

The plug-in uses this function to store a single value for a name in one of the members of the ObAzPluginInfo structure. The function takes the following form:

Name Purpose
key Name for the information whose value is to be set.
Val The value to be inserted.
operation Specifies whether to replace or append to existing values for the name. A value of ObListOper::ObAdd indicates append. All other values are a request to replace the current first value for key.

The function returns one of the ObAzASStatus_t values.

Note:

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

7.5.4.5 IObAsPluginListItem

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

public _gc _interface IObASPluginListItem
                     _property Sting* get_Value();
               };

7.5.4.5.1 get_Value

The plug-in uses this function to get the value for an item once the item has been obtained. The function returns the value of an item.

7.5.5 Interfaces to be Implemented in the Plug-In

For authorization plug-ins the plug-in writer must define a class with the following functions:

namespace sample
{
      public _gc class ObAuthzPlugin
      {
      public:
            ObAuthzPlugin();
            String* ObAzPluginGetVersion();
            IObAuthzPlugin::Status ObAzPluginInit
(Oblix::IObAzServerContext* context, String* msg);
            IObAuthzPlugin::Status
ObAzPluginFn(Oblix::IObAzServerContext* context, Oblix::IObAzPluginInfo* info);
            IObAuthzPlugin::Status ObAzPluginTerminate (Oblix::IObAzServerContext* context, String* msg);
            };
};

The class must be named ObAuthzPlugin, and may or may not be included in a namespace. All the functions need to have public access.

The Access Server calls the functions in this class in the following order:

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

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

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

  • ObAzPluginTerminate: When the Access Server shuts down.

7.5.5.1 ObAzPluginGetVersion

The Access Server calls this function once when the plug-in is first loaded. The plug-in returns its version number, as defined in the managed_plugin_interface.h file 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 support an obsolete version of the plug-in.

7.5.5.2 ObAzPluginInit

The Access Server calls this function after making the version check. You use ObAsPluginInit to initialize 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.

Name Description
pServerContext The name assigned by the plug-in to the Context information structure provided by the Access Server.

The function must return one of two ObAzASStatus values, describe in the following table:

Name Description
ObAzpluginStatusContinue The work space is successfully initialized.
ObAzpluginStatusAbort Initialization has failed.

7.5.5.3 ObAzPluginTerminate

The Access Server calls this function when it terminates. You use this function to clear the plug-in work area, for example, to disconnect from a database.

Name Description
pServerContext The name assigned by the plug-in to the context information structure provided by the Access Server.

The function must return one of two ObAzASStatus_t values, described in the following table:

Name Description
ObAzpluginStatus Continue The work space is successfully initialized.
ObAzpluginStatusAbort Initialization has failed.

7.5.5.4 ObAzPluginFn

The Access Server calls this function when a protected resource calls for authorization covered by a policy of which the plug-in is a part. You use this function to make the detailed decision or chain of decisions that determines whether access is denied or granted. The function defines either a customer authorization or a custom action process.

Name Description
pServerContext The name you want to assign to the context information structure provided by the Access Server.
pInfo Handle to the ObAzPluginInfo structure in the Access Server. You specify the name of this structure.

The function returns one of the ObAzpluginstatus_t values, described in the following table:

Name Description
ObAzpluginStatus Continue Regardless of the plug-in type, this signals the Access Server to move on to the next plug-in in the sequence. For an authorization plug-in, this means that the plug-in did not explicitly allow or deny access to the requester.
ObAzpluginStatus AccessAllowed If this results from an authorization plug-in, the requester is allowed to access the target. The Access Server stops evaluating authorization plug-ins and moves on to denied action plug-ins, if there are any. For a custom action plug-in, this status is ignored.
ObAzpluginStatus AccessDenied If this results from an authorization plug-in, the requester is denied access to the target. The Access Server stops evaluating authorization plug-ins and moves on to denied action plug-ins, if there are any. For a custom action plug-in this status is ignored.
ObAzpluginStatus Abort Regardless of the plug-in type, processing does not continue after the function. If this results from an authorization plug-in, authorization fails.

7.6 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 only if authentication fails, and then only when the Access Server is running on 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 user responsibility and should be considered when designing a plug-in. The total time required to process one authorization 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.

Coding errors at the system level in a plug-in, such as a memory or access violation, segmentation, or bus error fault, can cause the Access Server to fail.

Plug-ins allow optional parameters, that would usually be filled in by a Delegated 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.