2 Introduction to the Access SDK and API

This chapter provides the following sections:

2.1 Introduction to the Access SDK

The Oracle Access Manager 11g Access SDK is a platform independent package that Oracle has certified on a variety of enterprise platforms (using both 32-bit and 64-bit modes) and hardware combinations. It is provided on JDK versions that are supported across Oracle Fusion Middleware applications.

The oracle.security.am.asdk package provides the Oracle Access Manager 11g version of the Application Programming Interface (API). The 11g version is very similar to the Oracle Access Manager 10g API, with enhancements for use with the OAM 11g Server. The 11g Access SDK provides backwards compatibility by supporting com.oblix.access interfaces.

See Also:

Oracle Security Token Service Java API Reference

The Oracle Access Manager 10g (10.1.4.3) com.oblix.access package and classes are deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.

Note:

Oracle strongly recommends that developers use the Oracle Access Manager 11g Access SDK for all new development.

2.2 Locating Access SDK Packages and Resources

Once the Access 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.

Table 2-1 identifies the Access SDK packages and resources and where you can find each one.

Table 2-1 Locations: Access SDK Resources

Resources and Locations

Supported Versions and Platforms: Oracle Technology Network

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

Download Packages: Oracle Technology Network

http://www.oracle.com/technetwork/middleware/downloads/oid-11g-161194.html

Oracle Access Manager 11g Access SDK Packages:

  • oracle.security.am.asdk: A new authentication and authorization API that provides enhancements to take advantage of Oracle Access Manager 11g Server functionality. The Oracle Access Manager 11g version of the Access SDK API can be used with either Oracle Access Manager 10gR3 (10.1.4.3) or Oracle Access Manager 11gR1 (11.1.1.5+) version of the Server.

  • com.oblix.access: Available for compatibility with programs written with an Oracle Access Manager 10g JNI ASDK, this is the 10g version of the authentication and authorization API with some enhancements for Oracle Access Manager 11g.

Java Docs:

Each method includes the following details:

  • Comprehensive description of a method

  • Parameters of the method

  • Return values

  • Exceptions the method may throw

  • Other relevant details

2.3 Uses, Functionality, and New Features

The Oracle Access Manager 11g Access SDK is intended for Java application developers and the development of tightly coupled, performant integrations.

From a functional perspective, the Oracle Access Manager 11g Access SDK maintains parity with the 10g (10.1.4.3) Java Access SDK to ensure that you can re-write existing custom code using the new API layer.

The Oracle Access Manager 11g Access SDK includes authentication and authorization functionality. However, it does not include Administrative APIs (for instance, there is no 11g Policy Manager API) and does not use Oracle Access Manager 11g cookies.

The most common use of the Access SDK is to enable the development of a custom integration between Oracle Access Manager and other applications (Oracle or third party). Usage examples include:

  • Accessing session information that may be stored as part of the Oracle Access Manager authentication process.

  • Verifying the validity of the Oracle Access Manager session cookie rather than trusting an HTTP header for the principle user.

Another use for the Access SDK is the development a custom Access Client for a Web server or an application server for which Oracle does not provide an out-of-the-box integration.

Table 2-2 describes the primary features of the Oracle Access Manager 11g Access SDK.

Table 2-2 Oracle Access Manager 11g Access SDK Features

Feature Description

Installation

Client Package: Is comprised of a single jar file. Supporting files (for signing and TLS negotiations) are not included and should be generated separately.

Server Related Code: Is included as part of the core Oracle Access Manager server installation.

Note: Access Clients and plug-ins developed with Oracle Access Manager 10g (10.1.4.3) can be used with Oracle Access Manager 11g. Oracle Access Manager 10g (10.1.4.3) bundle patches are used to distribute Java SDK code enhancements for use with Oracle Access Manager 11g.

Built In Versioning

Enables you to:

  • Determine the Access SDK version that is installed.

  • Validate compatible versions it can operate with (Oracle Access Manager 10g (10.1.4.3) and Oracle Access Manager 11g).

    If there is a mismatch, Access SDK functions halt and an informative message is logged and presented.

Logging

The Access SDK logging mechanism enables you to specify the level (informational, warning, and error level) of detail you want to see in a local file. Messages provide enough detail for you to resolve an issue. For example, if an incompatible Access SDK package is used, the log message includes details about a version mismatch and what version criteria should be followed.

If the SDK generates large amounts of logs within a given period of time, you can configure a rollover of the logs based on a file limit or a time period. For example, if a file limit has been reached (or a certain amount of time has passed), the log file is copied to an archive directory and a new log file is started

New Calls

The Access SDK incorporates new calls to determine additional information about the session based on the new Oracle Access Manager 11g architecture.

Note: Access Clients and plug-ins developed with the Oracle Access Manager 10g com.oblix.access package can be migrated to operate with the OAM 11g Server.

The Access SDK enables you to develop custom integrations with Oracle Access Manager for the purpose of controlling access to protected resources such as authentication, authorization, and auditing. This access control is generally accomplished by developing and deploying custom Access Clients, which are applications or plug-ins that invoke the Access Client API to interface with the Access SDK runtime.

Access Client-side caching is used internally within the Access SDK runtime to further minimize the processing overhead. The Access SDK runtime, together with the Oracle Access Manager server, transparently performs dynamic configuration management, whereby any Access Client configuration changes made using Oracle Access Manager administration console are automatically reflected in the affected Access SDK runtimes.

You can develop different types of custom Access Clients, depending on their desired function, by utilizing all, or a subset of, the Access Client API. The API is generally agnostic about the type of protected resources and network protocols used to communicate with the users. For example, the specifics of HTTP protocol and any use of HTTP cookies are outside of the scope of Access SDK. You can develop Access Clients to protect non-HTTP resources as easily as agents protecting HTTP resources.

The typical functions that a custom Access Client can perform, individually or in combination with other Access Clients, are as follows:

  • Authenticate users by validating their credentials against Oracle Access Manager and its configured user repositories.

  • Authenticate users and check for authorization to access a resource.

  • Authenticate users and create unique Oracle Access Manager sessions represented by session tokens.

  • Validate session tokens presented by users, and authorize their access to protected resources.

  • Terminate Oracle Access Manager sessions given a session token or a named session identifier.

  • Enumerate Oracle Access Manager sessions of a given user by specifying named user identifier.

  • Save or retrieve custom Oracle Access Manager session attributes.

Some Access Client operations are restricted for use by the designated Access Client instances. For example, see OperationNotPermitted in Oracle Access Manager Access SDK Java API Reference.

An Oracle Access Manager administrator can use the Oracle Access Manager administration console to control the privileges of individual Access Clients. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

2.4 Messages, Exceptions and Logging

This section describes the messages and exceptions used by the Access SDK to indicate status or errors.

The execution log generated by the Access SDK is also described. The execution log provides information about operations performed. For example, operation status, any errors or exceptions that occur, and any general information that is helpful for troubleshooting.

The following topics are discussed in this section:

2.4.1 Messages

The Access SDK provides support for localized messages that indicate status or error conditions. Error messages, which are provided to the application as exceptions, are also localized. These localized error messages are logged in the Access SDK log file.

2.4.2 Exceptions

