4 Building AccessGates with the Access Manager SDK

This chapter describes the Access Manager SDK and how you use it to create custom AccessGates. It discusses the following topics:

• AccessGates, their role in the Access System, and AccessGate architecture.

• The tasks you must complete to create and enable an AccessGate.

• The directory structure and content of the installed SDK.

• Selecting an AccessGate development platform by comparing the development language-specific implementations of each class in the Access Manager API.

• Behavior with 10g (10.1.4.0.1) and earlier versions and backward compatibility.

• How to write each functional section of code that goes into a typical AccessGate.

• Reference details for the C++, C, C#, and Java implementation of the Access Manager API.

• Reference details for the C# implementation of the Access Manager API.

• Suggestions on how to avoid problems with your AccessGate. It also presents tips for identifying and resolving the most common AccessGate problems.

This chapter contains the following sections:

• About AccessGates

• About AccessGate Deployment

• About the Access Manager SDK

• About the Access Manager API

• Globalization and the Access Manager SDK, Access Manager APIs, Custom AccessGates

• About Custom AccessGate Code

• C++ Implementation Details

• C Implementation Details

• C# Implementation Details

• Java Implementation Details

• C-Family Status and Error Message Strings

• Best Practices

4.1 About AccessGates

AccessGates are Access Server clients or agents. They process user requests for access to resources within the LDAP domain protected by your Access System.

Typically, you embed custom AccessGate code in a servlet (plug-in) or standalone application that receives resource requests. This code uses Access Manager API libraries to perform authentication and authorization services on the Access Server.

If a resource is not protected, the AccessGate grants the user free access to the requested resource. If the resource is protected and the user is authorized to provide certain credentials to gain access, the AccessGate attempts to retrieve those user credentials so that the Access Server can validate them. If authentication of the user and authorization for the resource succeed, the AccessGate makes the resource available to the user.

Note:

For the purposes of this document, "Access Manager API" refers narrowly to the set of programming calls that enable developers to access the authentication, authorization, and other services of an Access Server. By contrast, "Access Manager SDK" refers to all the files installed by the Access Server SDK installation package.

4.1.1 About Prefabricated AccessGates (WebGates)

Oracle Access Manager ships with several prefabricated AccessGates known as WebGates. Each of these out-of-the box WebGates has been set up to protect HTTP resources on a specific web server such as:

• Microsoft Internet Information Server

• iPlanet/SunONE Web Server

• Apache Web Server

• Lotus Domino

• IBM HTTP Server (IHS)

Some WebGates can protect Embedded Java Bean (EJB) resources (which are non-HTTP resources) on application servers such as BEA WebLogic and IBM WebSphere. For a matrix listing the WebGate implementations available for various combinations of host server software and host machine operating system, see the Oracle Access Manager Installation Guide.

4.1.2 When to Create a Custom AccessGate

Typically, you deploy a custom AccessGate instead of a standard WebGate when you need to control access to a resource for which Oracle Access Manager does not already supply an out-of-the-box solution. This might include:

• Protection for non-HTTP resources

• Protection for a custom web server developed to implement a special feature (such as reverse proxy, for example)

• Implementation of single sign-on (SSO) to protect a combination of HTTP and non-HTTP resources

  For example, you can create an AccessGate that facilitates SSO within an enterprise environment that includes a WebLogic cluster as well as non-WebLogic resources.

4.1.3 AccessGate Architecture

Each AccessGate is built from three types of resources:

• Custom AccessGate code, which you build into a servlet or standalone application running on the machine where the rest of the AccessGate resides. You can write AccessGate code using any of four development language platforms:

  • C++

  • C (pseudo object-oriented classes)

  • C# (.NET framework managed code)

  • Java

  These platforms, which support equivalent functionality implemented in language-specific ways, serve as interfaces to the underlying Access System code, which is written in C++.

• Configuration information, which consists of the following:

  • Environment variables, which you set on the server where the AccessGate is installed. These variables differ, depending on whether your server runs UNIX or Windows.

  • An ObAccessClient.xml file, which is stored on the server where the AccessGate is installed. This file contains configuration information entered through the "configureAccessGate" command-line application.

  • AccessGate connection settings that you enter, view, and edit by navigating to Access System Console, then to AccessGate Configuration. These settings are stored in your Oracle configuration directory.

• The various implementations of the Access Manager API libraries, which facilitate AccessGate interaction with the Access Server. These include:

  • Header files for either Java or the "C-family" languages (C\C++\C#)

  • The JNI library (for Java only, packaged in jobaccess.jar)

  • The ObAccess library (specific to the operating system platform used by the machine hosting the AccessGate)

Figure 4-1 shows AccessGate components installed on a host server:

Figure 4-1 Architectural Detail of an AccessGate

Description of "Figure 4-1 Architectural Detail of an AccessGate"

4.1.4 AccessGate Variations

AccessGates can differ according to a variety of factors:

• The operating system of the host machine on which they are installed (Each OS platform requires a different Access Manager SDK installation package.)

• Whether they run as standalone applications or server plug-ins

• The development language in which they are written (These development languages provide a choice of interfaces to the underlying functionality of the API)

• The type of server for which they are written (You can protect web servers or application servers)

• The type of resources they protect (You can protect both HTTP and non-HTTP resources)

• The ways in which they retrieve user credentials (You can enable HTTP FORM-based input, the use of session tokens, and command-line input, among other methods)

4.1.5 How an AccessGate Handles a Resource Request

Regardless of the variability introduced by the preceding factors, most AccessGates follow the same basic steps to process user requests.

When a user or application submits a resource request to a servlet or application running on the server where the AccessGate is installed, the AccessGate code embedded in that servlet or application initiates the basic process shown in the following diagram.

Figure 4-2 illustrates the process of handling a resource request:

Figure 4-2 Process Overview: Handling a Resource Request

Description of "Figure 4-2 Process Overview: Handling a Resource Request"

Process Overview: Handling a resource request

1. The application or servlet containing the AccessGate code receives a user request for a resource.

2. The AccessGate constructs a ObResourceRequest structure, which the AccessGate code uses when it asks the Access Server whether the requested resource is protected.

3. The Access Server responds.

4. If the resource is not protected,

   1. The AccessGate grants the user access to the resource. Otherwise...

   2. The AccessGate constructs an ObAuthenticationScheme structure, which it uses to ask the Access Server what credentials the user needs to supply. (This step is only necessary if the AccessGate supports the use of different authentication schemes for different resources).

5. The Access Server responds.

6. The application uses a form or some other means to ask the user for her credentials. In some cases, the user credentials may already have been submitted as part of:

   • A valid session token

   • Input from a web browser

   • Arguments to the command-line script or keyboard input that launched the AccessGate application

7. The user responds to the application.

8. The AccessGate constructs an ObUserSession structure, which presents the user credentials to the Access Server, which maps them to a user profile in the Oracle Access Manager user directory.

9. If the credentials prove valid, the AccessGate creates a session token for the user, then it sends a request for authorization to the Access Server. This request contains the user identity, the name of the target resource, and the requested operation.

10. The AccessGate grants the user access to the resource, providing, of course, that the user is authorized for the requested operation on the particular resource.

11. (Not pictured). A well-behaved AccessGate deallocates the memory used by the objects it has created, then shuts down the Access Manager API.

The preceding steps represent only the main path of the authorization process. Typically, additional code sections within the servlet or application handle branch situations where:

• The requested resource is not protected

• The authentication challenge method associated with the protected resource is not supported by the application

• The user has a valid single sign-on cookie (ObSSOCookie), which enables the user to access to the resource without re-presenting her credentials for as long as the session token embedded in the cookie remains valid. For details about ObSSOCookies and single sign-on, see the Oracle Access Manager Access Administration Guide.

• The user fails to supply valid credentials under the specified conditions

• Some other error condition arises

• The developer has built additional custom code into the AccessGate to handle special situations or functionality

4.2 About AccessGate Deployment

AccessGates are typically deployed by teams, with each team member covering a specific area of expertise. For instance, a network administrator can install software and set the requisite environment variables, a developer can write the custom AccessGate code, and an Access Administrator can create policy domains to protect specific resources. Together, the developer and the Access Administrator can configure the Access Server to work with the new AccessGate.

Although the tasks handled by each individual can vary, the team responsible for the Access System must complete the following tasks.

Task overview: AccessGate deployment

1. Install the Access Manager SDK on the machine that will host the AccessGate, as described in "Installing the Access Manager SDK" .

2. Write custom AccessGate code and build it into a servlet or application that receives resource requests, as described in "Writing AccessGate Code" .

3. Configure the AccessGate, as described in "Configuring an AccessGate" and includes the following:

   • Set environment variables on the host server where the AccessGate will be installed.

   • Create an AccessGate entry on the Access System console (typically, the Access Administrator and the AccessGate developer work together to create this entry).

   • Create an ObAccessClient.xml file, which the AccessGate developer accomplishes by running the interactive, non-GUI configureAccessGate application on the machine that will host the AccessGate.

4. Protect enterprise resources by creating policy domains, as described in the Oracle Access Manager Access Administration Guide.

   This includes definition of the resource and the designation of operations permitted against that resource. Generally, an Access Administrator performs this task through the Access System console.

   Note:

   The Access Administrator and the developer must work closely to ensure that the resource types and challenge methods the AccessGate is programmed to handle match exactly the resource types and challenge methods assigned to the policy domains that the AccessGate will protect. For details about protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.

4.2.1 Supported Versions and Platforms

Any references to specific versions and platforms in this chapter are made for demonstration purposes.

You can find support and certification information at the following URL:

http://www.oracle.com/technology/documentation/

You must register with OTN to view this information.

Also, you can see the supported versions and platforms for this integration on Metalink, as follows.

To view information on Metalink

1. In your browser, enter the following URL:

   https://metalink.oracle.com

2. Log in to MetaLink.

3. Click the Certify tab.

4. Click View Certifications by Product.

5. Select the Application Server option and click Submit.

6. Choose Oracle Identity Management and click Submit.

7. Click Oracle Identity Management Certification Information 10g (10.1.4.0.1) (html) to display the Oracle Identity Management page.

8. Click the link for Section 6, Oracle Access Manager Certification to display the certification matrix.

4.2.2 Installing the Access Manager SDK

If your Access System uses WebGates exclusively, you do not need to install the Access Manager SDK, because each self-contained WebGate installation package already contains all the specific resources it needs.

If you use one or more custom AccessGates, you must install an instance of the Access Manager SDK on each server that hosts an AccessGate. You may install both UNIX-based and Windows-based AccessGates within the same deployment as long as each instance of the Access Manager SDK matches the type of server on which it is installed.

Note that the Access Manager SDK is not part of the Access Server installation package. The self-contained SDK ships in its own setup package which is labelled:

COREid#_#_Platform_AccessServerSDK[.ext]

where #_# is the installed version of Oracle Access Manager, platform is the operating system of the host server where you install the SDK, and ext is the file name extension ".exe," which appears only on Windows installation packages.

Thus, "COREid_10_1_4_sparc-s2_AccessServerSDK" contains the version of the Access Manager SDK appropriate for installation on servers running the Solaris operating system.

A convenient installation location for your Access Manager SDK on a typical Windows system might be:

C:\Program Files\Oblix\AccessServerSDK

In any case, make note of the SDK installation path, as you will need it later, whenever you see the string SDK_install_dir in the rest of this chapter.

4.2.2.1 Obtaining the Access Manager SDK

You can download the Access Manager SDK from the Oracle Technology Network at the following URL:

http://www.oracle.com/technology

4.2.2.2 Installing the SDK on Windows

After downloading the SDK, you can install it. The following procedure describes how to install the SDK on Windows.

To Install the SDK on a Windows Machine

1. On the machine where you plan to install your AccessGate, navigate to the directory where your Access Manager SDK installation package is stored. The path to this package resembles the following:

   Device\...\AccessSystem\Platform
   
   

   where Device is the CD or hard drive holding your installation image, and Platform is the operating system of the host server on which you are installing the AccessGate.

2. Double-click the following executable:

   COREid#_#_Platform_AccessServerSDK
   
   

   where #_# is the version you are running, and Platform is the operating system of the machine on which you are installing the AccessGate.

   For example:

   COREid_10_1_4_Win32_AccessServerSDK.exe
   
   

3. When the Welcome screen appears, click Next.

4. When the license agreement appears, decide whether to proceed by checking the box "I accept the terms of the license agreement."

5. The next screen emphasizes that you must have administrator privileges on the host machine where you are installing the SDK.

   If your current account has administrator rights, click Next.

   If you are not currently logged onto an account with such privileges, complete the following sub-task:

   1. Click Cancel to close the installation wizard

   2. Log off the system

   3. Log back on using an administrator account

   4. Restart the Access Manager SDK installation wizard

6. Select an install directory using any of the following methods:

   • Click Browse and navigate to the directory you prefer

   • Place your cursor in the "Destination Name" entry field and type the path to the directory you prefer

   • Simply accept the default installation directory as it appears in the "Destination Name" entry field.

     For Windows, the default is C:\Program Files\NetPoint. The sub-directory \AccessServerSDK is appended to the default base path during installation.

   In any case, when the directory you want appears in the "Destination Name" entry field, click Next to continue.

7. When a screen appears to announce the target installation directory, check to make sure that it shows the exact location you want. Make a note of this path, because you will need it every time SDK_install_dir appears in the rest of this chapter.

8. Click next to commence file installation.

9. Respond to the on-screen prompts, as necessary.

10. When installation completes, a screen appears to report that the process has succeeded.

4.2.2.3 Installing the SDK on UNIX

To install the SDK on a UNIX machine

1. On the machine where you plan to install your AccessGate, navigate to the directory where your Access Manager SDK installation package is stored.

   The path to this package resembles the following:

   Device\...\AccessSystem\Platform
   
   

   where Device is the CD or hard drive holding your installation image, and Platform is the operating system of the machine on which you are installing the AccessGate.

2. Locate the following executable:

   COREid#_#_Platform_AccessServerSDK
   
   

   where #_# is the version you are running, and Platform is the operating system of the machine on which you are installing the AccessGate.

   For example:

   COREid_10_1_4_sparc-s2_AccessServerSDK
   
   

3. At the UNIX prompt, enter the name of the appropriate Access Manager SDK installation package to commence GUI-mode installation.

   Note:

   This procedure assumes that your UNIX machine supports GUI-mode. You can also run the installation package in interactive command-line mode by entering the following:

   run ./installationPackage
   
   

   where installationPackage is the name of the Access Manager SDK installation package appropriate for your machine.

4. When the Welcome screen appears, click next.

5. When the license agreement appears, decide whether to proceed by checking the box "I accept the terms of the license agreement."

6. When the installer asks for a user and group to set as the owner of the installed files, you may find it convenient to specify the same user and group that "own" the server application your AccessGate will protect. In any case, you must be logged on as the user you specify, or as "root," in order to continue installation.

7. Accept the default install directory by hitting Return, or type your preference, then hit return.

   Note:

   You cannot install Oracle Access Manager components in any directory that contains special characters in its path. The proscribed characters are: blank spaces, new lines, *, [], {}, and so on.

8. When a screen appears to announce the target installation directory, check to make sure that it shows the exact location you want. If the directory does not exist, the installer creates it. Make a note of this path, because you will need it every time SDK_install_dir appears in the rest of this chapter.

9. Click next to commence file installation.

10. Respond to the on-screen prompts, as necessary.

11. When installation completes, a screen appears to report that the process has succeeded.

4.2.3 Configuring an AccessGate

AccessGate configuration, which is not to be confused with AccessGate creation or SDK installation, consists of the following sub-tasks.

Task overview: Configuring an AccessGate

1. Setting environment variables on the host server where the AccessGate will reside, as described in "Setting Environment Variables" .

2. Creating an AccessGate entry on the Access Server, as described in "Creating an AccessGate Entry on the Access Server" .

3. Creating the ObAccessClient.xml file within the Access Manager SDK installation, as described in "Running the configureAccessGate Utility".

4. For each AccessGate, you must run the configureAccessGate utility, as described in "Running the configureAccessGate Utility" .

   You can perform any of the AccessGate configuration either before or after you create custom code for your AccessGate.

   Note:

   Creating the ObAccessClient.xml file within the Access Manager SDK installation, as described in "Running the configureAccessGate Utility" .

4.2.3.1 Setting Environment Variables

Requisite environment variables differ according to the operating system on the host server where your AccessGate resides. Complete the procedure that is appropriate to your environment:

• Windows host

• UNIX host

To set environment variables on a Windows machine

1. Navigate to the Start Menu, then to Control Panel, then to System, then to Advanced, then to Environment Variables.

2. Examine the contents of the System Variables box.

3. If you see the Variable Name for the Variable Value you want to add, click that Variable Name, click Edit, then proceed to Step 6 (otherwise, click New and proceed to the next step).

4. Type Variable Name and Variable Value in the appropriate fields of the New System Variable entry box.

5. Click OK to commit the variable, then proceed to Step 7.

6. When the Edit System Variable entry box appears, click the Variable Value field, move the cursor to the end of the string, type "; value" (semi-colon followed by the blank space character followed by the new value), then click OK to commit the variable.

7. Repeat Steps 3-6 until you have added all the variables listed in the following table.

   Note:

   For Windows 2003, these variables take effect immediately and do not require a system restart.For Windows 2000, you should restart your machine after you have entered the variables. This ensures that all the variables will take effect.

Table 4-1 Windows Environment Variables

Variable Name = existing path; Value to Add	Description
PATH = existing path; SDK_install_dir\oblix\lib	Points to obaccess.dll and other library files.
CLASSPATH = existing path; SDK_install_dir\oblix\lib\jobaccess.jar	Points to the name and location of the Java class archive for the Access Manager API. (Required only if you use the Java implementation of the Access Manager API to write custom AccessGate code).
OBACCESS_INSTALL_DIR = SDK_install_dir	Points to the Access Manager SDK install root. (This is necessary only if your AccessGate does not specify SDK_install_dir as part of the ObConfig.initialize method).

To set environment variables on a UNIX machine

1. Use a text editor to open the file (or files) containing the variables on your UNIX system.

2. For all the variables in Table 4-2, append the values listed, or, if the variable name does not exist, add the variable name along with its associated value to the file.

   Note:

   To ensure that the new variables take effect, take whatever measures (such as system restart) are appropriate for your specific UNIX environment.

Table 4-2 UNIX Environment Variables

Variable Name = existing path; Value to Add	Description
LD_LIBRARY_PATH = existing path; SDK_install_dir/oblix/lib (for Solaris only)	Points to libobaccess.so and other library files on Solaris systems.
CLASSPATH = existing path; SDK_install_dir/oblix/lib/jobaccess.jar	Points to the name and location of the Java class archive for the Access Manager API. Required only if you use the Java implementation of the Access Manager API to write custom AccessGate code.
POST_CLASSPATH = existing path; SDK_install_dir/oblix/lib/jobaccess.jar
OBACCESS_INSTALL_DIR = existing path; SDK_install_dir	Points to the Access Manager SDK install root.

4.2.3.2 Creating an AccessGate Entry on the Access Server

Complete the following task to enable your Access Server to connect to your custom AccessGate. (You can complete this task before your create your AccessGate, as long as the information you enter matches the particulars of the AccessGate and the ObAccessClient.xml file).

To create an AccessGate entry on the Access Server

1. Navigate to the Access System Console, then to Access System Configuration, then to Add New AccessGate.

2. Type a convenient name in the AccessGate Name field.

   Note:

   Choose a name that distinguishes this particular AccessGate from all the others in your system. For instance, "CustCare5_6006" might help you identify an AccessGate installed on web server "Customer Care 5," which listens on port 6006.

3. In the HostName field, type the DNS name of the machine hosting the server instance on which the AccessGate resides.

   For example:

   CustomerCare5.oblix.com

4. Complete the following activity based on your environment:

   • If the machine on which your will install the AccessGate does not host additional Web or applications servers skip this step.

     Typically, this value is assigned by the administrator responsible for the server; the AccessGate administrator merely records this value in the AccessGate configuration profile).

   • If the machine on which your will install the AccessGate hosts does host additional Web or applications servers, specify the server instance that will use your AccessGate by typing in the port number the server uses to listen for user requests.

     Note:

     Oracle recommends using any number between 6000 and 65,536, which has not been used for any other ports on the network.

5. Type an alphanumeric string for use as a password whenever the AccessGate connects to the Access Server.

   This value is optional for all transport modes, although the Simple and Cert modes use other passwords not directly related to AccessGate configuration. However, Oracle strongly recommends that you set a password for your AccessGate, particularly if it uses Open mode. This will prevent unauthorized AccessGates from connecting to Access Servers.

6. Retype the password to confirm it.

7. Click Save at the bottom of the panel to commit the values.

The preceding steps provide all necessary information for this stage of AccessGate deployment. From this point forward, you can enter optional values for the other parameters, which will use the supplied default values until you replace them. For details on setting these other parameters by modifying an AccessGate, see the Oracle Access Manager Access Administration Guide.

4.2.3.3 Running the configureAccessGate Utility

For each AccessGate on your system, you must run the configureAccessGate utility, which stores data used to initialize the AccessGate in the file ObAccessClient.xml.

The configureAccessGate tool reads and updates this information each time you initialize the Access Manager API and at other points during AccessGate operation.

By default, this file is stored in the following directory on the machine hosting your AccessGate:

SDK_install_dir\oblix\config

You can view the contents of the ObAccessClient.xml file by opening it in any text editor. For details on the content of the ObAccessClient.xml file and modifying an AccessGate, see the Oracle Access Manager Access Administration Guide.

Note:

Never edit ObAccessClient.xml using a text editor. Instead, use the configureAccessGate application from a command-line window.

Using the configureAccessGate application from a command-line window to edit ObAccessClient.xml ensures that your AccessGate parameters remain consistent throughout the system. This is because confgureAccessGate not only modifies ObAccessClient.xml, it performs additional vital tasks related to the simple and cert modes, such as creating or requesting an X.509 certificate. See details on modifying an AccessGate in the Oracle Access Manager Access Administration Guide.

To run configureAccessGate on a UNIX Machine

1. From the UNIX command line, navigate to the following directory:

   SDK_install_dir\oblix\tools
   
   

   where SDK_install_dir is the root directory of your Access Manager SDK installation.

2. Type the following command, then press Enter:

   ./configureAccessGate -i SDK_install_dir -t AccessGate
   
   

   Where SDK_install_dir is the directory where you installed the SDK.

3. Respond to the series of prompts as they appear.

   For information on available switches, acceptable arguments, and defaults when configuring AccessGates, see the Oracle Access Manager Access Administration Guide.

When the configureAccessGate program successfully exits, the AccessGate is enabled on your server.

To run configureAccessGate.exe on a Windows Machine

1. Navigate to the Start Menu, then select Run.

2. Enter the following command in the Open field:

   cmd
   
   

3. When the command-line (non-GUI) window opens, switch directories by entering the following command:

   cd SDK_install_dir\oblix\tools\configureAccessGate
   
   

   where SDK_install_dir is the path to your Access Manager SDK installation.

4. Launch the configureAccessGate utility by entering the following command, including switches and arguments:

   configureAccessGate -i SDK_install_dir -t AccessGate
   
   

   where SDK_install_dir is the path to your Access Manager SDK installation.

Respond to the series of prompts as they appear. For information on available switches, acceptable arguments, and defaults when configuring AccessGates, see the Oracle Access Manager Access Administration Guide.

When the configureAccessGate program successfully exits, the AccessGate is enabled on your server.

4.2.4 Writing AccessGate Code

This procedure is covered in the section "About Custom AccessGate Code" .

4.2.4.1 Cloning a Custom AccessGate

When you need to protect an additional server by creating an AccessGate similar to an AccessGate you have already deployed, you do not necessarily have to write new code. In some cases, you might be able to clone the existing AccessGate to that additional server.

Task Overview: Cloning a custom AccessGate

1. Install the version of the Access Manager SDK that is compatible with the operating system of the server where the cloned AccessGate will reside. See "Supported Versions and Platforms" .

2. Create an entry for the new AccessGate on the Access Server to which it will connect. See "Creating an AccessGate Entry on the Access Server" .

3. Run the configureAccessGate utility to create an ObAccessClient.xml file for the new AccessGate on the server where the new AccessGate will reside. See "Running the configureAccessGate Utility" .

   Alternatively, you modify the ObAccessClient.xml file from the original AccessGate by copying it to the new host server, then running the configureAccessGate utility.

4. Set the Access Manager API environment variables for the server on which the cloned AccessGate will reside. See "Setting Environment Variables" .

5. Copy the plain text file containing your custom AccessGate code to the server where the cloned AccessGate will reside.

6. Modify the transferred code, as necessary, to fit the particulars of the new AccessGate.

7. Recompile the code using the compiler that is compatible with the operating system of the host server and the development language in which the custom AccessGate code was written. See "Supported Versions and Platforms" .

4.2.5 Protecting Resources

Policy domains specify which resources are protected by what protection methods applied to which users and groups. Usually, they are created and maintained by Access Administrators. AccessGate developers should work with Access administrators to create, modify, or identify the specific policy domains that the AccessGate will protect. For detailed information on creating policy domains, see the Oracle Access Manager Access Administration Guide.

4.3 About the Access Manager SDK

This section begins with an overview of the Access Manager SDK. Next, it outlines the content of the installed SDK directory and subdirectories. Finally, it introduces the set of files supplied to support custom AccessGates for BEA WebLogic systems.

4.3.1 SDK Overview

The Access Manager SDK is an optional component, and is installed independent of the Access Server. The SDK provides all the information and resources you need to build a custom AccessGate. In addition to the files that make up the various implementations of the Access Manager API, the SDK includes documentation and code samples, which show how to construct simple AccessGate servlets or applications for each of the supported development platforms.

4.3.2 SDK Content

The Access Manager SDK installation directory contains the following subdirectories and content:

_jvmAccessSDK: Contains the Java runtime resources used by the Access Manager SDK install wizard.

_uninstAccessSDK: Contains the resources for uninstalling the Access Manager SDK through the install wizard.

apidoc: Documents the Java implementation of the Access Manager API. You access this information through the following URL:

SDK_install_dir\apidoc\com\oblix\access\package-summary.html

Note:

The package com.oblix.access documents the Access Manager API. The package com.oblix.accessmgr documents the Policy Manager API.

examples: Includes a sample build file, a sample make script, and the Web page AppServer_ReadMe.html, which explains how to create an AccessGate for a WebLogic server.

obaccess: Contains an example Java servlet as well as prototypes for classes that can be used to extend the startup and shutdown classes for the server application.

ejbAccessTest: Holds the example "Broker Bean" EJB, along with a sample build file and a build script which follows the conventions used by BEA WebLogic.

include: Contains header files that define the classes, methods, and functions composing the C++ and C implementations of the Access Manager API.

oblix: Holds four subdirectories:

config: Contains configuration data for the Access Manager SDK installation.

lang: Contains language-specific files (English, French, and so on) for your installation of the Access Manager SDK, including:

• release notes: Contains information that was not received in time to include in the main documentation.

• netlibmsg.lst: A file of messages the AccessGate uses when errors occur. Depending on how your AccessGate is configured, these can be logged locally, displayed locally, or ignored.

• ObAccessClient.msg: Provides the message text the AccessGate displays in response to various events.

lib: Contains the Access Manager SDK libraries and Java archive files that are built into the application. These include:

• various libraries: Codes libraries required by the API. (For instance, .dll files for Windows, .so files for Solaris, and so on).

• jobaccess.jar: Which is the Java archive file for the API.

• ObAccessClient.xml file: An example of the AccessGate configuration file.

orig: Contains information created during the installation of the SDK. You should ignore this.

tools: Contains four significant subdirectories:

• configureAccessGate: Contains the tool that configures the AccessGate, as well as the messages the tool needs.

• lang_tools: Contains development language-specific files (Java, C, and so on) for your installation of the Access Manager SDK.

• migration_tools: Contains information about migrating AccessGates created with earlier versions of the API to the current version of the SDK.

• openssl: Contains a tool and short certificate used to configure the AccessGate for Simple or Cert mode operation.

samples: Provides versions of the standalone Access Test application written for Java, C, C++, and C# (.NET). These can be used to gain familiarity with the SDK build process before you attempt more complex applications.

Note:

Once the SDK is installed, do not change the relative locations of the subdirectories and files. Doing so may prevent an accurate build and proper operation of the API.

4.3.2.1 BEA WebLogic Support Files

To enable quick support of BEA WebLogic, the Access Manager SDK provides WebLogic-compatible Startup and Shutdown classes. The WebLogic Manager API itself provides extensible classes that can be used to extend the startup and shutdown capabilities of the WebLogic Server.

The ObStartupAppGate.java and ObShutdownAppGate.java classes reside in:

SDK_install_dir/examples/obaccess

These classes enable WebLogic Server initialization, which is necessary before AccessGate initialization can take place. They can be used out-of-the-box or modified to suit the application being developed.

The ObStartupAppGate and ObShutdownAppGate Java classes conform to the standards detailed in the WebLogic documentation supplied by BEA. Before writing your own Startup and Shutdown classes for the WebLogic Server, refer to the section on server startup and shutdown in the Access Manager SDK and WebLogic Application Server documentation in SDK_install_dir\examples\ AppServer_Readme.html.

The Access Manager API method ObConfig.initialize initializes the AccessGate. The ObConfig.shutdown method shuts down the AccessGate gracefully. After successful initialization, all Java components built using the Access Manager SDK share the AccessGate configuration when they are deployed to the WebLogic Server.

4.4 About the Access Manager API

This section begins by comparing the naming schemes used by each of the four Access Manager API implementations. It then introduces the API classes in turn, with special emphasis on the different ways specific features are handled in the various development environments.

Reference details for each of the four language-specific implementations appear in separate sections beginning on "C++ Implementation Details" . For the Java implementation only, reference details are also supplied as online JavaDoc HTML files accessible through SDK_install_dir/apidoc/index-all.html.

4.4.1 Implementations Compared

The Access Manager API enables developers to write custom AccessGate code in any of four development languages: Java, C, C++, or C#. While each of these implementations takes advantage of platform-specific features to implement the API, the four implementations are functionally equivalent.

4.4.1.1 About Memory Management

The four implementations of the Access Manager API differ most significantly in the area of memory management.

Java and C# both feature automatic garbage collection. Neither language enables you to call a destructor explicitly. Instead, you simply let the built-in garbage collector deallocate the memory for unused objects when it (the garbage collector) deems appropriate. Thus, the garbage collectors do not guarantee when an object will be cleaned up, but they do see to it that all objects are destroyed when they are no longer referenced, and no memory leak occurs.