The following types of exceptions are used to indicate error conditions to an application:

  • OperationNotPermittedException

    The Oracle Access Manager 11g Access SDK introduces a new set of session management APIs. Only privileged Access Clients can perform these session management operations.

    If the Access client is not allowed to perform these operations, the Oracle Access Manager 11g server returns an error. When the server returns an error, the Access SDK will throw this exception.

  • AccessException

    The Oracle Access Manager Access SDK API throws an AccessException whenever an unexpected, unrecoverable error occurs during the performance of any operation.

2.4.3 Logging

The Access SDK uses Java logging APIs for producing logs. Specifically, the oracle.security.am.asdk package contains the AccessLogger class, which produces the Access SDK log.

To generate the Access SDK log, you must provide a logging configuration file when you start the application. Provide this log configuration file as a Java property while running the application, where the Java property -Djava.util.logging.config.file is the path to logging.properties.

For example:

java -Djava.util.logging.config.file=JRE_DIRECTORY/lib/logging.properties

The logging.properties file defines the number of Loggers, Handlers, Formatters, and Filters that are constructed and ready to go shortly after the VM has loaded. Depending on the situation, you can also configure the necessary logging level.

You must provide the log file path against the java.util.logging.FileHandler.pattern property in the logging.properties file. If you provide only the file name, the file will be created under the current directory.

The following is an example logging.properties file:

# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
# Add handlers to the root logger.
# These are inherited by all other loggers.
handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
 
# Set the logging level of the root logger.
# Levels from lowest to highest are
# FINEST, FINER, FINE, CONFIG, INFO, WARNING and SEVERE.
# The default level for all loggers and handlers is INFO.
.level= ALL
 
# Configure the ConsoleHandler.
# ConsoleHandler uses java.util.logging.SimpleFormatter by default. 
# Even though the root logger has the same level as this,
# the next line is still needed because we're configuring a handler,
# not a logger, and handlers don't inherit properties from the root logger.
java.util.logging.ConsoleHandler.level =INFO
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter
 
# The following special tokens can be used in the pattern property
# which specifies the location and name of the log file.
#   / - standard path separator
#   %t - system temporary directory
#   %h - value of the user.home system property
#   %g - generation number for rotating logs
#   %u - unique number to avoid conflicts
# FileHandler writes to %h/demo0.log by default.
java.util.logging.FileHandler.pattern=%h/asdk%u.log
 
 
# Configure the FileHandler.
# FileHandler uses java.util.logging.XMLFormatter by default. 
#java.util.logging.FileHandler.limit = 50000
#java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level=ALL

The following is a sample of the log output:

Apr 19, 2011 5:20:39 AM AccessClient createClient
FINER: ENTRY
Apr 19, 2011 5:20:39 AM ObAAAServiceClient setHostPort
FINER: ENTRY
Apr 19, 2011 5:20:39 AM ObAAAServiceClient setHostPort
FINER: RETURN
Apr 19, 2011 5:20:39 AM ObAAAServiceClient setHostPort
FINER: ENTRY
Apr 19, 2011 5:20:39 AM ObAAAServiceClient setHostPort
FINER: RETURN
Apr 19, 2011 5:20:39 AM AccessClient createClient
FINER: RETURN
Apr 19, 2011 5:20:39 AM AccessClient initialize
FINER: read config from server, re-init if needed
Apr 19, 2011 5:20:39 AM AccessClient updateConfig
FINER: ENTRY
Apr 19, 2011 5:20:39 AM AccessClient readConfigFromServer
FINER: ENTRY
Apr 19, 2011 5:20:39 AM ObAAAServiceClient getClientConfigInfo
FINER: ENTRY
Apr 19, 2011 5:20:39 AM ObAAAServiceClient sendMessage
FINER: ENTRY
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.util.NAPLogger log
FINER: Getting object using poolid primary_object_pool_factory
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.util.pool.PoolLogger logEntry
FINER: PoolLogger : main entered: KeyBasedObjectPool.acquireObject
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.util.NAPLogger log
FINEST: Creating pool with id = primary_object_pool_factory
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.util.pool.PoolLogger log
FINER: PoolLogger:main : Maximum Objects = 1Minimum Objects1
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.util.pool.PoolLogger logEntry
FINER: PoolLogger : main entered: constructObject
Apr 19, 2011 5:20:39 AM oracle.security.am.common.nap.ObMessageChannelImpl <init>

2.5 Configuring and Deploying Access Clients

This section describes the configuration steps required before an Access Client developed using the Access SDK can be deployed. For more information, see Section 2.6.1.2, "Access Client Architecture".

After development, the Access Client must be deployed in a live Oracle Access Manager 11g environment before you can test and use it. The Access Client deployment process is similar to that of other Oracle Access Manager Agents.

The following overview outlines the tasks that must be performed by a user with Oracle Access Manager administrator credentials.

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service

Task overview: Deploying Access Client Code

It is assumed that the Access Client program is already developed and compiled.

  1. Retrieve the Access SDK jar file and copy this to the computer you will use to build the Access Client.

  2. Copy the Access Client to the computer hosting the application to be protected.

  3. Configure the Access Client.

  4. Verify you have the required Java environment available.

    If your Access Client is in a standalone environment, you can use Java Development Kit (JDK) or Java Runtime Environment (JRE). If your Access Client is a servlet application, you can use Java EE or the Java environment available with your Java EE container.

  5. Verify that the Access SDK jar file is in the class path.

2.5.1 Configuration Requirements

An Access SDK configuration consists of the following files:

  • Configuration File (ObAccessClient.xml)

    The configuration file holds various details such as Oracle Access Manager server host, port, and other configuration items that decide behavior of the Access Client. For example, idle session time. Name of this file is ObAccessClient.xml.

  • SSL Certification and Key File

    This file is required only if the transport security mode is Simple or Cert. Both the Oracle Access Manager 10g Server and Oracle Access Manager 11g Server supports transport security modes Open, Simple and Cert to communicate with agents. An Access Client developed using Access SDK is called an agent. Depending on the mode in which Oracle Access Manager server is configured, Access Client will have to be configured to communicate in the same mode.

    For Simple or Cert transport security mode, the following is required:

    • Certificate for the Access Client

    • Private key for the Access Client

    • CA certificate to trust OAM Server's certificate

  • password.xml File

    This file is required only if the transport security mode is Simple or Cert. This file contains a password in encrypted form. This password is the one using which SSL key file is protected.

  • Log Configuration

    Is required in order to generate a log file.

2.5.2 Generating the Required Configuration Files

The ObAccessClient.xml configuration file can be obtained by registering an Access Client as an OAM 10g Agent with the OAM 11g Server, using the Oracle Access Manager 11g administration console or a remote registration tool. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

If the transport security mode is given as Simple or Cert mode during registration, the Oracle Access Manager administration console will create an SSL certificate and key file in PEM format. The certificate and key file can then be imported in the oamclient-keystore.jks file. The CA certificate used to issue the certificate and key should be imported into oamclient-truststore.jks. For more information, see Section 2.5.3, "SSL Certificate and Key Files".

The Oracle Access Manager administration console will also create a password.xml file.

An Access Client application developed with the oracle.security.am.asdk API can specify the location to obtain the configuration file and other required files. This is done by initializing the Access SDK and providing the directory location where the configuration files exist.

For information about options available to specify location of the configuration files to the Access SDK, see Oracle Access Manager Access SDK Java API Reference.

2.5.3 SSL Certificate and Key Files

Oracle Access Manager 11g Access SDK uses SSL certificates and key files from a database commonly known as trust stores or key stores. It requires these stores to be in JKS (Java Key Standard) format.

2.5.3.1 Simple Transport Security Mode

Importing the CA Certificate

The CA certificate must be imported to the trust store. Oracle Access Manager 10g JNI ASDK provides a self-signed CA certificate that can be used in Simple mode, and is used for issuing certificates to the Access Client. OAM 11g Server also provides a self-signed CA certificate.

In Oracle Access Manager 10g JNI ASDK, the CA certificate is found in the following directory and is named cacert.pem: ASDK_INSTALL_DIR/oblix/tools/openssl/simpleCA.

In OAM 11g Server, the CA certificate is found in the following directory and is named cacert.der: $MIDDLEWARE_HOME/user_projects/domains/base_domain/config/fmwconfig.

Execute the following command to import the PEM or DER format CA certificate into trust store:

  1. Edit ca_cert.pem or cacert.der using a text editor to remove all data except what is contained within the CERTIFICATE blocks, and save the file. For example:

    -----BEGIN CERTIFICATE-----
        Content to retain
-----END CERTIFICATE-----

  2. Execute the following command, modifying as needed for your environment:

    keytool -importcert -file <<ca cert file cacert.pem or cacert.der>> -trustcacerts -keystore oamclient-truststore.jks -storetype JKS

  3. Enter keystore password when prompted. This must be same as the global pass phrase used in the OAM Server.

Setting Up The Keystore

The Access Client's SSL certificate and private key file must be added to the keystore. The SSL certificate and private key file must be generated in Simple mode so the Access Client can communicate with OAM Server.

Oracle Access Manager 10g JNI ASDK provides for generating a certificate and key file for the Access Client. These certificates are in PEM format.

OAM 11g Server provides a tool called Remote Registration and Administration Console for generating a certificate and key file for the Access Client. These certificates are also in PEM format. The names of these files are aaa_cert.pem and aaa_key.pem.

Execute the following commands in order to import the certificate and key file into keystore oamclient-keystore.jks.

  1. Edit aaa_cert.pem using any text editor to remove all data except that which is contained within the CERTIFICATE blocks, and save the file. For example:

    -----BEGIN CERTIFICATE-----
        Content to retain
-----END CERTIFICATE-----

  2. Execute the following command, modifying as needed for your environment:

    openssl pkcs8 -topk8 -nocrypt -in aaa_key.pem -inform PEM -out aaa_key.der -outform DER

    This command will prompt for a password. The password must be the global pass phrase.

  3. Execute the following command, modifying as needed for your environment:

    openssl x509 -in aaa_cert.pem -inform PEM -out aaa_cert.der -outform DER

  4. Execute the following command, modifying as needed for your environment:

    java -cp importcert.jar oracle.security.am.common.tools.importcerts.CertificateImport -keystore oamclient-keystore.jks -privatekeyfile aaa_key.der -signedcertfile aaa_cert.der -storetype jks -genkeystore yes

    In this command, aaa_key.der and aaa_cert.der are the private key and certificate pair in DER format.

  5. Enter the keystore password when prompted. This must be same as global pass phrase.

2.5.3.2 Cert Transport Security Mode

In Cert transport security mode, the certificates for the server and agent should be requested from a certifying authority. Optionally, the Simple mode self-signed certificates can also be used as a certifying authority, for purposes of issuing Cert mode certificates.

Follow these steps to prepare for Cert mode:

  1. Import a CA certificate of the certifying authority using the certificate and key pair issued for Access Client and OAM Server. Follow the steps in "Importing the CA Certificate". Instead of cacert.pem or cacert.der, substitute the CA certificate file of the issuing authority.

  2. If Oracle Access Manager 10g JNI ASDK install is available, it provides a way to generate certificate and key file for the Access Client. These certificates will be in PEM format.

    For more information about how to generate a certificate using an imported CA certificate, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

    To import this certificate, key pair in the oamclient-keystore.jks in PEM format, follow instructions in "Setting Up The Keystore".

2.6 Developing Access Clients

The following topics are discussed in this section:

2.6.1 Introduction to Access Clients

Access Clients process user requests for access to resources within the LDAP domain protected by the OAM Server. Typically, you embed custom Access Client code in a servlet (plug-in) or a standalone application that receives resource requests. This code uses Access Manager API libraries to perform authentication and authorization services on the OAM Server.

If a resource is not protected, the Access Client 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 Access Client attempts to retrieve those user credentials so that the OAM Server can validate them. If authentication of the user and authorization for the resource succeeds, the Access Client makes the resource available to the user.

Access Clients can differ according to a variety of factors, as described in Table 2-3.

Table 2-3 Access Client Variations

Variation Description

Type of application

Standalone application versus server plug-ins.

Development Language

Each development language provides a choice of interfaces to the underlying functionality of the API.

For Oracle Access Manager 11g, Java is the only development language for custom Access Clients.

Resource Type

Protect both HTTP and non-HTTP resources.

Credential Retrieval

Enable HTTP FORM-based input, the use of session tokens, and command-line input, among other methods.

2.6.1.1 When to Create a Custom Access Client

Typically, you deploy a custom Access Client 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 (for example, a reverse proxy).

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

    For example, you can create an Access Client that facilitates SSO within an enterprise environment that includes an Oracle WebLogic Server cluster as well as non-Oracle WebLogic Server resources.

2.6.1.2 Access Client Architecture

Each Access Client is built from three types of resources, as described in Table 2-4.

Table 2-4 Resources to Build Access Clients

Resource Description

Custom Access Client code

Built into a servlet or standalone application. For Oracle Access Manager 11g, you write Access Client code using the Java language platform.

Configuration information

  • Primary configuration file required for Access SDK is ObAccessClient.xml, which contains configuration information that constitutes an Access Client profile.

  • Additional configuration artifacts are required depending on the transport security mode (Open, Simple or Cert) in which an Access Client is configured to interact with OAM Server. If security mode is Simple or Cert, then the following files are required.

    • oamclient-truststore.jks – JKS format trust store file which should contain CA certificate of the certificate issuing authority.

    • oamclient-keystore.jks – JKS format key store file which should contain certificate and private key file issued for the Access Client.

    • password.xml – An XML file that holds the value of global pass phrase. Same password is also used to unprotect private key file.

Access Manager API libraries

Facilitate Access Client interaction with the OAM Server.

Figure 2-1 shows Access Client components installed on a host server:

Figure 2-1 Architectural Detail of an Access Client

Architectural detail of an AccessGate.
Description of "Figure 2-1 Architectural Detail of an Access Client "

2.6.1.3 Overview of Access Client Request Processing

Regardless of the variability introduced by the types of resources discussed in Section 2.6.1.2, "Access Client Architecture", most Access Clients 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 Access Client is installed, the Access Client code embedded in that servlet or application initiates the basic process shown in the following diagram.

Figure 2-2 illustrates the process of handling a resource request.

Figure 2-2 Process Overview: Handling a Resource Request

Handling a resource request.
Description of "Figure 2-2 Process Overview: Handling a Resource Request "