By contrast, you must explicitly call destructors in C and C++ to clean up the objects that your program no longer needs. For each C-language pseudo class, you use the functions whose names end with "_free." When you no longer need C++ objects previously created with the "new" operator, use the "delete" operator to destroy them.

4.4.1.2 Corresponding Classes

The functionality of the Access Manager API has been organized into seven basic classes. Even for the C language, which is not explicitly object-oriented, the functions have been organized into "pseudo object-oriented classes."

Table 4-3 lists the corresponding class names for each language platform:

Table 4-3 Access Manager API Implementation-Specific Classes Compared

Purpose of the Class	C++	C	C#	Java
Supports parameter storage structures (lists or hashtables).	ObMap	ObMap_t	ObDictionary	java.util.Hashtable, which extends java.util.Dictionary (This is not a Com. Oblix.Access class)
Supports iteration within lists (C and C++ implementations only; C# and Java enumerate hashtables).	ObMapIterator	ObMap Iterator_t	ObDictionary Enumerator	java.util.Hashtable, which extends java.util.Dictionary (This is not a Com. Oblix.Access class)
Creates and manipulates structures that handle user authentication.	ObAuthentication Scheme	ObAuthn Scheme_t	ObAuthentication SchemeMgd	ObAuthentication Scheme implements ObAuthentication Scheme Interface
Creates and manipulates structures that handle user requests for resources.	ObResource Request	ObResource Request_t	ObResource RequestMgd	ObResource Request implements ObResource RequestInterface
Creates and manipulates structures that handle user sessions, which begin when the user authenticates and end when the user logs off or the session times out.	ObUserSession	ObUserSession_t	ObUser SessionMgd	ObUserSession implements ObUserSession Interface
Retrieves and modifies AccessGate configuration information.	ObConfig	ObConfig_t	ObConfigMgd	ObConfig
Handles errors thrown by the Access Manager API	ObAccess Exception	ObAccess Exception_t	ObAccess ExceptionMgd	ObAccess Exception

4.4.1.3 About Multi-Language Implementation

You can select any of the four functionally-equivalent implementations of the Access Manager API as the development language interface you use to write your custom AccessGate code. However, you should remain aware that your code, no matter what language it was written in, will interact with underlying C++ binaries in the API.

Also, AccessGate code that is created for one specific development language, compiler, server, and operating system configuration might require recompilation to ensure that it will run correctly in another environment.

To ensure that your AccessGates behave as expected, you should follow certain best practices in the following areas:

• Portability: See "Cloning a Custom AccessGate" for details.

• Clean-up: See "About Memory Management" for details.

4.4.2 ObMap

When your AccessGate interacts with the Access Server, it stores, passes, and receives information through lists of entries (or items) arranged as name:value pairs. These list structures, which are opaque to the end user, are also known as maps in the C and C++ environments. When used within a Java or C# context, they are called hashtables.

These list and hashtable structures store many types of Access Manager API-related data, including the following:

• Resource request information

• Authentication scheme information

• User session information

• AccessGate configuration information

For instance, a typical AccessGate might pass a set of user credentials to the Access Server as a single-item list in the following form:

UserName=JSmith&Password=J5m1th

The C and C++ implementations of the Access Manager API create and manipulate these structures through the ObMap class and ObMap_t pseudo class, respectively. The equivalent class for the C# implementation is ObDictionary. The Java implementation of the API does not include a class of its own to handle list structures; rather, it relies on the standard Java class named java.util.Hashtable for all list-related functions.

All of these implementing classes provide methods to enable the following functionality:

• Create a list (or hashtable)

• Add a name:value pair to a list (or hashtable)

• Read a name:value pair from the list (or hashtable) when the name half of the item is known

• Report the total number of items in a list (or hashtable)

• Copy an existing list (or hashtable)

• Deallocate the memory used by the list structure (or hashtable)

For a discussion of additional methods that manipulate Access Manager API lists and hashtables, see "ObMapIterator" .

4.4.2.1 Equivalent Methods

Table 4-4 presents equivalent constructors and methods for the four API implementations of the ObMap class. Note that this table includes existing Java methods only if they correspond to an equivalent method in one of the C-family implementations of ObAccess:

Table 4-4 Methods (and Constructors) for the ObMap Class Compared

C++ (ObMap)	C (ObMap_t)	C# (ObDictionary)	Java (java.util.Hashtable)
get	ObMap_get	get_Item	get
put	ObMap_put	add	put
size	ObMap_size	get_Count	size
copy	ObMap_copy	Clone	Hashtable(map t)
Delete	ObMap_free	(built-in garbage collection)	(built-in garbage collection)
(constructor)	ObMap_new	(constructor)	(constructor)

4.4.3 ObMapIterator

Sometimes, it is necessary to step through (or iterate) the items in a hashtable or list. The C, C++, and C# implementations handle this and related functions through the ObMapIterator, ObMapIterator_t, and ObDictionary classes, respectively. The Java implementation achieves this functionality through java.util.Hashtable, which is a standard Java class, rather than an Access Manager API class.

The methods offered by the implementations differ because only the C and C++ implementations of the Access Manager API require full iterator functionality to parse their list structures. The C# and Java implementations of the API use hashtables, and therefore do not use the same iterator functionality for parsing operations.

ObMapIterator provides methods to enable the following pointer functionality:

• Create a list pointer

• Move the pointer from the current item to the next item in the list

• Determine whether additional items exist in the list beyond the position currently occupied by the pointer. By implication, you know that the pointer has reached the end of a list when no more items exist beyond the current position of the pointer.

• Deallocate the memory used by the pointer.

4.4.3.1 Equivalent Methods

Table 4-5 presents equivalent constructors and methods for the four API implementations of the ObMapIterator class. Note that this table includes Java methods only if they correspond to an equivalent method in one of the C-family implementations of ObAccess.

Table 4-5 Methods for the ObMapIterator Class Compared

C++ (ObMapIterator)	C (ObMapIterator_t)	C# (ObDictionary Enumerator)	Java (java.util.Hashtable)
next	ObMapIterator_next	MoveNext
		get_Current
hasMore	ObMapIterator_hasMore
		get_Entry
		get_Key
		get_Value
(constructor)	ObMapIterator_new	Reset
Delete	ObMapIterator_free	(built-in garbage collection)	(built-in garbage collection)

4.4.4 ObAuthenticationScheme

The Access Manager API creates ObAuthenticationScheme structures to store, pass, and retrieve information about the authentication scheme (authentication template) associated with the target resource requested by a particular user. In other words, an authentication scheme specifies how a user is to be challenged for a set of credentials.

The details for each authentication scheme are specified when the Access Administrator creates a policy domain on the Access Server to protect a specific resource. For a detailed discussion of authentication schemes, see the Oracle Access Manager Access Administration Guide.

Credentials are name:value pairs that the AccessGate passes to the Access Server in order to authenticate a user. For example, an AccessGate using the HTTP basic challenge method might pass the following credential string, which contains two name:value pairs:

userid=JSmith&Password=J5m1th

In the preceding example, the name:value pairs are separated by the ampersand character (&), and the name and value components are separated by equal signs (=).

Since the requisite authentication scheme can vary according to the resource requested, an ObAuthenticationScheme structure can be created only after an ObResourceRequest structure has specified the target resource.

Each authentication scheme contains the elements listed in Table 4-6:

Table 4-6 ObAuthenticationScheme Elements

Element	Details
Display Name	This is a friendly name used to identify the authentication scheme. For example, "Customer Form Login" might represent an authentication scheme used to grant preferred customers access to a price list for frequent buyers.
Mask Byte Mask Expected Credentials 0x00 No credentials needed. The plug-in should map to an anonymous user. 0x01 User ID and Password (as for HTTP basic) 0x02 A certificate using SSL/TLS client authentication (as for HTTPS) 0x04 Customer-defined credential fields in an HTML login form 0x08 Credentials must be sent over a secure connection (as for HTTPS) and a redirection URL must be used as well.	This byte indicates the type of challenge method to be used and whether credentials need to be sent over a secure connection:
	Challenge Method
	none
	basic
	certificate
	form
	secure
Strength	This positive integer defines the level of authentication.
Redirection URL	This is the URL (in the form "https://host:port") where HTTP secure authentication is to be performed. If secure authentication (or a central authentication server such as SecurID) is not required, this value is set to NULL.
Challenge Parameters Challenge Method Value basic The authentication domain (as for an LDAP directory) form The URL of the login form that will be displayed on the user web browser form A space-separated list of login form fields that will be used as credentials form The URL to which the login form posts the data it receives	This element stores additional authentication scheme-related information in name:value pairs. When these optional parameters are not supplied, Challenge Parameters is represented by an empty string.
	Parameter Name
	realm
	form
	creds
	action
Plug-in Sequence	This element is not visible through the Access Manager API.

4.4.4.1 Equivalent Methods

Table 4-7 presents equivalent constructors and methods for the four API implementations of the ObAuthenticationScheme class.

Table 4-7 Methods for the ObAuthenticationScheme Class Compared

C++ (ObAuthentication Scheme)	C (ObAuthentication Scheme_t)	C# (ObAuthentication SchemeMgd)	Java (ObAuthentication Scheme)
getName	ObAuthn_getName	get_Name	getName
getMask	ObAuthn_getMask	get_Mask	(this method is not public in Java)
requires SecureTransport	ObAuthn_requires SecureTransport	get_Requires SecureTransport	requires SecureTransport
IsBasic	ObAuthn_isBasic	get_IsBasic	isBasic
IsCertificate	ObAuthn_isCertificate	get_IsCertificate	isCertificate
IsForm	ObAuthn_isForm	get_IsForm	isForm
IsNone	ObAuthn_isNone	get_IsNone	isNone
getLevel	ObAuthn_getLevel	get_Level	getLevel
getRedirectUrl	ObAuthn_get RedirectUrl	get_RedirectUrl	getRedirectUrl
getChallenge Parameter	ObAuthn_get ChallengeParameter	get_Challenge Parameter	getChallenge Parameter
getAllChallenge Parameters	ObAuthn_getAll ChallengeParameters	get_All ChallengeParameters	getAllChallenge Parameters
getNumberOfChallenge Parameters	ObAuthn_getNumberOf ChallengeParameters	get_NumberOf ChallengeParameters	getNumberOfChallenge Parameters
(constructor)	ObAuthn_new	(constructor)	(constructor)
(copy constructor)	(not implemented)	Clone	clone
Delete	ObAuthn_free	(built-in garbage collection)	(built-in garbage collection)

4.4.5 ObResourceRequest

The Access Manager API uses the ObResourceRequest structure to store, pass, and retrieve information concerning a user request for access to a resource. This information includes the elements listed in Table 4-8.

Table 4-8 ObResourceRequest Elements

Element	Details
Resource Type	This can be a built-in type, such as HTTP or EJB, or a custom type defined through the Access System Console. For a detailed discussion about configuring resource types and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.
Resource Name	The name of the target resource within the Oracle Access Manager name space. This must be provided in the format [//host[:port]]/resourceName where the optional host and port values indicate the Web server servicing resourceName, which is the name of the targeted resource. Host and port apply only to HTTP resources.
Operation	The action to be performed against the resource, as dictated by the resource type. Examples are GET and POST for HTTP resources, and EXECUTE for EJB resources. For custom resource types, operations are defined through the Access System Console when the resource type is defined. For a detailed discussion, about configuring resource types and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.
Parameter Set (optional)	A name:value pair for the requested operation. Parameter names and values must be strings. For HTTP resources, they can be extracted from the request query string or POST data. For EJB resources, parameter entries can be "bean" method parameters. Neither of the preceding is a requirement. The names and values can be any arbitrary data that the developer and Access Administrator have agreed upon. The name:value pairs can be used to supply data for authorization requests. This is useful for authorizations that require data from external sources. For example, if you need to pass an account number, you can write a plug-in for this purpose. For details about customizing access control with plug-ins, see the Oracle Access Manager Customization Guide

The ObResourceRequest constructors return the following policy information from the Access Server, as described in Table 4-9:

Table 4-9 Information Returned by the Access Server in Response to ObResourceRequest

Element	Details
Protection Flag	Indicates whether the resource request is protected by Access System policies. If the resource is not protected, the AccessGate grants the user free access to the resource.
Authentication scheme name	An internal ID representing the authentication scheme associated with the target resource.

ObAuthenticationScheme constructors use the information contained in the ObResourceRequest structure to determine which authentication scheme is associated with the target resource. Similarly, the ObUserSession constructors can use the information in the ObResourceRequest structure to determine whether the user, once authenticated, is authorized to access the target resource.

4.4.5.1 Equivalent Methods

Table 4-10 lists the names of equivalent methods across the four implementations of the ObResourceRequest class.

Table 4-10 Methods for the ObResourceRequest Class Compared

C++ (ObResource Request)	C (ObResource Request_t)	C# (ObResource RequestMgd)	Java (ObResource Request)
getResourceType	ObResource_ getResourceType	get_ResourceType	getResourceType
getResource	ObResource_getResource	get_Resource	getResource
getOperation	ObResource_getOperation	get_Operation	getOperation
getParameters	ObResource_ getParameters	get_Parameters	getParameters
getNumberOf Parameters	ObResource_getNumber OfParameters	get_NumberOf Parameters	getNumberOf Parameters
isProtected	ObResource_isProtected	get_IsProtected	isProtected
getAuthorization Parameters	ObResource_ getParameters	get_Authorization Parameters	getAuthorization Parameters
getNumberOf Authorization Parameters	ObResource_getNumber OfAuthorizationParameters	get_NumberOf Authorization Parameters	getNumberOf Authorization Parameters
(copy constructor)	(not implemented)	Clone	Clone
Delete	ObMap_free	(built-in garbage collection)	(built-in garbage collection)
(constructor)	ObResourceRequest_new	(constructor)	(constructor)

4.4.6 ObUserSession

After the Access Server validates the user credentials necessary for successful login (or "authentication"), the AccessGate creates an ObUserSession structure to store, pass, and retrieve information about the user, the target resource, and various types of authentication policy information. This structure can be created from information drawn from the ObResourceRequest and ObAuthenticationScheme structures as well as information returned by the Access Server. Alternatively, the ObUserSession structure can be created from information contained in a session token, which is an ASCII character string that stores information about a currently valid user session.

A session token can be generated from a ObUserSession structure. An ObUserSession structure can be constructed from a valid session token, except for actions and error information, which are not carried in the session token. For details about obtaining data from an external source 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.

A key method in ObUserSession returns information from the Access Server as to whether the user, who has passed authentication successfully, is authorized to access the target resource. Other ObUserSession methods return information about when the user authenticated (and, by extension, when the current session will expire), the most recent time at which the user was authorized to access a resource, and so forth. In any case, a ObUserSession structure contains the pieces of information presented in Table 4-11:

Table 4-11 ObUserSession Elements

Element	Description
User Identity	The Distinguished Name (DN) of the user's profile entry in the LDAP user directory.
Level	The security level of the authentication scheme used to authenticate the user. This is a relative number assigned by the Access System Administrator. For additional discussion of changing the security level of an authentication scheme, see the Oracle Access Manager Access Administration Guide.
Location (optional)	The location of the user web browser (or the proxy server representing the user's web browser). Examples are the DNS hostname of the proxy server or the IP address of the user's browser.
Session start time	The time when the user authenticated. This and the maximum permitted session time can be used to calculate when the session expires.
Last use time	The most recent time at which the user was authorized; this is used to determine when an idle session expires.
Actions	Actions set during authentication and authorization according to Access System policy rules. Each rule includes a type, which can be user created, that tells the application how the action is to be interpreted. Examples for HTTP are "cookie" and "headerVar."
Status	The current status of the session, which may be one of the following: logged in logged out login failed expired
Error number and Error Message	Errors resulting from the most recent authentication or authorization.

4.4.6.1 Equivalent Methods

Table 4-12 presents the names of equivalent methods for the ObUserSession class in the Access Manager API.

Table 4-12 Methods for the ObUserSession Class Compared

C++ (ObUserSession)	C (ObUserSession_t)	C# (ObUserSessionMgd)	Java (ObUserSession)
getLocation	ObUser_getLocation	get_Location	getLocation
getAction	ObUser_getAction	getAction	getAction
getActions	ObUser_getActions	getActions	getActions
getActionTypes	ObUser_ getActionTypes	get_ActionTypes	getActionTypes
getNumberOfActions	ObUser_ getNumberOfActions	getNumberOfActions	getNumberOfActions
getLevel	ObUser_getLevel	get_Level	getLevel
getStartTime	ObUser_ getStartTime	get_StartTime	getStartTime
getLastUseTime	ObUser_ getLastUseTime	get_LastUseTime	getLastUseTime
getStatus	ObUser_getStatus	get_Status	getStatus
getUserIdentity	ObUser_ getUserIdentity	get_UserIdentity	getUserIdentity
getError	ObUser_getError	get_Error	getError
getErrorMessage	ObUser_ getErrorMessage	get_ErrorMessage	getErrorMessage
isAuthorized	ObUser_isAuthorized	isAuthorized	IsAuthorized
isAuthorizedWith Parameters	ObUser_isAuthorized WithParameters	isAuthorized WithParameters	IsAuthorized (with additional parameters)
getSessionToken	ObUser_ getSessionToken	get_SessionToken	getSessionToken
setLocation	ObUser_setLocation	set_Location	setLocation
(copy constructor)	(not implemented)	Clone	Clone
logoff	ObUser_logoff	LogOff	logoff
Delete	ObUser_free	(built-in garbage collection)	(built-in garbage collection)
ObUserSession (constructor)	ObUserSession_from Token ObUserSession_ Authenticate	ObUserSessionMgd (constructor)	ObUserSession (constructor)

4.4.7 ObConfig

The ObConfig class includes methods to initialize and shut down the Access Manager API as well as store, pass, retrieve, and in some cases, modify, configuration data for the AccessGate.

The ObConfig.initialize method does the following:

• Passes the name of the installation directory to the AccessGate after retrieving that value from either the "installDir" parameter or the environment variable OBACCESS_INSTALL_DIR

• Verifies that the ObAccessClient.xml file exists in the Access Server installation directory and is readable by the AccessGate

• Reads the bootstrap (current) AccessGate configuration from ObAccessClient.xml

• Opens the ObAccessGate.msg message catalog to obtain the text to be used for user errors and exceptions

• Connects to one or more Access Servers as specified in the bootstrap configuration

• Obtains the full AccessGate configuration from the Access Server

• Creates the local resource request and authentication scheme caches

• Creates a thread to update the AccessGate configuration periodically

ObConfig also contains a shutdown method that you must call to release resources when an application no longer needs to use the Access Manager API.

4.4.7.1 Configuration Parameters

Table 4-13 details the configuration information maintained for each AccessGate. These items are read into the ObConfig structure each time the AccessGate is initialized. They can be Accessed through ObConfig.getItem and ObConfig.getAllItems in the C++ implementation. For the C, C#, and Java implementations, the corresponding methods are ObConfig_getItem and ObConfig_getAllItems, ObConfigMgd.getItem and ObConfigMgd.getAllItems, and Com.Oblix.Access.getItem and Com.Oblix.Access.getAllItems, respectively.

Table 4-13 AccessGate Configuration Parameters

Parameter Name	Parameter Value
accessServerTimeout	The number of seconds that a connection to an Access Server is left open before the connection is re-established.
cacheTimeout	The number of seconds that a cached authentication scheme or resource request object can exist before being flushed automatically. A value of zero specifies that cached elements should never be flushed.
debug	On or Off. If debug is on, the AccessGate traces all messages sent to Access Servers.
failoverThreshold	If the number of primary Access Servers connected to the AccessGate falls under this threshold, the Access Manager API opens one or more connections to secondary Access Servers.
id	The string identifier for the AccessGate in the Oracle configuration directory.
idleTimeout	The maximum number of seconds allowed to elapse between authorizations. When this value is exceeded, the user needs to authenticate again.
transportSecurity	One of the following security modes used to connect to the Access Servers: open: no encryption simple: TLS encryption, using certificates generated from a built-in CA cert: TLS encryption, using certificates issued by a full CA
lastUpdateTime	The number of seconds between 1/1/1970 00:00 and the most recent time the AccessGate configuration was updated.
maxCacheElements	The maximum number of resource-request objects in the authentication scheme cache, which is of a fixed size.
maxConnections	The maximum number of connections that can be opened to AccessGates.
preferredHost	The Web server host address to which the user's browser is redirected when an authentication scheme requires secure authentication. For example, the AccessGate uses this value to specify the host in the authorization request.
primaryDomain	The domain used to set ObSSOCookies, as for a single sign-on domain. Other applications are free to interpret or ignore this parameter, as needed.
primary_server_list	A list of Access Servers to which the AccessGate connects first. The list follows the form: host1:port1,numConn1, host2:port2,numConn2 . . . where hostn is the DNS of the Access Server.
secondary_server_list	List of Access Servers to which the AccessGate connects if the number of connections to the primary servers falls under the failoverThreshold. The list follows the form: host1:port1,numConn1, host2:port2,numConn2 . . . where hostn is the DNS of the Access Server.
sessionTimeout	The maximum number of seconds a user session created by the application remains valid.
sleepFor	How often (in seconds) the AccessGate checks to confirm that the Access Server connections are up.
state	enabled or disabled. Interpretation of this parameter is up to the application. When disabled, an AccessGate immediately enables access to all resources.

4.4.7.2 Equivalent Methods

Table 4-14 presents the names of equivalent methods for the ObConfig class in the Access Manager API.

Table 4-14 Methods for the ObConfig Class Compared

C++ ObConfig	C ObConfig_t	C# ObConfigMgd	Java ObConfig
initialize	ObConfig_initialize	initialize	initialize
shutdown	ObConfig_shutdown	shutdown	shutdown
getAllItems	ObConfig_getAllItems	get_AllItems	getAllItems
getNumberOfItems	ObConfig_ getNumberOfItems	get_NumberOfItems	getNumberOfItems
getItem	ObConfig_getItem	getItem	getItem
getSDKVersion	ObConfig_getSDKVersion	get_SDKVersion	getSDKVersion
getNAPVersion	ObConfig_getNAPVersion	get_NAPVersion	getNAPVersion

4.4.8 ObAccessException

When the Access Manager API methods detect problems, they throw an ObAccessException. The kind of error that has occurred is deducible from the enumerated list of C-family error message names beginning on "C-Family Status and Error Message Strings" . (The Java equivalents are on "Java Status and Error Message Fields" ).

Depending upon the particular error, zero to five substrings of data can be inserted into the exception message text provided in the ObAccessGate.msg catalog. (This insertion feature applies only to the C-family of implementations; the Java message strings must be handled as indivisible units).

For example, ObAccessException_ NOT_PROTECTED, error code 208, is defined as follows:

ObAccessException_NOT_PROTECTED {
      Unprotected resource %1 used in an
      ObAuthenticationScheme or ObUserSession
      constructor.}

If this error occurs while the application is processing an unprotected resource named xresource, the API builds an ObAccessException, whose structure contains the error code 208 and the text "xresource," which replaces the %1 substring.

C-family methods for this class allow you to extract the error code and the substring, by its index (1 to 5). You can also generate a string equal to the entire message with the substring(s) inserted. In the C++ environment, you should delete the ObAccessException that it catches.

By comparison, the Java implementation is limited, because it only supports the retrieval of entire messages. In other words, you cannot extract or otherwise manipulate substrings.

The C implementation of ObAccessException requires you to write an exception handler to trap errors. See "C-language Error Handlers" for a full discussion. Such an error handler is implemented in the sample program "Example of a Simple AccessGate Using C Psuedo Classes: access_test_c.cpp" .

4.4.8.1 Equivalent Methods

Table 4-15 lists equivalent methods across the four implementations of the ObAccessException class.

Table 4-15 Methods for the ObResourceRequest Class Compared

C++ (ObAccess Exception)	C (ObAccess Exception)	C# (ObAccess ExceptionMgd)	Java (ObResource Request)
getCode	ObAccessException_getCode	get_Code
getParameter	ObAccessException_getParameter	getParameter
toString	ObAccessException_toString	get_String
getCodeString	ObAccessException_getCodeString (now deprecated; see "C-language Error Handlers" .	getCodeString
(constructor)	Exception Handler (registered callback function)	(constructor)	(constructor)

4.5 Globalization and the Access Manager SDK, Access Manager APIs, Custom AccessGates

After installing the Access Manager SDK, you can use the Access Manager API to write custom AccessGate code in any of the four supported development languages: Java, C and C++, and C# (.NET). The four implementations are functionally equivalent even though each takes advantage of platform-specific features to implement the API.

While you can select any of the four implementations as the development language interface you use to write your custom AccessGate code, your code will interact with underlying C++ binaries in the API, as described in this guide.

When you develop custom AccessGates using the 10g (10.1.4.0.1) C and C++ Access Manager APIs, data is sent and received in UTF-8 encoding automatically. In older releases, data was sent and received in Latin-1 encoding.

For the 10g (10.1.4.0.1) C# (.NET) Managed Code implementation of the Access Manager API, there have been no external changes. The C# .NET implementation internally uses UTF-16 encoding, which was converted to Latin-1 in earlier NetPoint releases. 10g (10.1.4.0.1) Access Servers and C# AccessGates use UTF-8 encoding automatically.

For Java interfaces and the Java implementation of the Access Manager API, there have been no external changes for 10g (10.1.4.0.1). JNI calls use UTF-16 encoded Java string objects. Earlier NetPoint releases converted this data to Latin-1. 10g (10.1.4.0.1) Access Servers and AccessGates use UTF-8 encoding automatically.

Note:

The 10g (10.1.4.0.1) Access Manager SDK and custom 10g (10.1.4.0.1) AccessGates are not backward compatible with older Access Servers, nor with the older Access Manager SDK and AccessGates. However, you can use older AccessGates with 10g (10.1.4.0.1) Access Servers that are enabled to be backward compatible. See also the Oracle Access Manager Introduction.

4.6 About Custom AccessGate Code

The structure of a typical AccessGate application roughly mirrors the sequence of events required to set up an AccessGate session.

AccessGate application structure contains the following sections

1. Include or import requisite libraries

2. Get resource

3. Get authentication scheme

4. Gather user credentials required by authentication scheme

5. Create user session

6. Check user authorization for resource

7. Clean up (for C and C++ only: C# and Java use automatic garbage collection)

8. Shut down

4.6.1 Typical AccessGate Execution Flow

All HTTP FORM-based AccessGate applications and plug-ins follow the same basic pattern, as illustrated by the following figure. The figure shows a process flow for form-based applications:

• The main flow: import libraries, initialize the Access Server SDK, create ObResource Request object, determine if the requested resource is protected.

• If the requested resource is protected: Create an obAuthentication Scheme object. If the authentication scheme is HTTP FORm based: create a structure for user ID and password, create obUserSession object, determine if the user is authenticated.

• If the user is authenticated: determine if the user is authorized.

• If the user is authorized: grant access to the requested resource, shut down the API and end program.

  If the user is not authorized: deny access, report reason, shut down the API and end program.

• If the authentication scheme is not HTTP FORM based: deny access and report reason, shut down the API and end program.

  If the resource is not protected: grant access, shut down the API, and end program.

Note:

To run this test application, or any of the other examples, in this chapter, you must make sure that your Access System is installed and set up correctly. Specifically, check that it has been configured to protect resources that match exactly the URLs and authentication schemes expected by the sample programs. For details on creating policy domains and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.

4.6.2 Example of a Simple AccessGate: JAccessGate.java

This example is the simplest AccessGate program presented in this document. It illustrates how to implement the bare minimum tasks required for a working AccessGate:

• Connect to the Access Server

• Log in using an authentication scheme employing the HTTP FORM challenge method

• Check authorization for a certain resource using an HTTP GET request

• Catch and report Access Manager API exceptions

Typically, this calling sequence is quite similar among AccessGates using the FORM challenge method. FORM-method AccessGates differ principally in the credentials they require for authentication and the type of resources they protect.

A complete listing for JAccessGate.java appears in Example 4–1. You can copy this code verbatim into the text file JAccessGate.java and execute it on the machine where your Access Manager SDK is installed. The subsection that follows the listing annotates the code line-by-line so that developers can become familiar with the Java versions of the Access Manager API calls.

Example 4-1 JAccessGate.java

import java.io.*;
import java.util.*;
import java.text.*;
import com.oblix.access.*;
 
public class JAccessGate {
   public static final String ms_resource = "//Example.com:80/secrets/
         index.html";
   public static final String ms_protocol = "http";
   public static final String ms_method = "GET";
   public static final String ms_login = "jsmith";
   public static final String ms_passwd = "j5m1th";
   public static void main(String argv[]) {
      try {
         ObConfig.initialize();
         ObResourceRequest rrq = new ObResourceRequest(ms_protocol, ms_resource,
               ms_method);
         if (rrq.isProtected()) {
            System.out.println("Resource is protected.");
            ObAuthenticationScheme authnScheme = new ObAuthenticationScheme(rrq);
            if (authnScheme.isForm()) {
               System.out.println("Form Authentication Scheme.");
               Hashtable creds = new Hashtable();
               creds.put("userid", ms_login);
               creds.put("password", ms_passwd);
               ObUserSession session = new ObUserSession(rrq, creds);
               if (session.getStatus() == ObUserSession.LOGGEDIN) {
                  if (session.isAuthorized(rrq)) {
                     System.out.println("User is logged in and authorized for the
                           request at level " + session.getLevel());
                  } else {
                     System.out.println("User is logged in but NOT authorized");
                  }
               } else {
                  System.out.println("User is NOT logged in");
               }
            } else {
               System.out.println("non-Form Authentication Scheme.");
            }
         } else {
            System.out.println("Resource is NOT protected.");
         }
      }
      catch (ObAccessException oe) {
         System.out.println("Access Exception: " + oe.getMessage());
      }
      ObConfig.shutdown();
   }
}

4.6.2.1 Annotated Code

Import three standard Java libraries to provide system input and output, text handling, and other basic functions.

import java.io.*;
import java.util.*;
import java.text.*;

Import the library containing the Java implementation of the Access Manager API classes. To ensure that these libraries are visible, check that the CLASSPATH environment variable (for both UNIX and Windows platforms) points to the directory containing jobaccess.jar, which is installed by default in SDK_install_dir/oblix/lib.

import com.oblix.access.*;

This application is named JAccessGate.

public class JAccessGate {

Since this is the simplest of example applications, we are declaring global constants to represent the parameters associated with a user request for access to a resource.

Typically, a real-world application receives this set of parameters as an array of strings passed from a requesting application, HTTP FORM-based input, or command-line input.

public static final String ms_resource = "//Example.com:80/secrets/index.html";
   public static final String ms_protocol = "http";
   public static final String ms_method = "GET";
   public static final String ms_login = "jsmith";
   public static final String ms_passwd = "j5m1th";

Launch the main method on the Java interpreter. An array of strings named argv is passed to the main method. In this particular case, the user "jsmith," whose password is "j5m1th," has requested the HTTP resource //Example.com:80/secrets/index.html. GET is the specific HTTP operation that will be performed against the requested resource. For details about supported HTTP operations and protecting resources with policy domains chapter of the Oracle Access Manager Access Administration Guide.

public static void main(String argv[]) {

Place all relevant program statements in the main method within a large try block so that any exceptions will be caught by the catch block at the end of the program.

try {

Initialize the Access Manager SDK so that both the Com.Oblix.Access Java classes and the native JNI objects are available to the JAccessGate application. Since you do not specify the SDK installation root here, we use the value stored in the OBACCESS_INSTALL_DIR environment variable.

You only need to initialize the SDK once, but the initialization must occur before you attempt any calls to the Access Manager API.

ObConfig.initialize();

Create a new resource request object named "rrq" using the ObResourceRequest constructor with the following three parameters:

• ms_protocol, which represents the type of resource being requested. When left unspecified, the default value is HTTP. EJB is another possible value, although this particular example does not cover such a case. You can also create custom types, as described in the Oracle Access Manager Access Administration Guide.

• ms_resource, which is the name of the resource. Since the requested resource type for this particular example is HTTP, it is legal to prepend a host name and port number to the resource name, as in the following:

  //Example.com:80/secrets/index.html
  
  

• ms_method, which is the type of operation to be performed against the resource. When the resource type is HTTP, the possible operations are GET and POST. For EJB-type resources, the operation must be EXECUTE. For custom resource types, you define the permitted operations when you set up the resource type in the Access System Console. For more information on defining resource types and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.

ObResourceRequest rrq = new ObResourceRequest(ms_protocol,
   ms_resource, ms_method);

Determine whether the requested resource "rrq" is protected by an authentication scheme.

if (rrq.isProtected()) {

If the resource is protected, report that fact.

System.out.println("Resource is protected.");

Use the ObAuthenticationScheme constructor to create an authorization scheme object named authnScheme. Specify the resource request "rrq" so that ObAuthentication Scheme checks for the specific authorization scheme associated with that particular resource.

ObAuthenticationScheme authnScheme =new ObAuthenticationScheme(rrq);

Determine if the authorization scheme is FORM-based.

if (authnScheme.isForm()) {

If the authorization scheme does use HTTP FORM as the challenge method, report that fact, then create a hashtable named creds to hold the name:value pairs representing the user name (userid) and the user password (password). Read the values for "ms_login" and "ms_passwd" into the hashtable.

System.out.println("Form Authentication Scheme.");
Hashtable creds = new Hashtable();
creds.put("userid", ms_login);
creds.put("password", ms_passwd);

Using the ObUserSession constructor, create a user session object named session. Specify the resource request as "rrq" and the authentication scheme as "creds" so that ObUserSession can return the new structure with state information as to whether the authentication attempt has succeeded.

ObUserSession session = new ObUserSession(rrq, creds);

Invoke the getStatus method on the ObUserSession state information to determine if the user is now successfully logged in (authenticated).

if (session.getStatus() == ObUserSession.LOGGEDIN) {

If the user is authenticated, determine if the user is authorized to access the resource specified through the resource request structure "rrq."

if (session.isAuthorized(rrq)) {
  System.out.println(
    "User is logged in " +
    "and authorized for the request " +

Determine the authorization level returned by the getLevel method for the user session named "session."

"at level " + session.getLevel());

If the user is not authorized for the resource specified in "rrq," then report that the user is authenticated but not authorized to access the requested resource.

} else {
  System.out.println("User is logged in but NOT authorized");

If the user is not authenticated, report that fact. (A real world application might give the user additional chances to authenticate).

} else {
  System.out.println("User is NOT logged in");

If the authentication scheme does not use an HTTP FORM-based challenge method, report that fact. At this point, a real-world application might branch to facilitate whatever other challenge method the authorization scheme specifies, such as "basic" (which requires only userid and password), "certificate" (SSL or TLS over HTTPS), or "secure" (HTTPS through a redirection URL). For more information about challenge Methods and configuring user authentication, see the Oracle Access Manager Access Administration Guide.

} else {
  System.out.println("non-Form Authentication Scheme.");
}

If the resource is not protected, report that fact. (By implication, the user gains access to the requested resource, because the AccessGate makes no further attempt to protect the resource).

} else {
  System.out.println("Resource is NOT protected.");
}
}

If an error occurs anywhere within the preceding try block, get the associated text message "oe" and report it.

catch (ObAccessException oe) {
  System.out.println(
  "Access Exception: " + oe.getMessage());
}

Now that the program is finished calling the Access Server, shut down the API, thus releasing any memory the API might have maintained between calls.

ObConfig.shutdown();
}
}

Exit the program. You don't have to deallocate the memory used by the structures created by this application because Java Garbage Collection automatically cleans up unused structures when it determines that they are no longer needed.

4.6.3 Example of a Simple AccessGate Using C Psuedo Classes: access_test_c.cpp

This sample demonstrates the use of C-language pseudo classes to implement a simple AccessGate. The member functions of these classes are really wrapped pointers that call C++ code.

Exception handling is performed by a callback function that is registered with the SDK before it is initialized. This error handling function is called from within SDK methods when an error condition needs to be reported. In this example, the error handler simply prints out the error message associated with the error code returned, then shuts down the program.

The complete listing for access_test_c.exe appears in Example 4–2. You can cut-and-paste the code into a text file with the ".cpp" file name extension and then generate executable code using a compiler appropriate for C-language programs on the server platform where your AccessGate will reside. The subsection that follows the listing annotates this code sample.

Example 4-2 access_test_c.cpp

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <obaccess_api_c.h>
 
void myExceptionHandler(ObAccessExceptionCode_t code) {
   printf("EXCEPTION: %s\n", ObAccessException_getCodeString(code));
   exit(1);
}
 
int main(int argc, char *argv[]) { 
   const char *userid, *password, *method, *url, *location; 
   ObResourceRequest_t res; 
   ObAuthnScheme_t authnScheme; 
   ObMap_t credentials; 
   ObUserSession_t user; 
   ObMap_t actions;
   ObMap_t parameters;
   ObMap_t requiredParameters;
   ObMapIterator_t iter;
   const char **actionTypes;
   const char *name, *val;
   int i;
   if (argc < 5 || argc > 7) { 
      printf("EXPECTED: userid password HTTP-method URL(without http:)
            [client-location [authz-parameters]]\n"); 
      return 1; 
   } 
   userid   = argv[1]; 
   password = argv[2]; 
   method   = argv[3]; 
   url      = argv[4];
   location = argc >= 6 ? argv[5] : NULL;
   if (argc == 7) {
      parameters = ObMap_new();
      for (name = strtok(argv[6], "="); name != NULL; name = strtok(NULL, "=")) {
         val = strtok(NULL, "&");
         ObMap_put(parameters, name, val);
      }
   } else {
      parameters = NULL;
   }
   ObAccessException_setHandler(myExceptionHandler);
   ObConfig_initialize(NULL);
   res = ObResourceRequest_new("http", url, method, NULL); 
   if (ObResource_isProtected(res)) { 
      authnScheme = ObAuthn_new(res); 
      if (ObAuthn_isBasic(authnScheme)) { 
         credentials = ObMap_new(); 
         ObMap_put(credentials, "userid",   userid); 
         ObMap_put(credentials, "password", password); 
         user = ObUserSession_authenticate(res, credentials, NULL); 
         if (ObUser_getStatus(user) == ObUser_LOGGEDIN) { 
            ObUser_setLocation(user, location); 
            if (parameters != NULL 
                     ? ObUser_isAuthorizedWithParameters(user, res, parameters) 
                     : ObUser_isAuthorized(user, res)) { 
               printf("GRANTED\n"); 
            } else { 
               printf("DENIED\n"); 
               printf("ERROR: %s\n", ObUser_getErrorMessage(user)); 
               if (ObUser_getError(user) == ObUser_ERR_NEED_MORE_DATA) { 
                  requiredParameters = ObResource_getAuthorizationParameters(res); 
                  printf("REQUIRED PARAMETERS:"); 
                  iter = ObMapIterator_new(requiredParameters); 
                  while (ObMapIterator_hasMore(iter)) { 
                     ObMapIterator_next(iter, &name, &val); 
                     printf(" "); 
                     printf(name); 
                  } 
                  printf("\n"); 
                  ObMapIterator_free(&iter); 
                  ObMap_free(&requiredParameters); 
               }
            }
         if (parameters != NULL) ObMap_free(&parameters); 
         printf("ACTIONS:"); 
         actionTypes = ObUser_getActionTypes(user); 
         for (i = 0; actionTypes[i] != NULL; i++) { 
            actions = ObUser_getActions(user, actionTypes[i]); 
            iter    = ObMapIterator_new(actions); 
            while (ObMapIterator_hasMore(iter)) { 
               printf("\n");
               ObMapIterator_next(iter, &name, &val); 
               printf("%s: %s=%s", actionTypes[i], name, val); 
            }
            ObMapIterator_free(&iter); 
         }
         ObUser_logoff(user); 
         } else { 
            const char *errmsg; 
            errmsg = ObUser_getErrorMessage(user); 
            printf("LOGIN FAILED: %s", errmsg); 
         } 
         ObUser_free(&user); 
         ObMap_free(&credentials); 
      } else { 
         printf("RESOURCE SCHEME NOT BASIC"); 
      }
      ObAuthn_free(&authnScheme);    } else {       printf("NOT PROTECTED");    }    ObResource_free(&res);    ObConfig_shutdown();    return 0; }

4.6.3.1 Annotated Code

Import three standard C libraries to support input and output, string manipulation, and other basic functionality.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

Import the C implementation of the Access Manager API.

#include <obaccess_api_c.h>

Set up an exception handler, which responds to an error by reporting the associated error message, then terminating the program.

void myExceptionHandler(ObAccessExceptionCode_t code) {
   printf("EXCEPTION: %s\n", ObAccessException_getCodeString(code));
   exit(1);
}

Declare the requisite variables and constants for the main method. Argc represents the total number of strings in the space-delimited array argv. The first string in argv is always the name of the program, access_test_c.exe.

int main(int argc, char *argv[]) { 
   const char *userid, *password, *method, *url, *location; 
   ObResourceRequest_t res; 
   ObAuthnScheme_t authnScheme; 
   ObMap_t credentials; 
   ObUserSession_t user; 
   ObMap_t actions;
   ObMap_t parameters;
   ObMap_t requiredParameters;
   ObMapIterator_t iter;
   const char **actionTypes;
   const char *name, *val;
   int i;

If the command-line input contains fewer that 5 or more than 7 strings, tell the user what information needs to be entered from the command line, and in what order.

if (argc < 5 || argc > 7) { 
      printf("EXPECTED: userid password HTTP-method URL(without http:) 
            [client-location [authz-parameters]]\n"); 
      return 1; 
   } 

If the command-line input contains 5 to 7 strings, assign the second through fifth strings (argv[1]-arg[4]) to the variables "userid," "password," "method," and "url," respectively.

userid   = argv[1]; 
   password = argv[2]; 
   method   = argv[3]; 
   url      = argv[4];

If six or more strings exist in the array received from command-line input, assign the sixth argument to the variable "location." Otherwise, set "location" to NULL.

location = argc >= 6 ? argv[5] : NULL;

If the command-line input array contains exactly 7 strings, create a new ObMap list structure and name it "parameters."

if (argc == 7) {
   parameters = ObMap_new();

By convention, the seventh string (argv[6]) takes the form "n1=v1&n2=v2..." We invoke the "strtok" method to break this string into name:value token pairs and read them into the list "parameters." The opening delimiter for each token is always NULL, because "strtok" considers the beginning of any string it parses to be NULL. Furthermore, after "strtok" finds the concluding delimiter for a token and returns the characters that compose the token, it sets everything prior to and including the concluding delimiter to NULL. Thus, the opening delimiter for every token is always NULL.

The concluding delimiter, on the other hand, changes from "=" to "&" and back again as "strtok" parses the name and value for successive parameters in the string.

for (name = strtok(argv[6], "="); name != NULL; name = strtok(NULL, "=")) {
         val = strtok(NULL, "&");
         ObMap_put(parameters, name, val);
      }

If only 5 or 6 arguments exist in "argv," set "parameters" to NULL.

} else {
      parameters = NULL;
   }

Register the callback function "myExceptionHandler" with the Access Manager SDK.

ObAccessException_setHandler(myExceptionHandler);

Initialize the AccessGate without specifying the directory in which the Access Manager API SDK is installed. Since no location is specified here, the operating system uses the value stored in the environment variable OBACCESS_INSTALL_ DIR.

ObConfig_initialize(NULL);

Create an ObResourceRequest structure that specifies the following:

• The resource type is HTTP.

• The target resource is the value stored in "url".

• The operation to be performed against the resource is the value stored in "method".

• The parameters required for authorization are NULL.

res = ObResourceRequest_new("http", url, method, NULL);

If the requested resource is protected, create an ObAuthn structure named "authnScheme" to return information on the specific authorization scheme used to protect the resource.

if (ObResource_isProtected(res)) {
  authnScheme = ObAuthn_new(res);

If the authorization scheme is "basic," create an ObMap structure and read into it the values for "userid" and "password" that represent the user credentials.

if (ObAuthn_isBasic(authnScheme)) { 
  credentials = ObMap_new(); 
  ObMap_put(credentials, "userid",   userid); 
  ObMap_put(credentials, "password", password); 

Invoke the "ObUserSession_authenticate" method for the specified resource request and the supplied userid and password.

user = ObUserSession_authenticate(res, credentials, NULL);

If the user is logged in, which is to say, the user has authenticated successfully, assign the value stored in "location" as the IP address of the user's machine.

if (ObUser_getStatus(user) == ObUser_LOGGEDIN) {
    ObUser_setLocation(user, location);

If the structure "parameters" is not empty, then determine whether the user is authorized to access the target resource under the parameters specified by "parameters." Otherwise, determine whether the user is authorized to access the target resource without any parameters attached.

if (parameters != NULL 
         ? ObUser_isAuthorizedWithParameters(user, res, parameters) 
         : ObUser_isAuthorized(user, res)) { 

If the user is authorized to access the target resource, report that fact.

printf("GRANTED\n");

Otherwise, report that the request has been denied, and report the associated error message as well.

If the error code returned is ObUser_ERR_NEED_MORE_DATA, report the names of all the parameters needed for authorization. Do this by creating an ObMapIterator structure named "requiredParameters" and then reporting the names of all the required parameters (but not the corresponding values that the user must supply!)

} else { 
   printf("DENIED\n"); 
   printf("ERROR: %s\n", ObUser_getErrorMessage(user)); 

Note:

The access policy for the resource requires authorization parameters that were not supplied in the original ObUser_isAuthorized call. This happens when the authorization rule for the policy uses an authorization scheme with an authorization plug-in that requires parameters. See Chapter 5, "Policy Manager API".

if (ObUser_getError(user) == ObUser_ERR_NEED_MORE_DATA) { 
   requiredParameters = ObResource_getAuthorizationParameters(res); 
   printf("REQUIRED PARAMETERS:"); 
   iter = ObMapIterator_new(requiredParameters); 
   while (ObMapIterator_hasMore(iter)) { 
      ObMapIterator_next(iter, &name, &val); 
      printf(" "); 
      printf(name); 
   } 

Clean up by destroying both the requiredParameters structure and the iterator iter, which is used to extract name strings from requiredParameters.

printf("\n"); 
      ObMapIterator_free(&iter); 
      ObMap_free(&requiredParameters); 
   }
}

If "parameters" is not empty, deallocate the memory used by the structure.

if (parameters != NULL) ObMap_free(&parameters);

Report all the actions defined by the authentication and authorization rules for the policy that applies to the resource. These can be any sequence of the form type:name:value:value:type. ObUser_getActionTypes returns an array of the action types (such as headerVar) present in the sequence of actions. ObUser_getActions returns an ObMap structure of the actions for each action type in turn. "iter" steps through each action in each ObMap structure.

printf("ACTIONS:"); 
actionTypes = ObUser_getActionTypes(user); 
for (i = 0; actionTypes[i] != NULL; i++) { 
   actions = ObUser_getActions(user, actionTypes[i]); 
   iter    = ObMapIterator_new(actions); 
   while (ObMapIterator_hasMore(iter)) { 
      printf("\n");
      ObMapIterator_next(iter, &name, &val); 
      printf("%s: %s=%s", actionTypes[i], name, val); 
   }

Destroy the string "iter" used to extract the information from the ObMapIterator structure "actions."

ObMapIterator_free(&iter);

Set the local ObUserSession structure to the logged off state.

Note:

To prevent residual session tokens (such as those stored in cookies on the user's browser) from being used to recreate the session, you must explicitly reset them using the logged off user session.

}
ObUser_logoff(user);

Otherwise, report that authentication has failed, and report the associated error message as well.

} else { 
   const char *errmsg; 
   errmsg = ObUser_getErrorMessage(user); 
   printf("LOGIN FAILED: %s", errmsg); 
} 

Clean up by deallocating the memory for the ObUser and ObMap structures named "user" and "credentials," respectively.

ObUser_free(&user);
ObMap_free(&credentials);

If the authentication scheme is not basic, report that fact.

} else {
    printf("RESOURCE SCHEME NOT BASIC");
}

Clean up by deallocating the memory used by the ObAuthn structure named authnScheme.

ObAuthn_free(&authnScheme);

If the requested resource is not protected, report that fact.

} else {
    printf("NOT PROTECTED");
}

Clean up by deallocating the memory used by the ObResourceRequest structure named "res." Then shutdown the AccessGate, returning 0 to indicate successful completion.

ObResource_free(&res);
   ObConfig_shutdown();
   return 0;
}

Exit the program.

4.6.4 Example: Java Login Servlet

This example follows the basic pattern of API calls that define an AccessGate, as described in the JAccessGate example. However, this example is implemented as a Java servlet running within a Web server, or even an application server. In this environment, the AccessGate servlet has an opportunity to play an even more important role for the user of a Web application. By storing an Access System session token in the user's HTTP session, the servlet can facilitate single sign-on for the user. In other words, the authenticated Access Server session information that the first request establishes is not discarded after one authorization check. Instead, the stored session token is made available to server-side application components such as beans and other servlets, so that they do not need to interrupt the user again and again to request the same credentials. For a detailed discussion of session tokens, ObSSOCookies, and configuring single sign-on, see the Oracle Access Manager Access Administration Guide.

This sample login servlet accepts userid/password parameters from a form on a custom login page, and attempts to log the user in to Oracle Access Manager. On successful login, the servlet stores a session token in the ObUserSession object. This enables subsequent requests in the same HTTP session to bypass the authentication step (providing the subsequent requests use the same authentication scheme as the original request), thereby achieving single sign-on.

Example 4–3 shows a complete listing for the Java login servlet. This code can provide the basis for a plug-in to a web server or application server. An annotated version of this code is given after this code sample.

Example 4-3 Java LoginServlet Example.

package obaccess;
 
import java.io.*;
import java.util.*;
import java.text.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.IOException;
import java.util.*;
import com.oblix.access.*;
 
public class LoginServlet extends HttpServlet {
 
   public void init(ServletConfig config) throws ServletException {
      try {
         ObConfig.initialize("install directory of access server sdk");
      } catch (ObAccessException oe) {
         oe.printStackTrace();
      }
   }
 
   public void service(HttpServletRequest request, HttpServletResponse response)
            throws IOException, ServletException {
      ObAuthenticationScheme authnScheme = null;
      ObUserSession user = null;
      ObResourceRequest resource = null;
       response.setContentType("text/html");
      PrintWriter out = response.getWriter(); 
      out.println("<HTML>");
      out.println("<HEAD><TITLE>LoginServlet: Error Page</TITLE></HEAD>");
      out.println("<BODY>");
      HttpSession session = request.getSession( false);
      String requestedPage = request.getParameter(Constants.REQUEST);
      String reqMethod = request.getMethod();
      Hashtable cred = new Hashtable();
      try {
         if (requestedPage == null) {
            out.println("<p>REQUESTED PAGE NOT SPECIFIED\n");
            out.println("</BODY></HTML>");
            return;
         }
         resource = new ObResourceRequest("http", requestedPage, "GET");
         if (resource.isProtected()) {
            authnScheme = new ObAuthenticationScheme(resource);
            if (authnScheme.isBasic()) {
               if (session == null) {
                  String sUserName = request.getParameter( Constants.USERNAME);
                  String sPassword = request.getParameter( Constants.PASSWORD);
                  if (sUserName != null) {
                     cred.put("userid", sUserName);
                     cred.put("password", sPassword);
                     user = new ObUserSession(resource, cred);
                     if (user.getStatus() == ObUserSession.LOGGEDIN) {
                        if (user.isAuthorized(resource)) {
                           session = request.getSession( true);
                           session.putValue( Constants.OBUSER, user);
                           response.sendRedirect( requestedPage );
                        } else {
                           out.println("<p>User " + sUserName + " not
                                 authorized for " + requestedPage + "\n");
                        }
                     } else {
                        out.println("<p>User" + sUserName + "NOT LOGGED IN\n");
                     }
                  } else {
                     out.println("<p>USERNAME PARAM REQUIRED\n");
                  }
               } else {
                  user = (ObUserSession)session.getValue(Constants.OBUSER);
                  if (user.getStatus() == ObUserSession.LOGGEDIN) {
                     out.println("<p>User " + user.getUserIdentity() + " already
                           LOGGEDIN\n");
                  }
               }
            } else {
               out.println("<p>Resource Page" + requestedPage + " is not
                     protected with BASIC\n");
            }
         } else {
            out.println("<p>Page " + requestedPage + " is not protected\n");
         } 
      } catch (ObAccessException oe) {
            oe.printStackTrace();
      }
   out.println("</BODY></HTML>");
   }
}

4.6.4.1 Annotated Code

All the classes defined in this listing belong to the package named "obaccess."

package obaccess;

Import three standard Java packages to support input and output, text manipulation, and basic functionality.

import java.io.*;
import java.util.*;
import java.text.*;

Import two packages of Java extensions to provide servlet-related functionality.

import javax.servlet.*;
import javax.servlet.http.*;

Import a standard Java package to handle exceptions.

import java.io.IOException;

Import the package com.oblix.access.jar, which is the Java implementation of the Access Manager API.

import com.oblix.access.*;

This servlet, which builds on the functionality of the generic HttpServlet supported by the Java Enterprise Edition, is named LoginServlet.

public class LoginServlet extends HttpServlet {

The "init" method is called once by the servlet engine to initialize the AccessGate. In the case of initialization failure, report that fact, along with the appropriate error message.

public void init() { 
      ObConfig.initialize(Òinstall directory of the access server sdkÓ); 
   } catch (ObAccessException oe) { 
         oe.printStackTrace(); 
   } 
} 

Invoke the javax.servlet.service method to process the user's resource request.

public void service(HttpServletRequest request, HttpServletResponse response)
  throws IOException, ServletException {

Initialize as NULL the variables that store the ObAccess structures used to process the resource request, then set the response type used by this application to "text/html."

ObAuthenticationScheme authnScheme = null;
ObUserSession user = null;
ObResourceRequest resource = null;
response.setContentType("text/html");

Open an output stream titled "LoginServlet: Error Page" and direct it to the user's browser.

PrintWriter out = response.getWriter();
out.println("<HTML>");
out.println("<HEAD><TITLE>LoginServlet: Error Page</TITLE></HEAD>");
out.println("<BODY>");

Determine if a session already exists for this user. Invoke the getSession method with "false" as a parameter, so the value of the existing servlet session (and not the ObUserSession) will be returned if it is present; otherwise, NULL will be returned.

HttpSession session = request.getSession(false);

Retrieve the name of the target resource, assign it to the variable requestedPage, then retrieve the name of the HTTP method (such as GET, POST, or PUT) with which the request was made and assign it to the variable reqMethod.

String requestedPage = request.getParameter(Constants.REQUEST);
String reqMethod = request.getMethod();

Create a hashtable named "cred" to hold the user's credentials.

Hashtable cred = new Hashtable();

If the variable requestedPage is returned empty, report that the name of the target resource has not been properly specified, then terminate the servlet.

try { 
   if (requestedPage == null) { 
out.println("<p>REQUESTED PAGE NOT SPECIFIED\n"); 
out.println("</BODY></HTML>"); 
return; 
   } 

If the name of the requested page is returned, create an ObResourceRequest structure and set the following:

• The resource type is HTTP

• The HTTP method is GET

• "resource" is the value stored by the variable requestedPage

resource = new ObResourceRequest("http", requestedPage, "GET");

If the target resource is protected, create an ObAuthenticationScheme structure for the resource request and name it authnScheme.

if (resource.isProtected()) {
   authnScheme = new ObAuthenticationScheme(resource);

If the authentication scheme associated with the target resource is HTTP "basic" and no user session currently exists, invoke javax.servlet.servletrequest. getParameter to return the user's credentials (user name and password) and assign them to the variables sUserName and sPassword, respectively.

Note:

For the authnScheme.isBasic call in the following statement to work properly, the user name and password must be included in the query string of the user's HTTP request, as in the following:

http://host.example.com/resource?username=bob&userpassword=bobspassword

where resource is the resource being requested, bob is the user making the request, and bobspassword is the user's password.

Note:

If you substitute authnScheme.isForm for authnScheme.isBasic, you need to write additional code to implement the following steps.

Additional Code for authnScheme.isForm will

1. Process the original request and determine that form-based login is required.

2. Send a 302 redirect response for the login form and also save the original resource information in the HTTP session.

3. Authenticate the user by processing the posted form data with the user's name and password.

4. Retrieve the original resource from the HTTP resource and send a 302 redirect response for the original resource.

5. Process the original request once again, this time using the ObUserSession stored in the HTTP session.

if (authnScheme.isBasic()) { 
   if (session == null) { 
      String sUserName = request.getParameter(Constants.USERNAME); 
      String sPassword = request.getParameter(Constants.PASSWORD); 

If the user name exists, read it, along with the associated password, into the hashtable named "cred."

if (sUserName != null) {
   cred.put("userid", sUserName);
   cred.put("password", sPassword);

Create a user session based on the information in the ObResourceRequest structure named "resource" and the hashtable "cred."

user = new ObUserSession(resource, cred);

If the status code for the user returns as LOGGEDIN, that user has authenticated successfully.

if (user.getStatus() == ObUserSession.LOGGEDIN) {

Determine if the user is authorized to access the target resource.

if (user.isAuthorized(resource)) {

Create a servlet user session (which is not to be confused with an ObUserSession) and add the name of the user to it.

session = request.getSession( true);
session.putValue( Constants.OBUSER, user);

Redirect the user's browser to the target page.

response.sendRedirect(requestedPage);

If the user is not authorized to access the target resource, report that fact.

} else {
    out.println("<p>User " + sUserName + " not authorized
      for " + requestedPage + "\n");
 }

If the user is not properly authenticated, report that fact.

} else {
    out.println("<p>User" + sUserName + "NOT LOGGED IN\n");
}

If the user name has not been supplied, report that fact.

} else {
out.println("<p>USERNAME PARAM REQUIRED\n");
}

If a session already exists, retrieve OBUSER and assign it to the session variable "user."

} else {
    user = (ObUserSession)session.getValue(Constants.OBUSER);

If the user is logged in, which is to say, the user has authenticated successfully, report that fact along with the user's name.

if (user.getStatus() == ObUserSession.LOGGEDIN) { 
      out.println("<p>User " + user.getUserIdentity() + " already 
      LOGGEDIN\n"); 
 }
}

If the target resource is not protected by a "basic" authentication scheme, report that fact.

} else {
   out.println("<p>Resource Page" + requestedPage + " is not protected
         with BASIC\n");
}

If the target resource is not protected by any authentication scheme, report that fact.

} else {
   out.println("<p>Page " + requestedPage + " is not protected\n");
} 

If an error occurs, report the backtrace.

} catch (ObAccessException oe) {
   oe.printStackTrace();
}

Complete the output stream to the user's browser.

out.println("</BODY></HTML>");
  }
}

4.6.5 Example Using the C# API: access_api_test.cs

This sample program demonstrates the C# (.NET managed code) API.

Process overview: Sample program

1. Initializes the system

   Note:

   Before you run this program on either a Windows or UNIX, make sure the environment variable OBACCESS_INSTALL_DIR is defined to point to SDK_install_dir.

2. Creates a resource request and determines if the target resource is protected.

3. Checks whether authentication for this resource is "basic."

4. Logs in the user named cuser10k429, as defined in the Oracle Access Manager user directory.

   Note:

   Change the name of the user and other particulars to match a valid entry in your Oracle Access Manager user directory.

5. Verifies that the user is logged in.

6. Checks if the user is authorized to access the target resource.

7. Obtains the identity of the user and the location of the user's machine.

The following line represents typical command-line input for this program:

access_api_test //www.example.com:88/managed

For specifics on compiling, linking, and running this .NET program, consult the following file:

SDK_install_dir\samples\access_csharp\README.txt

Example 4–4 shows a complete listing for Access_API_Test, with an annotated code section following the listing.

Example 4-4 Access_API_Test

using System;
using System.Reflection;
using System.Collections;
using Oblix.Access.Server;
using Oblix.Access.Common;
 
class Access_API_Test {
  public static int Main(string[] args) {
    String resourceString = "//www.oblix.com:80/managed";
    if ( args.Length > 0 )resourceString = args[0];
    Console.WriteLine("Initialize the configuration directory!");
    try {
      String config = "../../../../";
      ObConfigMgd.initialize(config);
    } catch (ObAccessExceptionMgd ex) {
      Console.WriteLine("Initialization Exception caught: " + ex.String);
      return -1;
    }
    ObDictionary parameters = new ObDictionary();
    ObResourceRequestMgd resource = new
        ObResourceRequestMgd("http",resourceString,"GET",parameters);
    if ( resource.IsProtected == true ) {
      Console.WriteLine("Resource " + resourceString + " is protected ..." );
      try {
        ObAuthenticationSchemeMgd authnScheme = new
            ObAuthenticationSchemeMgd(resource);
        if ( authnScheme.IsBasic ) {
          Console.WriteLine("Authentication is basic" );
          ObDictionary credentials = new ObDictionary();
          credentials.Add("userid","cuser10k429");
          credentials.Add("password","oblix");
          ObUserSessionMgd user = new ObUserSessionMgd(resource,credentials);
          ObUserStatusMgd status = user.Status;
          if ( !status.IsLoggedIn ) {
            Console.WriteLine("User is not logged in");
            return -1;
          }
          user.Location = "127.0.0.1";
          Console.WriteLine("User: " + user.UserIdentity + " is logged
              in...");
          Console.WriteLine("User location is: " + user.Location);
          if ( user.IsAuthorized(resource) ) {
            Console.WriteLine("User is authorized");
          } else {
            Console.WriteLine("User is not authorized");
          }
        } else {
          Console.WriteLine("Authentication is not basic" );
        }
      } catch (ObAccessExceptionMgd ex) {
        Console.WriteLine("Access Exception caught: " + ex.String);
        return -1;
      }
    } else {
      Console.WriteLine("Resource is NOT protected ... " );
    }
    return 1;
  }

4.6.5.1 Annotated Code

Import three .NET framework libraries to provide type management for loaded methods, support for lists and hashtables, and basic functionality.

using System;
using System.Reflection;
using System.Collections;

Import the C# implementation of the Access Manager API, which resides in a main library as well as a shared library for code used in common with the Policy Manager API.

using Oblix.Access.Server;
using Oblix.Access.Common;

This program is named Access_API_Test.cs.

class Access_API_Test {
   public static int Main(string[] args) {

This program does not retrieve user input from forms or session tokens. For convenience, we simply assign sample values to the parameters associated with the methods being demonstrated.

String resourceString = "//www.example.com:80/managed";

The C# application expects a maximum of one argument in the command line. If the array "args" contains one or more arguments, assign the first string in "args" to the variable resourceString, thus replacing the URL string we just assigned to it. If there are no arguments, go ahead and use the string we assigned to resourceString in the previous statement.

if ( args.Length > 0 )resourceString = args[0];
Console.WriteLine("Initialize the configuration directory!");
try {
  String config = "../../../../";
  ObConfigMgd.initialize(config);

If initialization fails, report that fact, along with the associated error message, then return a value of "-1," effectively terminating the program. (In this particular C# program, execution failure returns "-1." By contrast, the C++ sample "access_test_c" returns a "1" when execution fails and "0" when execution completes successfully.)

} catch (ObAccessExceptionMgd ex) {
..Console.WriteLine("Initialization Exception caught: " + ex.String);
..return -1;
}

Create an ObDictionary structure named "parameters" to hold the user's credentials.

ObDictionary parameters = new ObDictionary();

Create a resource request object, specifying parameters to accomplish the following:

• Set HTTP as the resource type

• Designate the URL previously assigned to "resourceString" as the target resource

• Specify GET as the action to be performed against the resource

• Store the parameters required for authentication in the ObDictionary structure "parameters"

ObResourceRequestMgd resource = new
   ObResourceRequestMgd("http",resourceString,"GET",parameters);

Determine whether the target resource is protected, and if it is, report that fact.

if ( resource.IsProtected == true ) {
   Console.WriteLine("Resource " + resourceString + " is protected ..." );

Create an object to return information about the authentication scheme associated with the requested resource.

try {
   ObAuthenticationSchemeMgd authnScheme = new
      ObAuthenticationSchemeMgd(resource);

If the authentication scheme is "basic," report that fact.

if ( authnScheme.IsBasic ) {
   Console.WriteLine("Authentication is basic" );

Create an ObDictionary structure named "credentials" to store the user's login credentials. In this test application, the userid and password are supplied within the source code; in a real-world application, these would be retrieved from keyboard input or a session token.

ObDictionary credentials = new ObDictionary();
credentials.Add("userid","cuser10k429");
credentials.Add("password","oblix");

Create a ObUserSessionMgd structure to store information about the current user, the resource requested, and the authentication scheme associated with that resource.

ObUserSessionMgd user = new ObUserSessionMgd(resource,credentials);
ObUserStatusMgd status = user.Status;

If the user is not logged in (in other words, the user has not authenticated successfully), report that fact and return -1, effectively terminating the program.

if (!status.IsLoggedIn) {
   Console.WriteLine("User is not logged in");
   return -1;
}

Set the IP of the user's machine to "127.0.0.1." If this were a real-life application, we would retrieve this location from keyboard input or the session token.

user.Location = "127.0.0.1";

Report that the user is logged in, then report the IP of the user's browser.

Console.WriteLine("User: " + user.UserIdentity + " is logged
   in...");
Console.WriteLine("User location is: " + user.Location);

Report whether or not the user is authorized to access the specified resource.

if ( user.IsAuthorized(resource) ) {
  Console.WriteLine("User is authorized");
} else {
  Console.WriteLine("User is not authorized");
}

If the authentication scheme associated with the requested resource is not basic, report that fact.

} else {
   Console.WriteLine("Authentication is not basic" );
}

If an execution error occurs, report the associated error message, then return "-1," effectively terminating the program.

} catch (ObAccessExceptionMgd ex) {
   Console.WriteLine("Access Exception caught: " + ex.String);
   return -1;
}

If the resource is not protected, report that fact and return "1," thus terminating the program after indicating successful execution.

} else {
      Console.WriteLine("Resource is NOT protected ... " );
    }
    return 1;
  }
}

4.6.6 Example Using Additional Methods: access_test_java.java

Building on the basic pattern established in the sample application "JAccessGate.java," the following sample program invokes several additional Access Server methods. For instance, it inspects the Access System session object to determine which actions are currently configured in the policy rules associated with the current authentication scheme.

For this demonstration to take place, you must configure some actions through the Access System console prior to running the application. For details about authentication action and configuring user authentication, see the Oracle Access Manager Access Administration Guide. The complete listing for this sample application appears in Example 4–5 and also in the file access_test_java.java, which is located in the directory SDK_install_dir\Samples. An annotated version of the code begins after this listing.

Example 4-5 access_test_java.java

import java.util.*;
import java.util.Enumeration;
import java.util.StringTokenizer;
import com.oblix.access.*;
 
public class access_test_java {
 
  public static void main(String[] arg) {
    String userid, password, method, url, configDir, type, location;
    ObResourceRequest res;
    Hashtable parameters = null;
    Hashtable cred = new Hashtable();
    if (arg.length < 5) {
      System.out.println("Usage: EXPECTED: userid password Type HTTP-method
          URL [Installdir [authz-parameters] [location]]]");
      return;
    } else {
      userid    = arg[0];
      password  = arg[1];
      type      = arg[2];
      method    = arg[3];
      url      = arg[4];
    }
    if (arg.length >= 6) {
      configDir = arg[5];
    } else {
      configDir = null;
    }
    if (arg.length >= 7 && arg[6] != null) {
      parameters = new Hashtable();
      StringTokenizer tok1 = new StringTokenizer(arg[6], "&");
      while (tok1.hasMoreTokens()) {
        String nameValue = tok1.nextToken();
        StringTokenizer tok2 = new StringTokenizer(nameValue, "=");
        String name = tok2.nextToken();
        String value = tok2.hasMoreTokens() ? tok2.nextToken() : "";
        parameters.put(name, value);
      }
    }
    location = arg.length >= 8 ? arg[7] : null;
    try {
      if (configDir != null) {
        ObConfig.initialize(configDir);
      } else {
        ObConfig.initialize();
      }
    } catch (ObAccessException ie) {
      System.out.println("Access Server SDK Initialization failed");
      ie.printStackTrace();
      return;
    }
    cred.put("userid", userid);
    cred.put("password", password);
    try {
      res = new ObResourceRequest(type, url, method);
      if (res.isProtected()) {
        System.out.println("Resource " + type + ":" + url + " protected"); 
      } else {
        System.out.println("Resource " + type + ":" + url + " unprotected");
      }
    } catch (Throwable t) {
      t.printStackTrace();
      System.out.println("Failed to created new resource request");
      return;
    }
    ObUserSession user = null;
    try {
      user = new ObUserSession(res, cred);
    } catch (Throwable t) {
      t.printStackTrace();
      System.out.println("Failed to create new user session");
      return;
    }
    if (user.getStatus() == ObUserSession.LOGGEDIN) {
      if (location != null) user.setLocation(location);
      System.out.println("user status is " + user.getStatus());
      try {
        if (parameters != null ? user.isAuthorized(res, parameters) :
              user.isAuthorized(res)) {
          System.out.println("Permission GRANTED");
          System.out.println("User Session Token =" +
              user.getSessionToken());
          if (location != null) {
            System.out.println("Location = " + user.getLocation());
          } 
        } else {
          System.out.println("Permission DENIED");
          if (user.getError() == ObUserSession.ERR_NEED_MORE_DATA) {
            int nParams = res.getNumberOfAuthorizationParameters();
            System.out.print("Required Authorization Parameters (" + 
                nParams + ") :");
            Enumeration e = res.getAuthorizationParameters().keys();
            while (e.hasMoreElements()) {
              String name = (String) e.nextElement();
              System.out.print(" " + name);
            }
            System.out.println();
          }
        }
      } catch (ObAccessException obe) {        System.out.println("Failed to get user authorization");      }    } else {      System.out.println("user status is " + user.getStatus());    }    String[] actionTypes = user.getActionTypes();    for(int i =0; i < actionTypes.length; i++) {      Hashtable actions = user.getActions(actionTypes[i]);      Enumeration e = actions.keys();      int item = 0;      System.out.println("Printing Actions for type " + actionTypes[i]);      while(e.hasMoreElements()) {        String name = (String)e.nextElement();        System.out.println("Actions[" + item +"]: Name " + name + " value " +            actions.get(name));        item++;      }    }    ObAuthenticationScheme auths;    try {      auths = new ObAuthenticationScheme(res);    } catch (ObAccessException ase) {      ase.printStackTrace();      return;    }  if (auths.isBasic()) {      System.out.println("Auth scheme is Basic");    } else {      System.out.println("Auth scheme is NOT Basic");    }    try {      ObResourceRequest resNew = (ObResourceRequest) res.clone();      System.out.println("Clone resource Name: " + resNew.getResource());    } catch (Exception e) {      e.printStackTrace();    }    res = null;    auths = null;    ObConfig.shutdown();  }}

4.6.6.1 Annotated Code

Import standard Java libraries to provide basic utilities, enumeration, and token processing capabilities.

import java.util.*;
import java.util.Enumeration;
import java.util.StringTokenizer;

Import the Access Manager API libraries.

import com.oblix.access.*;

This servlet is named access_test_java.

public class access_test_java {

Declare seven variable strings to store the values passed through the array named "arg."

public static void main(String[] arg) {
   String userid, password, method, url, configDir, type, location;

Set the current ObResourceRequest to "res."

ObResourceRequest res;

Initialize the hashtable parameters to NULL, just in case they were not already empty.

Hashtable parameters = null;

Create a new hashtable named "cred."

Hashtable cred = new Hashtable();

If the array named "arg" contains less than five strings, report the expected syntax and content for command-line input, which is five mandatory arguments in the specified order, as well as the optional variables configDir, authz-parameters, and location.

if (arg.length < 5) {
  System.out.println("Usage: EXPECTED: userid password type
    HTTP-method URL [configDir [authz-parameters] [location]]]");

Since fewer than five arguments were received the first time around, break out of the main method, effectively terminating program execution.

return;
} else {

If the array named "arg" contains five or more strings, assign the first five arguments (arg[0] through arg[4]) to the variables userid, password, type, method, and url, respectively.

userid = arg[0];
  password = arg[1];
  type = arg[2];
  method = arg[3];
  url = arg[4];
}

If "arg" contains six or more arguments, assign the sixth string in the array to the variable configDir.

if (arg.length >= 6)
  configDir = arg[5];

If "arg" does not contain six or more arguments (in other words, we know it contains exactly five arguments, because we have already determined it does not contain fewer than five) then set configDir to NULL.

else
  configDir = null;

If "arg" contains at least seven strings, and arg[6] (which has been implicitly assigned to the variable authz-parameters) is not empty, create a new hashtable named "parameters." The syntax for the string authz-parameters is: p1=v1&p2=v2&...

if (arg.length >= 7 && arg[6] != null) {
  parameters = new Hashtable();

Create a string tokenizer named tok1 and parse arg[6], using the ampersand character (&) as the delimiter. This breaks arg[6] into an array of tokens in the form pn=vn, where n is the sequential number of the token.

StringTokenizer tok1 = new StringTokenizer(arg[6], "&");

For all the items in tok1, return the next token as the variable nameValue. In this manner, nameValue is assigned the string pn=vn, where n is the sequential number of the token.

while (tok1.hasMoreTokens()) {
  String nameValue = tok1.nextToken();

Create a string tokenizer named tok2 and parse nameValue using the equal character (=) as the delimiter. In this manner, pn=vn breaks down into the tokens pn and vn.

StringTokenizer tok2 = new StringTokenizer(nameValue, "=");

Assign the first token to the variable "name."

String name = tok2.nextToken();

Assign the second token to "value." If additional tokens remain in tok2, return the next token and assign it to "value;" otherwise, assign an empty string to "value."

String value = tok2.hasMoreTokens() ? tok2.nextToken() : "";

Insert "name" and "value" into the hashtable "parameters."

parameters.put(name, value);
  }
}

If there are eight or more arguments in "arg," assign arg[7] to the variable "location;" otherwise make location empty.

location = arg.length >= 8 ? arg[7] : null;

If configDir" is not empty, initialize the Access Manager API using the current value of configDir.

try {
  if (configDir != null)
    ObConfig.initialize(configDir);

Otherwise, initialize the Access Manager API without specifying an explicit configDir location.

else
  ObConfig.initialize();
}

If the initialization attempt produces an error, report the appropriate error message (ie) to the standard error stream along with the backtrace.

catch (ObAccessException ie) {
  System.out.println("Initialize failed");
  ie.printStackTrace();

Break out of the main method, effectively terminating the program.

return;
}

Read the variables, user ID, and password into the hashtable named "cred."

cred.put("userid", userid);
cred.put("password", password);

Create an ObResourceRequest object named "res," which will return values for the variables type, url and method from the Access Server.

try {
res = new ObResourceRequest(type, url, method);

Determine whether the requested resource "res" is protected and display the appropriate message.

if (res.isProtected())
  System.out.println("Resource " + type ":" + url + " protected");
else
  System.out.println("Resource " + type + ":" + url + " unprotected");
}

If the attempt to create the ObResourceRequest structure does not succeed, report the failure along with the error message "t."

catch (Throwable t) {
  t.printStackTrace();
  System.out.println("Failed to create new resource request");

Break out of the main method, effectively terminating the program.

return;
}

Set the ObUserSession parameter "user" to empty.

ObUserSession user = null;

Create a ObUserSession structure named "user" so that it will return values for the ObResourceRequest structure "res" and the ObAuthenticationScheme structure "cred."

try
  user = new ObUserSession(res, cred);

If the attempt to create the ObUserSession structure does not succeed, then report the failure along with the error message "t."

catch (Throwable t) {
  t.printStackTrace();
  System.out.println("Failed to create new user session");

Break out of the main method, effectively terminating the program.

return;
}

Determine if the user is currently logged in, which is to say, authentication for this user has succeeded.

if (user.getStatus() == ObUserSession.LOGGEDIN) {

If the user is logged in, determine whether the variable "location" is not empty. If "location" is not empty, set the "location" parameter for ObConfig to the value of the variable "location," then report that the user is logged in along with the status code returned by the Access Server.

if (location != null) user.setLocation(location);
System.out.println("user status is " + user.getStatus());

Check authorization. To accomplish this, determine whether "parameters" exists. If it does, determine whether the user is authorized with respect to the target resource when the parameters stored in "parameters" are attached. If "parameters" does not exist, simply determine whether the user is authorized for the target resource.

try {
  if (parameters != null ? user.isAuthorized(res, parameters) :
    user.isAuthorized(res)) {

If the user is authorized to access the resource when all the appropriate parameters have been specified, report that permission has been granted.

System.out.println("Permission GRANTED");

Display also a serialized representation of the user session token.

System.out.println("User Session Token =" + user.getSessionToken());

If the variable location is not empty, report the location.

if (location != null) {
  System.out.println("Location = " + user.getLocation());
}

If the user is not authorized to access the resource, report that permission has been denied.

} else {
System.out.println("Permission DENIED");

If ObUserSession returns ERR_NEED_MORE_DATA, set the variable "nParams" to the number of parameters required for authorization, then report that number to the user.

if (user.getError() == ObUserSession.ERR_NEED_MORE_DATA) {
  int nParams = res.getNumberOfAuthorizationParameters();
  System.out.print("Required Authorization Parameters (" +
    nParams + ") :");

Set "e" to the value of the "keys" parameter in the hashtable returned by the getAuthorizationParameters method for the ObResourceRequest object named "res."

Enumeration e = res.getAuthorizationParameters().keys();

Report the names of all the elements contained in "e."

while (e.hasMoreElements()) {
  String name = (String) e.nextElement();
  System.out.print(" " + name);
}
System.out.println();
}

Otherwise, simply proceed to the next statement.

else
  }
}

In the case of an error, report that the authorization attempt failed.

catch (ObAccessException obe)
  System.out.println("Failed to get user authorization");
}

If the user is not logged in, report the current user status.

else
  System.out.println("user status is " + user.getStatus());

Now report all the actions currently set for the current user session. Do this by creating an array named actionTypes from the strings returned by the getActionTypes method. Next, read each string in actionTypes into a hashtable named "actions." Report the name and value of each of the keys contained in "actions."

String[] actionTypes = user.getActionTypes();
for(int i =0; actionTypes[i] != null; i++){
  Hashtable actions = user.getActions(actionTypes[i]);
  Enumeration e = actions.keys();
  int item = 0;
  System.out.println("Printing Actions for type " + actionTypes[i]);
  while(e.hasMoreElements()) {
String name = (String)e.nextElement();
System.out.println("Actions[" + item +"]: Name " + name + " value " +
  actions.get(name));
item++;
  }
}

Attempt to create an ObAuthenticationScheme object named "auths" for the ObResourceRequest object "res."

ObAuthenticationScheme auths;
try
  auths = new ObAuthenticationScheme(res);

If the ObAuthenticationScheme creation attempt is unsuccessful, report the failure along with the error message "ase."

catch (ObAccessException ase) {
  ase.printStackTrace();

Break out of the main method, effectively terminating the program.

return;
}

Determine if the authorization scheme is basic.

if (auths.isBasic())

If it is, report the fact.

System.out.println("Auth scheme is Basic");

It it is not basic, report the fact.

else
  System.out.println("Auth scheme is NOT Basic");

Use the copy constructor to create a new ObResourceRequest object named resNEW from the original object "res."

try {
  ObResourceRequest resNew = (ObResourceRequest) res.clone();

Report the name of the newly cloned object.

System.out.println("Clone resource Name: " + resNew.getResource());

If the ObResourceRequest object cannot be cloned for any reason, report the failure along with the associated backtrace.

}
catch (Exception e) {
  e.printStackTrace();
}

Set the ObResourceRequest object "res" and the ObAuthenticationScheme object "auths" to NULL, then disconnect the Access Manager API.

res = null;
    auths = null;
    ObConfig.shutdown();
  }
}

4.6.7 Example in C++ that Implements Several Features: access_test_cplus.cpp

Access_test_cplus.cpp, which is written with the C++ implementation of the Access Manager API, demonstrates a wide range of possible AccessGate features. The code sections roughly parallel those of the sample program access_test_java.java, but the syntax, I/O, and exception handling conform to C++.

The following subsections present an overview of the application, followed by the complete, unannotated listing, which can be copied into a C++ development environment for editing and compilation. Line-by-line annotations of the code begin on after this listing.

The program calls Access Manager API methods to set up a user session through either a session token or a user ID and password. The program then determines whether to grant the user access to the requested HTTP resource.

There are two modes of operation:

• Command Line: Command-line arguments are used for a single transaction.

• Interactive: No command-line arguments are used; instead, multiple transactions are read from stdin.

The possible transaction types are:

• Userid/password/method/URL: Uses a specified challenge method to authenticate the user and to determine whether to grant access to the requested URL.

• Token/method/URL: Retrieves user information from a serial token, then employs a specified challenge method to determine whether to grant access to the requested URL.

• Method/URL (Interactive mode only): Retrieves user information from a previous login and employs a specified challenge method to determine whether to grant access to the requested URL.

The URL to the requested resource takes the following form:

[resourceType:][//host[:port]]/resource[?p1=v1&p2=v2...]

The default resourceType is HTTP.

Examples

J.Smith 84CharingXRd GET /example/resource:

This command-line input logs in the user J. Smith with the password 84CharingXRd and checks GET access for the URL /example/resource.

GET /a/b.cgi?a=1&b=2:

This command-line input, which bases the transaction on an existing session, checks GET access to determine authorization for the URL /a/b.cgi with parameters a=1 and b=2.

Example 4-6 Access_test_cplus.cpp

#ifdef _WIN32
#pragma warning(disable : 4995)
#endif
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <iostream.h>
#ifdef _WIN32
#   include <sys/timeb.h>
#else
#   include <time.h>
#endif
#include <obaccess_api_cplus.h>
const char *sessionToken = NULL;
 
void parseUrl(char *urlCopy, const char **resourceType, const char **resource,
    ObMap &parameters) {
  char *colon   = strstr(urlCopy, ":");
  char *slashes = strstr(urlCopy, "//");
  if (colon != NULL && (slashes == NULL || colon < slashes)) {
    *resourceType = strtok(urlCopy, ":");
    *resource     = strtok(NULL,    "?");
  } else {
    *resourceType = "http";
    *resource     = strtok(urlCopy, "?");
  }
  char *name, *val;
  for (name = strtok(NULL, "="); name != NULL; name = strtok(NULL, "=")) {
    val = strtok(NULL, "&");
    if (val != NULL) parameters.put(name, val);
  }
}
 
void isAuthorized(ObUserSession &user, ObResourceRequest &res, const char
    *authzParmString){
  ObBoolean_t authz = ObFalse;
  if (authzParmString != NULL) {
    ObMap authzParameters;
    char *authzParms = strdup(authzParmString);
    char *name, *val;
    for (name = strtok(authzParms, "="); name != NULL; name = strtok(NULL,
        "=")) {
      val = strtok(NULL, "&");
      if (val != NULL) authzParameters.put(name, val);
    }
    authz = user.isAuthorized(res, authzParameters);
  } else {
    authz = user.isAuthorized(res);
  }
  if (authz) {
    cout << "GRANTED\n";
  } else {
    cout << "DENIED\n";
    cout << "ERROR: " << user.getErrorMessage() << "\n";
    if (user.getError() == ObUser_ERR_NEED_MORE_DATA) {
      ObMap *pRequiredParameters = res.getAuthorizationParameters();
      cout << "EXPECTED PARAMETERS:";
      ObMapIterator iter(*pRequiredParameters);
      while (iter.hasMore()) {
        const char *name = NULL, *value = NULL;
        iter.next(&name, &value);
        cout << " " << name;
      }
      cout << "\n";
      delete pRequiredParameters;
    }
  } 
  cout << "ACTIONS:";
  const char **actionTypes = user.getActionTypes();
  for (int i = 0; actionTypes[i] != NULL; i++) {
    const ObMap &actions = user.getActions(actionTypes[i]);
    ObMapIterator iter(actions);
    while (iter.hasMore()) {
      cout << "\n";
      const char *name = NULL, *value = NULL;
      iter.next(&name, &value);
      cout << actionTypes[i] << ": " << name << "=" << value;
    }
  }
}
 
void testLogin(const char *userid, const char *password, const char *method,
    const char *url, const char *location, const char *authzParmString) {
  char *urlCopy            = strdup(url);
  const char *resourceType = NULL;
  const char *resource     = NULL;
  ObMap parameters;
  parseUrl(urlCopy, &resourceType, &resource, parameters);
  ObResourceRequest res(resourceType, resource, method, parameters);
  if (res.isProtected()) {
    ObAuthenticationScheme authnScheme(res);
    if (authnScheme.isBasic()) {
      cout << "BASIC REALM : " << authnScheme.getChallengeParameter("realm")
        << "\n";
      ObMap credentials;
      credentials.put("userid", userid);
      credentials.put("password", password);
      ObUserSession user(res, credentials, location);
      if (user.getStatus() == ObUser_LOGGEDIN) {
        if (sessionToken != NULL) free((void *) sessionToken);        sessionToken = strdup(user.getSessionToken());        cout << "SESSION TOKEN : " << sessionToken << "\n";        isAuthorized(user, res, authzParmString);      } else {        cout << "LOGIN FAILED: " << user.getErrorMessage() << "\n";      }    } else {    cout << "RESOURCE SCHEME NOT BASIC";    }   } else {     cout << "NOT PROTECTED";  }  free(urlCopy);}void testToken(const char *token, const char *method, const char *url) {  if (sessionToken != NULL) free((void *) sessionToken);  sessionToken = token;  char *urlCopy = strdup(url);  const char *resourceType = NULL;  const char *resource     = NULL;  ObMap parameters;  parseUrl(urlCopy, &resourceType, &resource, parameters);  ObResourceRequest res(resourceType, resource, method, parameters);  if (res.isProtected()) {    ObUserSession user(sessionToken);    if (user.getStatus() == ObUser_LOGGEDIN) {      cout << "USER: " << user.getUserIdentity() << "\n";      if (user.getLocation() != NULL) {        cout << "LOCATION: " << user.getLocation() << "\n";      } else {        cout << "LOCATION: (none)\n";      }      isAuthorized(user, res, NULL);    } else {       cout << "BAD TOKEN";    }   } else {     cout << "NOT PROTECTED";   }  free(urlCopy);}void setLocation(const char *location) {  ObUserSession user(sessionToken);  user.setLocation(location);  sessionToken = strdup(user.getSessionToken());}void showConfig() {  cout << "CONFIGURATION:\n";  cout << "The current version of SDK is " << ObConfig::getSDKVersion() << "\n";  cout << "The current version of NAP is " << ObConfig::getNAPVersion() << "\n";  ObMapIterator iter(ObConfig::getAllItems());  while (iter.hasMore()) {    const char *name, *val;    iter.next(&name, &val);    cout << name << ": " << (val != NULL ? val : "(none)") << "\n";  }}void help() {  cout << "EXPECT ONE OF\n";  cout << "<userid> <password> <method> <url> [<location> [<authz-parameters>]]      (sets sessionToken)\n";  cout << "<sessionToken> <method> <url>      (sets sessionToken)\n";  cout << "<method> <url>                     (uses prior sessionToken)\n";  cout << "setLocation <newLocation>          (uses prior sessionToken)\n";  cout << "showconfig\n";  cout << "quit\n";  cout << "exit\n";}int innerMain(int argc, char *argv[]) {  float timeMilliSec;#ifdef _WIN32  struct _timeb startTime;  struct _timeb stopTime;  _ftime(&startTime);#else  struct timeval startTime;  struct timeval stopTime;  gettimeofday(&startTime, NULL);#endif  try {    if (argc == 2) {      if (strcmp(argv[1], "quit") == 0 || strcmp(argv[1], "exit") == 0) {        return 1;      } else       if (strcmp(argv[1], "showconfig") == 0) showConfig();    } else if (argc == 3) {      if (sessionToken != NULL) {        if (strcmp(argv[1], "setLocation") == 0) {          setLocation(argv[2]);        } else {          testToken(strdup(sessionToken), argv[1], argv[2]);        }      } else {        cout << "NO PRIOR LOGIN";      }    } else if (argc == 4) {      testToken(argv[1], argv[2], argv[3]);    } else if (argc == 5) {      testLogin(argv[1], argv[2], argv[3], argv[4], NULL, NULL);    } else if (argc == 6) {      testLogin(argv[1], argv[2], argv[3], argv[4], argv[5], NULL);    } else if (argc == 7) {
      testLogin(argv[1], argv[2], argv[3], argv[4], argv[5], argv[6]);
    } else {
      help();
    }
  }

Example 4-7 Access_test_cplus.cpp (more)

catch (ObAccessException *e) {     cout << "EXCEPTION: " << e->toString();    delete (e);  }#ifdef _WIN32  _ftime(&stopTime);  timeMilliSec = ((float) (stopTime.time    - startTime.time) * 1000) +    (float) (stopTime.millitm - startTime.millitm);#else  gettimeofday(&stopTime, NULL);  timeMilliSec = (((float) (stopTime.tv_sec - startTime.tv_sec) * 1000) +     ((float) (stopTime.tv_usec - startTime.tv_usec) / 1000));#endif  cout << "\nTIME : " << timeMilliSec << " milliseconds";  return 0;}int main(int argc, char *argv[]) {  try {    ObConfig::initialize();    if (argc == 1) {#      define MAX_ARGS 6#      define MAX_INPUT_CHARS 1000      int   ac;      char *av[MAX_ARGS];      char inputString[MAX_INPUT_CHARS];      char *arg;      help();       int stop = 0;      while (stop == 0) {        cout << "\n>";        cin.getline(inputString, MAX_INPUT_CHARS);        av[0] = (char *) "access_test_cplus";        ac = 1;        for (arg = strtok(inputString, " ");          arg != NULL && ac <= MAX_ARGS;          arg = strtok(NULL, " ")) {          av[ac] = arg;          ac++;        }        if (ac > 1) {          stop = innerMain(ac, av);          cout << "\n";        }      }    } else {      innerMain(argc, argv);    }    cout << "\n";    if (sessionToken != NULL) free((void *) sessionToken);    ObConfig::shutdown();  }  catch (ObAccessException *e) {    cout << "EXCEPTION: " << e->toString();    delete (e);  }  return 0;} 

4.6.7.1 Annotated Code

If the host machine for the AccessGate is running the Win32 platform, then disable the warning relating to the deprecation of old i/o streams.

#ifdef _WIN32
#pragma warning(disable : 4995)
#endif

Include several standard C++ libraries. In addition to basic functionality, they cover input and output, strings, and streams.

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <iostream.h>

Import the time-handling library appropriate for the operating system platform (Win32 or other) used by the machine hosting the AccessGate.

#ifdef _WIN32
# include <sys/timeb.h>
#else
# include <time.h>
#endif

Include the C++ implementation of the Access Manager API.

#include <obaccess_api_cplus.h>

Set to NULL the pointer to the current session token.

const char *sessionToken = NULL;

The parseURL method breaks the string "urlCopy" into its constituent elements, which are illustrated by the following:

[resourceType:][//host[:port]]/resource 

urlCopy might also contain an optional set of parameters in the following form:

[?p1=v1&p2=v2...]

where p represents the name of the parameter and v represents the value associated with that parameter name. In any case, urlCopy is optional.

void parseUrl(char *urlCopy, const char **resourceType, const char **resource,
  ObMap &parameters) {

Create pointers to the first colon (:) and double slash (//) within urlCopy and name them "colon" and "slashes," respectively.

char *colon = strstr(urlCopy, ":");
char *slashes = strstr(urlCopy, "//");

Determine whether urlCopy contains a colon but not a double slash, or whether it contains a colon which precedes a double slash.

if (colon != NULL && (slashes == NULL || colon < slashes)) {

If either of the preceding statements is true, we can assume that urlCopy follows the form resourceType:[//host[:port]]/resource[?p1=v1&p2=v2...].

Therefore, we need to return a pointer to the token "resourceType," which consists of everything in the string "urlCopy" prior to the delimiter colon (:).

*resourceType = strtok(urlCopy, ":");

Each time the strtok method is invoked, it changes the delimiter to NULL. Therefore, we retrieve the second token in the string by specifying NULL as the start point and the question mark (?) as the closing delimiter. This returns the URL for the requested resource.

*resource = strtok(NULL, "?");

If either part of the preceding "if" statement does not evaluate to true, we can assume that urlCopy follows the form [//host[:port]]/resource[?p1=v1&p2=v2...].

Therefore, we set resourceType to HTTP, and set a pointer to the token "resource," which consists of everything in urlCopy that precedes the delimiter question mark (?).

} else {
  *resourceType = "http";
  *resource = strtok(urlCopy, "?");
}

Now parse the optional parameters section of the urlCopy string. Do this by assigning to "name" everything between NULL (formerly the question mark delimiter) and the equal sign (=), which is the new closing delimiter. As long as "name" is not empty, assign the next token to "val," this time using the ampersand (&) as the closing delimiter. Repeat this process until "name" is returned as NULL. This indicates that the end of the string has been reached.

char *name, *val;
  for (name = strtok(NULL, "="); name != NULL; name = strtok(NULL, "=")) {
    val = strtok(NULL, "&");
    if (val != NULL) parameters.put(name, val);
  }
}

The isAuthorized method determines if the user submitting the request has permission to access a particular resource.

void isAuthorized(ObUserSession &user,ObResourceRequest &res, const char
  *authzParmString) {

Initiate the boolean variable "authz" as false.

ObBoolean_t authz = ObFalse;

Determine if the optional string authzParmString exists.

if (authzParmString != NULL) {

If authzParmString, which takes the format p1=v1&p2=v2...., does exist, break it into its constituent name:value pairs. Accomplish this by invoking the strtok method to read the name and value elements for each parameter into an ObMap structure named authzParameters. Keep reading name:value pairs into authzParameters until the token "name" returns a NULL value, indicating that the end of the list has been reached.

ObMap authzParameters;
char *authzParms = strdup(authzParmString);
char *name, *val;
for (name = strtok(authzParms, "="); name != NULL; name = strtok(NULL,
    "=")) {
  val = strtok(NULL, "&");
  if (val != NULL) authzParameters.put(name, val);
}

Determine if the user specified in the ObUserSession object "user" is authorized to access the ObResourceRequest object "res" by supplying the credentials specified in authzParmString.

authz = user.isAuthorized(res, authzParameters);
}

If the optional authzParmString variable has not been supplied, determine if the user specified by the ObUserSession object "user" is authorized to access the resource requested through the ObResourceRequest structure "res."

else {
  authz = user.isAuthorized(res);
}

If the user is authorized, report that access permission has been granted.

if (authz) {
  cout << "GRANTED\n";

Otherwise, report that access has been denied and append whatever error message has been returned.

} else {
  cout << "DENIED\n";
  cout << "ERROR: " << user.getErrorMessage() << "\n";

If ERR_NEED_MORE_DATA is returned, retrieve the required authorization parameters for the resource specified by "res." Place the pointers for the name and value associated with each parameter into the ObMap structure pointed to by pRequiredParameters. Report on a new line the name (but not the corresponding value!) of each required parameter.

if (user.getError() == ObUser_ERR_NEED_MORE_DATA) {
  ObMap *pRequiredParameters = res.getAuthorizationParameters();
  cout << "EXPECTED PARAMETERS:";
  ObMapIterator iter(*pRequiredParameters);
  while (iter.hasMore()) {
    const char *name = NULL, *value = NULL;
    iter.next(&name, &value);
    cout << " " << name;
  }
  cout << "\n";

To free the memory used by pRequiredParameters which is no longer needed, invoke "delete."

delete pRequiredParameters;
  }
}

Place the actions to be performed against the ObUserSession object "user" into the ObMap object "actions." Use ObMapIterator to report the name and value associated with each action.

cout << "ACTIONS:";
  const char **actionTypes = user.getActionTypes();
  for (int i = 0; actionTypes[i] != NULL; i++) {
    const ObMap &actions = user.getActions(actionTypes[i]);
    ObMapIterator iter(actions);
    while (iter.hasMore()) {
      cout << "\n";
      const char *name = NULL, *value = NULL;
      iter.next(&name, &value);
      cout << actionTypes[i] << ": " << name << "=" << value;
    }
  }
}

The testLogin method demonstrates AccessGate login capabilities. Start by initializing or retrieving the necessary variables and constants.

void testLogin(const char *userid, const char *password, const char *method,
    const char *url, const char *location, const char *authzParmString) {
  char *urlCopy            = strdup(url);
  const char *resourceType = NULL;
  const char *resource     = NULL;
  ObMap parameters;
  parseUrl(urlCopy, &resourceType, &resource, parameters);
  ObResourceRequest res(resourceType, resource, method, parameters);

Determine whether the resource specified by the ObResourceRequest object "res" is protected.

if (res.isProtected()) {

If the resource is protected, determine if the authentication scheme associated with "res" uses the basic challenge method.

ObAuthenticationScheme authnScheme(res);
if (authnScheme.isBasic()) {

If the authentication scheme does use the basic challenge method, report that fact along with the value of "realm," which is usually the name of the authentication domain (an LDAP directory, for instance).

cout << "BASIC REALM : " << authnScheme.getChallengeParameter("realm")
  << "\n";

Create an ObMap list named "credentials," and place into it the user ID and password supplied for the current user session.

ObMap credentials;
credentials.put("userid", userid);
credentials.put("password", password);
ObUserSession user(res, credentials, location);

Determine whether the user is logged in, which is to say, the user has authenticated successfully.

if (user.getStatus() == ObUser_LOGGEDIN) {

If the user is currently authenticated, determine whether the variable sessionToken exists. If it does, guard against stale data by deallocating the memory used by the sessionToken object.

if (sessionToken != NULL) free((void *) sessionToken);

Retrieve a copy of the session token associated with "user" and assign it to the variable sessionToken.

sessionToken = strdup(user.getSessionToken());

Report the contents of the serialized session token, which is an ASCII string representing the userid and password in encoded form.

cout << "SESSION TOKEN : " << sessionToken << "\n";

Check whether the user is authorized to access the resource using the credentials passed through authzParmString.

isAuthorized(user, res, authzParmString);

If the user has not authenticated successfully, report that along with the associated error message.

} else {
  cout << "LOGIN FAILED: " << user.getErrorMessage() << "\n";
}

If the challenge method is not basic, report that fact.

} else {
  cout << "RESOURCE SCHEME NOT BASIC";
}

If the resource is not protected, report that fact.

} else {
cout << "NOT PROTECTED";
}

Deallocate the memory used by the variable urlCopy.

free(urlCopy);
}

The testToken method demonstrates how authentication is achieved through an existing session token.

void testToken(const char *token, const char *method, const char *url) {

If the variable sessionToken exists, deallocate the memory assigned to it so as to avoid stale session data.

if (sessionToken != NULL) free((void *) sessionToken);

Initialize or retrieve the necessary variables and constants.

sessionToken = token;
char *urlCopy = strdup(url);
const char *resourceType = NULL;
const char *resource = NULL;
ObMap parameters;
parseUrl(urlCopy, &resourceType, &resource, parameters);
ObResourceRequest res(resourceType, resource, method, parameters);

Determine if the resource specified by the ObResourceRequest structure "res" is protected.

if (res.isProtected()){

If the resource is protected, determine whether the user is logged in (which is to say, has successfully authenticated).

ObUserSession user(sessionToken);
if (user.getStatus() == ObUser_LOGGEDIN) {

If the user is authenticated, report the DN (Distinguished Name) of the user as it exists in the LDAP directory.

cout << "USER: " << user.getUserIdentity() << "\n";

Determine if an IP address has been set for the user. Report the location, if that information it exists. Otherwise, report the location as "(none)".

if (user.getLocation() != NULL) {
  cout << "LOCATION: " << user.getLocation() << "\n";
} else {
  cout << "LOCATION: (none)\n";
}
isAuthorized(user, res, NULL);

If the user is not authenticated, report that the token is invalid.

} else {
  cout << "BAD TOKEN";
}

If the resource is not protected, report that fact.

} else {
  cout << "NOT PROTECTED";
}

Clean up by deallocating the memory used by the variable urlCopy.

free(urlCopy);
}

Set the IP address of the user's machine.

void setLocation(const char *location) {

Create a session with the existing token.

ObUserSession user(sessionToken);

Update the session token with the IP address returned by the setLocation method.

user.setLocation(location);
  sessionToken = strdup(user.getSessionToken());
}

The showConfig method reports the configuration information currently set for the AccessGate. This includes the version of the Access Manager SDK in use, the version of the access control protocol in use, all of the other configuration parameters in the configuration file ObAccessClient.xml. This may include items such as the maximum number of resource request objects that can be cached, the maximum number of seconds before the user must re-authenticate, or the frequency with which the AccessGate checks to make sure its connection to the Access Server is still up.

void showConfig() {
  cout << "CONFIGURATION:\n";
  cout << "The current version of SDK is " << ObConfig::getSDKVersion() << "\n";
  cout << "The current version of NAP is " << ObConfig::getNAPVersion() << "\n";
  ObMapIterator iter(ObConfig::getAllItems());
  while (iter.hasMore()) {
    const char *name, *val;
    iter.next(&name, &val);
    cout << name << ": " << (val != NULL ? val : "(none)") << "\n";
  }
}

The help method reports the command-line syntax and options available for this application.

void help() {
  cout << "EXPECT ONE OF\n";
  cout << "<userid> <password> <method> <url> [<location> [<authz-parameters>]]
      (sets sessionToken)\n";
  cout << "<sessionToken> <method> <url>      (sets sessionToken)\n";
  cout << "<method> <url>                     (uses prior sessionToken)\n";
  cout << "setLocation <newLocation>          (uses prior sessionToken)\n";
  cout << "showconfig\n";
  cout << "quit\n";
  cout << "exit\n";
}

This is the innerMain method, which enables the program to execute with supplied command-line arguments or without command-line arguments in interactive mode. The innerMain method contains the code to execute a single operation; the main method reads in the operations, then calls "innermain."

int innerMain(int argc, char *argv[]) {

Set up a variable to measure how long the application runs.

float timeMilliSec;

Have the compiler set the time format correctly for the host machine platform running the AccessGate.

#ifdef _WIN32
  struct _timeb startTime;
  struct _timeb stopTime;
  _ftime(&startTime);
#else
  struct timeval startTime;
  struct timeval stopTime;
  gettimeofday(&startTime, NULL);
#endif
  try {

If precisely two strings exist in the array named "argc," determine whether the second string (arg[1]) is quit or exit. If the user has entered quit or exit, break out of this method.

if (argc == 2) {
   if (strcmp(argv[1], "quit") == 0 || strcmp(argv[1], "exit") == 0) {
      return 1;

If the user has not entered quit or exit, determine whether the second string in the array "argv" is "showconfig." If so, invoke the showConfig method.

} else if (strcmp(argv[1], "showconfig") == 0) showConfig();

If precisely three strings exist in "argc," we can assume that input follows the form <method> <URL>. Therefore, determine if a session token exists.

} else if (argc == 3) {
  if (sessionToken != NULL) {

If a session token does exist, determine whether the user has entered setLocation. If so, invoke the setLocation method.

if (strcmp(argv[1], "setLocation") == 0) {
  setLocation(argv[2]);

If the user did not enter setLocation as the second element in the input string, invoke the testToken method, using the second and third arguments in "argc" as parameters.

} else {
  testToken(strdup(sessionToken), argv[1], argv[2]);
}

If a session token does not exist, report that the user is not currently authenticated.

} else {
  cout << "NO PRIOR LOGIN";
}

If precisely four strings exist in "argc," we can assume that input follows the form <sessionToken> <method> <URL>. Therefore, invoke the testToken method, using the second through fourth strings in "argc" as parameters.

} else if (argc == 4) {
  testToken(argv[1], argv[2], argv[3]);

If precisely five strings exist in "argc," we can assume that input follows the form <userid><password> <method> <URL>. Therefore, invoke the testLogin method, using the second through fifth strings in "argc" as parameters. Also, set the final two arguments for testLogin to NULL.

} else if (argc == 5) {
  testLogin(argv[1], argv[2], argv[3], argv[4], NULL, NULL);

If precisely six strings exist in "argc," we can assume that input follows the form <userid><password> <method> <URL><location>. Therefore, invoke testLogin, using the second through sixth strings in "argc" as parameters. Set the final argument for testLogin to NULL.

} else if (argc == 6) {
  testLogin(argv[1], argv[2], argv[3], argv[4], argv[5], NULL);

If precisely seven strings exist in "argc," we can assume that input follows the form <userid><password> <method> <URL><location><authzParameters>. Therefore, invoke testLogin, using the second through sixth strings in "argc" as parameters.

} else if (argc == 7) {
  testLogin(argv[1], argv[2], argv[3], argv[4], argv[5], argv[6]);
} else {

If the number of strings in "argc" is either one or more than seven, invoke the help method, which displays the command-line syntax for the application. This teaches the user how to enter the right type of information in the proper format.

help();
}

If an error occurs in the main part of the innerMain method, report that fact, along with the error message "e."

} catch (ObAccessException *e) {
  cout << "EXCEPTION: " << e->toString();

To free the memory used by "e," which is no longer needed, invoke "delete."

delete (e);
}

Have the compiler set up the appropriate time-related functions for the platform in use.

#ifdef _WIN32
  _ftime(&stopTime);
  timeMilliSec = ((float) (stopTime.time    - startTime.time) * 1000) +
    (float) (stopTime.millitm - startTime.millitm);
#else
  gettimeofday(&stopTime, NULL);
  timeMilliSec = (((float) (stopTime.tv_sec - startTime.tv_sec) * 1000) + 
    ((float) (stopTime.tv_usec - startTime.tv_usec) / 1000));
#endif

Report how long the application has been running.

cout << "\nTIME : " << timeMilliSec << " milliseconds";
  return 0;
}

The main method ties everything together.

int main(int argc, char *argv[])
{
  try {

Initialize the Access Manager SDK using the scope resolution operator to make sure we are calling the "initialize" method defined in Com.Oblix.Access.ObConfig.

ObConfig::initialize();

Determine whether "argc" contains a single string.

if (argc == 1) {

If it does, we are in interactive mode. Therefore, use the compiler to accept input lines containing no more than 1000 characters organized into a maximum of six (space-separated) arguments.

# define MAX_ARGS 6
# define MAX_INPUT_CHARS 1000

Initialize the appropriate variables. "ac" tracks the number of arguments in the input string. inputString stores the input retrieved from the command line, as long as it does not exceed 1,000 characters in length. "arg" stores each argument as it is parsed out of inputString. The array named "av" stores the space-separated arguments parsed from "inputString."

int ac;
char *av[MAX_ARGS];
char inputString[MAX_INPUT_CHARS];
char *arg;

Invoke the help method so that user knows the required syntax and permissible range for command-line input.

help();
int stop = 0;

Retrieve the command-line input string named inputString, as long as it does not exceed the permitted maximum length. The new line character that terminates input is not included in inputString.

while (stop == 0) {
  cout << "\n>";
  cin.getline(inputString, MAX_INPUT_CHARS);

Assign a pointer to the string access_test_plus to the first element in the array named "av." Casting is necessary here because the character string access_test_cplus is "const char *", while the array "av" must be declared "char *".

av[0] = (char *) "access_test_cplus";

Using the space character ( ) as the delimiter, return the first argument in inputString and assign it to the second argument in "av" (av[1]). Repeat this sequence as long as substrings remain in inputString, and the maximum number of arguments permitted for "av" has not been exceeded.

ac = 1;
for (arg = strtok(inputString, " "); 
   arg != NULL && ac <= MAX_ARGS; 
   arg = strtok(NULL, " ")) {
  av[ac] = arg;
  ac++;
}

When no more substrings exist to be extracted from inputString, determine whether any substring from inputString was assigned to the array "av." If so, pass "av" and "ac" to the innermain method for processing, then store the return status in the variable "stop."

if (ac > 1) {
      stop = innerMain(ac, av);
      cout << "\n";
    }
  }
}

Otherwise, invoke the innerMain method, passing it the current values for "argc" and "argv." If a session token exists, deallocate the memory it uses, then shutdown the Access Manager API.

else {
    innerMain(argc, argv);
  }
  cout << "\n";
  if (sessionToken != NULL) free((void *) sessionToken);
  ObConfig::shutdown();
  }

If an error occurs anywhere within the main method, report the appropriate error message.

catch (ObAccessException *e) {
  cout << "EXCEPTION: " << e->toString();

To free the memory used by "e," which is no longer needed, invoke "delete."

delete (e);
}

End the application.

return 0;
}

4.6.8 Example of Implementing Certificate-Based Authentication

The following is a code snippet that demonstrates implementing an AccessGate in Java that processes an X.509 certificate. This snippet is appropriate when an administrator configures certificate-based authentication in the Access System.

Note that the certificate must be Base 64-encoded. Also, the Access Server does not validate items, for example, the root certificate and validity period. It only maps the items to the user.

// cert must point to a valid java.security.cert.X509Certificate instance.
    X509Certificate cert = ...
 
// Convert the certificate into a byte array
    byte[] encodecCert = cert.getEncoded();
 
// Encode the byte array using Base 64-encoding and convert it into a string
    String base64EncodedCert = new String(Codecs.base64Encode(encodedCert));
 
// Create hashtable to hold credentials
    Hashtable creds = new Hashtable();
 
// Store the Base 64-encoded under the key "certificate"
    cred.put("certificate", base64EncodedCert);
 
// Create ObResourceResource request object including all information about the // // resource being accessed
    ObResourceRequest resourceRequest = new ObResourceRequest(resourceType, resourceUrl, operation);
 
// Create a ObUserSession with the requestRequest and the cred hashtable
    ObUserSession userSession = new ObUserSession(resourceRequest, creds);
 
// The above statement will throw an exception if the certificate cannot be mapped // to a valid user by the Access Server.

The following import statements are associated with the snippet:

import HTTPClient.Codecs;
     import com.cfluent.ccore.message.SOAPMessage;
     import com.cfluent.ccore.util.logging.ILogger;
     import com.cfluent.ccore.util.logging.Level;
     import com.cfluent.ccore.util.logging.LogManager;
     import com.cfluent.pipelineengine.container.MessageContext;
     import com.cfluent.pipelineengine.container.SecCredentials;
     import com.cfluent.policysteps.Constants;
     import com.cfluent.policysteps.sdk.Fault;
     import com.oblix.access.ObAccessException;
     import com.oblix.access.ObResourceRequest;
     import com.oblix.access.ObUserSession;
     import java.security.Principal;
     import java.security.cert.X509Certificate;
     import java.util.ArrayList;
     import java.util.Enumeration;
     import java.util.HashMap;
     import java.util.Hashtable;
     import java.util.Iterator;
     import java.util.StringTokenizer;
     import javax.xml.soap.Name;
     import javax.xml.soap.SOAPElement;
     import javax.xml.soap.SOAPException;
     import javax.xml.soap.SOAPFactory;
     import javax.xml.soap.SOAPHeader;
     import javax.xml.soap.SOAPHeaderElement;
     import org.apache.axis.Message;
     import org.apache.axis.message.MessageElement;
     import org.apache.axis.message.SOAPEnvelope;

4.7 C++ Implementation Details

This section details the classes, constructors, methods, and parameters associated with the C++ implementation of the Access Manager API. For an overview of the Access Manager API classes, see "About the Access Manager API" . The header file obaccess_api_cplus.h, also contains information on the C++ implementation of the API. This file resides at the following location:

SDK_install_dir\include

The C++ implementation of the Access Manager API includes the classes listed in Table 4-16:

Table 4-16 Overview of the Classes belonging to ObAccess (C++)

Class	Description
ObMap	Enables creation of and interaction with lists of name:value pairs.
ObMapIterator	Enables stepping through a list. You can determine the number of items in that list or retrieve a name:value pair from a specific position in that list.
ObAuthenticationScheme	Enables creation of and interaction with the structures that represent the authentication schemes used to authenticate users.
ObResourceRequest	Enables creation of and interaction with the structures that represent user requests to access resources.
ObUserSession	Enables creation of and interaction with structures representing sessions for users who have completed authentication successfully.
ObConfig	Enables your application to initialize or shut down the Access Server. You can also obtain AccessGate configuration data from the Access Server.
ObAccessException	Enables you to extract the entire error message string thrown by the Access Manager API in response to an error. Alternatively, you can extract any or all of the embedded substrings (up to five) in an error message.

Note:

For the C++ implementation of the Access Manager API, you must invoke the "delete" method to clean up structures when they are no longer needed. See "About Memory Management" .

4.7.1 ObMap

ObMap facilitates the storage of Access Manager API data by providing list structures into which name:value pairs can be written. The class also provides methods for retrieving information from the list, determining the number of items in that list, and copying the list. For a general discussion of ObMap, see "ObMap" .

For a list of the messages thrown in response to errors by the C++ implementation of ObMap, see "C-Family Status and Error Message Strings" .

4.7.1.1 Constructors (ObMap, C++)

Table 4-17 describes and details the constructors associated with the ObMap class.

Table 4-17 ObMap Constructors (C++)

Key Parameter	Details
NULL	ObMap() creates an empty list to hold name:value pairs. The name of this list is specified by the user when declaring the variable that represents this object.
otherMap	ObMap(const ObMap &otherMap) creates a copy of an existing list. The name of the new list is specified by the user. Parameters: OtherMap: The name of the list to be copied. Returns: A list to hold name:value pairs.

4.7.1.2 Methods (ObMap, C++)

Table 4-18 lists the ObMap methods and associated parameters.

Table 4-18 ObMap Methods (C++)

Method	Details
get	const char *get(const char *name) const returns from the list the string value corresponding to the name specified. Parameters: name: The name member of the name:value pair for which the corresponding value is to be returned. Returns: The value member of the name:value pair. If the name is not found in the list, the method returns NULL.
put	void put(const char *name, const char *val) stores a name:value pair in the list. If the name is already in the list, its value is replaced; otherwise the name:value pair is added to the list. By implication a name can map to a just one value at any given time. Parameters: name: A string representing the name to be stored. val: A string representing the value to be stored.
size	int size()const returns the total number of the name:value pairs in the list.
copy	ObMap *copy() const creates a copy of ObMap. Returns: A pointer to the copy.

4.7.2 ObMapIterator

ObMapIterator enables you to step through a list created by ObMap and extract a name:value pair from a specific position in the list. Alternatively, you can use the ObMapIterator pointer to determine when the end of the list has been reached. For a general discussion of ObMapIterator, see "ObMapIterator".

For a list of the messages thrown in response to errors by the C++ implementation of ObMapIterator, see "C-Family Status and Error Message Strings".

4.7.2.1 Constructors (ObMapIterator, C++)

Table 4-19 lists details for the ObMapIterator constructors.

Table 4-19 ObMapIterator Constructors (C++)

Key Parameter	Details
map	ObMapIterator(const ObMap &map) creates an iterator (pointer) to a specified ObMap list. This pointer is used with ObMapIterator(next). Parameters: map: The name of the list.
other	ObMapIterator(const ObMapIterator &other) creates an iterator (pointer) to a copy of a specified ObMap list. This pointer is used with ObMapIterator(next). Parameters: other: The name of the list to be copied.

4.7.2.2 Methods (ObMapIterator, C++)

Table 4-20 lists the methods and associated details for ObMapIterator.

Table 4-20 ObMapIterator Methods (C++)

Method	Details
next	void next(const char **name, const char **val) returns the name:value pair from the current position in the list and moves the iterator to the following pair. Returns: Text strings for the next name:value pair.
hasMore	ObBoolean_t hasMore() const watches for the end of a list. It returns ObTrue if more name:value pairs exist in the map. It returns ObFalse if the end of the list has been reached.

4.7.3 ObAuthenticationScheme

ObAuthenticationScheme enables creation of and interaction with the structures that define the challenge methods and other parameters used by your AccessGate to authenticate users. For a general discussion of ObAuthenticationScheme, see "ObAuthenticationScheme" .

For a list of the messages thrown in response to errors by the C++ implementation of ObAuthenticationScheme, see "C-Family Status and Error Message Strings" .

4.7.3.1 Constructors (ObAuthenticationScheme, C++)

Table 4-21 lists details for the ObAuthenticationScheme constructors.

Table 4-21 ObAuthenticationScheme Constructors (C++)

Key Parameter	Details
resource	public ObAuthenticationScheme(const ObResourceRequest &resource) constructs an ObAuthenticationScheme object for the specified ObResourceRequest. Parameters: resource: The resource request for which the authentication scheme object is being constructed. Returns: A structure holding the object.
presource	ObAuthenticationScheme(const ObResourceRequest *presource) constructs an ObAuthenticationScheme object for the specified ObResourceRequest. Parameters: resource: The resource request for which the authentication scheme object is being constructed. Returns: A structure holding the object.
other	ObAuthenticationScheme(const ObAuthenticationScheme &other) is the copy constructor for this class. Parameters: other: The existing authentication scheme object to be copied. Returns: A structure holding a copy of the object.

4.7.3.2 Methods (ObAuthenticationScheme, C++)

Table 4-22 lists the ObAuthenticationScheme methods and associated details.

Table 4-22 ObAuthenticationScheme Methods (C++)

Methods	Details
getName	const char *getName() const returns the display name assigned to the authentication scheme during configuration.
getMask	int getMask() const returns a mask byte defining the security level.
requiresSecure Transport	ObBoolean_t requiresSecureTransport() const returns ObTrue if the scheme requires an SSL client connection; otherwise, it returns ObFalse. If the return flag is ObTrue, a redirectUrl is required.
isBasic	ObBoolean_t isBasic() const returns a flag indicating if the authentication scheme requires only a userid-and-password challenge method. Returns: ObTrue if the scheme is Basic; otherwise, it returns ObFalse.
isCertificate	ObBoolean_t isCertificate() const returns ObTrue if the scheme requires a digital certificate; otherwise, it returns ObFalse.
isForm	ObBoolean_t isForm() const returns ObTrue if the authentication scheme uses customer-defined credential fields in an HTML login form (FORM-based authentication). Otherwise, it returns ObFalse.
isNone	ObBoolean_t isNone() const returns ObTrue if no credentials are required for authentication; otherwise, it returns ObFalse.
getLevel	int getLevel() const returns a numeric representation of the security level specified during authentication scheme configuration.
getRedirectUrl	const char *getRedirectUrl() const returns a string specified during configuration that represents the URL to which clients are redirected for authentication.
getChallenge Parameter	const char *getChallengeParameter(const char *parameterName) const returns the value for a challenge parameter that was specified by name during configuration. This parameter can be used to retrieve a space-separated list of context requests in the creds challenge parameter of an authorization scheme. The caller must parse the list to obtain the individual parameter names. Parameters: parameterName: The name of the challenge parameter. Returns: The corresponding challenge parameter value.
getAllChallenge Parameters	const ObMap &getAllChallengeParameters() const returns all the challenge parameters specified during configuration for a given authentication scheme. Returns: An ObMap list of name:value pairs.
getNumberOf Challenge Parameters	int getNumberOfChallengeParameters() const returns the total number of challenge parameters assigned to the Authentication Scheme during configuration.

4.7.4 ObResourceRequest

ObResourceRequest enables creation of and interaction with the structures that represent user requests to access resources. For a general discussion of ObResourceRequest, see "ObResourceRequest" .

For a list of the messages thrown in response to errors by the C++ implementation of ObResourceRequest, see "C-Family Status and Error Message Strings" .

4.7.4.1 Constructors (ObResourceRequest, C++)

Table 4-23 details the ObResourceRequest constructors.

Table 4-23 ObResourceRequest Constructors (C++)

Key Parameter	Details
operation	ObResourceRequest(const char *resType,const char *resource,const char *operation) constructs an ObResourceRequest object. The parameters are left as NULL values. Parameters: resType: The resource type (If resType is NULL, HTTP is used as a default.) resource: The name of the resource operation: The operation to be performed Returns: A structure holding the ObResourceRequest object.
parameters	ObResourceRequest(const char *resType, const char *resource, const char *operation, const ObMap &parameters) constructs an ObResourceRequest object. The parameter list is left as NULL values. Parameters: resource: The name of the resource. operation: The operation to be performed. parameters: A pointer to a list of context data (authorization parameters) resType: The resource type. (If resType is NULL, HTTP is used as a default.) Returns: A structure holding the object.
other	ObResourceRequest(const ObResourceRequest &other) is the copy constructor for this class. Parameters: other: The name of an existing ObResourceRequest structure to be copied. Returns: A structure holding a copy of the object.

4.7.4.2 Methods (ObResourceRequest, C++)

Table 4-24 details the ObResourceRequest methods.

Table 4-24 ObResourceRequest Methods (C++)

Methods	Details
getResourceType	const char *getResourceType() const returns the resource type for the request.
getResource	const char *getResource() const returns the resource name for the request.
getOperation	const char *getOperation() const returns the name of the requested operation.
getParameters	const ObMap &getParameters() const returns a pointer to the first name:value pair in the list of parameters provided as a set of name:value pairs.
getNumberOf Parameters	int getNumberOfParameters() const returns a count of the number of pairs in the list.
isProtected	ObBoolean_t isProtected() returns ObTrue if the resource is protected by Access System policies; it returns ObFalse if it is not
getAuthorization Parameters	ObMap *getAuthorizationParameters() const When a response to the "ObUserSession.IsAuthorized" method includes a list of required data points from an external source, the list is cached in the ObResourceRequest object specified through the isAuthorized call. An AccessGate can obtain the list through the getAuthorizationParameters method. The AccessGate can add the appropriate values and pass the ObMap through a subsequent isAuthorized call. The caller is responsible for using the "delete" method to deallocate the ObMap object returned by getAuthorizationParameters. Returns: A list of name-value pairs with NULL values.
getNumberOf Authorization Parameters	int getNumberOfAuthorizationParameters() const; returns the number of required context data items.

4.7.5 ObUserSession

ObUserSession enables creation of and interaction with structures that represent sessions for users who have completed authentication successfully. For a general discussion of ObUserSession, see "ObUserSession" .

For a list of the messages thrown in response to errors by the C++ implementation of ObUserSession, see "C-Family Status and Error Message Strings" .

4.7.5.1 Constructors (ObUserSession, C++)

Table 4-25 lists the ObUserSession constructors and associated details.

Table 4-25 ObUserSession Constructors (C++)

Key Parameter	Details
sessionToken	ObUserSession(const char *sessionToken) creates a user session object. Used for calls that load the session information immediately. Parameters: sessionToken: An ASCII text string that is parsed to obtain the result of authentication, which is to say, the user's DN and the level of the authentication scheme used. Returns: a structure holding a user session object. Throws: an ObAccessException if the user session object cannot be created for some reason or the sessionToken value is NULL.
lazyload	ObUserSession(const char* sessionToken, bool lazyload) creates a user session on demand. Parameters: lazyload: This flag, if true, indicates that the session token is not to be loaded immediately. Relies on getUserIdentity(), getLocation(), getLevel(), getStartTime(), and getEndTime() functions to make calls if the session token information is invalid, and lazyload loads the token on demand. Returns: A user session object. Throws: An ObAccessException if the user session object cannot be created for some reason or the resource object is NULL.
resource	ObUserSession(const ObResourceRequest &resource, const ObMap &credentials, const char *location = NULL) creates a user session object, as described under "ObUserSession" . Parameters: resource: The resource object for which the user is being authenticated. credentials: The user credentials. location: The location of the user, if it needs to be specified. A valid DNS name or IP address can be used to specify the location of the user's machine. Returns: A structure holding a user session object. Throws: An ObAccessException if the user session object cannot be created for some reason or the resource object is NULL.
presource	ObUserSession(const ObResourceRequest *presource, const ObMap &credentials, const char *location = NULL) creates a user session object. Parameters: presource: The name of the resource credentials: The user credentials. location: The location of the user, if it needs to be specified. A valid DNS name or IP address can be used to specify the location of the user's machine. Returns: A user session object. Throws: An ObAccessException if the user session object cannot be created for some reason or the resource object is NULL.
&other	ObUserSession(const ObUserSession &other) creates a copy of a user session object. Parameters: other: The existing user session object to be copied. Returns: A copy of the user session object. Throws: An ObAccessException if the user session object cannot be created for some reason or the resource object is NULL.

4.7.5.2 Methods (ObUserSession, C++)

Table 4-26 lists ObUserSession methods and associated details.

Table 4-26 ObUserSession Methods (C++)

Method	Details
getUserIdentity	const char *getUserIdentity() const returns the DN of the user's profile entry in the user directory.
getLocation	const char *getLocation() const returns the IP address of the user's web browser.
getAction	const char *getAction(const char *actionType, const char *name) const returns an action corresponding to the action name and type specified. Parameters: actionType: The type of action for which the value is returned. If this is left NULL, the default is headerVar. name: The name of the action for which the value is returned.
getActions	const ObMap &getActions(const char *actionType)const returns an ObMap list of action names and values in response to a specified action type. Parameters: actionType: The type of action for which the list is returned. If this is left NULL, the default is "headerVar".
getActionTypes	const **getActionTypes() const returns all the action types as an array of pointers to strings. The array is terminated by a NULL pointer.
getNumberofActions	int getNumberOfActions(const char *actionType) const returns the total number of actions of the specified action type that are associated with the user session. Parameters: actionType: The name of the action type for which a count of actions is needed. If this is left NULL, the default is headerVar.
getLevel	int getLevel() const returns a numeric value representing the level of the authentication scheme used to authenticate the user.
getStartTime	int getStartTime() const returns the time at which the user was authenticated. This value is used to determine when a session expires. Returns: The number of seconds since midnight, January 1, 1970 since the user was authenticated.
getLastUseTime	int getLastUseTime() const returns the time since the most recent user request was authorized. This value is used to determine when an idle session expires. Returns: The number of seconds since midnight, January 1, 1970 since the most recent user request was authorized.
getStatus	ObUserStatus_t getStatus() const describes the current session status. Returns: An ObUserStatus_t value, such as logged out, logged in, login failed, or expired.
getError	ObUserError_t getError() const returns one of the ObUserError_t error values determined by the most recent authentication or authorization.
getErrorMessage	const char *getErrorMessage(int err) const returns the detailed error message for the authentication or authorization failure. The text of this message is derived by the Access API and is not for user modification. Parameters: err: The numerical error code corresponding to the authentication or authorization failure.
getSessionToken	const char *getSessionToken() const returns the saved, encrypted ASCII string representing the user session.
getUserIdentity	const char *getUserIdentity() const returns the Distinguished Name of the user's profile entry in the user directory.
setLocation	void setLocation(const char *location) sets the location of the user's browser.
isAuthorized (resource)	ObBoolean_t isAuthorized() const ObResourceRequest &resource) returns ObTrue if the user is authorized to perform an operation for a particular resource; otherwise, it returns ObFalse. Parameters: resource: The resource object whose authorization is to be checked. Throws: An ObAccessException, if the authorization check cannot be completed for any reason.
isAuthorized (presource)	ObBoolean_t isAuthorized(const ObResourceRequest *presource) returns ObTrue if the user is authorized to request an operation for a particular resource; otherwise, it returns ObFalse. Parameters: presource: The resource object whose authorization is to be checked. Throws: An ObAccessException, if the authorization check cannot be completed for any reason.
isAuthorized (...res, parameters)	ObBoolean_t isAuthorized(const ObResourceRequest &res [const ObMap &parameters]) returns ObTrue if the user is authorized to request an operation for a particular resource; otherwise it returns ObFalse. Parameters: res: The resource object whose authorization is to be checked. ObMap &parameters: A list of name-value pairs that the Access Manager API will send in the request context object to the Access Server for authorization. The parameter argument is optional. When specified, the name-value pairs in the parameters are passed to the Access Server for authorization. Throws: An ObAccessException if the authorization check cannot be completed for any reason.
isAuthorized (...pRes, parameters)	ObBoolean_t isAuthorized(const ObResourceRequest &pRes [const ObMap &parameters]) returns ObTrue if the user is authorized to request an operation for a particular resource; otherwise it returns ObFalse. Parameters: pRes: The resource object whose authorization is to be checked. ObMap &parameters: A list of name-value pairs that the Access Manager API will send in the request context object to the Access Server for authorization. The parameter argument is optional. When specified, the name-value pairs in the parameters are passed to the Access Server for authorization. Throws: An ObAccessException if the authorization check cannot be completed for any reason.
logoff	void logoff() logs off the authenticated user and terminates the session.

4.7.6 ObConfig

ObConfig enables the application to initialize or shut down the Access Server or obtain AccessGate configuration data from the Access Server. For a list of AccessGate configuration parameters returned by ObConfig.getItem and ObConfig.getAllItems, see "Configuration Parameters" .

For a general discussion of ObConfig, see "ObAccessException" .

No constructors exist for the C++ implementation of the class ObAccess.ObConfig.

For a list of the messages thrown in response to errors by the C++ implementation of ObConfig, see "C-Family Status and Error Message Strings" .

4.7.6.1 Methods (ObConfig, C++)

Table 4-27 details the methods associated with ObConfig.

Table 4-27 ObConfig Methods (C++)

Method	Details
initialize	static void initialize(const char *installDir = NULL) initializes the AccessGate, including reading all AccessGate configuration parameters into the ObConfig structure. See "Configuration Parameters" . Parameters: installDir: A coded internal value provided for this parameter; otherwise, the value for the environment variable OBACCESS_INSTALL_DIR. Throws: An ObAccessException, if the user session object cannot be created, or if the OBACCESS_INSTALL_DIR is invalid.
shutdown	static void shutdown() disconnects the AccessGate from the Access Server, and releases memory and other resources.
getAllitems	static ObMap &getAllItems() reads all the configuration variables from the configuration file into an ObMap name:value list. See "Configuration Parameters" . Throws: An ObAccessException if an attempt is made to invoke the method before successful initialization takes place.
getSDKVersion	static const char *getSDKVersion() returns the SDK version as an internal value known to the API. Throws: An ObAccessException if an attempt is made to invoke the method before a successful initialization takes place.
getNAPVersion	static const char *getNAPVersion() returns, as an internal value known to the API, the version of the access control protocol being used by the API. Throws: An ObAccessException if an attempt is made to invoke the method before a successful initialization takes place.
getNumberOf Items	static int getNumberOfItems() returns the total number of items that can be extracted from the configuration file. Throws: An ObAccessException if an attempt is made to invoke the method before a successful initialization takes place.
getItem	static const char *getAction(const char* name) returns a string representing the name of a configuration item listed in "Configuration Parameters" . Parameters: name: The name of a configuration item. Throws: An ObAccessException if an attempt is made to invoke the method before a successful initialization takes place.

4.7.7 ObAccessException

The ObAccessException class enables you to trap errors generated in connection with the Access Manager API. The C++ implementation of ObAccessException enables you to return the full error message associated with an error code, or, in the case of the most recently generated error code, return up to five substrings from the full message so that you can embed them in custom error message text.

4.7.7.1 Constructors (ObAccessException, C++)

Table 4-28 lists the constructors for the C++ implementation of the ObAccessException class.

Table 4-28 ObAccessException Constructors (C++)

Key Parameter	Details
code	ObAccessException(ObAccessExceptionCode_t code, const char *p1 = NULL, const char *p2 = NULL, const char *p3 = NULL, const char *p4 = NULL, const char *p5 = NULL) constructs an exception in response to an error code. Parameters: code: The number corresponding to the error that has occurred. p1 to p5: Parameters that can be inserted into the message string, if the string permits variable content. Parameters are intended for internal use only.
other	ObAccessException(const ObAccessException &other) copies an existing exception. Parameters: other: The name of an existing exception.

4.7.7.2 Methods (ObAccessException, C++)

Table 4-29 lists the methods for the C++ implementation of ObAccessException.

Table 4-29 ObAccessException Methods (C++)

Parameter	Details
getCode	ObAccessExceptionCode_t get code returns the value of the last error code generated within the Access Manager API. (This is also the code that appears in the exception created by the API).
getParameter	const char *getParameter(int index) returns the substring that normally appears in the full error message at the location "%index." You can insert such a substring into custom message strings you have created. parameters: index: The index number of the location where the substring normally appears in the full error message generated by the API.
toString	const char *toString() returns the full error message string (including all applicable substrings) for the most recent error code generated within the API. To allow reporting of the message, do not free the return value.
getCodeString	const char *getCodeString(ObAccessExceptionCode_t code) returns the error message corresponding to the specified ObAccessExceptionCode_t error code. Since you specify the error code, this doesn't have to be the most recent error message generated by the API. Since the string is returned verbatim for the ObAccessGate.msg file, in which al the substrings are set to NULL, it does not contain current values for the substrings p1 to p5. To allow reporting of the message, do not free the return value. parameters: code: The ObAccessExceptionCode_t error code corresponding to the error message to be returned from ObAccessGate.msg.

4.7.8 ObDiagnostic (C++)

The ObDiagnostic class enables you to display diagnostic information such as the name and port of the Access Server, its location, the number of connections the AccessGate has with the Access Server, and so on. This class also displays diagnostic information about the directory that is associated with the Access Server.

Example:

class ObDiagnostic {
public:
 OBDLLEXPORT static const ObMap* getServerDiagnosticInfo() ;
 OBDLLEXPORT static const ObMap* getDirectoryDiagnosticInfo() ;
 OBDLLEXPORT static const ObMap* getClientDiagnosticInfo() ;
 };

4.7.8.1 Methods (ObDiagnostic, C++)

Table 4-30 lists the methods for the C++ implementation of ObDiagnostic.

Table 4-30 ObDiagnostic Methods (C++)

Parameter	Details
getServerDiagnosticInfo()	This parameter returns the following items on the ObMap structure: Access Server host name Access Server port Number of connections with the Access Server established by the current WebGate Access Server state (up or down) Access Server creation date and time (based on when it was installed) Access Server installation directory Maximum number of threads allowed in this Access Server.
getDirectoryDiagnosticInfo()	This parameter returns the following items in an ObMap structure: Directory type (Config, User, Policy) Directory host Directory port Directory state (up or down) Priority (primary or secondary) Mode (open or SSL) Size limit (the maximum number of search results) Time limit (the timeout threshold) Login DN Creation date and time based on when the Access server establishes connection with the Directory Server. (If you restart either server, the creation date and time change.)

4.8 C Implementation Details

The functions belonging to the "pseudo-classes" in the C implementation of the Access Manager API have been systematically named so as to parallel the naming scheme used by the paradigmatic C++ implementation of the Access Manager API. For example, the C function "ObMap_get" corresponds to the C++ method "ObMap.get," and "ObUser_isAuthorized" in C corresponds to "ObUserSession.isAuthorized"in C++. In fact, the "class member functions" in the C implementation are merely opaque pointers to methods in the C++ implementation.

The header file "obaccess_api_c.h" details the members of the "pseudo classes" belonging to the C implementation of the Access Manager API. It can be found at the following location:

SDK_install_dir\include.

For a comparative discussion of the implementations of the Access Manager API, see "About the Access Manager API" .

Note:

For the C-language implementation of the Access Manager API, you must "clean up" structures that are no longer needed by invoking the appropriate "_free" function for structures when they are no longer needed. See "About Memory Management" .

4.8.1 ObMap_t

The ObMap_t "pseudo class" provides list structures to hold the various sets of name:value pairs used by the Access Manager API. In addition to creating such structures, you can write to them, retrieve information from them, determine how many item pairs they contain, and copy their contents. Another function exists to deallocate the memory used by a list structure. To avoid memory leaks, use this destructor whenever you no longer need a list.

For a general discussion of the ObMap class, see "ObMap" .

For a list of the messages thrown in response to errors by the C implementation of ObMap_t, see "C-Family Status and Error Message Strings" .

4.8.1.1 Functions (ObMap_t, C)

Table 4-31 details the functions associated with ObMap_t.

Table 4-31 ObAccess.ObMap_t Pseudo-Class Functions (C)

Function	Details
ObMap_new	ObMap_t ObMap_new() creates an empty list with a name specified by the user. (This function serves as the constructor for this pseudo class). Returns: A list to hold name:value pairs.
ObMap_get	const char *ObMap_get(ObMap_t map, const char *name) returns a string value in response to a specified name from a specified list. Parameters: map: A pointer to a list. name: The name half of the name:value pair in a specified list for which a corresponding value is to be returned.
ObMap_put	void ObMap_put(ObMap_t map, const char *name, const char *val) stores a name:value pair in a specified list. If the name already exists in the list, its value is replaced. Parameters: map: The name of the list. name: A string representing the name of the item to be stored. val: A string representing the value to be stored.
ObMap_size	int ObMap_size(ObMap_t map) returns a number of name:value pairs in a specified list. Parameters: map: The name of the list.
ObMap_copy	ObMap_t ObMap_copy(ObMap_t map) makes a copy of a specified list. Parameters: map: The name of the list. Returns: A pointer to the copy.
ObMap_free	void ObMap_free(ObMap_t *pMap) frees the memory occupied by a specified list. (This function serves as the destructor for this pseudo class). Parameters: pMap: Pointer to the list location.

4.8.2 ObMapIterator_t

The ObMapIterator_t "pseudo class" provides functions that enable you to place a pointer within a list structure, so as to count the number of items in the list. Other functions enable you to "step through" a list by pointing to successive items in the list, determine when the end of a list has been reached, and deallocate the memory used by the pointer.

For a general discussion of the ObMapIterator class, see "ObMapIterator" .

For a list of the messages thrown in response to errors by the C implementation of ObMapIterator_t, see "C-Family Status and Error Message Strings" .

4.8.2.1 Functions (ObMapIterator_t, C)

Table 4-32 details the functions for ObMapIterator_t.

Table 4-32 ObAccess.ObMapIterator_t Pseudo-Class Functions (C)

Function	Details
ObMapIterator_ new	ObMapIterator_t ObMapIterator_new(ObMap_t map) creates an iterator for a specified list and points it initially at the first name:value pair in the list. (This function serves as the constructor for this pseudo class). Parameters: map: The name of the list. Returns: A pointer to the list.
ObMapIterator_ hasMore	ObBoolean_t ObMapIterator_hasMore(ObMapIterator_t iter) watches for the end of the list, returning ObTrue if name:value pairs exist beyond the current position of the iterator. It returns ObFalse when the iterator reaches the end of the list. Parameters: iter: A pointer to the next item in the list.
ObMapIterator_ next	void ObMapIterator_next(ObMapIterator_t iter, const char **name, const char **val) returns a text string representing the name:value pair existing at the current iterator position in the list. This function then moves the iterator to the following pair. Technically speaking, the "const char **" parameters are pointers to variables that will be set to pointers to character strings. Parameters: iter: A pointer to the next item in the list. name: The address of the variable that will receive the pointer to the character string represented by "name." val: The address of the variable that will receive the pointer to the character string represented by "val."
ObMapIterator_ free	void ObMapIterator_free(ObMapIterator_t *pIter) frees the memory used by the list. (This function serves as the destructor for this pseudo class). Parameters: pIter: A pointer to the list location.

4.8.3 ObAuthenticationScheme_t

The ObAuthenticationScheme "pseudo class" enables the creation of and interaction with the structures used to authenticate users. For a general discussion of ObAuthenticationScheme, see "ObAuthenticationScheme" .

For a list of the messages thrown in response to errors by the C implementation of ObAuthenticationScheme_t, see "C-Family Status and Error Message Strings" .

4.8.3.1 Functions (ObAuthenticationScheme_t, C)

Table 4-33 details the functions belonging to ObAuthenticationScheme_t.

Table 4-33 ObAccess.ObAuthenticationScheme_t Functions (C)

Function	Details
ObAuthn_ new	ObAuthnScheme_t ObAuthn_new(ObResourceRequest_t resource) constructs an ObAuthenticationScheme object that returns information on the specified ObResourceRequest, such as the challenge method required for authentication. Parameters: resource: The resource request for which the authentication scheme object is to be created.
ObAuthn_ getName	const char *ObAuthn_getName(ObAuthnScheme_t scheme) returns the display name assigned to the authentication scheme during configuration. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ getMask	int ObAuthn_getMask(ObAuthnScheme_t scheme) returns the mask byte indicating the authorization challenge method and whether credentials must be sent over a secure connection. For details on the mask byte, see "ObAuthenticationScheme" . Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ requires Secure Transport	ObBoolean_t ObAuthn_requiresSecureTransport (ObAuthnScheme_t scheme) returns ObTrue if the specified authentication scheme requires credentials to be sent over a secure (SSL or TLS) connection; otherwise, it returns ObFalse. If a secure connection is required, a redirectUrl must be specified during authenticate scheme configuration. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ isBasic	ObBoolean_t ObAuthn_isBasic(ObAuthnScheme_t scheme) returns ObTrue if the challenge method for the specified authentication scheme is HTTP BASIC. (In other words, it requires only a userid and password as credentials). Otherwise, it returns ObFalse. Parameters: scheme: A pointer to he specified authentication scheme.
ObAuthn_ isCertificate	ObBoolean_t ObAuthn_isCertificate(ObAuthnScheme_t scheme) returns ObTrue if the authentication scheme requires a digital security certificate; otherwise, it returns ObFalse. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ isForm	ObBoolean_t ObAuthn_isForm(ObAuthnScheme_t scheme) returns ObTrue if the authentication scheme requires customer-defined credential fields in an HTML login form; otherwise, it returns ObFalse. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ isNone	ObBoolean_t ObAuthn_isNone(ObAuthnScheme_t scheme) returns ObTrue if no credentials are required for authentication. If credentials are required, it returns ObFalse. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ getLevel	int ObAuthn_getLevel(ObAuthnScheme_t scheme) returns a numeric representation of the authentication strength, as specified during authentication scheme configuration. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ getRedirectUrl	const char *ObAuthn_getRedirectUrl(ObAuthnScheme_t scheme) returns a URL representing the location where secure authentication is to be performed. If secure authentication is not required by the specified authentication scheme, this value is set to NULL. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ getChallenge Parameter	const char *ObAuthn_getChallengeParameter (ObAuthnScheme_t scheme, const char *parameterName) returns a value corresponding to a specified challenge parameter associated with a specified authorization scheme. Parameters: scheme: A pointer to the authentication scheme. parameterName: The name of the challenge parameter.
ObAuthn_ getAll Challenge Parameters	ObMap_t ObAuthn_getAllChallengeParameters (ObAuthnScheme_t scheme) returns a name:value list containing all the challenge parameters specified for the specified authentication scheme. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_ getNumberOf Challenge Parameters	int ObAuthn_getNumberOfChallengeParameters (ObAuthnScheme_t scheme) returns the number of challenge parameters assigned to the specified authentication scheme. Parameters: scheme: A pointer to the specified authentication scheme.
ObAuthn_free	void ObAuthn_free(ObAuthnScheme_t *pScheme) frees the memory used by the specified authentication scheme, and sets the pointer value to NULL. Parameters: pScheme: A pointer to the specified authentication scheme.

4.8.4 ObResourceRequest_t

The ObResourceRequest_t "pseudo class" enables creation of and interaction with the structures that represent user requests to access resources. For a general discussion of ObResourceRequest, see "ObResourceRequest" .

For a list of the messages thrown in response to errors by the C implementation of ObResourceRequest_t, see "C-Family Status and Error Message Strings" .

4.8.4.1 Functions (ObResourceRequest_t, C)

Table 4-34 details the functions associated with ObResourceRequest_t.

Table 4-34 ObAccess.ObResourceRequest_t Pseudo-Class Functions (C)

Function	Details
ObResource Request_new	ObResourceRequest_t ObResourceRequest_new(const char *resType, const char *resource, const char *operation, ObMap_t parameters) constructs an ObResourceRequest using the specified resource type, resource name, operation, and parameters. Parameters: resType: The resource type. (If resType is NULL, HTTP is used by default). resource: A pointer to the resource. operation: The operation to be performed against the resource. parameters: A pointer to a list of parameters associated with the resource request. Returns: Pointer to a structure holding the object.
ObResource_ getResource Type	const char *ObResource_getResourceType (ObResourceRequest_t resource) returns the resource type for the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ getResource	const char *ObResource_getResource (ObResourceRequest_t resource) returns the name of the resource being requested through the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ getOperation	const char *ObResource_getOperation (ObResourceRequest_t resource) returns the name of the operation to be invoked against the resource through the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ getParameters	const ObMap_t ObResource_getParameters (ObResourceRequest_t resource) returns a pointer to the name:value list of parameters associated with the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ getNumberOf Parameters	int ObResource_getNumberOfParameters (ObResourceRequest_t resource) returns the number items in the name:value parameter list associated with the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ isProtected	ObBoolean_t ObResource_isProtected (ObResourceRequest_t resource) returns ObTrue if the resource is protected by Access System policies. Otherwise, it returns ObFalse. Parameters: resource: A pointer to the resource being requested.
ObResource_ free	ObBoolean_t isCertificate() const ObResourceRequest_t *resource) frees the memory used by the resource object and sets to NULL the pointer to the list of parameters associated with the specified resource request. Parameters: resource: A pointer to the resource being requested.
ObResource_ getAuthorization Parameters	ObMap_t ObResource_getAuthorizationParameters (ObResourceRequest_t res) returns a list of parameters for the particular authorization scheme associated with the specified resource request. All the parameter names are returned with the associated values set to NULL. Once the returned value is no longer in use, you must use ObMap_free() to deallocate the ObMap_t object returned by getAuthorizationParameters(). Returns: A list of required credentials.
ObResource_ getNumberOf Parameters	int ObResource_getNumberOfAuthorizationParameters (ObResourceRequest_t res) returns the number of context parameters required for the specified resource request.
ObResource_free	void ObResource_free(ObResourceRequest_t *pRes) deallocates the memory for the specified ObResourceRequest structure.

4.8.5 ObUserSession_t

The ObUserSession_t pseudo class enables creation of and interaction with structures representing sessions for users who have successfully completed Access System authentication. For a general discussion of ObUserSession, see "ObUserSession" .

For a list of the messages thrown in response to errors by the C implementation of ObUserSession_t, see "C-Family Status and Error Message Strings" .

4.8.5.1 Functions (ObUserSession, C)

Table 4-35 details the functions associated with ObUserSession:

Table 4-35 ObAccess.ObUserSession_t Pseudo-Class Functions (C)

Function	Details
ObUserSession_ authenticate	ObUserSession_t ObUserSession_authenticate (ObResourceRequest_t resource, ObMap_t credentials, const char *location) creates a user session object. Parameters: resource: The resource request object for which the user is being authenticated. credentials: User credentials. location: The location of the user, if it needs to be specified. A valid DNS name or IP address can be used to specify the location of the user's machine. Returns: A user session object. Exception: An internally generated ObAccessException if the user session object cannot be created for some reason or the resource object is NULL.
ObUserSession_ fromToken	ObUserSession_t ObUserSession_fromToken(const char *sessionToken) creates a user session object. Used when a session token is needed immediately. Parameters: sessionToken: A session token, which is parsed to obtain the associated credentials and user location information. Returns: A user session object. Exception: An internally generated ObAccessException if the user session object cannot be created for some reason or the session token is NULL.
ObUserSession_fromTokenwithLazyLoad	ObUserSession_t ObUserSession_fromTokenwithLazyLoad(const char *sessionToken,bool lazyload) creates a user session on demand. Parameters: lazyload: This flag, if true, indicates that the session token is not to be loaded immediately. Relies on getUserIdentity(), getLocation(), getLevel(), getStartTime(), and getEndTime() functions to make calls if the session token information is invalid, and lazyload loads the token on demand. Returns: A user session object. Throws: An internally generated ObAccessException if the user session object cannot be created for some reason or the session token is NULL.
ObUser_get UserIdentity	const char *ObUser_getUserIdentity(ObUserSession_t user) Parameters: user: A pointer to the user session object.
ObUser_get Location	const char *ObUser_getLocation(ObUserSession_t user) returns the IP address of the user's web browser. Parameters: user: A pointer to the user session object. Returns: IP address of the user's web browser.
ObUser_get Action	const char *ObUser_getAction(ObUserSession_t user, const char *actionType, const char *name) returns a value corresponding to the specified action name and action type for the specified user session. Parameters: user: A pointer to the user session object. actionType: The type of action for which the corresponding value is returned. (If this is left NULL, the default is headerVar). name: The name of the action for which the corresponding value is to be returned.
ObUser_get Actions	const ObMap_t ObUser_getActions(ObUserSession_t user, const char *actionType) returns a pointer to list of action name:value pairs corresponding to the specified action type for the specified user session. Parameters: user: A pointer to the user session object. actionType: The type of action for which the list is returned. If actionType is left NULL, the default is headerVar.
ObUser_get ActionTypes	const **getActionTypes(ObUserSession_t user) returns an array of pointers to strings. This array, which is terminated by a NULL pointer, represents all the action types associated with the specified user session. Parameters: user: A pointer to the user session object.
ObUser_get Numberof Actions	int getNumberOfActions(ObUserSession_t user, const char *actionType) returns the number of actions of the specified type that are associated with the specified user session. Parameters: user: A pointer to the user session object. actionType: The name of the action type for which a count of actions is needed. If this is left NULL, the default is headerVar.
ObUser_get Level	int ObUser_getLevel(ObUserSession_t user) returns a number representing the authentication level of the authentication scheme associated with the specified user session. Parameters: user: A pointer to the user session object.
ObUser_get StartTime	int ObUser_getStartTime(ObUserSession_t user) returns the number of seconds between midnight January 1, 1970 and the initial time the user was authenticated for the specified session. This value is used to determine session expiration. Parameters: user: A pointer to the user session object.
ObUser_get LastUseTime	int ObUser_getLastUseTime(ObUserSession_t user) returns the number of seconds between midnight January 1, 1970 and the most recent time the user was authenticated for the specified session. This value is used to determine expiration for an idle session. Parameters: user: A pointer to the user session object. Returns: A numeric value for the time.
ObUser_get Status	ObUserStatus_t ObUser_getStatus(ObUserSession_t user) returns one of the ObUserStatus_t values describing the status of the session, such as logged out, logged in, login failed, or expired. Parameters: user: A pointer to the user session object.
ObUser_get Error	ObUserError_t ObUser_getError(ObUserSession_t user) returns one of the ObUserError_t error values, as determined by the most recent authentication or authorization failure for the specified user session. Parameters: user: A pointer to the user session object.
ObUser_get ErrorMessage	const char *ObUser_getErrorMessage(ObUserSession_t user) returns a detailed error message associated with the most recent authentication or authorization failure for the specified user session. The text of this message is derived by the Access API and is not intended to be changed by the user. Parameters: user: A pointer to the user session object.
ObUser_is Authorized	ObBoolean_t ObUser_isAuthorized(ObUserSession_t user, ObResourceRequest_t resource) returns ObTrue if the user is authorized to request an operation for a particular resource; otherwise, it returns ObFalse. Parameters: user: A pointer to the user session object. resource: The name of the resource request object whose authorization is to be checked.
ObUser_is AuthorizedWith Parameters	ObBoolean_t ObUser_isAuthorizedWithParameters (ObUserSession_t user, ObResourceRequest_t res, ObMap_t parameters) returns ObTrue if the user is authorized to request an operation for a particular resource. Otherwise, it returns ObFalse. Parameters: user: A pointer to the user session object. resource: The name of the resource request object whose authorization is to be checked. parameters: Any data associated with the resource request. This parameter is optional.
ObUser_get SessionToken	const char *ObUser_getSessionToken(ObUserSession_t user) returns from a session token saved on the user's hard disk an ASCII string containing information on the specified user session. Parameters: user: The name of the user session object.
ObUser_set Location	void ObUser_setLocation(ObUserSession_t user, const char *location) sets the location of the user's browser. Parameters: user: A pointer to the user session object. location: A DNS or IP address representing the location of the user's browser.
ObUser_logoff	void ObUser_logoff(ObUserSession_t user); logs off the authenticated user and terminates the specified user session. Parameters: user: A pointer to the user session object.
ObUser_free	void ObUser_free(ObUserSession_t *puser) frees the memory assigned for the list and sets the list pointer to NULL. Parameters: puser: A pointer to the user session object.

4.8.6 ObConfig_t

The ObConfig_t pseudo class enables your application to initialize or shut down the Access Server. You can also obtain AccessGate configuration data from the Access Server. See "Configuration Parameters" .

For a general discussion of ObConfig, see "ObConfig" .

For a list of the messages thrown in response to errors by the C implementation of ObConfig_t, see "C-Family Status and Error Message Strings" .

4.8.6.1 Functions (ObConfig, C)

Table 4-36 lists the functions and details for the ObConfig pseudo class.

Table 4-36 ObAccess.ObConfig_t Pseudo-Class Functions (C)

Function	Details
ObConfig_ initialize	void ObConfig_initialize(const char *installDir) initializes the Access Manager API. This includes reading all the configuration parameters listed in "Configuration Parameters" . Parameters: installDir: The root of the Access Manager API installation. If no coded value is provided for this parameter, the value from the environment variable OBACCESS_INSTALL_DIR is used. Throws: An internally generated ObAccessException if the configuration object cannot be created for some reason, or if the OBACCESS_INSTALL_DIR is invalid.
ObConfig_ shutdown	void ObConfig_shutdown() disconnects the AccessGate from the Access Server and releases memory and other resources used by the AccessGate and the Access Manager API.
ObConfig_ getAllitems	ObMap_t ObConfig_getAllItems() returns a pointer to the list of all the AccessGate configuration items listed in "Configuration Parameters" . Throws: An internally generated ObAccessException if an attempt is made to invoke the method before the Access Manager SDK has been successfully initialized.
ObConfig_ getNumber OfItems	int ObConfig_getNumberOfItems() returns the number of items in the AccessGate configuration file. Throws: An internally generated ObAccessException if an attempt is made to invoke the method before the Access Manager SDK has been successfully initialized.
ObConfig_ getItem	const char *ObConfig_getItem(const char* name) returns a value corresponding to a name specified from the list of AccessGate configuration items. Parameters: name: The name of the item whose value is to be extracted. Throws: An internally generated ObAccessException if an attempt is made to invoke the method before the Access Manager SDK has been successfully initialized.
ObConfig_ getSDK Version	const char *ObConfig_getSDKVersion() returns the version of the Access Manager SDK as an internal value known to the API.

4.8.7 ObAccessException_t

ObAccess exceptions occur when the Access API detects unexpected, unrecoverable problems such as not being able to connect to an Access Server. For a general discussion of ObAccessException, see "ObAccessException" .

4.8.7.1 C-language Error Handlers

For an AccessGate written using the C implementation of the Access Manager API, you must write an ObAccessExceptionHandler_t function, which is called when an ObAccessException occurs. Otherwise, the C implementation of the API simply will not catch exceptions. Thus, if you use the C API to construct an object, and an exception occurs, that object will be returned empty, since no exception handler exists to report and otherwise handle the exception.

Note:

If the calling program is written in C++, the calling program, rather than the AccessGate, which is written without any exception handler in C, might catch some exceptions.

The C version of ObAccessExceptionHandler_t prior to version 6 has been deprecated, because it passed only the exception code, not the full exception. Consequently, "ObAccessException_getCodeString" could not insert any exception parameter data into the exception message.

A new version of the exception handler for AccessGates using the C implementation of the Access Manager API. This new version, ObAccessExceptionHandler2_t, passes the entire exception, so that ObAccessException_toString can display the exception message, complete with embedded parameters. When you create AccessGates, be sure to use ObAccessExceptionHandler2_t instead of the previous version.

The preferred way to write an exception handler is:

void myExceptionHandler(ObAccessException e){
  printf("EXCEPTION: %s\n", ObAccessException_toString(e));
  exit(1);
}

The following line then informs the API (in other words, it registers the callback function) as to the name of the exception:

ObAccessException_setHandler2(myExceptionHandler);

4.8.7.2 Functions (ObAccessException, C)

Table 4-37 lists the functions and details for the C implementation of the ObAccessException class.

Table 4-37 ObAccess.ObAccessException_t Pseudo-Class Functions (C)

Parameter	Details
ObAccess Exception Handler2_t	typedef void (*ObAccessExceptionHandler2_t) (ObAccess ExceptionCode_t exception) This is not actually a function. Rather, it defines a pointer to a C++ function used within the API. You implement this definition with your own code. See "C-language Error Handlers" . Parameters: None. Rather, the pointer name you specify is passed to the ObAccessException_setHandler2 function and used automatically by other functions when exceptions occur. The exception argument that appears in this function is the exception generated by the API.
ObAccess Exception_ setHandler2	void ObAccessException_setHandler(ObAccessException Handler2_t handler) connects exception handling to whatever activities the user has chosen to include in the user-written exception handler. Parameters: handler: A pointer to the user-written exception handler function.
ObAccess Exception_ getCode	ObAccessExceptionCode_t ObAccessException_getCode (ObAccessException_t e) returns the error code associated with the full exception generated by the API. Parameters: e: The exception provided by the API.
ObAccess Exception_ getParameter	const char *ObAccessException_getParameter (ObAccessException_t e, int which) returns a text substring corresponding to the specified exception and the index of the substring (1 to 5). Parameters: e: The exception provided by the API. which: The index of the parameter (1 to 5), for which a text string equivalent is needed.
ObAccess Exception_ toString	const char *ObAccessException_toString(ObAccessException_t e) returns the full error message string (including all applicable substrings) for the most recent error code generated within the API. To allow reporting of the message, do not free the return value. Parameters: e: The exception provided by the API.

4.8.8 ObDiagnostic (C)

The ObDiagnostic class enables you to display diagnostic information such as the name and port of the Access Server, its location, the number of connections the AccessGate has with the Access Server, and so on. This class also displays diagnostic information about the directory that is associated with the Access Server.

Example:

OBDLLEXPORT const ObMap_t ObDiagnostic_getServerDiagnosticInfo();
OBDLLEXPORT const ObMap_t ObDiagnostic_getDirectoryDiagnosticInfo();
OBDLLEXPORT const ObMap_t ObDiagnostic_getClientDiagnosticInfo();

4.8.8.1 Methods (ObDiagnostic, C)

Table 4-38 lists the methods for the C implementation of ObDiagnostic.

Table 4-38 ObDiagnostic Methods (C)

Parameter	Details
getServerDiagnosticInfo()	This parameter returns the following items on the ObMap structure: Access Server host name Access Server port Number of connections with the Access Server established by the current WebGate Access Server state (up or down) Access Server creation date and time (based on when it was installed) Access Server installation directory Maximum number of threads allowed in this Access Server.
getDirectoryDiagnosticInfo()	This parameter returns the following items: Directory type (Config, User, Policy) Directory host Directory port Directory state (up or down) Priority (primary or secondary) Mode (open or SSL) Size limit (the maximum number of search results) Time limit (the timeout threshold) Login DN Creation date and time based on when the Access server establishes connection with the Directory Server. (If you restart either server, the creation date and time change.)

4.9 C# Implementation Details

The following sections describe the C# (.NET) managed code implementation for the Access Manager API.

For the most part, the classes in the C# version follow the pattern established by the Java implementation of the Access Manager API. However, the C# version departs from the Java paradigm in the following significant ways:

• The enumerators used to specify various conditions are wrapped by managed classes

• The class ObMap is wrapped by ObDictionary

• The class ObMapIterator is wrapped by ObDictionaryEnumerator

• Certain method names have been changed to match the naming conventions used for .NET properties.

  Note:

  A .NET property resembles a Java member variable in that both enable the user to read and write values to an object, but a .NET property is implemented using the get and set methods.

• The Mgd suffix has been appended to all the managed classes. Thus, ObAuthenticationScheme. ObResourceRequest, ObUserSession, ObConfig, and ObAccessException become, respectively, ObResourceRequestMgd, ObUserSessionMgd, ObConfigMgd, and ObAccessExceptionMgd.

• In contrast to the C and C++ development-language interfaces, but like Java, the C# environment features a garbage collection service which automatically cleans up objects when they are no longer needed. Therefore, you do not invoke the delete or _free methods to clean up unused structures. See "About Memory Management" .

The listings in this document can also be found in the header file obaccess_api_mgd.h, which resides in the following location:

SDK_install_dir/include

The classes common to both the Access Manager API and Policy Manager API are listed in the file obaccess_api_common_mgd.h, which is also in the directory: SDK_install_dir/include.

4.9.1 ObDictionary

ObDictionary provides hashtable into which key-and-value pairs (the .NET equivalent of the name:value pairs in Java hashtables) can be written. The class also provides methods for retrieving information from the dictionary hashtable, determining the number of items in that list, and copying the list.

The ObDictionary class is derived from the .NET IDictionary class and corresponds to the ObMap class in the Java and C++ implementations of the Access Manager API. It also corresponds to the ObMap_t "pseudo class" in the C implementation of the Access Manager API. For a general discussion of the ObMap class, see "ObMap" .

For a list of the messages thrown in response to errors by the C# implementation of ObDictionary, see "C-Family Status and Error Message Strings" .

4.9.1.1 Constructors (ObDictionary, C#)

Table 4-39 provides details for the ObDictionary constructor.

Table 4-39 ObDictionary Constructors (C#)

Key Parameter	Details
(none)	ObDictionary()
map	ObDictionary(const ObMap &map) using a name specified by the user, creates a copy of an existing list in the form of an ObDictionary object. Parameters: map: The name of the list to be copied.

4.9.1.2 Methods (ObDictionary, C#)

Table 4-40 presents the ObDictionary methods and associated details

Table 4-40 ObDictionary Methods (C#)

Method	Details
get_Item	__property virtual System::Object *get_Item(System::Object *key) returns a string value that corresponds to a name supplied from a dictionary list. If the name is not found in the list, NULL is returned. The item is returned as the base class object. The user is responsible for casting this item to an appropriate form. Parameters: key: The key (or name) in a dictionary list for which a value is to be returned.
add	virtual void Add (System::Object *key, System::Object *value) stores a key-and-value pair in the list. If the name is already in the list, its value is replaced; otherwise the pair is added. Parameters: key: The name half of the item to be stored in the dictionary. value: The value half of the item to be stored.
get_Count	__property int get_Count() returns the total number of key-and-value pairs in the list.
Clone	Object *Clone() makes a copy of ObDictionary. Returns: A pointer to the copy.

4.9.2 ObDictionaryEnumerator

You use the ObDictionaryEnumerator class to locate the entries in a dictionary hashtable. You can also determine the number of items in that list or retrieve a key-and-value pair from a specific position in that list.

For the C++ managed classes version of the Access Manager API, the ObMapIterator class is implemented as the ObDictionaryEnumerator class, which is derived from the IDictionaryEnumerator class in the .NET Framework class library. Instead of the name:value pairs found in a Java hashtable, an ObDictionaryEnumerator dictionary contains key-and-value pairs.

For a general discussion of the ObMapIterator class, see "ObMapIterator" .

For a list of the messages thrown in response to errors by the C# implementation of ObDictionaryEnumerator, see "C-Family Status and Error Message Strings" .

4.9.2.1 Constructors (ObDictionaryEnumerator, C#)

Table 4-41 presents details for the ObDictionaryEnumerator constructor.

Table 4-41 ObDictionaryEnumerator Constructors (C#)

Key Parameter	Details
dictionary	ObDictionaryEnumerator(ObDictionary *dict) creates an enumerator, which initially points to the first item in a specified ObDictionary hashtable. MoveNext and other ObDictionaryEnumerator methods make use of this structure. Parameters: dict: The name of the ObDictionary hashtable you want to step through.

4.9.2.2 Methods (ObDictionaryEnumerator, C#)

Table 4-42 lists the ObDictionaryEnumerator methods and associated details.

Table 4-42 ObDictionaryEnumerator Methods (C#)

Method	Details
MoveNext	bool MoveNext() watches for the end of the list. It returns ObTrue when additional key-and-value pairs exist in the dictionary list. It returns ObFalse when it reaches the final item in the list.
get_Current	__property Object *get_Current() returns an object that represents the dictionary entry currently referenced by the enumerator.
get_Entry	__property DictionaryEntry get_Entry() returns a dictionary key-and-value pair for the current dictionary entry.
get_Key	__property Object *get_Key() returns the key (name) value from the current dictionary entry. The user must then cast the returned object to the appropriate class.
get_Value	__property Object *get_Value() returns the value from the current dictionary entry. The user must then cast the returned object to the appropriate class.
Reset	void Reset() points the enumerator to the first entry in the dictionary list.

4.9.3 ObAuthenticationSchemeMgd

ObAuthenticationSchemeMgd structures enable users to store, pass, and retrieve information related to authentication schemes. An authentication scheme specifies how a user is challenged for a set of credentials. For a general discussion of the ObAuthenticationScheme class, see "ObAuthenticationScheme" .

For a list of the messages thrown in response to errors by the C# implementation of ObAuthenticationSchemeMgd, see "C-Family Status and Error Message Strings" .

4.9.3.1 Constructors (ObAuthenticationSchemeMgd, C#)

Table 4-43 provides details for the ObAuthenticationSchemeMgd constructor.

Table 4-43 ObAuthenticationSchemeMgd Constructors (C#)

Key Parameter	Details
pRes	ObAuthenticationSchemeMgd(ObResourceRequestMgd *pRes) creates an ObAuthenticationScheme object for the specified ObResourceRequest. Parameters: pRes: A pointer to the resource request for which the authentication scheme object is being constructed. Returns: A structure holding the object.

4.9.3.2 Methods (ObAuthenticationSchemeMgd, C#)

Table 4-44 lists the methods and associated details for the ObAuthenticationSchemeMgd class.

Table 4-44 ObAuthenticationSchemeMgd Methods (C#)

Method	Details
get_Name	__property System::String *get_Name() returns the display name assigned to the authentication scheme.
get_Mask	__property int get_Mask() returns the mask byte defining the security level of the authentication scheme.
get_Requires Secure Transport	__property bool get_RequiresSecureTransport() returns ObTrue if the authentication scheme requires an SSL client connection; otherwise, it returns ObFalse. When the return flag is ObTrue, a redirectUrl is required to implement Secure Transport.
get_IsBasic	__property bool get_IsBasic() returns ObTrue if the authentication scheme requires only a "HTTP basic" challenge method (in other words, it requires only a userid and password); otherwise it returns ObFalse.
get_IsCertificate	__property bool get_IsCertificate() returns ObTrue if the authentication scheme requires a digital security certificate; otherwise it returns ObFalse.
get_IsForm	property bool get_IsForm() returns ObTrue if the authentication scheme uses "HTML form" login (in other words, it uses customer-defined credential fields); otherwise it returns ObFalse.
get_IsNone	__property bool get_IsNone() returns ObTrue if no credentials are required for authentication. If credentials are required, it returns ObFalse.
get_Level	__property int get_Level() returns a number representing the level of authentication strength, as specified during authentication scheme configuration.
get_RedirectUrl	__property System::String *get_RedirectUrl() returns a string representing the URL to which clients are redirected for Secure Transport authentication.
getChallenge Parameter	System::String *getChallengeParameter(System::String *parameterName) returns the value for a parameter corresponding to the current challenge method. For instance, the creds parameter for the form challenge method retrieves a space-separated list of context-dependent login requests. You must parse this list to obtain the individual parameter names. Parameters: parameterName: The name of the parameter corresponding to the current challenge method.
get_AllChallenge Parameters	__property ObDictionary *get_AllChallengeParameters() returns an ObDictionary list containing a key-and-value pair for each of challenge parameter assigned to the authentication scheme.
get_NumberOf Challenge Parameters	__property int get_NumberOfChallengeParameters() returns the total number of challenge parameters assigned to the authentication scheme during configuration.
Clone	Object* Clone() crates a copy of the specified authentication scheme structure.

4.9.4 ObResourceRequestMgd

The constructors and methods for the ObResourceRequestMgd class enable creation of and interaction with the structures that represent user requests to access resources. For a general discussion of the ObResourceRequest class, see "ObResourceRequest" .

For a list of the messages thrown in response to errors by the C# implementation of ObResourceRequestMgd, see "C-Family Status and Error Message Strings" .

4.9.4.1 Constructors (ObResourceRequestMgd, C#)

Table 4-45 lists the ObResourceRequestMgd constructors and associated details.

Table 4-45 ObResourceRequestMgd Constructors (C#)

KeyParameter	Details
op	ObResourceRequestMgd(System::String *resType, System::String *res, System::String *op) constructs an ObResourceRequest object. Parameters: resType: The resource type. (If resType is NULL, HTTP is used as a default.) res: The name of the resource. op: The operation to be performed. Returns: A structure representing the ObResourceRequest object.
parameters	ObResourceRequestMgd(System::String *resType, System::String *res, System::String *op, ObDictionary *parameters) constructs an ObResourceRequest object. Parameters: resType: The resource type. (If resType is NULL, HTTP is used as a default.) res: The name of the resource. op: The operation to be performed. parameters: A pointer to a list of parameters to be used. Returns: A structure representing the object.

4.9.4.2 Methods (ObResourceRequestMgd, C#)

Table 4-46 lists the methods and associated details belonging to ObResourceRequestMgd.

Table 4-46 ObResourceRequestMgd Methods (C#)

Method	Details
get_Resource Type	__property System::String *get_ResourceType() returns a string representing the resource type for the request.
get_Resource	__property System::String *get_Resource() returns the resource name for the request.
get_Operation	__property System::String *get_Operation() returns the name of the requested operation.
get_Parameters	__property ObDictionary *get_Parameters() returns a pointer to the first key-and-value pair in a list of parameters.
get_Number OfParameters	__property int get_NumberOfParameters() returns the number of pairs in the list.
get_Is Protected	__property bool get_IsProtected() returns ObTrue if the resource is protected by Access System policies; otherwise, it returns ObFalse. Throws: an ObAccessException in response to a fatal error such as failure to connect with the Access Server.
get_ Authorization Parameters	__property ObDictionary *get_AuthorizationParameters() when an IsAuthorized response includes a list of required context data, the list is cached in the ObResourceRequest object specified by the isAuthorized() call. An AccessGate can get the list through the get_AuthorizationParameters method. The AccessGate can add the appropriate values and pass the ObDictionary into a subsequent isAuthorized call. The caller is responsible for using delete to deallocate the ObDictionary object returned by get_AuthorizationParameters. Returns: List of key-and-value pairs with null values.
get_NumberOf Authorization Parameters	__property int get_NumberOfAuthorizationParameters() returns the number of required context data items.

4.9.5 ObUserSessionMgd

ObUserSession enables creation of and interaction with structures that represent sessions for users who have completed authentication successfully. For a general discussion of ObUserSession, see "ObUserSession" .

For a list of the messages thrown in response to errors by the C# implementation of ObUserSessionMgd, see "C-Family Status and Error Message Strings" .

4.9.5.1 Constructors (ObUserSessionMgd, C#)

Table 4-47 presents ObUserSessionMgd constructor details.

Table 4-47 ObUserSessionMgd Constructors (C#)

Key Parameter	Details
sessionToken	UserSessionMgd(System::String *sessionToken) creates a user session object immediately. Parameters: sessionToken: An ASCII text string that is parsed to obtain the credentials and location information. Returns: A structure holding a user session object. Throws: An ObAccessException if the user session object cannot be created for some reason, or if the sessionToken value is NULL.
lazyload	ObUserSessionMgd::ObUserSessionMgd(string sessionToken, bool lazyload) creates a user session on demand. Parameters: lazyload: This flag, if true, indicates that the session token is not to be loaded immediately. Relies on getUserIdentity(), getLocation(), getLevel(), getStartTime(), and getEndTime() functions to make calls if the session token information is invalid, and lazyload loads the token on demand. Returns: A user session object. Throws: An internally generated ObAccessExceptionMgd if the user session object cannot be created for some reason or the session object is NULL.
credentials	ObUserSessionMgd(ObResourceRequestMgd *pRes, ObDictionary *credentials) creates a user session object. Parameters: pRes: The resource object requested by the user. credentials: User credentials. Returns: A structure holding a user session object. Throws: An ObAccessException if the user session object cannot be created for some reason, or if the resource object is NULL.
location	ObUserSessionMgd(ObResourceRequestMgd *pRes, ObDictionary *credentials, System::String *location) creates a user session object. Parameters: pRes: The name of the resource. credentials: User credentials. location: The location of the user, if it needs to be specified. A valid DNS name or IP address can be used to specify the location of the user's machine. Returns: A user session object. Throws: An ObAccessException if the user session object cannot be created for some reason, or if the resource object is NULL

4.9.5.2 Methods (ObUserSessionMgd, C#)

Table 4-48 lists the methods and associated details for the ObUserSessionMgd class.

Table 4-48 ObUserSessionMgd Methods (C#)

Method	Details
get_UserIdentity	__property System::String *get_UserIdentity() returns the Distinguished Name of the user's profile entry in the user directory.
get_Location	__property System::String *get_Location() returns the location of the user. A valid DNS name or IP address can be used to specify the location of the user's machine.
getAction	System::String *getAction(System::String *actionType, System::String *name) returns an action corresponding to the name of the action and action type specified. Parameters: actionType: The type of action for which the value is returned. If this is left NULL, the default is headerVar. name: Name of the action for which the value is to be returned. Returns: A string representing the action.
getActions	ObDictionary *getActions(System::String *actionType); returns an ObDictionary list of action names and values, given an action type. Parameters: actionType: The type of action for which the list is returned. If this is left NULL, the default is "headerVar".
get_ActionTypes	__property System::String *get_ActionTypes() returns an array of pointers to strings, representing all the action types. The array is terminated by a NULL pointer.
getNumber OfActions	int getNumberOfActions(System::String *actionType) returns the total number of actions belonging to the specified action type that are also associated with the current user session. Parameters: actionType: The name of the action type for which a count of actions is needed. If this is left NULL, the default is headerVar.
get_Level	_property int get_Level() returns a number representing the level of the current authentication scheme.
get_StartTime	__property int get_StartTime() returns the time when the user was authenticated, in seconds since midnight January 1, 1970. Used to determine a session expiration.
get_LastUseTime	__property int get_LastUseTime() returns the time set when user request is authorized, in seconds since midnight January 1, 1970. Used to determine an idle session expiration.
get_Status	__property ObUserStatusMgd *get_Status() returns one of the ObUserStatus_t values describing the status of the session, such as logged out, logged in, login failed, or expired.
get_Error	__property ObUserError_t get_Error() returns one of the ObUserError_t error values determined by the most recent authentication or authorization.
get_ErrorMessage	__property System::String *get_ErrorMessage() returns a detailed error message pertaining to authentication or authorization failure. The text of this message is derived by the Access API and is not intended to be changed by the user.
IsAuthorized	bool IsAuthorized(ObResourceRequestMgd *pRes) determines if the user is authorized to perform an operation in reference to a particular resource. Parameters: pRes: The resource object whose authorization is to be checked. Returns: ObTrue if authorization succeeds, otherwise ObFalse. Throws: An ObAccessExceptionMgd if the authorization check cannot be completed for any reason.
IsAuthorizedWith Parameters	bool IsAuthorizedWithParameters(ObResourceRequestMgd *pRes, ObDictionary *parameters) determines if the user is authorized to request an operation for a particular resource. The parameters argument is optional. If specified, the key-and-value pairs in the parameters will be passed to the Access Server. Parameters: pRes: The resource object whose authorization is to be checked. parameters: A list of key-and-value pairs sent to the Access Server as part of the request-context object. Returns: ObTrue if authorization succeeds, otherwise ObFalse. Throws: An ObAccessException if the authorization check cannot be completed for any reason.
get_SessionToken	__property System::String *get_SessionToken() returns the saved encrypted ASCII representation of the user session. Returns: The ASCII string representing the user session.
LogOff	void LogOff() logs off the authenticated user and terminates the session.

4.9.6 ObConfigMgd

ObConfigMgd enables the application to initialize or shut down the Access Server or obtain AccessGate configuration data from the Access Server.

For a list of AccessGate configuration items see "Configuration Parameters" .

For a general discussion of the ObConfig class, see "ObConfig" .

For a list of the messages thrown in response to errors by the C# implementation of ObConfigMgd, see "C-Family Status and Error Message Strings" .

4.9.6.1 Constructors (ObConfigMgd, C#)

There are no constructors for the C# implementation of this class.

4.9.6.2 Methods (ObConfigMgd, C#)

Table 4-49 lists the methods and associated details for the ObConfigMgd class.

Table 4-49 ObConfigMgd Methods (C#)

Method	Details
initialize	static void initialize(System::String *configDir) initializes the AccessGate, including reading all parameters into the structure defined under "Configuration Parameters" . Parameters: configDir: If no coded value is provided for this parameter, the value from the environment variable OBACCESS_INSTALL_DIR is used. Throws: An ObAccessException if the user session object cannot be created for some reason, or if the OBACCESS_INSTALL_DIR is invalid.
shutdown	static void shutdown() disconnects the AccessGate from the Access Server, and releases memory and other resources.
getItem	static System::String *getItem(System::String *name) returns the value corresponding to the key from a key-and-value pair in an ObDictionary hashtable. For a list of possible items, see "Configuration Parameters" . Parameters: name: The name of a configuration item in a dictionary list. Throws: An ObAccessException if an attempt is made to invoke the method before a successful initialization is achieved.
get_AllItems	__property static ObDictionary *get_AllItems() reads all the configuration variables from the configuration file into a named ObDictionary key-and-value dictionary list. See the list of possible items in "Configuration Parameters" . Throws: An ObAccessExceptionMgd exception, if an attempt is made to invoke the method before a successful initialization is achieved.
get_Number OfItems	__property static int get_NumberOfItems() returns the total number of items extracted from the configuration file. Throws: An ObAccessExceptionMgd exception, if an attempt is made to invoke the method before a successful initialization is achieved.
get_SDKVersion	__property static System::String *get_SDKVersion() returns the SDK version, an internal value known to the API. Throws: An ObAccessExceptionMgd exception, if an attempt is made to invoke the method before a successful initialization is achieved.
get_NAPVersion	__property static System::String *get_NAPVersion() returns a string representing the version of the access control protocol being used by the Access Manager API This internal value is known to the API. Throws: An ObAccessExceptionMgd exception, if an attempt is made to invoke the method before a successful initialization is achieved.

4.9.7 ObAccessExceptionMgd

This class enables you to extract the entire error message string thrown by the Access Manager API in response to an error. Alternatively, you can extract from the full error message one or more (up to five) of the indexed substrings that may be embedded in the full error message.

For a general discussion of the ObAccessException class, see "ObAccessException" .

4.9.7.1 Constructors (obAccessExceptionMgd, C#)

Table 4-50 lists the ObAccessExceptionMgd constructor and associated details for the class.

Table 4-50 ObAccessExceptionMgd Constructor (C#)

Parameter	Details
ex	ObAccessExceptionMgd(ObAccessException *ex) takes ownership of the passed-in value of ObAccessException and then cleans up the memory it uses. Parameters: ex: An ObAccessException.

4.9.7.2 Methods (ObAccessExceptionMgd, C#)

Table 4-51 lists the details for the methods associated with ObAccessExceptionMgd.

Table 4-51 ObAccessExceptionMgd Methods (C#)

Method	Details
get_Code	__property ObAccessExceptionCode_t get_Code() returns the value of the last error code generated by the API.
getParameter	System::String *getParameter(int index) returns just the substring that would appear in a full error message at location %index. This enables you to obtain the substring in isolation, perhaps for insertion into a logged message along with customized text. Parameters: Index: The location where the substring (parameter) would ordinarily appear in the message generated by the API.
get_String	__property System::String *get_String() returns the error message string corresponding to the last error code generated by the API. This enables you to get the entire message as defined by the API, perhaps for insertion verbatim into an error log. Do not free the return value.
getCodeString	System::String *getCodeString(ObAccessExceptionCode_t code) returns the error message string corresponding to the specified error code, which need not be the last one generated within the API. Because the substring (parameter) pointers are all set to NULL, the ObAccessGate.msg file text is returned verbatim, without the substrings (parameters) inserted. Do not free the return value. Parameters: code: The number corresponding to the error message string that should be found. Returns: The verbatim ObAccessGate.msg file text for the specified error.

4.9.8 ObDiagnostic (C#)

The ObDiagnostic class enables you to display diagnostic information such as the name and port of the Access Server, its location, the number of connections the AccessGate has with the Access Server, and so on. This class also displays diagnostic information about the directory that is associated with the Access Server.

Example:

public __gc class ObDiagnosticMgd {public: __property static ObDictionary *get_ServerDiagnosticInfo();
__property static ObDictionary *get_DirectoryDiagnosticInfo();__property static ObDictionary *get_ClientDiagnosticInfo(); };

4.9.8.1 Methods (ObDiagnostic, C#)

Table 4-52 lists the methods for the C# implementation of ObDiagnostic.

Table 4-52 ObDiagnostic Methods (C#)

Parameter	Details
getServerDiagnosticInfo()	This parameter returns the following items on the ObMap structure: Access Server host name Access Server port Number of connections with the Access Server established by the current WebGate Access Server state (up or down) Access Server creation date and time (based on when it was installed) Access Server installation directory Maximum number of threads allowed in this Access Server.
getDirectoryDiagnosticInfo()	This parameter returns the following items: Directory type (Config, User, Policy) Directory host Directory port Directory state (up or down) Priority (primary or secondary) Mode (open or SSL) Size limit (the maximum number of search results) Time limit (the timeout threshold) Login DN Creation date and time based on when the Access server establishes connection with the Directory Server. (If you restart either server, the creation date and time change.)

4.10 Java Implementation Details

The Java package that implements the Access Manager API consists of the following:

• Three interfaces, which contain pure virtual methods and no implementation code

• Four implementing (base) classes, which inherit most of their member methods from the ObAccess interfaces

• One class that handles program errors

All of these classes implement the interface "java.lang.cloneable," and all except ObConfig and ObAccessException implement a corresponding Com.Oblix.Access interface.

For a general discussion of the classes in the Access Manager API, see "About the Access Manager API" .

Note:

Java Garbage Collection automatically deallocates the memory of Access Manager API objects when they are no longer needed. For a discussion of how memory management is handled by the four implementations of the Access Manager API, see "About Memory Management" .

4.10.1 Interfaces

In the Java programming language, an interface is a special class that contains methods, but does not contain the code to implement those methods. An interface does not allow the construction of objects, nor can you instantiate variables. Instead, one or more implementing classes inherit methods from the interface. Typically, each base class implements the methods it inherits from the interface in a fashion that distinguishes it from its sibling base classes.

At present, however, the three interfaces in the Access Manager API each have just one implementing class. Therefore, polymorphism does not come into play for the Access Manager API.

The name of each interface matches the name of its sole implementing class, except "interface" is appended at the end. Thus, the ObAuthenticationScheme base class implements ObAuthenticationSchemeInterface.

Table 4-53 correlates interfaces and corresponding base classes in the Access Manager API.

Table 4-53 Java Interface Implementation for Com.Oblix.Access

Implementing ObAccess Base Class	Corresponding ObAccess Interface
ObAccessException	none
ObAuthenticationScheme	ObAuthenticationSchemeInterface
ObConfig	none
ObResourceRequest	ObResourceRequestInterface
ObUserSession	ObUserSessionInterface

4.10.1.1 ObAuthenticationSchemeInterface

ObAuthenticationSchemeInterface provides methods to enable the creation and manipulation of the structures used to authenticate users who have requested access to a resource. You cannot directly invoke any of the member methods in this interface. Instead, you invoke the corresponding member methods of ObAuthenticationScheme, the base class that implements ObAuthenticationSchemeInterface.

Methods

ObAuthenticationSchemeInterface contains the following methods: getName(), requiresSecureTransport(), isBasic(), isCertificate(), isForm(), isNone(), getLevel(), getRedirectUrl(), getNumberOfChallengeParameters(), getAllChallengeParameters(), and getChallengeParameter(). See "ObAuthenticationScheme" .

4.10.1.2 ObResourceRequestInterface

ObResourceRequestInterface provides methods to enable manipulation of structures used to represent user requests for access to specified resources. You cannot directly invoke any of the member methods in this interface. Instead, you invoke the corresponding member methods of ObResourceRequest, the base class that implements ObResourceRequestInterface.

Methods

ObResourceRequestInterface contains the following methods: isProtected(), getResourceType(), getResource(), getOperation(), getParameters(), and getAuthorizationParameters(). See "ObResourceRequest" .

4.10.1.3 ObUserSessionInterface

ObUserSessionInterface provides methods to enable the creation and manipulation of the structures that represent a user session. You cannot directly invoke any of the member methods in this interface. Instead, you invoke the corresponding member methods of ObUserSession, the base class that implements ObUserSessionInterface.

Methods

ObUserSessionInterface contains the following methods: getUserIdentity(), getLevel(), getLocation(), setLocation(), getStartTime(), getLastUseTime(), getNumberOfActions(), getActions(), getAction(), getActionTypes(), getStatus(), getError(), getErrorMessage(), getSessionToken(), and logoff(). See "ObUserSession" .

4.10.2 (java.util.Hashtable)

The Java implementation of the Access Manager API does not include its own class to handle the storage and manipulation of API-related parameters, which is handled by ObMap and ObMapIterator in the C++ implementation of the API. The equivalent classes for the C implementations are ObMap_t and ObMapIterator, respectively. For the C# implementation, the equivalents are ObDictionary and ObDictionaryEnumerator, respectively.

By contrast, the Java implementation relies on the standard Java class java.util.Hastable to provide equivalent functionality in this area. For a discussion of ObMap and ObMapIterator, see "Implementations Compared" .

4.10.2.1 Constructors (java.util.Hashtable, Java)

The following table details the constructors in java.util.Hashtable that provide relevant hashtable functionality for Com.Oblix.Access. It lists only those constructors corresponding to constructors in the C-family implementations of the ObMap and ObMapIterator classes.

java.util.Hashtable Constructors (Java)

Hashtable() creates a new, empty hashtable with a default initial capacity of 11 items and load factor of 0.75. (The size of the hashtable is automatically increased when it is filled beyond 0.75 of its maximum capacity).

4.10.2.2 Methods (java.util.Hashtable, Java)

Table 4-54 details the methods in java.util.Hashtable that provide relevant hashtable functionality for Com.Oblix.Access. It lists only those methods corresponding to methods in the C-family implementations of the ObMap and ObMapIterator classes.

Table 4-54 java.util.Hashtable Methods (Java)

Method	Details
get	get() returns the value corresponding to the name of the specified item in the specified hashtable.
put	put() inserts a specified name:value pair the specified hashtable.
size	size() returns the number of items in the specified hashtable
(copy constructor)	Hashtable(map_t) copies a specified hashtable. Parameter: map_t - The name of the hashtable to be copied.

4.10.3 ObAuthenticationScheme

ObAuthenticationScheme enables you to create and manipulate structures that represent the authentication scheme associated with the resource requested by the specified user.

For a general discussion of ObAuthenticationScheme, see "ObAuthenticationScheme" .

For a list of the messages thrown in response to errors by the Java implementation of ObAuthentication Scheme, see "Java Status and Error Message Fields" .

4.10.3.1 Constructors (ObAuthenticationScheme, Java)

Table 4-55 presents the constructor for ObAuthenticationScheme.

Table 4-55 Com.Oblix.Access.ObAuthenticationScheme Constructors (Java)

Key Parameter	Details
res	public ObAuthenticationScheme(ObResourceRequest res) creates an ObAuthenticationScheme object for the specified ObResourceRequest. Parameter: res - The resource request object for which the authentication scheme object is being constructed. Throws: ObAccessException if the attempt to create the object fails or if resource object is NULL.

4.10.3.2 Methods (ObAuthenticationScheme, Java)

Table 4-56 details the methods belonging to the ObAuthenticationScheme class. The "clone" method implements a corresponding method inherited from the interface java.lang.Clonable. The method "setNativeHandle" is reserved for internal use only. All the other methods in ObAuthenticationScheme implement corresponding methods inherited from ObAuthenticationSchemeInterface or the ObAuthenticationScheme superclass java.lang.Object.

Table 4-56 Com.Oblix.Access.ObAuthenticationScheme Methods (Java)

Method	Details
clone	public java.lang.Object clone() clones ObAuthenticationScheme objects. Throws: java.lang.CloneNotSupportedException.
getAllChallenge Parameters	public java.util.Hashtable getAllChallengeParameters() returns a hashtable containing name:value pairs representing all the challenge parameters currently set for the specified authentication scheme.
getChallenge Parameter	public java.lang.String getChallengeParameter(java.lang.String parameterName) returns a value corresponding to the specified challenge parameter name for the specified authentication scheme. Parameters: parameterName - name of the challenge parameter
getLevel	public int getLevel() returns the authentication level currently set for the specified authentication scheme.
getName	public java.lang.String getName() returns the display name of the specified authentication scheme.
getNumberOf Challenge Parameters	public int getNumberOfChallengeParameters() returns the number of challenge parameters currently set for the specified authentication scheme.
getRedirectUrl	public java.lang.String getRedirectUrl() returns the URL to which the user's browser is redirected for secure authentication.
isBasic	public boolean isBasic() returns true if the specified authorization scheme is Basic (in other words, it requires only userid and password for authentication); otherwise, it returns false.
isCertificate	public boolean isCertificate() returns true if the specified authorization scheme requires a digital certificate; otherwise, it returns false.
isForm	public boolean isForm() returns true if the specified authorization scheme requires HTTP FORM-based authentication; otherwise, it returns false.
isNone	public boolean isNone() returns true if the authentication scheme does not have a specified challenge method. If the resource is protected by an authorization scheme that does specify a challenge method, it returns false.
requiresSecure Transport	public boolean requiresSecureTransport() returns true if the authentication scheme requires a secure connection; otherwise, it returns false.
setNativeHandle	public void setNativeHandle(int nativeHandle) Users must not invoke this method; it is reserved of internal use only.
equals, getClass, hashCode, notify, notifyAll, toString, wait	All of the methods in the cell to the left were inherited by ObAuthenticationScheme from the superclass java.lang.Object.

4.10.4 ObResourceRequest

This class enables the creation, passing, and retrieval of structures that represent user requests to access resources. For a general discussion of ObResourceRequest, see "ObResourceRequest" .

For a list of the error messages thrown in response to errors by member methods of the Java implementation of ObResourceRequest, see "Java Status and Error Message Fields" .

4.10.4.1 Constructors (ObResourceRequest, Java)

Table 4-57 lists the constructors for the ObResourceRequest class.

Table 4-57 Com.Oblix.Access.ObResourceRequest Constructors (Java)

Key Parameter	Constructor
operation	public ObResourceRequest(java.lang.String resType, java.lang.String resName, java.lang.String operation) constructs a ObResourceRequest object of the specified resource type, name and operation. Parameters: resType - The type of the requested resource, which can be HTTP, EBJ, or user-defined. When this value is NULL, the default value is HTTP. res - The name of the resource being requested. operation - The operation to be performed against the resource request object. This can be GET or POST for HTTP resources and EXECUTE for EJB resources. Throws: ObAccessException if an error occurs during native object creation or if either the resName or operation parameters are NULL.
parameters	public ObResourceRequest(java.lang.String resType, java.lang.String resName, java.lang.String operation, java.util.Hashtable parameters) constructs a ObResourceRequest object of the specified resource type, name, operation. When "parameters" is specified as an argument, a hashtable containing all the authorization parameters currently assigned to the resource is passed to the constructor. The Access Server uses this information to determine the applicable policies and authorization decisions. Parameters: resType - The type of the requested resource, which can be HTTP, EBJ, or user-defined. When this value is NULL, the default value is HTTP. res - The name of the resource being requested. operation - The operation to be performed against the resource request object. This can be GET or POST for HTTP resources and EXECUTE for EJB resources. parameters - a hashtable containing all the authorization parameters currently assigned to the resource. Throws: ObAccessException if an error occurs during native object creation or if either the resName or operation parameters are NULL.l

4.10.4.2 Methods (ObResourceRequest, Java)

Table 4-58 lists the methods and details for the ObResourceRequest class. The clone method implements a corresponding method inherited from the interface Java.lang.Cloneable. The method getNativeHandle is reserved for internal use only. All the other methods in ObResourceRequest implement corresponding methods inherited from the interface ObResourceRequestInterface and the ObResourceRequest superclass java.lang.Object.

Table 4-58 Com.Oblix.Access.ObResourceRequest Methods (Java)

Method	Details
isProtected	public boolean isProtected() returns true if the resource specified by the ObResourceRequest structure is protected; otherwise it returns false.
getResourceType	public java.lang.String getResourceType() returns the resource type of the specified resource.
getResource	public java.lang.String getResource() returns the name of the resource associated with the specified resource request object.
getOperation	public java.lang.String getOperation() returns the name of the operation (such as GET or POST for HTTP) to be performed against the resource associated with the specified resource request object.
getParameters	public java.util.Hashtable getParameters() returns a hashtable containing name:value pairs representing all the parameters that have been set to define the resource associated with the specified resource request object.
getAuthorization Parameters	public java.util.Hashtable getAuthorizationParameters() returns a hashtable containing the parameters required for authorization of the resource associated with the specified resource request object. All the value halves of the name:value pairs representing these parameters are set to NULL. In other words, the hashtable contains only the names of the parameters.
getNumberOf Authorization Parameters	public int getNumberOfAuthorizationParameters() returns the number of parameters required for authorization of the resource associated with the specified resource request object. This total equals the number of items contained in the hashtable returned by the getAuthorizationParameters method.
clone	public java.lang.Object clone() clones ObResourceRequest objects. Throws: java.lang.CloneNotSupportedException.
equals, getClass, hashCode, notify, notifyAll, toString, wait	All of the methods in the cell to the left were inherited from the ObResourceRequest superclass java.lang.Object.

4.10.5 ObUserSession

ObUserSession enables creation of and interaction with structures representing sessions for users who have successfully completed authentication. For a general discussion of ObUserSession, see "ObUserSession" .

A list of error messages thrown by ObUserSession methods in response to errors follows.

4.10.5.1 Java Status and Error Message Fields

The following table lists the self-descriptive field names thrown in response to errors by the constructors and methods for the ObUserSession class. The syntax for declaring these fields is the following:

public static final int fieldname

where fieldname represents the specified status message string.

The following table lists the fields associated with the Java implementation of the ObUserSession class. The first five fields constants refer to session states, while the rest refer to errors

The following are Com.Oblix.Access.ObUserSession fields (Java):

AWAITINGLOGIN
LOGGEDIN
LOGGEDOUT
LOGINFAILED
EXPIRED
OK
ERR_UNKNOWN
ERR_NO_USER
ERR_USER_REVOKED
ERR_WRONG_PASSWORD
ERR_INVALID_CERTIFICATE
ERR_AUTHN_PLUGIN_DENIED
ERR_INSUFFICIENT_LEVEL
ERR_NOT_LOGGED_IN
ERR_SESSION_TIMEOUT
ERR_IDLE_TIMEOUT
ERR_DENY
ERR_PASSWORD_EXPIRED
ERR_PASSWORD_CHANGE_ON_RESET
ERR_USER_LOCKED_OUT
ERR_NEED_MORE_DATA
ERR_INCONCLUSIVE
AWAITINGLOGIN = 0 SessionExpired SessionInvalid
DIAGNOSTICS_FAILED
UNKNOWN_CLIENT_ID
MODUSER_FAILED

The following status code is used to indicate to clients that the session has expired:

ObAAAStatus_SessionExpired = 70  

The following status code is used to indicate to clients that the session is invalid:

SessionInvalid = 71, 
SessionIdle = 72,
SessionTimeout = 73,
ModUserFailed = 74,
DBInfoUnavailable = 75

4.10.5.2 Constructors (ObUserSession, Java)

Table 4-59 lists the ObUserSession constructors along with their associated parameters and details.

Table 4-59 Com.Oblix.Access.ObUserSession Constructors (Java)

Parameter	Details
NULL	public ObUserSession() is the default constructor for ObUserSession Object
sessionToken	public ObUserSession(java.lang.String sessionToken) used the specified session token to create an ObUserSession object immediately. Parameters: sessionToken - A serialized representation of a user session Throws: ObAccessException if object creation fails or if session token is NULL.
lazyload	public ObUserSession(java.lang.String sessionToken, boolean lazyload) creates a user session on demand. Parameters: lazyload: This flag, if true, indicates that the session token is not to be loaded immediately. Relies on getUserIdentity(), getLocation(), getLevel(), getStartTime(), and getEndTime() functions to make calls if the session token information is invalid, and lazyload loads the token on demand. Returns: A user session object. Throws: An internally generated ObAccessException if the user session object cannot be created for some reason or the session token is NULL.
location	public ObUserSession(ObResourceRequest res, java.util.Hashtable Credentials, java.lang.String location) constructs a user session object for the specified resource and credentials Parameters: res - The resource request object for which user is being authenticated. credentials - The user credentials formatted as name:value paris in a hashtable location - The location of the user, if it needs to be specified. A valid DNS name or IP address can be used to specify the location of the user's machine. Throws: ObAccessException if object creation fails or if session token is NULL.
credentials	public ObUserSession(ObResourceRequest res, java.util.Hashtable Credentials) creates a user session object for the specified resource and credentials. Parameters: res - The resource object for which user is being authenticated. credentials - The name of the hashtable containing the name:value pairs that represent the user's credentials. Throws: ObAccessException if object creation fails or if session token is NULL.

4.10.5.3 Methods (ObUserSession, Java)

Table 4-60 lists the methods and details associated with the Java implementation of the ObUserSession class.The clone method implements a corresponding method inherited from the interface java.lang.Clone. The method setNativeHandle is reserved for internal use only. All the other methods in ObUserSession implement corresponding methods inherited from ObUserSessionInterface or the ObUserSession superclass java.lang.Object.

Table 4-60 Com.Oblix.Access.ObUserSession Methods (Java)

Method	Details
clone	public java.lang.Object clone() clones ObUserSession objects. Throws: java.lang.CloneNotSupportedException.
getAction	public java.lang.String getAction(java.lang.String actionType, java.lang.String name) returns the name of an action that corresponds to the type of action that has been specified. Parameters: actionType - The action type corresponding to the action to be named. For instance, the action type can be "cookie" or "headerVar" for HTTP resources. If the type of the action is unspecified, the default type is "headerVar." actionName - The name of the action associated with the specified action type.
getActions	public java.util.Hashtable getActions(java.lang.String actionType) returns the names of all the actions of the specified action type that are currently set for the specified user session. Parameters: actionType -The type of action for which the actions set for the specified user session are returned. For instance, the action type can be cookie or headerVar for HTTP resources. If the type of the action is unspecified, the default type is "headerVar".
getAction Types	public java.lang.String[] getActionTypes() returns an array of action types for the specified user session.
getError	public int getError() returns the error number from the most recent authentication or authorization.
getError Message	public java.lang.String getErrorMessage() returns the detailed error message for the authentication or authorization failure.
getLastUseTime	public int getLastUseTime() returns the number of seconds between January 1, 1970 and the time when the user request was authorized. This value is used to determine when an idle session expires.
getLevel	public int getLevel() returns the level of the authentication scheme used to authenticate the user making the resource request.
getLocation	public java.lang.String getLocation() returns the location of the user. A valid DNS name or IP address can be used to specify the location of the user's machine.
getNumber OfActions	public int getNumberOfActions(java.lang.String actionType) returns the number of actions currently set for the specified action type. Parameters: actionType - The type of action. For instance, the action type can be cookie or headerVar for HTTP resources. If the type of the action is unspecified, the default type is "headerVar".
getSession Token	public java.lang.String getSessionToken() returns a serialized representation of user session.
getStartTime	public int getStartTime() returns the time when the user was authenticated; used to determine a session expiration.
getStatus	public int getStatus() returns the status of the specified session, such as logged out, logged in, login failed, or expired.
getUserIdentity	public java.lang.String getUserIdentity() returns the Distinguished Name of the authenticated user's profile entry in the current LDAP directory.
isAuthorized	public boolean isAuthorized(ObResourceRequest res) returns true if the user is authorized to request the specified operation for the specified resource. Otherwise, returns false. Parameters: res - resource object being checked for authorization Throws: ObAccessException if the operation fails.
isAuthorized (parameters)	public boolean isAuthorized(ObResourceRequest res, java.util.Hashtable parameters) returns true if the user is authorized to request a specified operation against a specified resource when a set of additional parameters is specified. Otherwise, it returns false. Parameters: res - The resource object being checked for authorization parameters - A hashtable of parameter names and values Throws: ObAccessException if the operation fails.
logoff	public void logoff() logs off the authenticated user and terminates the session
setLocation	public void setLocation(java.lang.String location) sets the location of the user. A valid DNS name or IP address can be used to specify the location of the user's machine.
setNativeHandle	public void setNativeHandle(int nativeHandle) Do not invoke this method. It is reserved for internal use only.
equals, getClass, hashCode, notify, notifyAll, toString, wait	All of the methods listed in the cell to the left have been inherited from the ObUserSession superclass java.lang.Object.

4.10.6 ObConfig

The ObConfig class enables you to store, pass, retrieve, and modify configuration information for your AccessGate.

4.10.6.1 Constructors (ObConfig, Java)

The following table presents the constructors for the ObConfig class.

public ObConfig() is the default constructor for the ObConfig Object.

4.10.6.2 Methods (ObConfig, Java)

Table 4-61 presents the methods for the ObConfig class.:

Table 4-61 Com.Oblix.Access.ObConfig Methods (Java)

Method	Details
getAllItems	public static java.util.Hashtable getAllItems() a hashtable containing name:value pairs representing all the configuration parameters currently in the AccessGate configuration file. Throws: ObAccessException if this method is invoked before initialization of the Access Manager API succeeds.
getItem	public static java.lang.String getItem(java.lang.String itemName) returns a value corresponding to the specified configuration parameter. Parameters: itemName - the name of the configuration parameter whose value is being requested. Throws: ObAccessException if this method is invoked before initialization of the Access Manager API succeeds.
getNAPVersion	public static java.lang.String getNAPVersion() returns the version of the Oracle Access Protocol that is in use.
getNumber OfItems	public static int getNumberOfItems() returns the number of configuration items currently set for the AccessGate. Throws: ObAccessException if this method is invoked before initialization of the Access Manager API succeeds.
getSDK Version	public static java.lang.String getSDKVersion() returns version of the Access Server SDK that is in use.
initialize (installDir)	public static void initialize(java.lang.String installDir) initializes the Accessgate using the Access Manager SDK whose root is installDir. (Sometimes it is helpful to specify the location of the SDK instance supporting your AccessGate, especially when multiple server instances, each one protected by a different AccessGate or WebGate, have been installed on the same host machine. Parameters: installDir - The directory on the AccessGate host machine where the Access Manager SDK is installed. Throws: ObAccessException if initialization fails.
initialize	public static void initialize() initializes the AccessGate using the environment variable OBACCESS_INSTALL_DIR for AccessGates running on either UNIX or WIndows host machines. Throws: ObAccessException if initialization fails.
shutdown	public static void shutdown() disconnects the AccessGate from the Access Server.

4.10.7 ObAccessException

The Java implementation of ObAccessException differs from the corresponding C-family implementations, in that the Java environment only permits the extraction of entire error message strings, and not the extraction of the individual, indexed substrings that can be extracted through the C-family implementations. For a general discussion of ObAccessException, see "ObAccessException" .

An ObAccessException is thrown by the Access Manager API whenever unexpected, unrecoverable errors occur between an AccessGate and an Access Server.

4.10.7.1 Constructors (ObAccessException, Java)

Table 4-62 presents the constructor for the ObAccessException class.

Table 4-62 Com.Oblix.Access.ObAccessException Constructors (Java)

Key Parameter	Details
NULL	public ObAccessException() constructs an ObAccessException.
message	public ObAccessException(java.lang.String message) constructs an ObAccessException that includes a specified message. Parameters: message - The exception message string.

4.10.7.2 Inherited Methods (ObAccessException, Java)

The Java implementation of ObAccessException has no native methods of its own. Table 4-63 presents the ObAccessException classes inherited from java.lang.Throwable and java.lang.Object.

Table 4-63 Com.Oblix.Access.ObAccessException Inherited Methods (Java)

Inherited Methods	Source
fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, toString	All of the methods in the cell to the left were inherited from the ObAccessException superclass java.lang.Throwable
equals, getClass, hashCode, notify, notifyAll, wait	All of the methods in the cell to the left were inherited from the ObAccessException superclass java.lang.Object

4.10.8 ObDiagnostic (Java)

The ObDiagnostic class enables you to display diagnostic information such as the name and port of the Access Server, its location, the number of connections the AccessGate has with the Access Server, and so on. This class also displays diagnostic information about the directory that is associated with the Access Server.

Example:

public class ObDiagnostic{public static Hashtable getServerDiagnosticInfo() throws ObAccessExceptionpublic static Hashtable getClientDiagnosticInfo() throws ObAccessExceptionpublic static Hashtable getDirectoryDiagnosticInfo() throws ObAccessException}

4.10.8.1 Methods (ObDiagnostic, Java)

Table 4-64 lists the methods for the Java implementation of ObDiagnostic.

Table 4-64 ObDiagnostic Methods (Java)

Parameter	Details
getServerDiagnosticInfo()	This parameter returns the following items on the ObMap structure: Access Server host name Access Server port Number of connections with the Access Server established by the current WebGate Access Server state (up or down) Access Server creation date and time (based on when it was installed) Access Server installation directory Maximum number of threads allowed in this Access Server.
getDirectoryDiagnosticInfo()	This parameter returns the following items: Directory type (Config, User, Policy) Directory host Directory port Directory state (up or down) Priority (primary or secondary) Mode (open or SSL) Size limit (the maximum number of search results) Time limit (the timeout threshold) Login DN Creation date and time based on when the Access server establishes connection with the Directory Server. (If you restart either server, the creation date and time change.)

4.11 C-Family Status and Error Message Strings

This section lists constants that are common to all of the C-family implementations of the Access Manager API (C, C++, and C#). The list presented here is also included in obaccess_api_defs.h, which resides in the following directory:

SDK_install_dir/include

Note:

In Java, errors are handled by reference, rather than by code number. For example, ObAccessException_NOT_INITIALIZED, error 205, is referenced as ObAccessException.NOT_INITIALIZE. See "Java Status and Error Message Fields".

The exception codes in the following table are returned by the Access Server if it cannot perform an operation because of missing data or system problems.

Note:

All of the strings the following table must be prepended with the string ObAccessException_. Thus, OK = 0 becomes ObAccessException_OK = 0.

The following are Access Server error codes:

OK = 0
UNKNOWN = 200
BAD_SESSION_TOKEN
NO_SCHEME_ID
NEED_PARAMETERS
NOT_INITIALIZED
CACHE_PROBLEM
NO_CONFIG_FILE
NO_INSTALL_DIR_ENV
NOT_PROTECTED
MISSING_RESOURCE
MISSING_OPERATION
BAD_LOCATION
NO_CLIENT_ID
JNI_ERROR
OUT_OF_MEMORY
MISSING_ITEM
NO_MSG_CAT
CLIENT_NOT_IN_DIR
OBERROR
DIAGNOSTICS_FAILED
UNKNOWN_CLIENT_ID
MODUSER_FAILED

The exception codes in the following table are returned by the Access Server if it cannot perform an operation because of missing data or system problems.

Note:

All of the strings the following table must be prepended with the string "ObAccessException_." Thus, "AS_UNKNOWN = 300" becomes "ObAccessException_AS_UNKNOWN = 30"

The following are AccessGate error codes:

AS_UNKNOWN = 300
ENGINE_DOWN
NOCODE
NULL_RESOURCE
HOSTPORT_LOOKUP_FAILED
URL_LOOKUP_FAILED
SD_LOOKUP_FAILED
WROR_LOOKUP_FAILED
WROR_AUTHENT_LOOKUP_FAILED
NO_AUTHENT_SCHEME
EXCEPTION
INVALID_SCHEME_ID
INVALID_SCHEME_MAPPING
AS_UNKNOWN = 300
ENGINE_DOWN
INVALID_SCHEME_PARAMETERS
NO_USER
NONUNIQUE_USER
USER_REVOKED
MISSING_OBCRED_PASSWORD
WRONG_PASSWORD
MISSING_PASSWORD
MISSING_CERTIFICATE,
INVALID_CERTIFICATE
INVALID_SELECTION_FILTER
MISSING_AUTHN_PLUGIN
AUTHN_PLUGIN_ABORT
AUTHN_PLUGIN_DENIED
AUTHN_PLUGIN_NO_USER

The codes in the following table are returned to indicate the status of a user session.

Note:

All of the strings listed in the following table must be prepended with the string "ObUser_." Thus, "AWAITINGLOGIN = 0" becomes "ObUser_ AWAITINGLOGIN = 0".

The following are Session Status codes:

AWAITINGLOGIN = 0
LOGGEDIN
LOGGEDOUT
LOGINFAILED
EXPIRED

The codes in the following table are returned to indicate the status of a user session.

Note:

All of the strings listed in the following table must be prepended with the string "OAAAStatus_." Thus, "SessionExpired" becomes "ObAAAStatus_ SessionExpired".

The following status code is used to indicate to clients that the session has expired:

ObAAAStatus_SessionExpired = 70  

The following status code is used to indicate to clients that the session is invalid:

SessionInvalid = 71, 
SessionIdle = 72,
SessionTimeout = 73,
ModUserFailed = 74,
DBInfoUnavailable = 75

Note:

All of the strings listed in the following table must be prepended with the string "ObUser_." Thus, "AWAITINGLOGIN = 0" becomes "ObUser_ AWAITINGLOGIN = 0".

The following table lists the codes that describe problems that might occur in the authentication or authorization process.

Note:

All of the strings listed in the following table must be prepended with the string ObUser_. Thus, OK = 0 becomes ObUser_OK = 0.

The following are authentication and authorization error codes:

OK = 0
ERR_UNKNOWN = 100
ERR_NO_USER,
ERR_USER_REVOKED
ERR_WRONG_PASSWORD
ERR_INVALID_CERTIFICATE
ERR_AUTHN_PLUGIN_DENIED
ERR_INSUFFICIENT_LEVEL
ERR_NOT_LOGGED_IN
ERR_SESSION_TIMEOUT
ERR_IDLE_TIMEOUT
ERR_DENY

The following table lists the codes used to ensure consistent meaning of true and false within the Access Manager API.

The following are ObBoolean return codes:

ObFalse = 0
ObTrue = 1

4.12 Best Practices

This section presents a number of ways to avoid problems and to resolve the most common problems that crop up during development.

4.12.1 Avoiding Problems

Here are some suggestions for avoiding problems with the AccessGates you create:

• Make sure that your AccessGate attempts to connect to the correct Access Server.

• Make sure the configuration information on your Access Server matches the configuration information on your AccessGate. You can check the AccessGate configuration information on your Access Server, which is stored in the Oracle configuration directory. Go to the Access System Console and click Access System Configuration, then AccessGate Configuration, then the name of the AccessGate whose configuration information you want to check. For details about AccessGate and Access Server configuration, see the Oracle Access Manager Access Administration Guide.

• To ensure clean connect and disconnect from the Access Server, use the "initialize" and "shutdown" methods in the ObConfig class.

• The environment variable, OBACCESS_INSTALL_DIR, must be set on your Windows or Solaris host machine so that you can compile and link your AccessGate. In general, you also want the variable to be set whenever your AccessGate is running.

• Use the exception handling features (try, throw, and catch) of the language used to write your custom AccessGate code to trap and report problems during development.

4.12.1.1 Thread Safe Code

Your AccessGate represents just one thread in your entire, multithreaded application.

To ensure safe operation within such an environment, Oracle recommends that developers observe the following practices:

• Use a thread safe function instead of its single thread counterpart. For instance, use localtime_r instead of localtime.

• Specify the appropriate build environment and compiler flags to support multithreading. For instance, use -D_REENTRANT. Also, use -mt for Solaris platforms and /MD for Windows platforms.

• Take care to use in thread-safe fashion shared local variables such as FILE pointers.

4.12.2 Identifying and Resolving Problems

Here are some things to look at if your AccessGate fails to perform:

• Make sure that your Access Server is running. On Windows systems, you can check this by navigating to Computer Management, then to Services, then to AccessServer.

  where AccessServer is the name of the Access Server to which you want to connect your AccessGate.

• Check that the domain policies your code assumes are in place and enabled for your Access System.

• Read the Release Notes that accompanies the Access System product you are working with.

• Check that your AccessGate is not being answered by a lower-level Access System policy which overrides the one you think you are testing.

• Check that you have run the configureAccessGate tool and that you did not make any input errors when you did so. See "Running the configureAccessGate Utility" for a description of how to run the tool.

• The Access Tester in the Policy Manager enables you to check which policy applies to a particular resource. For details about using the Access Tester and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.