Process Overview: Handling a resource request

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

  2. The Access Client constructs an ResourceRequest structure, which the Access Client code uses when it asks the OAM Server whether the requested resource is protected.

  3. The OAM Server responds.

  4. Depending upon the situation, one of the following occurs:

    • If the resource is not protected, the Access Client grants the user access to the resource.

    • If the resource is protected, the Access Client constructs an AuthenticationScheme structure, which it uses to ask the OAM Server what credentials the user needs to supply. This step is only necessary if the Access Client supports the use of different authentication schemes for different resources.

  5. The OAM Server responds.

  6. The application uses a form or some other means to ask for user 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 Access Client application

  7. The user responds to the application.

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

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

  10. The Access Client grants the user access to the resource, providing that the user is authorized for the requested operation on the particular resource.

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

The steps detailed in "Process Overview: Handling a resource request" 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 again 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 Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

  • 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 Access Client to handle special situations or functionality.

2.6.2 Structure of an Access Client

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

Access Client Application Structure 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 (Java uses automatic garbage collection).

  8. Shut down.

2.6.2.1 Typical Access Client Execution Flow

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

Figure 2-3 Process Flow for Form-based Applications

A process flow for form-based applications.
Description of "Figure 2-3 Process Flow for Form-based Applications"

Process overview: Access Client Execution for Form-based Applications

  1. Import libraries.

  2. Initialize the SDK.

  3. Create ResourceRequest object.

  4. Determine if the requested resource is protected.

    Resource Not Protected: Grant access, shut down the API, and end program.

  5. Requested Resource is Protected: Create an AuthenticationScheme object

  6. Authentication Scheme HTTP FORM-based: Create a structure for user ID and password, create UserSession object, determine if the user is authenticated

  7. Authentication Scheme Not HTTP FORM-based: Deny access and report reason, shut down the API and end program.

  8. User is Authenticated: Determine if the user is authorized (Step 10).

  9. User is Not Authenticated: Deny access and report reason, shut down the API and end program.

  10. User is Authorized: Grant access, shut down the API, and end program.

  11. User Not Authorized: Deny access and report reason, shut down the API and end program.

Note:

To run this test application, or any of the other examples, 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 application domains and protecting resources with application domains, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

2.6.2.2 Example of a Simple Access Client: JAccess Client.java

This example is a simple Access Client program. It illustrates how to implement the bare minimum tasks required for a working Access Client, as described here.

Simple Access Client Processing: JAccess Client.java

  • Connect to the OAM 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 SDK API exceptions

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

A complete listing for JAccess Client.java appears in Example 2-1. You can copy this code verbatim into the text file JAccess Client.java and execute it on the computer where your Access Manager SDK is installed.

Section 2.6.2.2.1, "Annotated Code: JAccess Client.java" provides annotated code line-by-line to help you become familiar with Java Access Manager API calls.

Example 2-1 JAccess Client.java

import java.util.Hashtable;
import oracle.security.am.asdk.*;

public class JAccessClient {
   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 String m_configLocation = "/myfolder";
   public static void main(String argv[]) {
          AccessClient ac = null; 
      try {
          ac = AccessClient.createDefaultInstance(m_configLocation,
 AccessClient.CompatibilityMode.OAM_10G);
          
         ResourceRequest rrq = new ResourceRequest(ms_protocol, ms_resource,
               ms_method);
         if (rrq.isProtected()) {
            System.out.println("Resource is protected.");
            AuthenticationScheme authnScheme = new AuthenticationScheme(rrq);
            if (authnScheme.isForm()) {
               System.out.println("Form Authentication Scheme.");
               Hashtable creds = new Hashtable();
               creds.put("userid", ms_login);
               creds.put("password", ms_passwd);
               UserSession session = new UserSession(rrq, creds);
               if (session.getStatus() == UserSession.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");
                  }
                        //user can be loggedout by calling logoff method on the session object
               } 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 (AccessException ae) {
         System.out.println("Access Exception: " + ae.getMessage());
      }
      ac.shutdown();
   }
}
2.6.2.2.1 Annotated Code: JAccess Client.java

Import standard Java library class Hashtable to hold credentials.

import java.io.Hashtable;

Import the library containing the Java implementation of the Access SDK API classes.:

import oracle.security.am.asdk.*;

This application is named JAccessClient.

public class JAccessClient {

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. For example:

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 application domains, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

 public static void main(String argv[]) {

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

AccessClient ac = null;

 try {

Initialize the Access SDK by creating AccessClient instance by providing directory location of configuration file ObAccessClient.xml. There are multiple ways to provide configuration location to initialize the Access SDK. For more information refer to Oracle Access Manager Access SDK Java API Reference.

You only need to create an instance of AccessClient and it initializes Access SDK API. AccessClient.CompatibilityMode.OAM_10G indicates that Access SDK will be initialized to work in a mode which is compatible with both the 10g and 11g releases of Oracle Access Manager.

 ac = AccessClient.createDefaultInstance(m_configLocation ,
 AccessClient.CompatibilityMode.OAM_10G);

Create a new resource request object named rrq using the ResourceRequest 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 Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

  • 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. For more information on defining resource types and protecting resources with application domains, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

ResourceRequest rrq = new ResourceRequest(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 AuthenticationScheme constructor to create an authorization scheme object named authnScheme. Specify the resource request rrq so that AuthenticationScheme checks for the specific authorization scheme associated with that particular resource.

 AuthenticationScheme authnScheme =new AuthenticationScheme(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 UserSession constructor, create a user session object named session. Specify the resource request as rrq and the authentication scheme as creds so that UserSession can return the new structure with state information as to whether the authentication attempt has succeeded.

UserSession session = new UserSession(rrq, creds);

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

if (session.getStatus() == UserSession.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 Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

} 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 Access Client 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 from object ae and report it.

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

If the application need to logout user, then it can invoke logoff method on the object of UserSession class.

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

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

2.6.2.3 Example: Java Login Servlet

This example follows the basic pattern of API calls that define an Access Client, as described in Section 2.6.2.2, "Example of a Simple Access Client: JAccess Client.java". However, this example is implemented as a Java servlet running within a Web server, or even an application server. In this environment, the Access Client servlet has an opportunity to play an even more important role for the user of a Web application. By storing a session token in the user's HTTP session, the servlet can facilitate single sign-on for the user. In other words, the authenticated OAM 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 Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

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

A complete listing for the Java login servlet is shown in Example 2-2. This code can provide the basis for a plug-in to a web server or application server.

Section 2.6.2.3.1, "Annotated Code: Java Login Servlet" is an annotated version of this code.

Example 2-2 Java Login Servlet Example

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.*;
import oracle.security.am.asdk.*;
 
public class LoginServlet extends HttpServlet {
 
   public void init(ServletConfig config) throws ServletException {
      try {
          
           AccessClient ac = AccessClient.createDefaultInstance("/myfolder" ,
 AccessClient.CompatibilityMode.OAM_10G);                  
      } catch (AccessException ae) {
         ae.printStackTrace();
      }
   }
 
   public void service(HttpServletRequest request, HttpServletResponse response)
            throws IOException, ServletException {
      AuthenticationScheme authnScheme = null;
      UserSession user = null;
      ResourceRequest 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("request");
      String reqMethod = request.getMethod();
      Hashtable cred = new Hashtable();
      try {
         if (requestedPage == null || requestedPage.length()==0) {
            out.println("<p>REQUESTED PAGE NOT SPECIFIED\n");
            out.println("</BODY></HTML>");
            return;
         }
         resource = new ResourceRequest("http", requestedPage, "GET");
         if (resource.isProtected()) {
            authnScheme = new AuthenticationScheme(resource);
            if (authnScheme.isBasic()) {
               if (session == null) {
                  String sUserName = request.getParameter("userid");
                  String sPassword = request.getParameter("password");
                  if (sUserName != null) {
                     cred.put("userid", sUserName);
                     cred.put("password", sPassword);
                     user = new UserSession(resource, cred);
                     if (user.getStatus() == UserSession.LOGGEDIN) {
                        if (user.isAuthorized(resource)) {
                           session = request.getSession( true);
                           session.putValue( "user", 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 = (UserSession)session.getValue("user");
                  if (user.getStatus() == UserSession.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 (AccessException ex) {
          out.println(ex);
      }
   out.println("</BODY></HTML>");
   }
}
2.6.2.3.1 Annotated Code: Java Login Servlet

Import standard Java packages to support input and output and basic functionality.

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

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

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

Import the package oracle.security.am.asdk.jar, which is the Java implementation of the Access SDK API.

import oracle.security.am.asdk.*;

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 Access Client. In init method, Access SDK can be initialized by instantiating AccessClient by passing the location of the configuration file ObAccessClient.xml file. For more information for creating Access Client refer to Oracle Access Manager Access SDK Java API Reference. OAM_10g compatibility flag initialized Access SDK in a mode such that it is compatible with both OAM 10g server and OAM 11g server.

In the case of initialization failure, report that fact, along with the appropriate error message.

public void init() { 
      AccessClient ac =
 AccessClient.createDefaultInstance("/myfolder" ,
 AccessClient.CompatibilityMode.OAM_10G);
   } catch (AccessException ae) { 
         ae.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 members as null. These will store the Access structures used to process the resource request, then set the response type used by this application to text/html.

AuthenticationScheme authnScheme = null;
UserSession user = null;
ResourceRequest 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 UserSession) 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 a ResourceRequest 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 ResourceRequest("http", requestedPage, "GET");

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

if (resource.isProtected()) {
   authnScheme = new AuthenticationScheme(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.

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.

Additional Code for authnScheme.isForm

Note:

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

  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 sends a 302 redirect response for the original resource.

  5. Process the original request once again, this time using the UserSession 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 ResourceRequest structure named resource and the hashtable cred.

 user = new UserSession(resource, cred);

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

 if (user.getStatus() == UserSession.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 UserSession) and add the name of the user to it.

 session = request.getSession( true);
session.putValue( "user", 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 USER and assign it to the session variable user.

 } else {
    user = (UserSession)session.getValue("user");

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() == UserSession.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 (AccessException ex) {
   oe.println(ex);
}

Complete the output stream to the user's browser.

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

2.6.2.4 Example Using Additional Methods: access_test_java.java

Building on the basic pattern established in the sample application JAccess Client.java, discussed in Section 2.6.2.2, "Example of a Simple Access Client: JAccess Client.java", the following sample program invokes several additional OAM Server methods. For instance, it inspects the session object to determine which actions, also named responses, 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 OAM Server prior to running the application. For details about authentication action and configuring user authentication, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service. The complete listing for this sample application appears in Example 2–3.

An annotated version of the code is provided in Section 2.6.2.4.1, "Annotated Code: access_test_java.java".

Example 2-3 access_test_java.java

import java.util.*;
import oracle.security.am.asdk.*;
 
public class access_test_java {
 
  public static void main(String[] arg) {
    String userid, password, method, url, configDir, type,
 location;
    ResourceRequest res;
    Hashtable parameters = null;
    Hashtable cred = new Hashtable();
    AccessClient ac = null; 
    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 {
      ac = AccessClient.createDefaultInstance(configDir ,
 AccessClient.CompatibilityMode.OAM_10G);
          
    } catch (AccessException ae) {
      System.out.println("OAM Server SDK Initialization
 failed");
      ae.printStackTrace();
      return;
    }
    cred.put("userid", userid);
    cred.put("password", password);
    try {
      res = new ResourceRequest(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;
    }
    UserSession user = null;
    try {
      user = new UserSession(res, cred);
    } catch (Throwable t) {
      t.printStackTrace();
      System.out.println("Failed to create new user session");
      return;
    }
    try {
    if (user.getStatus() == UserSession.LOGGEDIN) {
      if (location != null) user.setLocation(location);
      System.out.println("user status is " + user.getStatus());
      
        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() == UserSession.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();
          }
        }      
   } 
   else 
   {      
           System.out.println("user status is " + user.getStatus());  
   } 
    } catch (AccessException ae)
    {    
          System.out.println("Failed to get user authorization");      
    }
   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++;   
           }
        }
   AuthenticationScheme auths;
   try 
   {
           auths = new AuthenticationScheme(res);
       if (auths.isBasic())
       {
             System.out.println("Auth scheme is Basic");
       }
       else 
       {
             System.out.println("Auth scheme is NOT Basic");
       }
   }
   catch (AccessException ase)
   {   
           ase.printStackTrace();
           return;
   }
   try 
   {      
           ResourceRequest resNew = (ResourceRequest) res.clone();   
           System.out.println("Clone resource Name: " +
 resNew.getResource());
   } 
   catch (Exception e) 
   {    
           e.printStackTrace(); 
   }  
   res = null;  
   auths = null; 
   ac.shutdown();
   }
  }
2.6.2.4.1 Annotated Code: access_test_java.java

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

import java.util.*;

Import the Access SDK API libraries.

import oracle.security.am.asdk.*;

This class 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 ResourceRequest to res.

ResourceRequest 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();

Initialize AccessClient reference to null.

AccessClient ac = null;

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;

Create AccessClient instance using configDir, in case if its null provide configuration file location using other options. For more information for creating Access Client, see Oracle Access Manager Access SDK Java API Reference.

try {
 ac = AccessClient.createDefaultInstance(configDir , 
   AccessClient.CompatibilityMode.OAM_10G); 
}

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

catch (AccessException ae) {
  System.out.println("
OAM Server SDK Initialize failed");
  ae.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 a ResourceRequest object named res, which returns values for the variables type, url and method from the OAM Server.

try {
res = new ResourceRequest(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 ResourceRequest 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 UserSession parameter user to empty.

UserSession user = null;

Create a UserSession structure named user so that it returns values for the ResourceRequest structure res and the AuthenticationScheme structure cred.

try
  user = new UserSession(res, cred);

If the attempt to create the UserSession 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.

try
{
if (user.getStatus() == UserSession.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 AccessClient to the value of the variable location, then report that the user is logged in along with the status code returned by the OAM 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 UserSession 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() == UserSession.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 ResourceRequest 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
  }
}

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

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

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

  catch (AccessException ae)
  System.out.println("Failed to get user authorization");
}

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 AuthenticationScheme object named auths for the ResourceRequest object res.

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

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

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

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

  return;
}

Determine if the authorization scheme is basic.

try
{
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 ResourceRequest object named resNEW from the original object res.

  ResourceRequest resNew = (ResourceRequest) res.clone();

Report the name of the newly cloned object.

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

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

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

Set the ResourceRequest object res and the AuthenticationScheme object auths to NULL, then disconnect the Access SDK API.

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

2.6.2.5 Example of Implementing Certificate-Based Authentication in Java

The following is a code snippet that demonstrates implementing an Access Client 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. The OAM Server uses this certificate only to identify the user. It does not perform validation such as the validity period, if the root certification is trusted or not, and so on.

File oCertFile = new File("sample_cert.pem");
 FileInputStream inStream = new FileInputStream(oCertFile);
 CertificateFactory cf =
 CertificateFactory.getInstance("X.509");

// cert must point to a valid java.security.cert.X509Certificate instance.
X509Certificate cert = (X509Certificate)
cf.generateCertificate(inStream);
 
// 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(Base64.encodeBase64 (encodedCert));
 
// Create hashtable to hold credentials
    Hashtable creds = new Hashtable();
 
// Store the Base 64-encoded under the key "certificate"
    cred.put("certificate", base64EncodedCert);
 
// Create ResourceResource request object including all information about the // // resource being accessed
    ResourceRequest resourceRequest = new ResourceRequest(resourceType, resourceUrl, operation);
 
// Create a UserSession with the requestRequest and the cred hashtable
    UserSession userSession = new UserSession(resourceRequest, creds);
 
// The above statement will throw an exception if the certificate cannot be mapped // to a valid user by the OAM Server.

The following import statements are associated with the snippet:

import java.security.cert.CertificateFactory;
     import java.security.cert.X509Certificate;
     import java.io.FileInputStream;
     import oracle.security.am.common.nap.util.Base64;

2.7 Building and Deploying an Access Client Program

The following topics are discussed in this section:

2.7.1 Setting the Development Environment

The required environment is as follows:

  • Install JDK 1.6.0 or higher.

  • Install Oracle Access Manager 11g Access SDK.

  • Define a JAVA_HOME environment variable to point to JDK installation directory. For example, on UNIX-like operating systems, execute the following command:

    setenv JAVA_HOME <JDK install dir>/bin

  • Modify the PATH environment variable to the same location where JAVA_HOME/bin points. For example, on UNIX-like operating systems, execute the following command:

    setenv PATH $JAVA_HOME/bin:$PATH

  • Modify the CLASSPATH environment variable to point to JDK and Access SDK jar files. For example, on UNIX-like operating systems, execute the following command:

    setenv CLASSPATH $JAVA_HOME/lib/tools.jar:$ACCESSSDK_INSTALL_DIR/oamasdk-api.jar:$CLASSPATH

2.7.2 Compiling a New Access Client Program

After the development environment is configured (see Section 2.7.1, "Setting the Development Environment"), you can compile your Access Client program using a command similar to the following:

Javac –cp <location of Access SDK jar> SampleProgram.java

Modify details such as class path and Access Client program name as needed.

2.7.3 Configuring and Deploying a New Access Client Program

For information, see Section 2.5, "Configuring and Deploying Access Clients".

2.8 Compatibility: 11g versus 10g Access SDK and APIs

The following topics are discussed in this section:

The 11g Access Manager API enables developers to write custom Access Client code in Java, which is functionally equivalent to the 10g (10.1.4.3) Java Access Client. With Oracle Access Manager 11g, your Java code will interact with underlying Java binaries in the API.

The automatic built-in Java garbage collector deallocates the memory for unused objects when it (the garbage collector) deems appropriate. Garbage collectors do not guarantee when an object will be cleaned up, but do ensure that all objects are destroyed when they are no longer referenced, and no memory leak occurs.

10g and 11g Access Manager API functionality has been organized into seven basic classes. Table 2-5 lists the corresponding class names for the Java language platform.

Table 2-5 Comparison: 11g versus 10g Access API Classes

Purpose of the Class 11g Java Class 10g Java Class

Supports parameter storage structures (lists or hashtables)

From the Java Development Kit:

java.util.Hashtable, which extends java.util.Dictionary

java.util.Set

java.util.Hashtable, which extends java.util.Dictionary (This is not a Com. Oblix.Access class)

Supports iteration within lists (Java enumerate hashtables)

From the Java Development Kit:

java.util.Hashtable, which extends java.util.Dictionary

java.util.Set

java.util.Hashtable, which extends java.util.Dictionary (This is not a Com. Oblix.Access class)

Creates and manipulates structures that handle user authentication

AuthenticationScheme class from oracle.security.am.asdk

ObAuthenticationScheme implements ObAuthenticationSchemeInterface

Creates and manipulates structures that handle user requests for resources

ResourceRequest class from oracle.security.am.asdk

ObResourceRequest implements ObResourceRequestInterface

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

UserSession class from oracle.security.am.asdk

ObUserSession implements ObUserSessionInterface

Retrieves and modifies Access Client configuration information

AccessClient class from oracle.security.am.asdk

ObConfig

Handles errors thrown by the Access Manager API

AccessException, OperationNotPermittedException from oracle.security.am.asdk

ObAccessException

2.8.1 Compatibility of the Access SDK

The Access SDK implements the same functionality that is supported by the 10g JNI ASDK. This functionality is implemented so that you can use it to develop custom access gates that work seamlessly with both the Oracle Access Manager 10g server and the Oracle Access Manager 11g server.

The Access SDK also implements some new and modified functionality that can only be used with an Oracle Access Manager 11g server. Consequently, the Access SDK can gracefully detect whether the application is trying to use this functionality with Oracle Access Manager 10g server.

The new functionalities in Oracle Access Manager 11g Access SDK (oracle.security.am.asdk) are as follows:

  • Enumerating sessions for the given user

  • Terminating the given session

  • Setting attributes in the given user session

  • Retrieving attributes set in the given session

  • Validating user credentials without establishing a session

  • Validating user credentials without establishing a session and performing authorization in the same request

Note:

The last two functions are also provided with the com.oblix.access package in the Oracle Access Manager 11g Access SDK.

Additionally, the Access SDK provides a modified implementation of the user logout functionality for removing the server side session. This functionality is not supported with Oracle Access Manager 10g server.

2.8.2 Compatibility of 10g JNI ASDK and 11g Access SDK

The following figure depicts the one-to-one mapping between the Oracle Access Manager 10g JNI version and the Oracle Access Manager 11g Access SDK version of the com.oblix.access package.

Figure 2-4 Mapping Between Versions of the com.oblix.access Package

Description of Figure 2-4 follows
Description of "Figure 2-4 Mapping Between Versions of the com.oblix.access Package "

Custom access gates developed using 10g JNI ASDK can continue to work with 11g Access SDK without any code changes.

As shown in Figure 2-4, the following classes have been added to the Oracle Access Manager 11g Access SDK com.oblix.access package:

  • ObPseudoUserSession: This class provides the following functionalities, which you can only use with Oracle Access Manager 11g server:

    • Validating user credentials without establishing a session.

    • Validating user credentials without establishing a session and performing authorization in the same request.

  • ObAccessRuntimeException: This class indicates a runtime error while performing operations that use ObAuthenticationScheme and ObResourceRequest classes.

2.8.3 Deprecated: Oracle Access Manager 10g JNI SDK

The Access SDK provides support for interfaces in the 10g JNI ASDK com.oblix.access package. However, all APIs in com.oblix.access are marked as deprecated. These APIs will not be enhanced or supported in future Oracle Access Manager 11g Access SDK releases.

2.9 Migrating Earlier Applications or Converting Your Code

This section describes the migration processes to follow if you want to use the Access SDK. Migrating to the Access SDK can be necessary for the following reasons:

  • Migrate applications to replace the com.oblix.access API of Oracle Access Manager 10g JNI ASDK with the corresponding API in Oracle Access Manager 11g Access SDK without changing how those applications use Access SDK.

  • Migrate application code to use oracle.security.am.asdk API instead of com.oblix.access, which is supported in Oracle Access Manager 11g Access SDK for backward compatibility.

This section contains the following topics:

2.9.1 Modifying Your Development and Runtime Environment

Before migrating an application, ensure that your development environment is configured. Also ensure that the Oracle Access Manager 11g Access SDK is configured correctly. For more information, see Section 2.5, "Configuring and Deploying Access Clients".

2.9.2 Migrating Your Application

You can migrate Access Clients and plug-ins developed with the Oracle Access Manager 10g com.oblix.access package to operate with the OAM 11g Server. This section describes how programs written with the Oracle Access Manager 10g JNI ASDK can be used with Oracle Access Manager 11g.

Note:

For information about the similarities and differences between the com.oblix.access APIs in Oracle Access Manager 10g JNI and in Oracle Access Manager 11g Access SDK, see Section 2.8.2, "Compatibility of 10g JNI ASDK and 11g Access SDK".

Support for the classes and interfaces provided in Oracle Access Manager 10g JNI SDK and in Oracle Access Manager 11g Access SDK is identical.

In general, you are not required to change or recompile any application code when migrating applications to use com.oblix.access classes from Oracle Access Manager 11g Access SDK.

A new runtime exception, ObAccessRuntimeException, was introduced in the com.oblix.access package. Oracle Access Manager throws this exception when performing operations of AuthenticationScheme and ResourceRequest classes.

Oracle recommends that you perform proper exception handling in the application code. If this is done, the application should be recompiled with the OAM 11g Access SDK jar file.

2.9.2.1 Configuration Specific to Migration

This discussion assumes that Oracle Access Manager 10g ASDK component is installed and configured with the OAM Server. This scenario uses existing Access Client applications developed using Oracle Access Manager 10g JNI ASDK. The following assumptions are made:

  • The configuration items listed in Section 2.5.1, "Configuration Requirements" are referenced from the Oracle Access Manager 10g ASDK installation directory (ASDK_INSTALL_DIR).

  • ObAccessClient.xml is read from ASDK_INSTALL_DIR/access/oblix/lib.

  • password.xml is read from ASDK_INSTALL_DIR/access/oblix/config if the transport security mode is Simple or Cert.

Simple Mode

To configure the Oracle Access Manager 10g ASDK component in Simple mode, see the Oracle Access Manager Administration Guide for the 10g release.

Perform the following steps:

  1. Import the aaa_cert.pem and aaa_key.pem files into oamclient-keystore.jks.

    The aaa_cert.pem and aaa_key.pem files are located in ASDK_INSTALL_DIR/access/oblix/config/simple.

  2. Located the self-signed CA certificate used for issuing Simple mode certificates in ASDK_INSTALL_DIR/access/oblix/tools/openssl/simpleCA.

  3. Import the self-signed CA certificate into oamclient-truststore.jks.

  4. Import the certificate and key files into the JKS store by following the steps in Section 2.5.3, "SSL Certificate and Key Files".

  5. Copy the JKS stores to ASDK_INSTALL_DIR/access/oblix/config/simple.

Cert Mode

To configure the Oracle Access Manager 10g ASDK component in Cert mode, see the Oracle Access Manager Administration Guide for the 10g release.

Perform the following steps:

  1. Import the aaa_cert.pem and aaa_key.pem files into oamclient-keystore.jks. Import the aaa_chain.pem into oamclient-truststore.jks.

    The aaa_cert.pem, aaa_key.pemand aa_chain.pem files are located in ASDK_INSTALL_DIR/access/oblix/config.

  2. Import the certificate and key files into the JKS store by following the steps in Section 2.5.3, "SSL Certificate and Key Files".

  3. Copy the JKS stores to ASDK_INSTALL_DIR/access/oblix/config/simple.

Configuration File Location

An Access Client application migrated to use the com.oblix.access API can specify the Oracle Access Manager 10g JNI ASDK configuration file locations as follows:

  • Either specify the direction location where Oracle Access Manager 10g ASDK is installed while initializing ASDK, or

  • Set an environment variable OBACCESS_INSTALL_DIR, which points to the directory location where Oracle Access Manager 10g JNI ASDK is installed.

Oracle Access Manager 11g Access SDK then determines the path of the required files based on the location passed to it.

Environment

To set your environment, follow the instructions in Section 2.7.1, "Setting the Development Environment". The Oracle Access Manager 10g JNI ASDK is named jobaccess.jar. If jobaccess.jar is in your CLASSPATH, it must be removed.

2.9.3 Converting Your Code

This section describes how to use programs written with the Oracle Access Manager 10g JNI ASDK with Oracle Access Manager 11g.

The 11g Access SDK supports the functionality of 10g JNI ASDK APIs in the com.oblix.access package. Implementing these functionalities in the 11g Access SDK enables backward compatibility with the 10g JNI ASDK. However, all of the APIs in com.oblix.access are deprecated. These APIs will not be enhanced or supported in future 11g Access SDK releases.

The oracle.security.am.asdk package contains a new authentication and authorization API. In addition to functionality supplied by the com.oblix.access package, the oracle.security.am.asdk package also contains enhancements that take advantage of OAM 11g Server functionality.

2.9.3.1 Understanding Differences Between JNI ASDK and Access SDK

The following table compares the APIs from the Oracle Access Manager 10g JNI SDK com.oblix.access package with the APIs from the Oracle Access Manager 11g Access SDK oracle.security.am.asdk package. Where applicable, this table also maps the classes between Oracle Access Manager 10g ASDK and Oracle Access Manager 11g Access SDK.

Table 2-6 Differences Between JNI ASDK com.oblix.access Package and Access SDK oracle.security.am.asdk Package

JNI ASDK com.oblix.access Package Access SDK oracle.security.am.asdk Package

Interface Summary:

  • ObAuthenticationSchemeInterface

  • ObResourceRequestInterface

  • ObUserSessionInterface

Interface Summary:

None

Class Summary:

  • ObAuthenticationScheme

  • ObConfig

  • ObDiagnostic

  • ObResourceRequest

  • ObUserSession

Class Summary:

  • AuthenticationScheme

  • AccessClient

  • Supported through AccessClient

  • ResourceRequest

  • UserSession

  • PseudoUserSession

  • BaseUserSession

Exception Summary:

ObAccessException

Exception Summary:

  • AccessException

  • OperationNotPermittedException

Enumeration Summary:

None

Enumeration Summary:

AccessClient.CompatibilityMode.OAM_10G

Note that the Oracle Access Manager 11g Access SDK contains a new set of APIs that are functionally similar to the Oracle Access Manager 10g JNI SDK APIs, but with new interfaces.

2.9.3.2 Converting Code

You can migrate application code that was implemented using Oracle Access Manager 10g JNI ASDK to achieve the same functionality in Oracle Access Manager 11g Access SDK. This section explains how to modify existing application code to use the new API in Oracle Access Manager 11g Access SDK.

2.9.3.2.1 Initializing and Uninitializing Access SDK

In Oracle Access Manager 10g JNI SDK, the com.oblix.access.ObConfig class provides a function to perform ASDK initialization and uninitialization. In Oracle Access Manager 11g Access SDK, the oracle.security.am.asdk.AccessClient provides this function.

As with Oracle Access Manager 10g JNI SDK, the Access Client application instance can work with a given configuration.

Depending on the requirement, you can use the AccessClient class in two different ways:

  • You can use the createDefaultInstance static function to create a single instance of the AccessClient class. Only a single default instance of this class is permitted. Invoking this method multiple times within a single instance of the Access Client application causes an exception.

    If you use the createDefaultInstance method, you must use the AccessClient class instance obtained using this method when instantiating any of AuthenticationScheme, ResourceRequest, or UserSession classes

  • You can use the createInstance static function to create a new AccessClient class instance initialized with a given configuration. This class is required when it is within the same running instance of an Access Client application, and the application must work with different Oracle Access Manager systems or different configurations. Each AccessClient class instance can log its messages to different log files by passing in an appropriate logger name while constructing the Access Client instances.

    You must pass AccessClient.CompatibilityMode.OAM_10G in compatibility mode when initializing AccessClient objects.

    If you use the createInstance method, you must use the AccessClient class instance obtained using this method when instantiating the AuthenticationScheme, ResourceRequest, or UserSession classes.

While the application is shutting down, it should invoke the AccessClient class shutdown method to perform uninitialization as shown in the following examples:

  • For Oracle Access Manager 10g JNI ASDK

    Public static void main (String args[]) {
  try {
   ObConfig.Initialize (); // Configuration is read from the location pointed by OBACCESS_INSTALL_DIR
                                         // environment variable

    OR

      ObConfig.Initialize (configLocation); //Configuration is read from the location provided
   ………..
   }catch (ObAccessException e){
   }
ObConfig.shutdown();
}//main ends here

  • For Oracle Access Manager 11g Access SDK

    import java.io.*;
import java.util.*;
import oracle.security.am.asdk.*; //Import classes from OAM11g Access ASDK
…………..
Public static void main (String args[]) {
  try {
     ac = AccessClient.createDefaultInstance (“”, AccessClient.CompatibilityMode.OAM_10G); // Refer to Oracle Access Manager Access SDK Java API Reference

    OR

         AccessClient.createInstance(“”,AccessClient.CompatibilityMode.OAM_10G); // Refer to Oracle Access Manager Access SDK Java API Reference
   ………..
   }catch (AccessException e){
   }
ac.shutdown();
}//main ends here
2.9.3.2.2 Performing Access Operations

As shown in Table 2-6, there is a one-to-one mapping between the classes that are used to perform access operations. The classes in oracle.security.am.asdk are AuthenticationScheme, ResourceRequest, and UserSession.

Depending how the AccessClient class is instantiated, use the corresponding constructor of these classes.

Similar to Oracle Access Manager 10g JNI ASDK, any error that occurs during initialization or while performing access operations, is reported as an exception. AccessException is the exception class used in Oracle Access Manager 11g Access SDK as seen in the following examples:

  • For Oracle Access Manager 10g JNI ASDK

    Public static void main (String args[]) {
  try {
   ObConfig.Initialize (); // Configuration is read from the location pointed by OBACCESS_INSTALL_DIR
                                         // environment variable
   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();
}//main ends here

  • For Oracle Access Manager 11g Access SDK

    import java.io.*;
import java.util.*;
import oracle.security.am.asdk.*; //Import classes from OAM11g Access ASDK
 
Public static void main (String args[]) {
  AccessClient ac;
  try {
    ac = AccessClient.createDefaultInstance(“”,
     AccessClient.CompatibilityMode.OAM_10G);
 
    ResourceRequest rrq = new ResourceRequest(ms_protocol,ms_resource, ms_method);
 
    if (rrq.isProtected()) {
      System.out.println("Resource is protected.");
      AuthenticationScheme authnScheme =new AuthenticationScheme(rrq);
      if (authnScheme.isForm()) {
        System.out.println("Form Authentication Scheme.");
        Hashtable creds = new Hashtable();
        creds.put("userid", ms_login);
        creds.put("password", ms_passwd);
        creds.put("ip", ms_ip);
        creds.put("operation", ms_method);
        creds.put("resource", ms_resource);
        creds.put(“targethost”, ms_targethost);
 
        UserSession session = new UserSession(rrq, creds);
        if (session.getStatus() == UserSession.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");
        }
      }
    }catch (AccessException oe) {
      System.out.println("Access Exception: " + oe.getMessage());
    }
    ac.shutdown();
} //main ends here

2.10 Best Practices

This section presents a number of ways to avoid problems and to resolve the most common problems that crop up during development.

2.10.1 Avoiding Problems

Here are some suggestions for avoiding problems with the Access Clients you create:

  • Make sure that your Access Client attempts to connect to the correct OAM Server.

  • Make sure the configuration information on your OAM Server matches the configuration information on your Access Client. You can check the Access Client configuration information on your OAM Server, using the Oracle Access Suite. For details, see "Registering an Access Client" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

  • To ensure clean connect and disconnect from the OAM Server, use the initialize and shutdown methods in the AccessClient class.

  • The environment variable, OBACCESS_INSTALL_DIR, must be set on your Windows or UNIX-like host computer so that you can compile and link your Access Client. In general, you also want the variable to be set whenever your Access Client is running.

  • Use the exception handling features (try, throw, and catch) of the language used to write your custom Access Client code to trap and report problems during development.

2.10.1.1 Thread Safe Code

Your Access Client represents just one thread in your entire, multi threaded 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 UNIX-like platforms and /MD for Windows platforms.

  • Take care to use in thread-safe fashion shared local variables such as FILE pointers.

  • If Access Client is developed using com.oblix.access API of Access SDK, the environment variable, OBACCESS_INSTALL_DIR, must be set on your Windows or UNIX-like host computer so that you can compile and link your Access Client. In general, you also want the variable to be set whenever your Access Client is running. If Access Client is developed using oracle.security.am.asdk API of Access SDK, make sure that environment is setup correctly. Please refer documentation of AccessClient class in Oracle Access Manager Access SDK Java API Reference.

2.10.2 Identifying and Resolving Problems

Here are some things to look at if your Access Client fails to perform:

  • Make sure that your OAM 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 OAM Server to which you want to connect your Access Client.

  • Make sure that Access Client performs user logout to ensure that OAM Server-side sessions are deleted. An accumulation of user sessions can prevent successful user authentication.

  • 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 Access Client is not being answered by a lower-level Access System policy which overrides the one you think you are testing.

  • The Oracle Access Manager 11g Access Tester enables you to check which policy applies to a particular resource. For details about using the Access Tester and protecting resources with application domains, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.