22 Managing Authentication and Shared Policy Components

Administrators can configure shared policy components, manage authentication schemes, and deploy and manage plug-ins for authentication.

• Prerequisites to Managing Authentication and Shared Policy Components

• Configuring Shared Policy Components

• Managing Resource Types

• Managing Host Identifiers

• Understanding Authentication Methods and Credential Collectors

• Managing Native Authentication Modules

• Orchestrating Multi-Step Authentication with Plug-in Based Modules

• Deploying and Managing Individual Plug-ins for Authentication

• Managing Authentication Schemes

• Extending Authentication Schemes with Advanced Rules

• Configuring Challenge Parameters for Encrypted Cookies

• Configuring Authentication POST Data Handling

• Long URL Handling During Authentication

• Using Application Initiated Authentication

22.1 Prerequisites to Managing Authentication and Shared Policy Components

The Oracle Access Management Console and at least one OAM Server must be installed and running within a WebLogic Server domain, and Access Manager must be running with at least two registered Agents.

Oracle recommends that you review information in Understanding Single Sign-On with Access Manager before performing activities in this section.

22.2 Configuring Shared Policy Components

You can configure shared policy components required for use in Access Manager authentication policies that protect resources and enable single sign-on.

See Also:

Understanding Single Sign-On with Access Manager

1. Confirm that the desired resource type is defined, as described in this chapter:

   • Managing Resource Types

2. Confirm that a host identifier definition named for the agent was created during agent registration, (or create one yourself), as described in:

   • Managing Host Identifiers

3. Gain comprehension about credential collection with Access Manager:

   • Understanding Authentication Methods and Credential Collectors

4. Learn about and use the authentication plug-ins that enable multi-step authentication:

   • Orchestrating Multi-Step Authentication with Plug-in Based Modules

   • Deploying and Managing Individual Plug-ins for Authentication

5. Create and manage authentication schemes that you can add to authentication policies, as described in:

   • Managing Authentication Schemes

   • Configuring Challenge Parameters for Encrypted Cookies

6. Set up your own global password policy for either the default embedded or optional detached credential collector (unless specified, tasks apply to both ECC and DCC, with minor changes noted in the discussion):

   • Accessing Password Policy Configuration Page

   • Managing Global Password Policy

   • Configuring Password Policy Authentication

   • DCC: Configuring OAM WebGate and Authentication Policy for DCC

   • Completing Password Policy Configuration

7. Proceed to Managing Policies to Protect Resources and Enable SSO to set up authentication policies.

22.3 Managing Resource Types

Administrators can add a resource to an application domain, search a defined resource type, or create a defined resource type.

• Resource Types and Their Use

• Resource Type Page

• Searching for a Specific Resource Type

• Creating a Custom Resource Type

22.3.1 Resource Types and Their Use

When adding a resource to an Application Domain, Administrators must choose from a list of defined Resource Types.

Oracle-provided resource types include:

• HTTP

• wl_authen

• TokenServiceRP

Administrators can configure additional resource types, and define operations on both Oracle-provided and custom resource types. A particular resource can be defined to use a subset of the declared operations, or all of them (which includes any new operators defined on the resource's type subsequently.Administrators cannot remove custom resource types or operations for which resources have been created. Oracle-provided resource types and operations are marked as read-only within the policy store and cannot be removed.

Note:

Changes to the operation list of a resource type is not allowed if a resource of that type exists.

22.3.2 Resource Type Page

In the Oracle Access Management Console, resource types are organized with other Components under the Policy Configuration tab. The navigation tree shows Oracle-provided resource types: HTTP, wl_authen, and TokenServiceRP.

Note:

Pre-defined resource types cannot be deleted. Pre-defined operations are shown with a lock icon and cannot be deleted. Additional operations can be created, edited, or deleted as needed.

The HTTP resource type, shown in Figure 22-1, is used for Web applications protected by Access Manager and accessed using internet protocols (HTTP or HTTPS).

Figure 22-1 Default HTTP Resource Type Definition

Description of "Figure 22-1 Default HTTP Resource Type Definition"

The wl_authen resource type is shown in Figure 22-2. It is used for Fusion Middleware applications that use one of the following Access Manager Identity Assertion Provider configurations described in the Securing Applications with Oracle Platform Security Services:

• Identity Asserter

• Identity Asserter with Oracle Web Services Manager

• Authenticator function

Figure 22-2 Default Resource Type wl_authen

Description of "Figure 22-2 Default Resource Type wl_authen"

The TokenServiceRP resource type represents the Token Service Relying Party, as shown in Figure 22-3. The operation for this resource type is Issue.

Figure 22-3 Default Resource Type TokenServiceRP Resource Type

Description of "Figure 22-3 Default Resource Type TokenServiceRP Resource Type"

Table 22-1 describes the elements in each resource type definition.

Table 22-1 Resource Type Definition

Element	Description
Name	Required. A unique name of up to 30 alpha or numeric characters. Note: A non-HTTP Resource Type name cannot match a Host Identifier (and vice versa).
Description	Optional. Use this field to describe the purpose of this resource type using up to 200 alpha or numeric characters. For example: Resources representing WebLogic Authentication schemes.
Operations	Optional. Policies that govern a particular resource apply to all specified operations defined for the resource. Add (or remove) operations for this resource type as a string and the operations will be available when you define a resource of this type within an Application Domain. There is no limit to the number of operations that can be added to the resource type. Get Post Put Head Issue (TokenServiceRP) Login (wl_authen) Delete Trace Options Connect Other (available with Oracle Access Manager 10 is not supported in 11g). Remote Registration: During automatic policy creation, specified operations are supported. During automatic policy creation with no operations specified, then All operations defined for that type are supported. See Also: Resource Types and Their Use and Resources in an Application Domain.

22.3.3 Searching for a Specific Resource Type

Users with valid Administrator credentials can to locate a defined resource type.

See Also:

"SSO Agent Search Page"

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Resource Types in the Access Manager section.
3. In the Name field, enter the name of the Resource Type you want to find (with or without a wild card (*)), and click Search. For example:

   h*
   

   Alternatively: Go to the desired Application Domain, open the Resources node to display controls for that domain, choose a Resource Type from the list, and click Search.

4. In the results table, you can:

   • Edit or View: Click the Edit button in the tool bar to display the configuration page.

   • Delete: Click the Delete button in the tool bar to remove the instance; confirm removal in the Confirmation window.

   • Detach: Click Detach in the tool bar to expand the table to a full page.

   • Reorder Columns: Select a View menu item to alter the appearance of the results table.

22.3.4 Creating a Custom Resource Type

Users with valid Administrator credentials can create a defined resource type.

For instance, you can define a custom resource type that applies to as few as one or two (or more) operations. Any defined custom resource type is listed with default resource types when adding resources to an authentication or authorization policy.

See Also:

• "Resource Types and Their Use"

• "Defining Resources in an Application Domain"

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Resource Types in the Access Manager section.
3. Click Create Resource type.
4. In the page that appears, enter the following information:

   • Name: A unique name that identifies this resource type.

   • Description: Optional.

   • Operations: Click + in the Operations table, type the operation name into the field provided. Repeat as needed to define all operations for this resource type.

   • Reconfigure Table: Select a View menu item to alter the appearance of the results table.

5. Click Apply to submit this custom resource definition.
6. Add this resource definition to an Application Domain as described in "Adding and Managing Policy Resource Definitions".

22.4 Managing Host Identifiers

Administrators can create, modify, and remove host identifiers manually.

• About Host Identifiers

• About Virtual Web Hosting

• Host Identifier Page

• Creating a Host Identifier

• Searching for a Host Identifier Definition

• Viewing or Editing a Host Identifier Definition

• Deleting a Host Identifier Definition

22.4.1 About Host Identifiers

Access Manager policies protect resources on computer hosts. Within Access Manager, the computer host is specified independently using a host identifier.

Table 22-2 illustrates the different host names under which a Web server might be accessible to employees. Creating a single Host Identifier using all of these names allows you to define a single set of policies to appropriately protect the application, regardless of how the user accesses it.

Table 22-2 Host Identifiers Examples

Sample Host Identifier	Description
hrportal.intranet.company.com	A friendly name employees can remember. This is a load-balanced proxy, and requests to this could actually utilize one of several servers hosting the HR application.
hr-sf-02.intranet.company.com	A single machine hosting the application, which can be accessed directly.
hrportal.company.com	The same application is also accessible externally to the corporate firewall, primarily for use by ex-employees to check benefits, 401k info, and so on. This is also a load-balanced reverse proxy.

Based on a defined host identifier, Administrators can add specific resources to an Application Domain and apply policies to protect those resources.

Registered Agents protect all requests that match the addressing methods defined for the host identifier used in a policy. A request sent to any address on the list is mapped to the official host name and Access Manager can apply the policies that protect the resource and OAM can apply the policies that protect the resource.

A host identifier is automatically created when an Agent (and application) are registered using either the Oracle Access Management Console or the remote registration tool. Administrators can manually add a host identifier if an application and resources exist on a host that does not have a mapped host identifier. Also, Oracle Access Management Administrators can modify an existing host identifier to add in the new host name variations. For instance, adding another proxy Web server with a different host name requires a new host name variation.

For more information, see:

• Host Identifier Usage

• Host Identifier Guidelines

• Host Identifier Variations

22.4.1.1 Host Identifier Usage

At design time, the host identifier can be used while defining which resources belong to a specific Application Domain. Resources are scoped using their host identifier (HTTP) or type (non-HTTP). This combination uniquely identifies them across Access Manager.

Note:

Each resource should be unique across all Application Domains; each resource and host identifier combination must be unique across all Application Domains.

Runtime Usage

At run time, Web server host information in the access query from an OAM Agent is mapped to a host identifier and associated with the resource that is being accessed by a user. The OAM Agent obtains the Web server host information in one of two ways:

• If the Preferred Host parameter is configured for virtual Web hosting support (see"About Virtual Web Hosting"), Web server host information for the given request is obtained from the Web server.

• If the Preferred Host parameter directly specifies the Web server host information, it is always used irrespective of the Web server's own host information.

This allows for the Resources to be specified in terms of logical host names in their Host Identifiers, instead of the host names matching the present deployment of the Web server.

For instance, a user accessing aseng-wiki, would enter:

http://example-wiki.uk.example.com/wikiexample

Here, wikiexample is the resource URL and example-wiki.uk.example.com is the host. Matching this host and port (port is 80) provides the host identifier.

Preferred Host

Web server host information is generally acquired by setting the Preferred Host string of the OAM Agent. If the Agent is actively protecting multiple virtual hosts, this string can be set to server_name to ensure that the actual request hostname is correctly picked up from the Web server's request object. For more information, see "About Virtual Web Hosting"

Authenticating Hosts and Challenge Redirect in Authentication Schemes

When a user attempts to access a protected resource URL, she is redirected to the server specified in the Challenge Redirect field of the authentication scheme. If the authentication challenge is to be processed by another host, the name of that host must be defined to be available in the Host Identifiers list. For example, if a user is redirected to an SSL-enabled server for authentication, that server must be defined as a host identifier.

Note:

If you enter a host name in the Challenge Redirect field of an authentication scheme, it must be defined as a Host Identifier.

22.4.1.2 Host Identifier Guidelines

Each host identifier can be defined to represent one or more Web server hosts.

Following are several important guidelines for host identifiers:

• Each host name must be unique.

• Each host name:port pair must be unique.

• Each host name:port pair must belong to only one host identifier.

• Each host name:port pair must match the end user's entry exactly.

• A Host Identifier name cannot match a non-HTTP Resource Type name (and vice versa).

• Each resource and host identifier combination must be unique across all Application Domains.

For more information, see "Host Identifier Variations".

22.4.1.3 Host Identifier Variations

Host identifiers are used to simplify the identification of a Web server host by defining all possible hostname variations. Host identifiers consist of a list of all URL addressing methods. A host identifier must be configured for each Web site or virtual Web site that you want to protect with Access Manager.

You can identify Web server hosts to Access Manager in various ways, for example, by providing a computer name or an IP address. The following are examples of how the same host can be addressed:

• example.com

• example.com:80

• www.example.com

• www.example.com:80

• 216.200.159.58

• 216.200.159.58:80

22.4.2 About Virtual Web Hosting

You can install a Webgate on a Web server that contains multiple Web site and domain names. The Webgate must reside in a location that enables it to protect all of the Web sites on that server.

The virtual Web hosting feature of many Web servers enables you to support multiple domain names and IP addresses that each resolve to their unique subdirectories on a single virtual server. For example, you can host abc.com and def.com on the same virtual server, each with its own domain name and unique site content. You can have name-based or IP-based virtual hosting.

A virtual host referees the situation where the same host has multiple sites being served either based on multiple NIC cards (IP based) or multiple names (for example, abc.com and def.com resolving to same IP).

Consider a case where you have two virtual hosts configured on an OHS Server acting as reverse proxy to OAM Server, as follows:

• One virtual host is configured in two-way SSL mode

• One virtual host configured in non-SSL mode

Suppose there are two resources protected with different authentication schemes and Application Domains:

• /resource1 is protected by a X509Scheme with a Challenge URL (to define the credential collection URL) of https://sslvhost:port/

  When the user accesses /resource1 he is redirected to the OHS Server on the SSL port for authentication and is asked for the X.509 Certificate.

• /resource2 is protected by a LDAPScheme on the second virtual host with a Challenge Redirect of http://host:port/

  When user accesses /resource2 he is redirected to second virtual host which is in non-SSL mode (or in one way SSL mode if required). The Login form for LDAP authentication is displayed.

22.4.2.1 Configuring Virtual Hosting for Non-Apache Web Servers

Ensure that the Virtual Host box is checked on the OAM Webgate registration page. On most Web servers, other than Apache-based servers, you must set the Preferred Host value to HOST_HTTP_HEADER. This ensures that, when user's browser sends a request, the Webgate sets the value of the Preferred Host to the host value in the request.

For example, suppose a user enters the string example2 in a URL:

http://example2

On the Web server, if one of the Web sites has a host named example2, the request is served by the matching virtual site.

In the Preferred Host field of the expanded OAM Webgate registration page, enter the following:

HOST_HTTP_HEADER.

IIS Virtual Hosting: From the IIS console, you must configure each virtual Web site to contain the following fields:

• Host Header Name

• IP address

• Port

22.4.2.2 Associating a Webgate for Apache with Virtual Hosts, Directories, or Files

Ensure that the Virtual Host box is checked on the OAM Webgate registration page. On Apache-based Web servers (Apache, Apache 2, IBM HTTP Server, Oracle HTTP Server, and so on), the Preferred Host value must be set to SERVER_NAME.

Note:

The SERVER_NAME value is not supported for any host other than an Apache-based server. If you set this value for a non-Apache-based server, users will be unable to access any resources that are protected by Webgate on that Web server. Users will, instead, receive an error that the Webgate configuration is incorrect.

The ServerName directive must be explicitly set with 7777 along with the hostName. This is irrespective of the Listen directive is set correctly. The Server sometimes requires this value explicitly to identify itself, most often it can identify itself automatically.

When using an Apache-based reverse proxy for single sign-on, in the Web server configuration file (httpd.config, for example) file you specify the Web sites to run on the Apache server. The settings can be global across all Web sites or local to a Web site. You can restrict the Access Manager loading references in the httpd.config file to be associated with a specified site, with virtual hosts, specific directories or even files.

To associate the Webgate with specific targets, you move the following directives the the http.conf file:

AuthType Oblix
require valid-user

You can put these directives in a block that tells Apache to use Webgate for every request. You can also move the directives to a block that limits when the Webgate is called. The following is an example of putting the LocationMatch directive after a VirtualHost directive:

  DocumentRoot /usr/local/apache/htdocs/myserver    
  ServerName myserver.example.net    
  AuthType Oblix       
  require valid-user    

After you move the LocationMatch block to the VirtualHost directive, the Webgate will only work for that virtual host. You can add the LocationMatch block to as many virtual hosts as you want. The following examples shows how you could protect one virtual server:

ServerAdmin [e-mail]
DocumentRoot "Z:/Apps/Apache/htdocs/MYsrv"
ServerName apps.example.com
    ProxyRequests On
    SSLEngine on
    SSLCACertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/intermediateca.cer
    SSLCertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_ptcweb32.cer
    SSLCertificateKeyFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_ptcweb32.key
    ErrorLog logs/proxysite1_log
    CustomLog logs/proxysite1_log common
    ProxyPass /https://apps.example.com/
    ProxyPassReverse /https://apps.example.com/
    ProxyPass /bkcentral https://apps.example.com/bkcentral
    ProxyPassReverse /bkcentral https://apps.example.com/bkcentral
    ProxyPass /NR https://apps.example.com/NR
    ProxyPassReverse /NR https://apps.example.com/NR
    
      AuthType Oblix
      require valid-user
    
#*** BEGIN Oracle Access Manager Webgate Specific **** 
 
LoadModule obWebgateModule Z:/apps/Oracle/WebComponent/access/oblix/apps/webgate/bin/webgate.dll
WebgateInstalldir Z:/apps/Oracle/WebComponent/access
WebgateMode PEER
 
 SetHandler obwebgateerr
 
SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none
 
SSLLog logs/SSL.log
SSLLogLevel info
# You can later change "info" to "warn" if everything is OK

22.4.3 Host Identifier Page

A host identifier is automatically created when an Agent (and application) are registered using either the Oracle Access Management Console or the remote registration tool. In the Application Domain that is registered with the Agent, the host identifier is used automatically.

Administrators can use the console to create and manage host identifiers. Within the Oracle Access Management Console, host identifiers are organized under Shared Components, on the Policy Configuration tab navigation tree. Administrators can manually create a new host identifier definition, modify a definition, delete a definition, or copy an existing definition to use as a template. The name of the copy is based on the original definition name. For example, if you copy a definition named host3, the copy is named copy of host3.

Figure 22-4 illustrates the Create Host Identifier configuration page in the console, where you enter the canonical name for the host, and every other name by which the same host can be addressed by users.

Note:

Each host identifier must be unique. You cannot use the same host name and port in any other host identifier definition.

Figure 22-4 Create Host Identifier Page

Description of "Figure 22-4 Create Host Identifier Page"

Table 22-3 describes the host identifier definitions.

Table 22-3 Host Identifier Definitions

Property	Description
Name	A unique name for this definition. Use only upper- and lower-case alpha characters. No punctuation or special characters are allowed.
Description	The optional description, up to 200 characters, that explains the use of this configuration.
Host Name Variations	Host Name: A list of the various host names or permutations that users might use when accessing the application. See also: "Host Identifier Variations" and "Host Identifier Guidelines". Port: The Web server port used by each host or permutation

22.4.4 Creating a Host Identifier

Users with valid Administrator credentials can create a host identifier definition manually. This is needed if an application and resources were manually added to a host that has no mapped host identifier. When you choose Auto Create Policies when registering an Agent, this is done automatically.

If you copy an existing definition to use as a template, you must modify all unique identifiers in the copy.

See Also:

• "About Host Identifiers"

• "About Virtual Web Hosting"

1. In the Oracle Access Management Console, click Application Security at the top of the window.

2. In the Application Security console, click Host Identifiers in the Access Manager section.

3. Click Create Host Identifier.

4. On the Create Host Identifier page, fill in the:

   1. Name

   2. Description

   3. Host Name Variations: Add (or remove) host name and port variations in the Operations list.

      Add: Click the Add (+) button, then enter a new host name and port combination to identify variables that map to the Host Identifier Name.

      Remove: Click a host name, then click the Delete button to remove it.

5. Repeat step 3c as needed to identify all variations of this host that users can access.

6. Click Apply to submit the new definition (or close the page without applying changes).

7. Close the Confirmation window, and confirm the new definition is listed in the results table.

22.4.5 Searching for a Host Identifier Definition

Users with valid Administrator credentials can search for a specific host identifier.

Note:

During Delete, if the Host Identifier is associated with a resource, you are prompted with an alert. Without any association, the Host Identifier is deleted successfully.

See Also:

"SSO Agent Search Page"

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Host Identifiers in the Access Manager section.
3. In the Search Host Identifiers page Name field, enter a name (or a partial name with wild card (*)), or leave the Name field blank to show all Host Identifiers. For example:

   my_h*
   

4. Click the Search button to initiate the search and display results in a table, then:

   • View or Edit: Double-click the name in the Search Results table to display the configuration page, then add or edit as usual.

   • Delete: Click the Delete button in the tool bar to remove the selected item in the results table; confirm removal in the Confirmation window.

   • Detach: Click Detach in the tool bar to expand the Search Results table to a full page (or from the View menu, click Detach).

   • Reorder Columns: From the View menu, select reorder Columns and use the arrows provided to reorder the columns.

22.4.6 Viewing or Editing a Host Identifier Definition

Users with valid Administrator credentials can modify a host identifier definition.

This can include adding, changing, or removing individual host identifiers from the definition. For instance, when adding another proxy Web server with a different host name, you might need to modify an existing host identifier definition to add the new host name variation.

Prerequisite: Inventory Application Domains that refer to the host identifier and

Note:

After viewing settings, you can either close the page or modify settings as needed.

See Also:

"Host Identifier Page"

1. Locate the desired host identifier and view it as described in "Searching for a Host Identifier Definition".

2. On the Host Identifier page, modify information as needed (Table 22-3):

   1. Name

   2. Description

   3. Host Name Variations: In the table provided:

      Add (+) Host Name Variations: Click the Add (+) button, then enter a new host name and port combination to identify variables that map to the Host Identifier Name.

      Delete (X) Host Name Variations: Click a host name, then click the Delete button to remove it.

3. Repeat step 3c as needed to add or remove variations.

4. Click Apply to submit the changes (or close the page without applying changes).

5. Dismiss the Confirmation window, and close the page when you finish.

22.4.7 Deleting a Host Identifier Definition

Users with valid Administrator credentials can delete an entire host identifier definition. A validation error occurs if you attempt to delete the host identifier that is being used in a resource.

If the Host Identifier is associated with a resource, you are alerted. Without any association, the Host Identifier is deleted.

Prerequisites

Each resource in an Application Domain is associated with a specific host identifier. If you intend to delete a host identifier you must first modify any resource definitions in an Application Domain that uses this host identifier.

See Also:

"Viewing or Editing a Host Identifier Definition" if you want to remove a single host identifier from an existing definition.

1. Locate and modify related resource definitions in any application domains that uses this host identifier. See "Searching for a Resource Definition".
2. Locate the desired host identifier as described in "Searching for a Host Identifier Definition".
3. View: Double-click the name in the results table to display the configuration page, and confirm this can be removed.
4. Delete: Click the Delete button in the tool bar to remove the selected item in the results table; confirm removal in the Confirmation window.

22.5 Understanding Authentication Methods and Credential Collectors

With Access Manager, authentication involves redirecting the requester (user) to a centralized component that performs authentication (known as the Credential Collector).

This section provides the following topics:

• Authentication Methods Supported by Access Manager

• Embedded Credential Collector Versus Detached Credential Collector

• Authentication Event Logging and Auditing

22.5.1 Authentication Methods Supported by Access Manager

Authentication is the process of proving that a user is who he or she claims to be. Authenticating a user's identity with Access Manager refers to running a pre-defined set of processes to verify the digital identity of the user. Using Access Manager, a resource or group of resources can be protected by a single authentication process known as an authentication scheme. Authentication schemes rely on pre-defined authentication modules or plug-ins.

This section describes multi-level authentication and other authentication methods supported by Access Manager.

Multi-level Authentication

Access Manager enables Administrators to assign different authentication levels to different authentication schemes, and then choose which scheme protects which application. Every authentication scheme requires a strength level. The lower this number, the less stringent the scheme. A higher level number indicates a more secure authentication mechanism.

SSO capability enables users to access more than one protected resource or application with a single sign in. A user who is authenticated to access resources at level 2, is eligible to access resources protected at levels less than or equal to 2. However, if the user is authenticated to access resources at level 2 and then attempts to access resources protected by level 3, the user is asked to re-authenticate (this is known as step-up authentication).

For more information, see "About Multi-Level and Step-Up Authentication".

See Also:

"Multi-Step Authentication"

Multi-Step Authentication

Multi-step authentication requires a custom authentication module composed of two or more authentication plug-ins that transmit information to the backend authentication scheme several times during the login process. All information collected by the plug-in and saved in the context will be available to the plug-in through the authentication process. Context data can also be used to set cookies or headers in the user's login page.

See "Simple Form Versus Multi-Factor (Multi-Step) Authentication".

Windows Native Authentication

Integrated Windows Native Authentication is supported for Webgate protected applications. This form of authentication relies on the Kerberos authentication module. For more information, see Configuring Access Manager for Windows Native Authentication.

Other Authentication Types

Authentication features required by Oracle Fusion Middleware applications are supported, including:

• Weak authentication, typically a user name and password, no certificates

• Auto-login with third-party self-service user provisioning

• HTTP header support for user context information. For instance, host identifiers are used to create a host context for the resource. This is useful when adding resources that have the same URL paths on different computers.

If you use different authentication schemes for two WebGates, users can go from a higher authentication scheme to a lower one without re-authentication, but not from a lower level to a higher level.

Note:

During single sign-on, users might pass the authentication tests but might fail authorization tests when attempting to access a second or third resource. Each resource in the domain might have a unique authorization policy.

For details about configuring and using authentication schemes with Access Manager, see "Managing Authentication Schemes".

22.5.2 Embedded Credential Collector Versus Detached Credential Collector

Access Manager 12c supports the embedded credential collector (ECC) by default but also enables you to configure the latest WebGate to use as a detached credential collector (DCC, also known as an Authenticating WebGate). The centralized DCC presents the login page, collects the user credentials (userID and password, for example), and sends these to the OAM Server using the back channel Oracle Access Protocol (OAP). Additional credentials can be requested using the DCC.

Note:

Use of ECC is the recommended approach for credential collection. See Understanding Credential Collection and Login for more details.

When OAM Server is configured to use the DCC, the ECC and its HTTP endpoints are disabled. The only HTTP communication is to the Oracle Access Management Console hosted by the WebLogic AdminServer in the domain where the OAM Server is deployed. Connectivity to the AdminServer can be controlled at the network level, for example, to disallow administration requests from outside the internal network.

• Allowing both the ECC and DCC to co-exist enables you to use authentication schemes and policies configured for use with either the ECC or the DCC. This enables a fallback mechanism for resources that rely on the ECC, which includes the Oracle Access Management Console.

• Disabling (turning off) the ECC entirely prohibits access to resources that rely on the ECC mechanism, including the Oracle Access Management Console.

While the embedded and detached credential collectors (ECC and DCC, respectively) are essentially the same, compare the two in Table 22-4.

See Also:

"Understanding Credential Collection and Login"

Table 22-4 Comparing the DCC and ECC

Feature	DCC	ECC
Deployment	The Detached Credential Collector remains a logical part of the server and acts as a front channel communication endpoint of the OAM Server. However, the DCC also: Stands alone (detached from the OAM Server and does not require an application server). Supports RSA SecurID passcode verification, get next token, create new pin workflows. Authenticates Webgate with greater flexibility for server scale-out and attack resilience as well as credential collection UI construction, flow, and lifecycle management.	The Embedded Credential Collector is deployed with, and integral to, the OAM Server and part of the protocol binding layer. The ECC supports RSA SecurID passcode verification, get next token, create new pin workflows.
DMZ Deployment	Yes. The main benefit of a deployment using DCC in the DMZ is the termination of the end-user network connections within the public network, and the use of Oracle Access Protocol (Oracle's proprietary application network protocol) over mutually authenticated connections reaching the OAM Server. This offers a complete isolation of the OAM Server from the establishment of any unauthenticated network connection. Unauthenticated users cannot send malformed requests to the OAM Server.	No. A Defense in Depth strategy, at the infrastructure, is necessary to mitigate threats and risks facing a typical Enterprise.
Communication channel	DCC consumes HTTP/HTTPS requests from the user, then communicates with the OAM Server across the Oracle Access Protocol (back channel), which can be SSL-enabled.	ECC communicates with both the user and the OAM Server across HTTP/HTTPS.
DCC login, error, and password pages	Dynamic pages general login/logout and password policy with the DCC are excluded automatically through the OHS httpd.conf/webgate.conf file--you do not need to configure a policy to exclude these. See the Webgate host in $WEBGATE_HOME/webgate/ohs/oamsso/*, $WEBGATE_HOME/webgate/ohs/oamsso-bin/*pl, and $WEBGATE_HOME/webgate/ohs/oamsso-bin/templates/* directory: Login page: /oamsso-bin/login.pl Logout: /oamsso-bin/logout.pl RSA SecurID login pages: /oamsso-bin/securid.pl Note: Update the Perl location in the first line of the login, logout, and securid scripts in /oamsso-bin. See Also: Integrating RSA SecurID Authentication with Access Manager Developing Custom Pages in Fusion Middleware Developer's Guide for Oracle Access Management.	Pages where the user enters her credentials arrive out of the box on the OAM Server and require no additional settings or changes. Login page: /pages/login.jsp Logout page: /pages/logout.jsp Error page: /pages/servererror.jsp Multi-step: /pages/mfa_login.jsp
Perl Scripts for DCC-based Login and Logout	Perl Scripts for DCC-based Login and Logout The path name of the Perl executable must be updated in Oracle-provided Perl scripts on the Webgate host $WEBGATE_HOME/webgate/ohs/oamsso-bin/*pl to be consistent with the actual location. Unix: The which command finds Perl on the OAM Server. For example: which perl /usr/bin/perl However, Perl scripts themselves point to: /usr/local/bin/perl Windows: The default Perl Interpreter specified in Oracle-provided Perl scripts will not be available. You must update the Perl Interpreter path in these scripts to actual path to Perl on your system.	N/A
Password policy enforcement	Yes. See Configuring OAM WebGate and Authentication Policy for DCC	Yes See: Managing Global Password Policy
Authentication scheme collection methods	DCC supports only Form Based Authentication.	ECC supports all challenge methods. The ECC collects user credentials based on the challenge method of the Authentication Scheme and sends it back to OAM Server for validation.
Custom Authentication Plug-ins and Challenge Methods	Yes; same as ECC.	All challenge methods and multi-step authentication (Password Policy and other custom authentication plugins) are supported.
Single Step (Simple Form) Authentication	Yes; same as ECC.	Yes. Both the DCC and ECC handle this, where: All credentials are supplied in one simple form Upon credential validation and authentication, either success or failure status is returned This can be retried upon failure
Multi-Step Authentication	Yes. Both the DCC and ECC handle complex multi-factor (multi-step, iterative, and variable) Authentication processing. In this case: Not all required credentials are supplied at once Depending on the authentication status, PENDING state, expected credentials and context data are returned, expecting those credentials to be supplied in the next round Each intermediate step, submit required credentials and context data to feed authentication engine, until a success or failure status returned The Authentication plug-in can have multiple steps configured See "Understanding Multi-Level and Step-Up Authentication"	Yes. Both the DCC and ECC handle complex multi-factor (multi-step, iterative, and variable) Authentication processing.
Authentication Processing	The DCC does not restrict authentication functionality of the OAM Server in any way as compared to the ECC. The DCC: Handles authentication redirects from OAM Webgates. Handles Form-based authentication, which consists of a challenge to the user for their credentials (simple form or multi-factor). Decrypts the authentication request message from the agent using the agent key; performs basic integrity checks; validates request time; and extracts all parameters from the request including request context. Constructs the authentication response message, including request context originally retrieved, encrypts obrar using the agent key. Decrypts the logout redirect request using the agent key to trigger logout processing.	During authentication: The ECC handles the request coming to the protocol binding layer (PBL), which converts it and sends it to the SSO Engine. The SSO Engine checks for a valid session and, if none, transfers control to the Authentication Engine. The Authentication Engine checks for resource protection and fetches the authentication scheme associated with the resource. The ECC interacts with the client, accepts the data, and submits this to the PBL.
Overriding the ECC	To deploy the DCC and override the ECC, an Administrator must perform the following tasks to specify the relevant DCC URLs and forms. OAM Agent registration: Allow Credential Collector Operations (enable for DCC) Authentication Module, Step Orchestration: Error (if Failure) Authentication Scheme: Challenge Redirect URL (DCC host and port) Authentication Scheme: Challenge URL /oamsso-bin/login.pl (DCC login pages) Authentication Scheme: Challenge Method Password Policy: Password Service URL for DCC (Default: /oamsso-bin/login.pl) See Configuring OAM WebGate and Authentication Policy for DCC	N/A
Logout Configuration	See "Configuring Logout When Using Detached Credential Collector-Enabled WebGate"	See "Configuring Centralized Logout for OAM WebGates"
Cookie/Token	DCCCtxCookie OAM WebGate: OAMAuthnCookie OAM WebGate: OAMRequestContext See: "Single Sign-On Cookies During User Login"	OAM Webgate: OAMAuthnCookie OAM Webgate: OAM_REQ OAM Webgate: OAM_ID OAM Webgate: OAMRequestContext See: "Single Sign-On Cookies During User Login"

22.5.3 Authentication Event Logging and Auditing

Authentication Success and Failure events are audited, in addition to administration events. Auditing covers creating, modifying, viewing, and deleting authentication schemes, modules, and policies.

Information that is collected about the user who is authenticating includes:

• IP address

• User Login ID

• Time of Access

During logging (or auditing), user information, user sensitive attributes are not recorded. Secure data (user passwords, for example) are removed to avoid misuse.

See Also:

• Logging Component Event Messages

• Auditing Administrative and Run-time Events.

• Monitoring Oracle Access Management Performance and Access Manager Health

22.6 Managing Native Authentication Modules

In Access Manager, each authentication scheme requires an authentication module.

Native authentication modules lack the flexibility to orchestrate two or more plug-ins to meet specialized authentication needs. Therefore, native authentication modules are targeted for deprecation in future releases. Oracle strongly recommends using plug-in based authentication modules as described "Orchestrating Multi-Step Authentication with Plug-in Based Modules".

This section provides the following information:

• Native Access Manager Authentication Modules

• Viewing or Editing Native Authentication Modules

• Deleting a Native Authentication Module

22.6.1 Native Access Manager Authentication Modules

Native Access Manager Authentication Modules include LDAP, LDAPNoPasswordAuthModule, Kerberos, X509, and, Custom Authentication Modules.

"Table 22-5" lists the Native Access Manager Authentication Modules and description.

Table 22-5 Native Authentication Modules

Module Name	Description
LDAP	Matches the credentials (username and password) of the user who requests a resource to a user definition stored in an LDAP directory server. An LDAP module is required for Basic and Form challenge methods. See Also: "Native LDAP Authentication Modules".
LDAPNoPasswordAuthModule	Matches the credentials (username and password) of the user who requests a resource to a user definition stored in an LDAP directory server. An LDAP module is required for Basic and Form challenge methods. See Also: "Native LDAP Authentication Modules".
Kerberos	Identifies the key tab file and krb5.configuration file names and Principal. Use this plug-in when configuring Access Manager for Windows Native Authentication, as described in Configuring Access Manager for Windows Native Authentication. See Also: "Native Kerberos Authentication Module".
X509	Similar to the LDAPPlugin with additional properties that indicate which attribute of the client's X.509 certificate should be validated against the user attribute in LDAP. See Also: "Native X.509 Authentication Module".
Custom Authentication Modules	This type of module relies on bundled plug-ins (or those that are developed using the Access Manager Authentication Extensibility Java API). This type of module generally uses more than one plug-in that you can orchestrate to ensure that each one performs a specific authentication function. Depending on the success or failure action defined for each plug-in, another authentication plug-in is called. See Also: "Pre-populated Plug-ins for Configuring Access Manager with Multi-Step Authentication", and Developing Custom Authentication Plug-insin the Developer’s Guide for Oracle Access Management for details about developing and deploying plug-ins, custom authentication modules, and schemes that use custom modules.

See Also:

• "Credential Challenge Methods"

• To create custom authentication plug-ins, seeDeveloping Custom Authentication Plug-ins in the Developer’s Guide for Oracle Access Management.

22.6.1.1 Native Kerberos Authentication Module

The pre-configured Kerberos authentication module is illustrated in Figure 22-5. Additional details follow the figure.

Figure 22-5 Native Kerberos Authentication Module

Description of "Figure 22-5 Native Kerberos Authentication Module"

Table 22-6 describes the definition of the native Kerberos authentication module. You can use the existing, pre-configured Kerberos authentication module or create one of your own.

Table 22-6 Native Kerberos Authentication Module Definition

Element	Description
Name	The unique ID of this module, which can include upper and lower case alpha characters as well as numbers and spaces.
Key Tab File	The path to the encrypted, local, on-disk copy of the host's key, required to authenticate to the key distribution center (KDC). For example: /etc/krb5.keytab. The KDC authenticates the requesting user and confirms that the user is authorized for access to the requested service. If the authenticated user meets all prescribed conditions, the KDC issues a ticket permitting access based on a server key. The client receives the ticket and submits it to the appropriate server. The server can verify the submitted ticket and grant access to the user submitting it. The key tab file should be readable only by root, and should exist only on the machine's local disk. It should not be part of any backup, unless access to the backup data is secured as tightly as access to the machine's root password itself.
Principal	Identifies the HTTP host for the principal in the Kerberos database, which enables generation of a keytab for a host.
KRB Config File	Identifies the path to the configuration file that controls certain aspects of the Kerberos installation. A krb5.conf file must exist in the /etc directory on each UNIX node that is running Kerberos. krb5.conf contains configuration information required by the Kerberos V5 library (the default Kerberos realm and the location of the Kerberos key distribution centers for known realms).

22.6.1.2 Native LDAP Authentication Modules

Oracle provides two LDAP authentication modules: LDAP and LDAPNoPasswordAuthModule.

Both modules have the same requirements (Name and User Identity Store), as illustrated in Figure 22-6. Additional details follow the figure.

Figure 22-6 Native LDAP Authentication Module

Description of "Figure 22-6 Native LDAP Authentication Module"

Table 22-7 describes the elements in an LDAP authentication module. The same elements and values are also used in LDAPNoPasswordAuthnModule.

Note:

These standard LDAP Authentication Modules are targeted for deprecation. Future enhancements will not be available in standard modules. Oracle strongly recommends using plug-in based modules.

Table 22-7 Native LDAP Authentication Modules Definition

Element	Description
Name	A unique name for this module.
User Identity Store	The designated LDAP user identity store must contain any user credentials required for authentication by this module. The LDAP store must be registered with Access Manager. See Also: "Registering and Managing User Identity Stores". Multiple identity store vendors are supported. Upon installation, there is only one User Identity Store, which is also the designated System Store. If you add more identity stores and designate a different store as the System Store, be sure to change the LDAP module to point to the System Store. The authentication scheme OAMAdminConsoleScheme relies on the LDAP module for Administrator Roles and credentials. See Also: "About using the System Store for User Identities" and "Administrator Lockout".

22.6.1.3 Native X.509 Authentication Module

Access Manager provides a pre-configured X.509 authentication module as a default. Administrators can also create new X.509 authentication modules. In cryptographic terms, X.509 is a standard for digital public key certificates used for single sign-on (SSO). X.509 specifies standard formats for public key certificates, certificate revocation lists, and attribute certificates among other things.

With X.509 digital certificates you can assume a strict hierarchical system of certificate authorities (CAs) issuing the certificates. In the X.509 system, a CA issues a certificate that binds a public key to a particular Distinguished Name, or to an Alternative Name such as an e-mail address or a DNS-entry.

The trusted root certificates of an enterprise can be distributed to all employees so that they can use the company PKI system. Certain Web browsers provide pre-installed root certificates to ensure that SSL certificates work immediately.

Access Manager uses the Online Certificate Status Protocol (OCSP) Internet protocol to maintain the security of a server and other network resources. OCSP is used for obtaining the revocation status of an X.509 digital certificate. OCSP specifies the communication syntax used between the server containing the certificate status and the client application that is informed of that status.

When a user attempts to access a server, OCSP sends a request for certificate status information. OCSP discloses to the requester that a particular network host used a particular certificate at a particular time. The server returns a response of "current", "expired," or "unknown." OCSP allows users with expired certificates a configurable grace period, during which they can access servers for the specified period before renewing.

OCSP messages are encoded in ASN.1 and are usually transmitted over HTTP. The request and response characteristic of OCSP has led to the term "OCSP responders" when referring to OCSP servers. With Access Manager, the computer hosting the Oracle Access Management Console is the OCSP responder.

An OCSP responder can return a signed response signifying that the certificate specified in the request is 'good', 'revoked' or 'unknown'. If OCSP cannot process the request, it can return an error code.

Figure 22-7 Native X.509 Authentication Module

Description of "Figure 22-7 Native X.509 Authentication Module"

Table 22-8 describes the requirements of the native X.509 authentication module.

Note:

This standard Authentication Module is targeted for deprecation. Future enhancements will not be available in standard modules. Oracle strongly recommends using plug-in based modules.

Table 22-8 X509 Authentication Module Definition

Element	Description
Name	Identifies this module definition with a unique name.
Match LDAP Attribute	Defines the LDAP distinguished name attribute to be searched against given the X509 Cert Attribute value. For example, if the certificate subject EMAIL is [e-mail] and it must be matched against the "mail" LDAP Attribute, an LDAP query must search LDAP against the "mail" attribute with a value "[e-mail] (cn). Default: cn
X509 Cert Attribute	Defines the certificate attribute to be used to bind the public key (attributes within subject, issuer scope to be extracted from the certificate: subject.DN, issuer.DN, subject.EMAIL, for example). See Also. Match LDAP Attribute earlier in this table.
Cert Validation Enabled	Enables (or disables if not checked) X.509 Certificate validation. When enabled, the OAM Server performs the certificate validation (rather than having the WebLogic server intercept and validate the certificate before passing it to the OAM Server). Access Manager performs the entire certificate path validation.
OCSP Enabled	Enables (or disables when not checked) the Online Certificate Status Protocol. Values are either true or false. For example: OCSP Enabled: true Note: OCSP Server Alias, OCSP Responder URL and OCSP Responder Timeout are required only when OCSP Enabled is selected.
OCSP Server Alias	An aliased name for the OSCSP Responder pointing to CA certificates in .oamkeystore file--a mapping between the aliased name and the actual instance name or the IP address of the OSCSP Responder instance.
OCSP Responder URL	Provides the URL of the Online Certificate Status Protocol responder. For example, OpenSSL Responder URL: http://localhost:6060
OCSP Responder Timeout	Specifies the grace period for users with expired certificates, which enables them to access OAM Servers for a limited time before renewing the certificate.

22.6.2 Viewing or Editing Native Authentication Modules

Users with valid Administrator credentials can modify an existing authentication module.

This includes changing the name of an existing module as well as changing other attributes.

Prerequisites

Modify each authentication scheme that references the module you will change, to use another authentication module if needed.

Note:

By default, the LDAP module is used in the authentication scheme that protects the Oracle Access Management Console. To ensure Administrator access, the LDAP module must point to the User Identity Store that is designated as the System Store. If you change the designated System Store, be sure to change the LDAP Module to reference the newly designated System Store.

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Authentication Modules in the Plug-ins section.
3. In the Search Results list, select the desired module to open its properties page.
4. On the properties page, modify information as needed:

   • Kerberos Module: See Table 22-6

   • LDAP Module: See Table 22-7

   • X.509 Module: See Table 22-8 and Table 22-14

5. Click Apply to submit the changes and close the Confirmation window (or close the page without applying changes).
6. Add the updated authentication module to authentication schemes (or change to another authentication module in each authentication scheme that references this module), as described in "Managing Authentication Schemes".

22.6.3 Deleting a Native Authentication Module

Users with valid Administrator credentials can use the following procedure to delete an authentication module.

The following procedure is the same whether you are deleting a custom authentication module or a native module.

Prerequisites

In each authentication scheme that references the module to be deleted, specify another authentication module.

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Authentication Modules in the Plug-ins section.
3. Optional: Open the module to verify this is the module to remove, then close the page.
4. In the Search Results list, click the desired module name, then click the Delete button.
5. Confirm removal (or dismiss the confirmation window to retain the module).

22.7 Orchestrating Multi-Step Authentication with Plug-in Based Modules

Authentication involves determining which credentials a user must supply when requesting access to a resource, gathering credentials, and returning a response that is based on the results of credential validation.

All authentication processing relies on an authentication module to define the rules governing requirements and transmission of information to the backend authentication scheme. All information collected by the plug-in and saved in the context is available to the plug-in through the authentication process.

Context data can also be used to set cookies or headers in the user's login page.

Note:

Oracle strongly recommends using authentication plug-ins to create custom authentication modules.

This section provides the following topics:

• Simple Form Versus Multi-Factor (Multi-Step) Authentication

• Access Manager Plug-ins for Multi-Step Authentication Modules

• Pre-populated Plug-ins for Configuring Access Manager with Multi-Step Authentication

• Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints

• Creating a Custom Authentication Module using Bundled Plug-ins

• Steps and Plug-ins in Customized Step-up Authentication Module

• Configuring an HTTPToken Extractor Plug-in

• JSON Web Token Plug-in

See Also:

To create custom authentication plug-ins, see Developing Custom Authentication Plug-ins in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.

22.7.1 Simple Form Versus Multi-Factor (Multi-Step) Authentication

Simple form-based authentication is the default and does not require additional configuration unless you want to customize forms. Authentication plug-ins provide processing that meets your specific multi-step authentication needs.

Simple form-based authentication relies on the default embedded or optional detached credential collector and Web forms that process user logins with Access Manager authentication mechanisms. With simple form-based authentication:

• All credentials are supplied in one simple form.

• Upon credential validation and authentication, either success or failure status is returned.

• Authentication can be retried upon failure.

See Also:

Developing Custom Pages for details about customizing login pages and forms

For dynamic, multi-step authentication, Access Manager provides a number of plug-ins with which you can design and orchestrate your own customized authentication modules. Both the ECC and DCC handle complex multi-factor (multi-step, iterative, and variable) Authentication processing, where:

• Not all required credentials are supplied at once

• Depending on the authentication status, PENDING state, expected credentials and context data are returned, expecting those credentials to be supplied in the next round

• Each intermediate step, submit required credentials and context data for the authentication engine, until a success or failure status is returned.

• The Authentication plug-in can have multiple steps configured.

Note:

Administrators can install multiple user identity stores for Access Manager. Each identity store can rely on a different LDAP provider. Each authentication plug-in can be configured to use a different user identity store.

Table 22-9 provides more information about these two forms of authentication.

Table 22-9 Simple Form versus Multi-Step Authentication

Authentication Method	Description
Simple form-based authentication	Simple form-based authentication relies on Credential Collectors (both ECC and DCC) and Web forms that process user logins using Access Manager authentication mechanisms. This is the default and does not require additional configuration unless you want to customize forms. See Also: Developing Custom Pages for details about customizing login pages and forms
Multi-Step Authentication	Multi-step authentication requires a custom authentication module composed of two or more authentication plug-ins that transmit information to the backend authentication scheme several times during the login process. All information collected by the plug-in and saved in the context will be available to the plug-in through the authentication process. Context data can also be used to set cookies or headers in the user's login page. Multi-Step authentication relies on: Authentication Chaining: You can chain multiple authentication plug-ins in a new authentication module, and add the module to an authentication scheme. Challenge Mechanism: Controls the way in which the required credentials are collected. Currently, this is tied to the authentication scheme. Both the ECC and DCC use the same challenge mechanisms. Credential Collection: Either the ECC or DCC can be used for multi-step authentication. (DCC provides greater flexibility for interactions with users or programmatic entities when collecting authentication-related information that involves several methods to establish the user's identity). See Also: Configuring OAM WebGate and Authentication Policy for DCC "Steps and Plug-ins in Customized Step-up Authentication Module" Developing Custom Authentication Plug-ins for details about custom authentication plug-ins

22.7.2 Access Manager Plug-ins for Multi-Step Authentication Modules

Plug-ins operate with either the default embedded credential collector (ECC) or the optional detached credential collector (DCC-enabled WebGate). Each authentication plug-in provides an individual piece of functionality that you can use alone or string together into a series of steps. The lifecycle of a plug-in centers around the ability to add and use the plug-ins to build features and work flows that act as extensions to the OAM Server. Each plug-in is deployed as a JAR file and each plug-in's configuration requirements must be given in XML format.

You can create custom plug-in based authentication modules using existing Access Manager. To create your own plug-ins, see Developing Custom Authentication Plug-ins in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.

Note:

Standard (native) Authentication Modules are targeted for deprecation; future enhancements will not be available in the standard modules. Oracle strongly recommends using plug-in based modules as described in "Orchestrating Multi-Step Authentication with Plug-in Based Modules".

Figure 22-8 shows plug-ins available out of the box. These plug-ins, and any that you create using the SDK and import, appear in a list when you add steps to build a custom authentication module.

Figure 22-8 Access Manager Plug-ins for Customized Authentication Modules

Description of "Figure 22-8 Access Manager Plug-ins for Customized Authentication Modules"

The Name generally defines the component that relies on the plug-in. The Description is optional. The Type column indicates the purpose of the plug-in. Activation Status lets you know if this is active and ready to use.

See Also:

Developing Custom Authentication Plug-ins in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details about building your own custom plug-ins. You can import new plug-ins, distribute, activate, deactivate, and remove custom plug-ins.

Whether you use an Oracle-provided plug-in or create one of your own, adding a plug-in when you create a custom authentication module is the same. Each custom module requires the following types of information:

• General identifies the unique name and optional description for the individual plug-in.

• Steps identify the specific plug-ins to use, and their execution order, based on the configuration details of each plug-in (including the user identity store to use).

• Step Orchestration specifies the action to be taken on success or on failure or on error.

Note:

When multi-factor authentication is used, the UserIdentificationPlugin should be invoked in the last pass during the authentication process.

Figure 22-9 shows the Custom Authentication Module within the Access Manager section of the System Configuration tree. Each module has three configuration tabs.

Figure 22-9 Creating Custom Authentication Modules: General

Description of "Figure 22-9 Creating Custom Authentication Modules: General "

Table 22-10 describes the content of the General tab.

Table 22-10 General tab

Element	Description
Name	A unique name up to 60 characters.
Description	Optional; up to 250 characters.

Clicking the Steps tab opens a fresh page where you can add a new step. When you add a new Step, the following dialog box appears. Information that you enter is used to populate the table and Details sections of the page.

Figure 22-10 Adding a Step and Associating a Plug-in

Description of "Figure 22-10 Adding a Step and Associating a Plug-in"

Table 22-11 describes the information required when adding a new step. Each step requires a plug-in and each plug-in requires specific details for proper operation.

Table 22-11 Add New Step Entries, Steps Results Table, and Details Section

Element	Description
Step Name	The unique name you enter to identify this step, up to 60 characters.
Description	The optional description for this step, as entered when adding the step (up to 250 characters).
Plugin Name	The plug-in that you select for a particular step from the list of imported and activated plug-ins. See Also: To create custom plug-ins, see Developing Custom Authentication Plug-ins in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
Step Details	Plug-in configuration details must be specified to ensure proper operation. Details might differ depending the chosen plug-in and its requirements. See Also: Table 22-12.

Table 22-12 describes the Plug-in Parameter Details required by Oracle-provided plug-ins. Absent from this table are the plug-in exceptions (those plug-ins with no initial parameters): KerberosTokenIdentifier, FedAuthnRequestPlugin, and FedUserAuthenticationPlugin.

Table 22-12 Parameter Details for Various Plug-ins

Plug-in Parameter	Display Name	Description
KEY_IDENTITY_STORE_REF	Identity Store Name	Most plug-ins require this attribute to ensure that the appropriate user identity store is called during authentication. The following plug-in uses only this property: TAPAssertionPlugIn For additional Details required by plug-ins that employ this property, see: UserIdentificationPlugIn UserAuthenticationPlugIn UserPasswordPolicyPlugin TAPUserAuthenticationPlugin TenantDisambiguationPlugin
CredentialCollectorPlugIn	CredentialCollectorPlugIn	This plugin allows the administrator to configure which credentials will be collected for authentication. Credentials to be collected are configured as step parameters. The plugin validates these parameters and renders the UI to collect the credentials. After user input, the plugin parses the credential parameters and builds the user context with credential objects. NOTE: Plugin error responses are set to the context if the credentials are invalid and the plugin returns failure. The plugin supports the collection of 4 credentials as step level parameters. CRED_PARAM_1 CRED_PARAM_2 CRED_PARAM_3 CRED_PARAM_4 The following example illustrates how to collect a username and password. CRED_PARAM_1= {ID=KEY_USERNAME},{DISPLAY_NAME=KEY_USERNAME},{TYPE=text} {ID=KEY_PASSWORD},{DISPLAY_NAME=KEY_PASSWORD},{TYPE=password} Where ID, DISPLAY_NAME and TYPE are constants.
Actiontype	Action Type	Indicates if the plugin wants to REDIRECT or FORWARD to the login page to collect credentials.
loginPageURL	Login Page URL	The URL to which the user will be forwarded or redirected for credential collection.
NO_OF_CREDENTIALS		The number of credentials provided for the plugin instance. If the number of instances is more than 4, the user must update the oam-config file to add additional CRED_PARAMS as plugin parameters.
UserIdentificationPlugIn	UserIdentificationPlugIn	This native plug-in maps the user to a specific LDAP user record.
KEY_LDAP_FILTER	LDAP Filter	The search filter required to identify the user. LDAP attributes are used when defining an LDAP search filter.
KEY_SEARCHBASE_URL	LDAP Searchbase	The search base required for the query. The node in the directory information tree (DIT)) under which user data is stored; the highest possible base for all user data searches.
UserAuthenticationPlugIn	UserAuthenticationPlugIn	This native plug-in authenticates the supplied username/password credentials against an LDAP directory.
KEY_PROP_AUTHN_EXCEPTION	Propagate LDAP errors	Enables (or disables) propagation of LDAP errors. UserAuthenticationPlugIn employs this attribute.
UserAuthnLevelCheckPlugin	UserAuthnLevelCheckPlugin	This native plug-in shall determine if the user has been authenticated to the authentication level X - where the value of X is provided by the plugin parameter AUTHN_LEVEL_FOR_PLUGIN. For example, it checks the current Authentication Level of the user with the value specified. In addition, the plug-in specifies a list of parameters to collect depending on whether the Authentication Level check succeeded or failed.
AUTHN_LEVEL_FOR_PLUGIN	AUTHN_LEVEL_FOR_PLUGIN	Specify the authentication level as an integer. Multiple steps can use UserAuthnLevelCheckPlugin. However, each Step must have a unique name and AUTHN_LEVEL_FOR_PLUGIN. See Also: "Steps and Plug-ins in Customized Step-up Authentication Module"
UserPasswordPolicyPlugin	UserPasswordPolicyPlugin
PLUGIN_EXECUTION_MODE	Mode of Operation	The execution mode of UserPasswordPolicyPlugin. UserPasswordPolicyPlugin is supported only when using LDAP based authentication modules. It does not work with non LDAP authentication modules. Depending upon the configuration, can operate either alone or with other default plug-ins. Values are one of the following: PSWDONLY: Default. The most preferred configuration where only the password status is determined. The ID and authentication must be performed using the UserIdentification and UserAuthentication Plugins. AUTHWITHPSWD: Both authentication and password are performed using this plug-in. AUTHONLY: Only the user identification and authentication is performed using this plug-in
NEW_USERPSWD_BEHAVIOR	Force Password Change on First Login	Configures retroactive behavior of the new-user password-policy. Used with UserPasswordPolicyPlugin.Values are either: FORCECHANGEPASSWORD: Forces a password change. NOFORCEPASSWORDCHANGE: The password policy change does not affect user passwords that are already set. Default: FORCECHANGEPASSWORD
DISABLED_STATUS_SUPPORT	Disabled Account Status Support	Specifies whether the disabled status is to be supported and acted upon in this password service. Valid values are either True or False. Default: TRUE
URL_ACTION	Password Management Action URL	Specifies the URL to which the user is sent for password management. The type of servlet action needed for redirecting the user to the specific password page for expiry and warning pages. Values can be either: REDIRECT_POST REDIRECT_GET FORWARD Default: REDIRECT_POST
FedUserProvisioningPlugin
KEY_USER_RECORD_ATTRIBUTE_LIST	List of User Attributes	For Federation. Comma-separated list of assertion attributes required to create the user record.
KEY_PROVIDERID_ATTRIBUTE_NAME	Partner Attribute Name	For Federation. The attribute name of the LDAP user record whose value will be set to the Partner's Identity Provider ID when provisioning the user. This field is optional and if empty, the Partner's Identity Provider ID will not be set in the LDAP user record.
KEY_USERID_ATTRIBUTE_NAME	User UserID Attribute	For Federation. Name of the attribute in the assertion attributes that is used as the LDAP UserID.
TAPIdentifyPlugIn
KEY_TAP_RETURN_ATTRIBUTE	Username Mapping Attribute	Name of the attribute used for account linking by TAPIdentifyPlugIn.
SequentialPlugInExecutionStrategy
StrategyName	Orchestration Strategy	Name of the plugin orchestration strategy required by SequentialPlugInExecutionStrategy.
KerberosTokenAuthenticator
KEY_KEYTAB_FILE	Location of Keytab file	Name of the file containing Kerberos principals and encrypted keys required by KerberosTokenAuthenticator
KEY_PRINCIPAL	OAM Service Principal	Your OAM Account SPN, required by KerberosTokenAuthenticator.
KEY_KRB_CONFIG_FILE	Location of Kerberos Configuration file	Location of the Kerberos configuration properties file, required by KerberosTokenAuthenticator.
KEY_DOMAIN_DNS2DN_MAP	AD Domain DNS Names to DN Mapping	Comma-separated list of Active Directory DNS Domains to DN mappings required by KerberosTokenAuthenticator.
X509CredentialExtractor
KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT	User Mapping Attribute	X509 certificate Attribute to be used for user mapping required by X509CredentialExtractor.
KEY_IS_CERT_VALIDATION_ENABLED	Certificate Validation	Enable or disable X.509 certificate validation, required by X509CredentialExtractor.
KEY_IS_ENFORCE_EKU_ENABLED	Enable Extended Key Usage (EKU) Validation	Enable or Disable validation for Extended Key Usage (EKU) extensions in the client certificate: YES NO (Default) TRUE FALSE Note: An empty or incorrect value is handled as NO. For details, see X.509 Authentication Using Extended Key Usage (EKU)
KEY_ENFORCE_KEY_USAGES	Object Identifier (OID) Mapping	Specify a comma separated list of object identifiers (OID) that needs to be present in the EKU extension of the client certificate. Note: KEY_IS_ENFORCE_EKU_ENABLED must be set to YES/TRUE. By default, the OID 1.3.6.1.5.5.7.3.2 is specified. This OID is used for client authentication through TLS web client. Note: The values must be specified as OIDs only. Any other values, in any other format is not recognized and the authentication fails. For Smart Card Login, specify the OID 1.3.6.1.4.1.311.20.2.2 To specify multiple OIDs, use a comma (,) between the OIDs. For example: 1.3.6.1.5.5.7.3.2,1.3.6.1.4.1.311.20.2.2. Note: Both the values must be present in the EKU extension of the client certificate. If either of these values is not present, the authentication fails. See also, Global OID Reference Database for OID details.
TAPRequestPlugin
TAPS2PVersion	Integration Protocol Version	Token version for Integration.
TAPPartnerId	Integration PartnerId	Integration Partner Identifier.
TAPChallengeURL	Partner Integration Endpoint URL	Remote Partner End Point URL.
TAPUserAuthenticationPlugin
KEY_USERNAME_ATTRIBUTE	Username Mapping Attribute	Name of the attribute used for account linking required by TAPUserAuthenticationPlugin
KEY_CHECK_TOKEN_EXPIRY	Enable Token Expiration Checking	Enable or disable Integration token expiration.
TenantDisambiguationPlugin
KEY_FEDERATED_TENANTS	FederatedTenantNames	Optional names of tenants (comma separated) for whom federated authentication is enabled. Plugin will check with Federation engine if tenant names are not mentioned.
RSA SecurID Plugin
username	Username Parameter	Name of the username plugin parameter required by RSA SecurID Plugin.
passcode	Passcode Parameter	Name of the passcode plugin parameter required by RSA SecurID Plugin.
nexttoken	Next Token Parameter	Name of the next token plugin parameter required by RSA SecurID Plugin.
newpin	New PIN Parameter	Name of the new pin plugin parameter required by RSA SecurID Plugin.
confirmnewpin	Confirm New PIN Parameter	Name of the confirm new pin plugin parameter required by RSA SecurID Plugin.
HTTPTokenExtractor
KEY_HEADER_PROPERTY	HTTP Header Names	Comma separated list of HTTP Headers. See Configuring an HTTPToken Extractor Plug-in.
KEY_COOKIE_PROPERTY	HTTP Cookie Names	Comma separated list of Cookies. See Configuring an HTTPToken Extractor Plug-in.

Figure 22-11 illustrates the Steps tab and Details section for a custom authentication module. When adding Steps, there is no data to display in the table. However, when you add one or more Steps to the table, the Details sections are populated.

Figure 22-11 Plug-in Based Authentication Module Steps and Details

Description of "Figure 22-11 Plug-in Based Authentication Module Steps and Details"

Figure 22-12 illustrates the Steps Orchestration tab of a custom authentication module, which is populated by information for each defined step (and the action you choose for each operational condition).

Figure 22-12 Steps Orchestration for Plug-in Based Authentication Modules

Description of "Figure 22-12 Steps Orchestration for Plug-in Based Authentication Modules"

Table 22-13 describes the elements on the Steps Orchestration tab. The lists available for OnSuccess, OnFailure, and OnError include the following choices:

• success

• failure

• StepName (any step in the module can be selected as the action for an operational condition)

Table 22-13 Steps Orchestration Tab

Element	Description
Initial Step	Choose the starting step from those listed. The list includes only those steps defined for this module.
Name	Each step added to this module is listed by the name that was entered when the step was added.
Description	The optional description for this step, entered when this step was added.
OnSuccess	The action selected for successful operation. A list provides actions you can choose: Success Failure StepName (activates the next step)
OnFailure	The action selected for failure of this step. A list provides actions you can choose: Success Failure StepName (activates the next step)
OnError	The action selected for an error when executing this step. A list provides actions you can choose: Success Failure StepName (activates the next step)

22.7.3 Pre-populated Plug-ins for Configuring Access Manager with Multi-Step Authentication

The following topics describe several of the native Custom modules provided with pre-populated plug-ins. You can use these to orchestrate your own custom authentication modules:

• KerberosPlugin

• LDAPPlugin

• X509Plugin

• Password Policy Validation Module and Plug-ins

See Also:

• Table 22-12

• Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints

• "Steps and Plug-ins in Customized Step-up Authentication Module"

KerberosPlugin

Use this plug-in when configuring Access Manager for Windows Native Authentication, as described in Configuring Access Manager for Windows Native Authentication.

Figure 22-13 shows the KerberosPlugin module that is bundled with Access Manager 11g. This is a credential mapping module that matches the credentials (username and password) of the user who requests a resource to the encrypted "kerberos ticket".

Figure 22-13 KerberosPlugin

Description of "Figure 22-13 KerberosPlugin"

Figure 22-14 shows the default steps and details. Figure 22-15 shows the orchestration of the steps and conditions.

Figure 22-14 Default KerberosPlugin Steps and Details

Description of "Figure 22-14 Default KerberosPlugin Steps and Details"

Figure 22-15 Default KerberosPlugin Steps and Orchestration

Description of "Figure 22-15 Default KerberosPlugin Steps and Orchestration"

LDAPPlugin

Figure 22-16 shows the LDAPPlugin module that is bundled with Access Manager. By default, LDAPPlugin has 2 steps, shown in Figure 22-17. Figure 22-18 shows the default orchestration of steps for LDAPplugin.

Figure 22-16 LDAPPlugin

Description of "Figure 22-16 LDAPPlugin"

Figure 22-17 Default LDAPPlugin Steps and Details

Description of "Figure 22-17 Default LDAPPlugin Steps and Details"

Figure 22-18 Default Orchestration of Steps for LDAPplugin

Description of "Figure 22-18 Default Orchestration of Steps for LDAPplugin"

X509Plugin

Figure 22-19 shows the X509Plugin module that is bundled with Access Manager 11g. The X509Plugin is similar to the LDAPPlugin with additional properties that indicate which attribute of the client's X.509 certificate should be validated against the user attribute in LDAP. Figure 22-20 shows default steps and details for this plug-in. Figure 22-21 shows the default orchestration of steps for the X509Plugin.

Figure 22-19 X509Plugin

Description of "Figure 22-19 X509Plugin"

Figure 22-20 X509Plugin Default Steps and Details

Description of "Figure 22-20 X509Plugin Default Steps and Details"

With this plug-in, the root and sub CA certificates must be added to the $DOMAIN_HOME/config/fmwconfig/amtruststore because the X509CredentialExtractor plug-in loads certificates from this location.

Table 22-14 lists the stepX509 values for Subject and Subject Alternative Names. Such processing is only supported when the X509Plugin is used.

See Also:

• Table 22-12

• Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints

Table 22-14 X509 Step Details (KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT)

issuer.D	Subject
subject.	EDIPI Note: EDIPI refers to the Electronic Data Interchange Personal Identifier.
subjectAltName.	OTHER_NAME (FASC-N) Note: FASC-N refers to the Federal Agency Smart Credential Number.
subjectAltName.	RFC822_NAME
subjectAltName.	UNIFORM_RESOURCE_IDENTIFIER

Figure 22-21 Default Orchestration for X509Plugin Steps

Description of "Figure 22-21 Default Orchestration for X509Plugin Steps"

See Also:

"Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints"

Password Policy Validation Module and Plug-ins

Oracle provides a Password Policy Validation Module that employs the following plug-ins as individual steps in the authentication process:

• User Identification Step

• User Authentication Step

• User Password Status Step

Figure 22-22 shows the Steps tab. Additional details follow the figure.

Figure 22-22 Password Policy Validation Module Plug-ins

Description of "Figure 22-22 Password Policy Validation Module Plug-ins"

Figure 22-23 shows the Steps Orchestration page for the Password Policy Validation Module plug-ins, which is self explanatory.

See Also:

• Table 22-12

• Accessing Password Policy Configuration Page

Figure 22-23 Steps Orchestration: Password Policy Validation Plug-ins

Description of "Figure 22-23 Steps Orchestration: Password Policy Validation Plug-ins"

22.7.4 Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints

Access Manager 11g support for personal identity verification (PIV) cards (a United States Federal smart card), is to use FASC-N and EDIPI attributes from the SubjectaltName extension to map the user during X.509 authentication. While multiple OCSP providers are not supported, you can use an OCSP Gateway or write a custom authentication plug-in that uses the OSDT OCSP APIs to validate against multiple OCSP providers.

The following functionality is available only with the X.509 Plug-in (not the X.509 Authentication module). The Plug-in configuration specifies the LDAP attribute to which the extracted attribute from the X.509 client certificate will be mapped.

1. In the Oracle Access Management Console, click Application Security at the top of the window.

2. In the Plug-ins section, click Authentication Modules.

3. In the list of modules, select the X509Plugin module.

4. In the page that opens, click Duplicate and fill out the fields as follows:

   See Also:

   "Creating a Custom Authentication Module using Bundled Plug-ins"

   General Tab:

   1. Name: CustomX509Plugin.

   2. Description: Custom Plug-in for X509.

   Steps Tab:

   1. Click + to add a step to the plug-in.

   2. Enter a Name and Description, then select the X509CredentialExtractor plug-in.

   Step Details:

   1. KEY_IS_CERT_VALIDATION_ENABLED true.

   2. KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT (Table 22-14): subject.EDIPI, subjectAltName.OTHER_NAME (FASC-N), subjectAltName.RFC822_NAME, subjectAltName.UNIFORM_RESOURCE_IDENTIFIER

   3. Click the Save button.

   Add Another Plug-in:

   1. Click + to add a different plug-in.

   2. Enter the Name, Description, and select UserIdentificationPlugin

   Step Details for Second Plug-in:

   1. Set KEY_IDENTITY_STORE_REF to the required identity store.

   2. Add the LDAP filter to the KEY_LDAP_FILTER attribute. For example:

      (&(uid= 
      Unknown macro: {subject.CN} 
      )(mail=
      Unknown macro: {subject.E} 
      ))
      

   3. Add the user search base, if required, to the KEY_SEARCH_BASE_URL attribute.

   4. Click the Save button.

   5. Proceed to Step Orchestration tab (Step2).

5. Orchestrate Steps:

   1. Initial Step: Select the X509CredentialPlugin Step from the drop down.

   2. On Success: X509CredentialPlugin step, select the UserIdentificationPlugin Step from the drop down list.

   3. On Success: UserIdentificationPlugin step, select Success from the drop down list.

   4. On Failure: Select Failure for both X509CredentialPlugin and UserIdentificationPlugin steps.

   5. On Error: Select Failure for both X509CredentialPlugin and UserIdentificationPlugin steps.

   6. Click the Apply button and review the confirmation window stating that the plug-in has been created successfully.

6. Set up the Certificate Validation Module for Certificate Validation and Revocation using OCSP.

   See Also:

   "Certificate Validation and Revocation"

   1. In the Oracle Access Management Console, click Configuration at the top of the window.

   2. In the Configuration console, click Certificate Validation.

   3. In the Certificate Revocation list, confirm that Enabled is checked, then click Save.

   4. In the OCSP/CDP section, enable OCSP, enter the OCSP URL and the Subject of the OCSP Server's certificate, then click Save.

   5. On the command line, use the Java keytool application to import the trusted certificates into the $DOMAIN_HOME/config/fmwconfig/amtruststore keystore, as trusted certificate entries.

      Note:

      Initially the keystore is empty; its password is set the first time the Java keytool application is used.

22.7.5 Creating a Custom Authentication Module using Bundled Plug-ins

Users with valid Administrator credentials can create custom authentication module that uses one or more authentication plug-ins.

This procedure outlines general steps for any authentication module (with sample information to configure an authentication X509 module for use with the Online Certificate Status Protocol (OCSP) to maintain the security of a server and other network resources).

See Also:

• "Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints"

• "Steps and Plug-ins in Customized Step-up Authentication Module"

Prerequisite

Ensure that any user identity store associated with the module is running and includes the required user population.

1. In the Oracle Access Management Console, click Application Security at the top of the window.

2. In the Application Security console, select Create Custom Authentication Module from the Create (+) drop-down list in the Plug-ins section.

3. In the page that appears, enter the Name and optional Description. For example: CustomX509Plugin and Plugin for X509, respectively.

   Click Apply to save general information.

4. Add Steps:

   1. Click the Steps subtab.

   2. Click the Add (+) button above the Steps table.

   3. In the Add New Step dialog box, enter a unique Step Name and optional Description.

   4. Browse for and select the desired plug-in name (X509CredentialExtractor, for instance) and click OK.

   5. Confirm information in the results table.

   6. Repeat b through e to add other steps until you have listed all required plug-ins for your module.

5. Define Step Details: Use appropriate values for requested parameters (Table 22-11, Table 22-12, Custom Plug-ins Actions and "Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple OCSP Endpoints"):

   1. Click a StepName in the table to reveal required details, enter appropriate values for the requested details.

   2. Validate User Cert using OCSP:

      Confirm that KEY_IS_CERT_VALIDATION_ENABLED is set to true.

      Add the certificate attributes to be extracted with KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT (Table 22-14):

      subject.EDIPI
      subjectAltName.OTHER_NAME (FASC-N)
      subjectAltName.RFC822_NAME
      subjectAltName.UNIFORM_RESOURCE_IDENTIFIER
      

   3. Click the Save button.

   4. Repeat to configure each step appropriately.

   5. Ensure that users are provisioned in any user identity stores assigned in the steps.

6. Orchestrate Steps: See Table 22-13 as you perform following steps.

   1. Click the Steps Orchestration subtab.

   2. From the InitialStep list, choose the name of the first step to be used.

   3. Select a StepName in the table.

   4. From the OnSuccess List, choose a condition (success or failure) or a step name.

   5. From the OnFailure List, choose the desired condition or a StepName.

   6. From the OnError List, choose the desired condition or a StepName.

   7. Repeat Steps c through f to orchestrate operations for each plug-in this module.

   8. Review your orchestration.

7. Initiate Strategy Validation: Click Apply to initiate validation of your orchestration strategy:

   • Successful Strategy: The orchestration strategy is applied and the module is ready to include in an authentication scheme. Continue with Steps 9 and 10.

   • Invalid Strategy: Click OK in the Error box, then edit your OnSuccess, OnFailure, OnError strategies (or add or remove plug-ins) to correct the problem. Repeat this step until your strategy is successful.

8. In the navigation tree, confirm the new Custom Authentication Module is listed, and then close the page when you finish.

9. Use your custom module in an authentication scheme, as described in "Managing Authentication Schemes".

22.7.6 Steps and Plug-ins in Customized Step-up Authentication Module

The processing that occurs with a customized step-up authentication module is driven by the steps and plug-ins described in Table 22-15. For more information, see Table 22-12.

Table 22-15 Steps and Plug-ins in a Customized Step-up Authentication Module

Step #	Step Name	Plug-in Name	Description
1	StandardLevelCheck-2	UserAuthnLevelCheckPlugin	Configurable with the LevelCheck Rule and credentials parameters associated with the SUCCESS or FAILURE outcome resulting from the check. This plugin communicates with the authentication engine to determine the current authentication level of the user and compares it with the plugin level parameter AUTHN_LEVEL_FOR_PLUGIN. It interacts with a custom credential collector and checks the current Authentication Level of the user against the value specified. For example, if 2 is specified for X: Authentication Level >= X returns ExecutionStatus.SUCCESS and proceeds to the next step; for example it will check for higer level authentication. Authentication Level < X returns ExecutionStatus.FAILURE and proceeds to the next step in the plugin; for example it will collect the standard credentials for level 2 (username and password). Specifies parameters to collect depending on whether the Authentication Level check succeeded or failed: ON SUCCESS, go to SensitiveLevelCheck-6 ON FAILURE, go to CollectUserNamePassword ON ERROR, Failure
2	CollectUserNamePassword	CredentialCollectorPlugin Flow must start with the Plug-in communicating the credential parameters to collect. The Action must support allowing the Server to mark parameters as immutable.	This plugin interacts with the credential collector (CustomReadServlet) to allow the administrator to configure the credentials collected for authentication. Credentials to be collected are configured as step parameters. The plugin validates these parameters and renders the UI to collect them. The user provides the credentials that need to be collected in the step parameter. In this example, since in previous step user was not authenticated to level 2, he will be prompted to enter a user name and password. loginPageURL: /CustomRead/Servlet (generic credential collector for UserAuthnLevelCheckPlugin to render the interface to acquire plug-in specified credentials. No_OF_CREDENTIALS: 4 CRED_PARAM_4 CRED_PARAM_3 CRED_PARAM_2: {ID=KEY_PASSWORD},{DISPLAY_NAME=KEY_PASSWORD},{TYPE=password} CRED_PARAM_1: {ID=KEY_USERNAME},{DISPLAY_NAME=KEY_USERNAME },{TYPE=text} actiontype: FORWARD Credentials to be collected should be specified in this format only for the credential collector to render the UI interface. Also specifies action on: ON SUCCESS, go to UserIdentificationProcess ON FAILURE, Failure ON ERROR, Failure
3	UserIdentificationProcess	UserIdentificationPlugIn	Out of the box plug-in that maps the user to a specific LDAP user record: ON SUCCESS, go to UserAuthenticationStep ON FAILURE, Failure ON ERROR, Failure
4	UserAuthenticationStep	UserAuthenticationPlugin	Out of the box plug-in that authenticates the supplied username and password credentials against an LDAP directory. ON SUCCESS, go to SensitiveLevelCheck-6 ON FAILURE go to CollectSensitiveLevelCreds ON ERROR, Failure
5	SensitiveLevelCheck-6	UserAuthnLevelCheckPlugin	This plugin communicates with the authentication engine to determine the current authentication level of the user and compares it with the plugin level parameter AUTHN_LEVEL_FOR_PLUGIN. It interacts with a custom credential collector and checks the current Authentication Level of the user against the value specified. Specifies parameters to collect depending on whether the check succeeded or failed: ON SUCCESS, Success ON FAILURE, go to CollectSensitiveLevelCreds ON ERROR, Failure
6	CollectSensitiveLevelCreds	CredentialCollectorPlugin	This plugin renders the UI for collecting credentials for level 6 authentication. This is similar to CollectUserNamePwd. ON SUCCESS, go to ValidateSensitiveLevelCreds ON FAILURE, Failure ON ERROR, Failure CRED_PARAM_1: {ID=securitycode},{DISPLAY_NAME=form_securecode},{TYPE=text}
7	ValidateSensitiveLevelCreds	SubjectSetPlugin	This custom developed plug-in validates the security code against the server. ON SUCCESS, Success ON FAILURE, Failure ON ERROR, Failure

After defining and orchestrating plug-ins in an authentication module, you can use the module in an authentication scheme and use the scheme in a policy.

See Also:

"Creating a Custom Authentication Module using Bundled Plug-ins"

22.7.7 Configuring Step-up Authentication

You can define step-up authentication using plug-ins within a customized module.

In this example, there are users who need standard level access to pages on the corporate portal and those who need access to sensitive information. For standard applications, authentication credentials include username and password. For sensitive applications, credentials include username, password, and a security code (the later obtained with a custom plugin that validates the code).

1. Create or edit a custom authentication module for step up authentication:
   
   Description of the illustration stepup_authn_smry.gif
2. Define your custom authentication module based on the Steps shown here.
   
   Description of the illustration stepup_authn_steps.gif
3. Orchestrate your Steps and Plug-ins as shown here and described in Table 22-15.
   
   Description of the illustration stepup_authn_orch.gif
4. Sensitive Scheme: Create or edit an Authentication Scheme for sensitive applications that uses your customized step-up authentication module. For example:

   See Also:

   "Managing Authentication Schemes"

   
   Description of the illustration stepup_sensitv_scheme.gif
5. Lower-Level Scheme: Create or edit an Authentication Scheme for the lowest level applications using your customized step-up authentication module F.or example:
   
   Description of the illustration stepup_std_scheme.gif
6. Sensitive Policy: Create or edit an Authentication Policy for sensitive-level resources using your customized step-up Authentication Scheme. For example:

   See Also:

   Managing Policies to Protect Resources and Enable SSO

   
   Description of the illustration stepup_authn_pol.gif
7. Lower-Level Policy: Create or edit an Authentication Policy for the lowest level resources using your customized step-up Authentication Scheme. For example:
   
   Description of the illustration stepup_authn2_pol.gif
8. Verify: Verify your resources and the policies that protect them.

22.7.8 Configuring an HTTPToken Extractor Plug-in

You can configure an HTTPToken Extractor plug-in.

To configure:

1. Create a sample plug-in that will re-direct the user to the authenticating application.

   The authenticating application will authenticate the user and set the user name in the HTTP header or cookie.

2. Create a custom authentication module that will access any applicable plug-ins.

   For example, if you add the plug-in created in the previous step and the HTTPToken Extractor and User identification plug-ins, successful authentication occurs when the process for all three plug-ins has been successfully completed.

3. Add values for the header name and the user search filter properties.

   The KEY_HEADER_PROPERTY is set in the HTTPToken Extractor plug-in while KEY_LDAP_FILTER is set in the UI plug-in. For example:

   • KEY_HEADER_PROPERTY = cookieorheadername

   • KEY_LDAP_FILTER = (uid={cookieorheadername})

   Note:

   The user should be present in the data store which is being used.

22.7.9 JSON Web Token Plug-in

Oracle Access Manager (OAM) provides complete but different access management solutions for both users and applications. After OAM authentication, SSO tokens are issued which can be used with WebGates or products like Oracle API Gateway. These tokens are specific to OAM though and there are often business requirements where Web services or REST services need to be protected. While OAM tokens can be used to protect web services, they are usually protected by standard tokens. A JSON Web Token (JWT) is one of the standard tokens that is widely used.

In the RSPS2 release, OAM introduced complete support for an OAuth authorization service provided by the Oracle Access Manager Mobile and Social (OAMMS) service. The OAuth Service issues a JSON Web Token (JWT) for accessing Web services subsequent to the user's authentication and/or authorization. Thus, a user can be authenticated with an OAM authentication mechanism and subsequently have both an OAM and a JWT for access to different resources. A typical scenario in which this can be used is when a WebGate protected application is accessed. The user is authenticated by an OAM authentication module and both an OAM token and a JWT are provided. The OAM token is used for access through the WebGate and the JWT can be used to access a Web service or a REST service when needed. (The Web service or REST service is protected by a product like Oracle API Gateway or Oracle Web Services Manager.)

A JSON Web Token Plug-in is now available in OAM. Use this JSON Web Token Plug-in when you need to protect REST or Web services with standard tokens. The JSON Web Token Plug-in issues both an OAM token and a Mobile and Social JWT that can be used for Web services access. Oracle API Gateway and Oracle Web Services Manager can use this JWT for Web services protection as well. See the following sections for additional details.

• Understanding the JSON Web Token Plug-in

• Configuring the JSON Web Token Plug-In

22.7.9.1 Understanding the JSON Web Token Plug-in

You can use JSON Web Token Plug-in in deployments.

The following flow describes how to use JSON Web Token Plug-in:

• Configure the Oracle Access Management WebGate to use both OAM authentication and the JSON Web Token Plug-in.

• When a user accesses a resource protected by the WebGate, the WebGate redirects the user to authenticate with Access Manager.

• Upon authentication, the plug-in identifies which OAuth service end point should generate the JWT. (OAuth service end points are unique and can be configured to point to a specific OAuth service profile within a specific Identity Domain.) Oracle Access Manager Mobile and Social creates the JWT and the plug-in returns it as a cookie. (The cookie name can be configured in the plug-in configuration.)

• The Web application intercepts the response and accesses the cookie so that it can be used later for Web service access. Depending on how the web application is deployed, there may be other options to retrieve the JWT. The user can now access the Web resource.

• When the Web resource needs to access a Web service, it extracts the OAM Mobile and Social JWT and sends it to the Oracle API Gateway.

• The Oracle API Gateway uses the Oracle OAuth Service REST API to validate the token. It then grants access to the Web service. The Oracle API Gateway can also validate the JWT locally without making a remote call to the OAuth service.

Note:

Currently there is not a mechanism to pass scope to the OAuth service while issuing a JWT with OAM authentication. Consequently, the token should be considered to have global scope.

Both the OAM token timeout and the JWT timeout can be set to the same value to have the same validity. The OAM tokens and JWT are not linked, so they cannot be terminated using single logout.

22.7.9.2 Configuring the JSON Web Token Plug-In

You can configure the JSON Web Token Plug-in.

You will be creating a custom authentication module.

1. In the Oracle Access Management Console, click Application Security at the top of the window.

   The Search Authentication Modules screen is displayed.

2. Select Create Custom Authentication Module from the Create (+) drop-down menu in the Plug-ins section.

   The General tab is displayed.

3. Enter a name (and optional description) for the custom authentication module.

   For this example, we name the module JWTToken AuthnModule.

4. Click the Steps tab and the + (plus sign) to add a new step.

   The Add New Step dialog is displayed. Three new steps will be added.

5. Specify a step name (and optional description), select an activated plug-in from the Plug-in name drop down list and click OK.

   For this example, the values are StepUI and UserIdentificationPlugin. The flow parameters for that plug-in can be edited after it is added to the step

6. Enter values for the UserIdentificationPlugin parameters and click Save.

7. Click the + (plus sign) to add a second step, enter the name StepUA, select UserAuthenticationPlugin from the drop down list and click OK.

8. Enter values for the UserAuthenticationPlugin parameters and click Save.

9. Click the + (plus sign) to add a third step, enter the name StepOAuth, select OAuthTokenResponsePlugin from the drop down list and click OK.

10. Enter values for the OAuthTokenResponsePlugin parameters and click Save.

11. Click the Steps Orchestration tab to configure the orchestration of the steps in the following order.

    1. StepUI

    2. StepUA

    3. StepOAuth

12. Click Apply and close the Custom Authentication Module tab.

13. Click Authentication Schemes from the Launch Pad.

14. Select LDAPScheme and click Duplicate.

    A Copy of LDAPScheme screen displays.

15. Change the value of Name to JWTToken AuthnScheme and the value of Authentication Module to JWTToken AuthnModule.

16. Click Save.

17. Configure an Authentication policy with the newly defined JWTToken AuthnScheme Authentication Scheme.

22.7.10 X.509 Authentication Using Extended Key Usage (EKU)

OAM supports validation of Extended Key Usage (EKU) extensions in a client certificate.

OAM validates the X.509 client certificate acquired through two-way TLS using path validation. In addition to this, it also supports the validation of EKU extensions in a client certificate.

By default, the validation of EKU extensions in a client certificate is disabled. You can enable this feature by setting the value of KEY_IS_ENFORCE_EKU_ENABLED to TRUE/YES in the X509CredentialExtractor plugin.

The EKU extensions in a client certificate are validated against the corresponding object identifiers (OID) that you specify under KEY_ENFORCE_KEY_USAGES in the X509CredentialExtractor plugin. For more information, see Table 22-12

The X.509 authentication succeeds only if the EKU extensions in a client certificate includes all the OIDs specified in the KEY_ENFORCE_KEY_USAGES parameter of the X509CredentialExtractor plugin.

Note:

KEY_IS_ENFORCE_EKU_ENABLED must be set to TRUE/YES.

The following sections provide details about the X.509 Authentication Module, Scheme and configurations for EKU Validation:

• X.509 Authentication Module for EKU Validation

• X509 Steps Orchestration for EKU

• X509 Scheme for EKU

• Protecting Resources with X509 for EKU Scheme

22.7.10.1 X.509 Authentication Module for EKU Validation

Create a new Authentication module and configure the following steps: UserIdentificationPlugin and X509CredentialExtractor.

To configure the X.509 authentication module for EKU validation in the Oracle Access Management Console:

1. Log into the Oracle Access Management Console as System Administrator.
2. From the Application Security Launch Pad, click Authentication Modules under Plug-ins.
3. From the Authentication Modules tab, click Create Authentication Module and then Custom Authentication Module.
4. Add a name and description for the authentication module under the General tab. For example, X509.
5. Add the X509 authentication module steps as follows:
   1. Add the UserIdentificationPlugin step and set following parameters:

      Table 22-16 UserIdentification Step

      Step Details	Description
      KEY_IDENTITY_STORE_REF	The name of the registered Identity Store containing the module users. Default: The registered Default Store.
      KEY_LDAP_FILTER	Add the LDAP filter to the KEY_LDAP_FILTER attribute. Only standard LDAP attributes can be used when defining an LDAP search filter. For example: (uid={KEY_USERNAME})
      KEY_SEARCH_BASE_URL	Base URL for user searches. For example: dc=us,dc=example,dc=com

   2. Add the X509CredentialExtractor step and set the following parameters:

      Table 22-17 X509CredentialExtractor Step

      Parameters	Display Name	Description
      KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT	User Mapping Attribute	X509 certificate Attribute to be used for user mapping required by X509CredentialExtractor.
      KEY_IS_CERT_VALIDATION_ENABLED	Certificate Validation	Enable or disable X.509 certificate validation, required by X509CredentialExtractor.
      KEY_IS_ENFORCE_EKU_ENABLED	Enable Extended Key Usage (EKU) Validation	Enable or Disable validation for Extended Key Usage (EKU) extensions in the client certificate: YES NO (Default) TRUE FALSE Note: An empty or incorrect value is handled as NO. For details, see X.509 Authentication Using Extended Key Usage (EKU)
      KEY_ENFORCE_KEY_USAGES	Object Identifier (OID) Mapping	Specify a comma separated list of object identifiers (OID) that needs to be present in the EKU extension of the client certificate. Note: KEY_IS_ENFORCE_EKU_ENABLED must be set to YES/TRUE. By default, the OID 1.3.6.1.5.5.7.3.2 is specified. This OID is used for client authentication through TLS web client. Note: The values must be specified as OIDs only. Any other values, in any other format is not recognized and the authentication fails. For Smart Card Login, specify the OID 1.3.6.1.4.1.311.20.2.2 To specify multiple OIDs, use a comma (,) between the OIDs. For example: 1.3.6.1.5.5.7.3.2,1.3.6.1.4.1.311.20.2.2. Note: Both the values must be present in the EKU extension of the client certificate. If either of these values is not present, the authentication fails. See also, Global OID Reference Database for OID details.

22.7.10.2 X509 Steps Orchestration for EKU

Configure the Orchestration steps for the Authorization flow.

1. Click the Steps Orchestration subtab
2. From the InitialStep list, choose the X509_EKU step.
3. Set On Success, On Failure, and On Error for each of the steps as shown in the following example:

Table 22-18 X509 Step Orchestration for EKU

Name	Description	On Success	On Failure	On Error
X509_EKU	X509CredentialExtractor Step	User_Identification	Failure	Failure
User_Identification	UserIdentificationPlugin Step	Success	Failure	Failure

22.7.10.3 X509 Scheme for EKU

Create a new X509 Authentication Scheme.

To create a new Authentication Scheme:

1. From the Application Security Launch Pad, click Authentication Schemes under Access Manager.
2. From the Authentication Schemes tab, click Create Authentication Scheme.
3. Set all the parameters as described in Authentication Schemes and Pages.

   The following figure shows a Sample Authentication Scheme Page:

   Figure 22-24 Sample Authentication Scheme Page

   

22.7.10.4 Protecting Resources with X509 for EKU Scheme

Complete the configuration for the X509 for EKU, by assigning the X509_EKU_Scheme to the protected resource policy.

1. From the Application Security Launch Pad, select Application Domains under Access Manager.
2. Search and open the required Application Domain.
3. Open the Authentication Policies tab and click Protected Resource Policy.
4. Select the X509_EKU_Scheme from the Authentication Scheme drop-down list and click Apply.

22.8 Deploying and Managing Individual Plug-ins for Authentication

Administrators can create custom plug-ins and add, validate, distribute, and activate them for defining customized multi-step authentication.

This section provides the following topics:

• About Managing Your Own Authentication Plug-ins

• Making Custom Authentication Plug-ins Available for Use

• Checking an Authentication Plug-in's Activation Status

• Deleting Your Custom Authentication Plug-ins

• Plug-ins Page

• Plug-in Details Page

22.8.1 About Managing Your Own Authentication Plug-ins

You can create custom authentication plug-ins and use them to define customized multi-step authentication modules.

Create custom plug-ins as specified in the Developing Custom Authentication Plug-ins in the Fusion Middleware Developer's Guide for Oracle Access Management. After development, the plug-in must be deployed on the AdminServer, as a JAR file, which is validated automatically. After validation, you can configure and distribute the plug-in using the Oracle Access Management Console.

The server processes the XML configuration file within the plug-in JAR file to extract data about the plug-in. After the plug-in is imported, you can see and modify the various plug-in states based on information available from the AdminServer.

Plug-ins Page illustrates the Plug-ins Node under the Common Configuration section of the System Configuration tab. Plug-in Details Page reflects configuration details for the selected plug-in the table.

22.8.2 Making Custom Authentication Plug-ins Available for Use

Users with valid Administrator credentials can add, validate, distribute, and activate a custom plug-in.

Prerequisites

Developing a custom plug-in as described in the Developing Custom Authentication Plug-ins in the Fusion Middleware Developer's Guide for Oracle Access Management.

1. Import the Plug-in:

   1. In the Oracle Access Management Console, click Application Security at the top of the window

   2. In the Application Security Console, click Authentication Plug-ins in the Plug-ins section.

   3. In the page that appears, click Import Plug-in.

   4. In the Import Plugin dialog box, click Browse and select your plug-in JAR file.

   5. Review the message in the dialog box, then click Import.

2. Configure Parameters: Expand the Plugin Details section, click Configuration Parameters, and enter appropriate information as needed.

3. Distribute the Plug-in to OAM Servers:

   1. In the Plug-ins table, select the target plug-in.

   2. Click Distribute Selected, then check the plug-in's Activation Status tab.

4. Activate the Plug-in (and the custom plugin implementation class) so it is ready to be used by OAM Server:

   1. In the Plug-ins table, select the target plug-in.

   2. Click Activate Selected, then check the plug-in's Activation Status.

5. Perform the following tasks as needed:

   • Checking an Authentication Plug-in's Activation Status

   • Deleting Your Custom Authentication Plug-ins

   • Creating a Custom Authentication Module using Bundled Plug-ins

22.8.3 Checking an Authentication Plug-in's Activation Status

Users with valid Administrator credentials can activate a custom plug-in and check the status of activation.

Prerequisites

Making Custom Authentication Plug-ins Available for Use

1. In the Oracle Access Management Console, click Application Security at the top of the window
2. In the Application Security console, click Authentication Plug-ins in the Plug-ins section.
3. In the Plug-ins table, select the target plug-in.
4. Server Instance Name: Expand the Plug-in Details section and click Activation Status to display the location and status of the plug-in.
5. Perform the following tasks as needed:

   • Deleting Your Custom Authentication Plug-ins

   • Creating a Custom Authentication Module using Bundled Plug-ins

22.8.4 Deleting Your Custom Authentication Plug-ins

Users with valid Administrator credentials can deactivate and then delete a custom plug-in.

When an Administrator deletes a custom authentication plug-in, its name is not removed from the list of plug-ins. To delete the plug-in (for the purpose of re-importing the same plug-in later), the Administration must stop the WebLogic Server and edit the oam-config.xml manually.

Prerequisites

The plug-in must have been added and available in the console

1. In the Oracle Access Management Console, click Application Security at the top of the window

2. In the Application Security console, click Authentication Plug-ins in the Plug-ins section.

3. Deactivate the Plug-in: You must perform this before removing a plug-in.

   1. In the Plug-ins table, select the target plug-in.

   2. Click Deactivate Selected, then check the plug-in's Activation Status.

4. Delete the Deactivated Plug-in:

   1. In the Plug-ins table, select the target plug-in.

   2. Click Delete Selected.

   3. Stop the WebLogic Administration Server, locate and edit oam-config.xml manually to remove the deactivated plug-in, and then restart the WebLogic Administration Server.

5. Perform the following tasks as needed:

   • Making Custom Authentication Plug-ins Available for Use

   • Creating a Custom Authentication Module using Bundled Plug-ins

22.8.5 Plug-ins Page

Provides information about the Plug-ins Node under the Common Configuration section of the System Configuration tab, and the Plug-ins page.

The Plug-ins page includes a tool bar with command buttons, most of which operate on the plug-in that is selected in the table. The table provides information about the existing custom plug-ins and their state.

Figure 22-25 Plug-ins Page

Description of "Figure 22-25 Plug-ins Page"

Administrators control plug-in states using the command buttons, across the table, at the top of the Plug-ins page, as described in Table 22-19.

Table 22-19 Custom Plug-ins Actions

Action Button	Description
Import Plugin...	Uploads the plugin information to the OAM_FILE_ARTIFACTS table in the database and also adds the plug-in JAR file to the AdminServer $DOMAIN_HOME/oam/plugins and begins plug-in validation. Same JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins) matches an existing plug-in JAR name (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), Oracle Access Manager extracts new configuration metadata from the XML file in the JAR (in $DOMAIN_HOME/oam/plugins) and checks the version of the new plug-in. XML Version: If the new plug-in XML version (in $DOMAIN_HOME/oam/plugins) is greater than the existing XML version (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), validation is successful. Otherwise, "invalid plugin name with invalid version" is returned and the new plug-in JAR is removed (from $DOMAIN_HOME/oam/plugins). Different JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins) is different then existing plug-in JAR names (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), the new plug-in JAR is uploaded and validation is successful. On Success: Status is reported as "Uploaded" (even if an OAM Server is down). If all registered OAM Servers report "Uploaded", then the status on AdminServer is also "Uploaded". See Also: Developing Custom Authentication Plug-ins in the Fusion Middleware Developer's Guide for Oracle Access Management.
Distribute Selected	Downloads the imported plugin from the database to the $DOMAIN_HOME/config/fmwconfig/oam/plugins directory on the AdminServer only Propagates the plug-in to all registered OAM Servers. Starts the distribution listener and notification mechanism between AdminServer and OAM Servers Distributes the plug-in JAR from database to each OAM Server node under $DOMAIN_HOME/config/fmwconfig/oam/plugins On Success: Status is reported as "Distributed" (even if an OAM Server is down). If all registered OAM Servers report "Distributed", then the status on AdminServer is also "Distributed". On Failure: Status is reported as "Distribution Failed"
Activate Selected	After successful distribution the plug-in can be activated on all registered OAM Servers. Activation: Starts the Message listener and notification mechanism between AdminServer and OAM Servers AdminServer sends Activate notification to all registered OAM Servers On Success: Status is reported as "Activated" (even if an OAM Server is down). If all registered OAM Servers report "Activated", then the status on AdminServer is also "Activated". On Failure: Status is reported as "Activation Failed" Following activation on all OAM Servers, the plug-in can be used and executed in any authentication module construction or orchestration.
Deactivate Selected	Following plug-in activation, an Administrator can choose to deactivate the plug-in: if the plug-in is not used in any authentication module or scheme, for example. The selected plug-in from all registered OAM Servers. Deactivate: Starts the Distribution listener and notification mechanism between AdminServer and OAM Servers Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_HOME/config/fmwconfig/oam/plugins) AdminServer sends De-activation notification to all registered OAM Servers On Success: Status is reported as "Deactivated" (even if an OAM Server is down). If all registered OAM Servers report "Deactivated" then the status on AdminServer is also "Deactivated". Plug-in configuration is removed from oam-config.xml. Note: After deactivation, the plug-in cannot be used or executed in any authentication module or orchestration. On Failure: Status is reported as "Deactivation Failed"
Remove Selected	Following plug-in deactivation, an Administrator can delete the selected plug-in. During this process, Access Manager: Delete: Starts the Distribution listener and notification mechanism between AdminServer and OAM Servers Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_HOME/config/fmwconfig/oam/plugins) On Success: Status is reported as "Removed" (even if an OAM Server is down). Plugin configuration continues to remain in oam-config.xml with the updated status "Removed". On Failure: Status is reported as "Removal Failed"

Table 22-20 describes elements in the Plug-ins status table.

Table 22-20 Plugins Status Table

Element	Description
Plugin Name	Extracted from the Plugin name element of the XML metadata file.
Description	Extracted from the description element of the XML metadata file.
Activation Status	Reported activation status based on information from AdminServer.
Type	Extracted from the type element of the XML metadata file.
Last Updated on	Extracted from the creation date element of the XML metadata file.
Last Updated by	Extracted from the author element of the XML metadata file.

22.8.6 Plug-in Details Page

Provides information about the Plug-in Details page.

In the Plug-in Details section of the page, the Activation Status is maintained by the AdminServer, as shown in Figure 22-26.

Figure 22-26 Plugin Details: Activation Status of Selected Plug-in

Description of "Figure 22-26 Plugin Details: Activation Status of Selected Plug-in"

Depending on your plug-in, various configuration details are extracted from the configuration element of the XML metadata file to populate Configuration Parameters in the Plugin Details section. Examples are shown in Table 22-21; see also, Table 22-12.

Table 22-21 Example of Plugin Details Extracted from XML Metadata File

Configuration Element	Description
DataSource	- <configuration> - <AttributeValuePair> <Attribute type="string" length="20">DataSource</Attribute> <mandatory>true</mandatory> <instanceOverride>false</instanceOverride> <globalUIOverride>true</globalUIOverride> <value>jdbc/CISCO</value> <AttributeValuePair> <configuration>
Kerberos Details	Defines the following Kerberos details: KEY_KEYTAB_FILE, KEY_PRINCIPAL, KEY_KRB_CONFIG_FILE
User Identification Details	Defines the User Identity Store and LDAP filter parameters. for this plug-in to use: KEY_IDENTITY_STORE_REF, KEY_LDAP_FILTER
User Authentication Details	Defines the User Identity Store for this plug-in to use: KEY_IDENTITY_STORE_REF
X.509 Details	Defines the X.509 certificate details for this plug-in to use: KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT, KEY_IS_CERT_VALIDATION_ENABLED

22.9 Managing Authentication Schemes

Access to a resource or group of resources can be governed by a single authentication process known as an authentication scheme. An authentication scheme is a named component that defines the challenge mechanism required to authenticate a user.

Each authentication scheme must also include a defined authentication module (standard or custom, as described in "Deploying and Managing Individual Plug-ins for Authentication").

When you register a partner (either using the Administration Console or the remote registration tool), the Application Domain that is created is seeded with a policy that uses the authentication scheme that is set as the default scheme. You can choose any of the existing authentication schemes as the default for use during policy creation.

You can also create a new authentication scheme, copy an existing definition to use as a template, modify a definition, or delete the definition. The copy uses a default name that is based on the original. For example, if you copy the scheme named KerberosScheme, the copy is named Copy of KerberosScheme.

This section is divided into the following topics:

• Authentication Schemes and Pages

• Understanding Multi-Level and Step-Up Authentication

• Creating an Authentication Scheme

• Viewing, Editing, or Deleting an Authentication Scheme

• Searching for an Authentication Scheme

22.9.1 Authentication Schemes and Pages

All authentication schemes include the same elements with differing values.

Figure 22-27 shows the default LDAPScheme page as an example.

Figure 22-27 Default LDAPScheme Page

Description of "Figure 22-27 Default LDAPScheme Page"

Table 22-22 provides information about each of the elements and values in any authentication scheme. Use the Set as Default button to make this the default scheme.

Table 22-22 Authentication Scheme Definition

Element	Description
Name	The unique name for this scheme, which appears in the navigation tree. See Also:"Pre-configured Authentication Schemes"
Description	The optional description, up to 200 characters, that explains the use of this scheme.
Authentication Level	The trust level of the authentication scheme. This reflects the challenge method and degree of trust used to protect transport of credentials from the user. The trust level is expressed as an integer value between 0 (no trust) and 99 (highest level of trust). Note: Level 0 is unprotected. Only unprotected resources can be added to an Authentication Policy that uses an authentication scheme at protection level 0. For more information, see Table 25-1. Note: After a user is authenticated for a resource at a specified level, the user is automatically authenticated for other resources in the same Application Domain or in different Application Domains, if the resources have the same or a lower trust level as the original resource. See Also: "About Multi-Level and Step-Up Authentication".
Default	A non-editable box that is checked when the Set as Default button is clicked.
Challenge Method	One challenge method must be selected from those listed as available: Form Basic (LDAP) X509 (Certificate) WNA (Windows Native Authentication) None DAP See Also: "Credential Challenge Methods"
Challenge Redirect URL	This URL declares the end point referencing the Credential Collector (ECC or DCC). For example: ECC: /oam/server DCC: http://<dcc-host:port>/ See Also: "About Host Identifiers" Configuring OAM WebGate and Authentication Policy for DCC
Authentication Module	Identifies the pre-configured authentication module to be used to challenge the user for credentials. The module or plug-in specified here identifies the exact user identity store to be used. FederationMTPlugin FederationPlugin Kerberos Plugin (Authentication Modules and Custom Authentication Module) MTLDAPBasic MTLDAPPlugin OIFMTLDAPPlugin Password Policy Validation Module TAPModule X509 Plugin (under the X509 Authentication Modules node) See Also "Managing Native Authentication Modules" and "Orchestrating Multi-Step Authentication with Plug-in Based Modules".
Challenge URL	This URL is associated with the designated Challenge Method (FORM, for instance). FORM-based, out of the box authentication scheme (LDAPScheme and LDAPNoPasswordValidationScheme), Challenge URL is "/pages/login.jsp". The context type and context values are used to build the final URL. X509-based Challenge URL takes the form: https://managed_server_host:managed_server_ssl_port/oam/CredCollectServlet/X509 Note: The default Challenge URL is based on the credential collector embedded with the OAM Server (ECC). If you are using detached credential collector-enabled Webgate and related DCC pages installed with WebGate, see Configuring OAM WebGate and Authentication Policy for DCC.
Challenge Parameters	Supported challenge parameters are discussed in "Challenge Parameters for Authentication Schemes".
For schemes using Challenge Method FORM, X509, or DAP	Only Schemes with the Challenge Method of FORM, X509, or DAP include the following additional elements. Other schemes use defaults that require no change.
Context Type	Used to build the final URL for the Embedded Credential Collector (ECC only, DCC does not use this) based on the following possible values: default: The Context Value is used to construct the final URL to forward to for credential collection. For example: with a challenge URL of "/pages/login.jsp" and a context value of /oam, the server forwards to "/oam/pages/login.jsp" for credential collection by the ECC. customWar: If a customized credential collector page "customlogin.jsp" is deployed in a WAR file (with context root, "custom") within the same domain, it should be used to collect credentials. Then set the following values to have server forward to the WEB application page "/custom/customlogin.jsp" to collect credentials: challenge_url = "/customlogin.jsp" contextType="customWar" contextValue="/contextroot of custom application" customHtml: A custom html credential collector page. This file can be placed in a location that is accessible to the application. Set the following values to have the server forward to the custom servlet provided to read the html file and render the page: challenge_url = "/CustomReadServlet" contextType="customHtml" contextValue="html file location" external: If the login page is external, the file can be placed in a location that is accessible to the application. Set the following values to have the server redirect to the challenge URL (the fully-qualified URL of the external credential collector page) for credential collection. The username and password are collected by the external form (HTML or jsp) and submitted to the OAM Server: challenge_url = "http://host:port/externallogin.jsp" contextType="external" contextValue=Not applicable See Also: "About Custom Login Pages" and Managing Global Password Policy
Context Value	Used to build the final URL for the credential collector. The default value is /oam.

About Custom Login Pages

Only Schemes with the Challenge Method of FORM, X509, or DAP include additional elements described at the end of Table 22-22. All custom login pages must meet the following requirements:

• Custom login pages require two form fields (username and password). Access Manager supports custom forms as described in Developing Applications with Oracle Access Management.

• CustomWar and external context types, require logic within the custom login page to perform the following two tasks:

  • Send back the request ID the page received from the Access Manager server. For example: String reqId = request.getParameter("request_id"); <input type="hidden" name="request_id" value="<%=reqId%>">

  • Submit back to the OAM Server the end point, "/oam/server/auth_cred_submit". For example: <form action="/oam/server/auth_cred_submit"> or "http://oamserverhost:port/oam/server/auth_cred_submit".

For more information, see the following topics:

• Pre-configured Authentication Schemes

• Credential Challenge Methods

• Challenge Parameters for Authentication Schemes

See Also:

Developing Applications with Oracle Access Management for details about customizing login pages and messages.

22.9.1.1 Pre-configured Authentication Schemes

Pre-configured Authentication Schemes such as BasicFAScheme and KerberosScheme are available with Access Manager.

"Table 22-23" identifies the pre-configured authentication schemes available with Access Manager and some specific details of each. For more information about challenge parameters, see "Table 22-23".

Table 22-23 Pre-configured Authentication Schemes

Scheme Name	Specifications	Purpose
AnonymousScheme	Authentication Level: 0 Challenge Method: None Authentication Module: AnonymousModule	Leaves unprotected specific Access Manager URLs and allows users to access such URLs without a challenge. Users are not challenged and do not need to enter their credentials. Note: Authentication Level 0 is for public pages. Oracle recommends that you do not use Level: 0 in a custom authentication scheme. Also: When a resource is protected by AnonymousScheme, it is not displayed in a session search.
BasicFAScheme Only for Oracle Fusion Applications	For Fusion Applications	For specific information about this authentication scheme, refer to the Oracle Fusion Applications Technology Library located on the Oracle Technology Network (OTN) web site: http://www.oracle.com/technetwork
BasicScheme	Authentication Level: 1 Challenge Method: Basic Authentication Module: LDAP	Protects Access Manager-related resources (URLs) for most directory types. Note: Authentication Level 1 is only one step higher than 0 public pages. Oracle recommends that you do not use Level: 1 in a custom authentication scheme.
BasicSessionlessScheme	Authentication Level: 1 Challenge Method: Basic Authentication Module: LDAP	Primarily used for clients that don't support URL redirect or cookies. Challenge Parameters: CookieLessMode=true Note: Authentication Level 1 is only one step higher than 0 public pages. Oracle recommends that you do not use Level: 1 in a custom authentication scheme.
FAAuthScheme Only for Oracle Fusion Applications	Authentication Level: 2 Challenge Method: FORM Authentication Module: LDAP Context: customWar Context Value: /fusion_apps	For specific information about this authentication scheme, refer to the Oracle Fusion Applications Technology Library located on the Oracle Technology Network (OTN) web site: http://www.oracle.com/technetwork
FederationMTScheme Only for Oracle Fusion Applications	Authentication Level: 2 Challenge Method: FORM Authentication Module: FederationMTPlugin Context Type: customWar Context Value: /fusion_apps Challenge Parameters: initial_command=NONE is_rsa=true	For specific information about this authentication scheme, refer to the Oracle Fusion Applications Technology Library located on the Oracle Technology Network (OTN) web site: http://www.oracle.com/technetwork See Also: "Challenge Parameters for Authentication Schemes".
FederationScheme Only for Identity Federation 11.1.2.	Authentication Level: 2 Challenge Method: FORM Authentication Module: FederationPlugin Context Type: customWar Context Value: /oam Challenge Parameters: initial_command=NONE is_rsa=true	See Also: Managing Oracle Access Management Identity Federation.
KerberosScheme	Authentication Level: 2 Challenge Method: WNA Authentication Module: Kerberos Context Type: customWar Context Value: /fusion_apps	Protects Access Manager-related resources (URLs) for most directory types based on a Windows Native Authentication challenge method and valid WNA credentials in Active Directory.
LDAPNoPasswordValidationScheme	Authentication Level: 2 Challenge Method: FORM Authentication Module: LDAPNoPasswordAuthModule Context Type: default Context Value: /oam Note: LDAPNoPasswordAuthModule is similar to the DAP (asserter) mechanism.	Protects Access Manager-related resources (URLs) for most directory types based on a form challenge method. Used with the Identity Asserter for SSO when you have resources in a WebLogic Container. See Securing Applications with Oracle Platform Security Services.
LDAPScheme	Authentication Level: 2 Challenge Method: FORM Authentication Module: LDAP Context Type: customWar Context Value: /fusion_apps	Protects Access Manager-related resources (URLs) for most directory types based on a form challenge method.
	enableCoexistMode and disableCoexistMode in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
OAMAdminConsoleScheme	Authentication Level: 2 Challenge Method: FORM Authentication Module: LDAP Context Type: default Context Value: /oam	Authentication scheme for Oracle Access Management Console.
OIFScheme Only for Oracle Identity Federation 11.1.1. For Identity Federation 11.1.2, use FederationScheme.	Authentication Level: 2 Challenge Method: DAP Authentication Module: DAP Context Type: External	This scheme delegates authentication to OIF, after which, Oracle Identity Federation sends back a token that is asserted by the OAM Server. The Delegated Authentication Protocol (DAP) challenge method is used to delegate authentication to a third-party (OIF in this case). Challenge Parameters: TAPPartnerId=OIFDAPPartner See Also: "Challenge Parameters for Authentication Schemes".
PasswordPolicyValidationScheme	Authentication Level: 2 Challenge Method: FORM Authentication Module: Password Policy Validation Module Context: External	Enables password policy evaluation.
TAPResponseOnlyScheme	Authentication Level: 2 Challenge Method: DAP Authentication Module: DAP
		From the IAM Suite Application Domain, Protected Higher Level Policy, remove IAMSuiteAgent:/oamTAPAuthenticate. Create a new Authentication Policy in the IAM Suite Application Domain, that uses LDAPScheme. Protect IAMSuiteAgent:/oamTAPAuthenticate using the newly created policy. Challenge Parameters: TAPPartnerId=TAPPartnerName
X509Scheme	Authentication Level: 5 Challenge Method: X509 Authentication Module: X509	This authentication scheme is a certificate-based user identification method. To use this method, a certificate must be installed on the user's browser and the Web server must be SSL-enabled. Note: This scheme relies on SSL to deliver the use's X.509 certificate to the OAM Server.

22.9.1.2 Credential Challenge Methods

Authentication involves determining what credentials a user must supply when requesting access to a resource, gathering credentials over HTTP, and returning an HTTP response that is based on the results of credential validation.

Access Manager provides the following credential challenge methods for use in an authentication scheme:

• FORM

• BASIC

• X509

• WNA

• NONE

• DAP

FORM

This authentication challenge uses an HTML form with one or more text input fields for user credentials. In a typical form-based challenge, users enter a user name and password in two text boxes on the form. The most common credential choices are user name and password; however, you can use any user attributes: for example, user name, password, and domain.

A Submit button posts the content of the form. When the user clicks the Submit button, the form data is posted to the Web server. Upon validation of the user credentials collected in the form, the user is authenticated.

Note:

This challenge method relies on an LDAP Authentication Module and the user identity store associated with that module.

You might want to use form-based authentication challenge for reasons such as:

• A consistent user experience: Using form-based login and a standardized logout means that the user experience for login and logout features will be consistent across browsers.

• A Custom Form: You can apply your organization's look and feel in the authentication process.

  For example, a custom form can include a company logo and a welcome message instead of the standard user name and password window used in Basic authentication.

• Additional Information: You can gather additional information at the time of login.

• Additional Functionality: You can provide additional functionality with the login procedure, such as a link to a page for lost password management.

BASIC

This built-in Web server challenge mechanism requires a user to enter her login ID and password. The credentials supplied are compared to the user's definition in the LDAP directory server. Thus, a Basic challenge relies on the LDAP Authentication Module and user identity store associated with that module.

Note:

If a URL is protected by Access Manager using Basic Authentication with OID configured as the identity store, OID defined users can not log in. To resolve this, add the following line before the closing </security-configuration> tag in the config.xml file.

<enforce-valid-basic-auth-credentials>false
   </enforce-valid-basic-auth-credentials>

X509

With the X509 certificate challenge method, a user's browser must supply an X.509 digital certificate over SSL to the OAM Server through the Agent to perform authentication.

Note:

X509 is the challenge method for the X509Scheme. The user's organization can determine how to obtain a certificate.

The X.509 client certificate must be verified against the trusted CAs in the keystore used by OAM Proxy and OAM Servers to ensure the validity of X.509 Client certificate for authentication.

The following attributes of the X.509 certificate can be validated against the user identity store associated with Access Manager:

• SubjectDN

• SubjectUniqueID

• Mail

• CN

To acquire the user entry, the X509 Authentication Module takes the attribute name of the X.509 certificate to be validated and the LDAP attribute against which the search will be launched. The expected result is the single user entry matching the criteria. If the search returns no user entry, or more than one entry, authentication fails. Authentication scheme parameters are located in oam-policy.xml.

Note:

For X509 authentication, Administrators must configure the Oracle HTTP Server as a reverse proxy (or a server with the wl-proxy plug-in). The Oracle HTTP Server must be configured in two way SSL Mode to acquire X.509 certificate for authentication. Oracle HTTP Server can also be configured for CRL verification.

The online certificate status protocol (OCSP) capabilities are also provided. Any certificate passed for X.509 certificate-based authentication is validated using an OCSP request. Administrators can configure the system to communicate with one or more OCSP servers to retrieve the certificate status.

The X509 Authentication Module configuration for the OCSP responder URL indicates whether OCSP validation is to be done. The value, if specified, indicates the URL for validation of the X.509 client certificate using OCSP. No value indicates no OCSP validation.

WNA

Uses Windows Native Authentication with Active Directory, and the Kerberos Authentication Module.

Note:

The KerbScheme relies on the WNA challenge method and Kerberos Authentication Module.

See Also:

Configuring Access Manager for Windows Native Authentication for details about integration with Windows Native Authentication

NONE

The challenge method of None means that users are not challenged and do not need to enter their credentials. This is used in the AnonymousScheme authentication scheme, which allows users to access Access Manager-specific URLs that you do not want to protect.

DAP

The Delegated Authentication Protocol (DAP) challenge method is required for OIFScheme (Oracle Identity Federation 11.1.1 integration) with the DAP authentication module and external context type (Table 22-22). The DAP challenge mechanism indicates that Access Manager does an assertion of the token that it receives, which differs from the standard challenge "FORM" mechanism with the external option.

DAPModule is an assertion module, though it is specialized for this one application and does not appear in the list of Authentication Modules in the Oracle Access Management Console.

The DAP challenge mechanism delegates authentication to a third party (Identity Federation in this case). The challenge_url points to the Identity Federation Server URL. When a resource is protected by this scheme, the OAM Server redirects to the Identity Federation Server URL for credential collection. OAM Server does not perform the credential collection or validation in this case. Identity Federation collects the credentials, authenticates the user against its identity store and returns an assertion token to the OAM Server consisting of the username. Access Manager receives and decrypts this token, checks whether the user is a valid user in the default identity store for Oracle Access Management. If the user is valid, Access Manager gives access to the resource.

The DAPToken is encrypted and decrypted with a key that is shared between Access Manager and Identity Federation. The DAPToken is built from the Access Manager side.

The Identity Federation Administration EM Console provides a way to generate the keystore containing the encryption keys that will be used to secure communications between the Access Manager and Identity Federation. Access Manager provides a WLST command (registerOIFDAPPartner), that takes the keystore location generated by the Identity Federation store and retrieves the keys and stores it on the Identity Federation side.

22.9.1.3 Challenge Parameters for Authentication Schemes

Challenge parameters are short text strings consumed and interpreted by Webgates and Credential Collector modules to operate in the manner indicated by those values.

The syntax for specifying any challenge parameter is:

<parmatername>=<value>

This syntax is not specific to any Webgate release. Authentication schemes are independent of Webgate release.

Table 22-24 identifies the pre-configured schemes with challenge parameters.

Table 22-24 Challenge Parameters in Pre-configured Schemes

Pre-configured Schemes	Challenge Parameter
BasicSessionlessScheme	CookieLessMode=true Primarily used for clients that do not support URL redirect or cookies.
FederationMTScheme	initial_command=NONE Primarily used for Fusion Applications that support multiple factor authentication. is_rsa=true Used with RSA multi-step authentication, as described in Integrating RSA SecurID Authentication with Access Manager and Process Overview: Multi-Step AuthenticationDeveloping Applications with Oracle Access Management.
FederationScheme For Identity Federation 11.1.2.only. Use OIFScheme for Oracle Identify Federation 11.1.1.	Primarily used for clients that do not support URL redirect or cookies. Context Value: /fusion_apps Challenge Parameters: initial_command=NONE is_rsa=true Primarily used for clients that do not support URL redirect or cookies.
OIFScheme For Oracle Identify Federation 11.1.1 only. Use FederationScheme for Identity Federation 11.1.2.	TAPPartnerId=OIFDAPPartner This scheme delegates authentication to Oracle Identity Federation 11.1.1, after which, Federation sends back a token that is asserted by the OAM Server.
TapScheme	TAPPartnerId=TAPPartnerName

An authentication scheme can collect context-specific information before submitting the request to the Access Server. Context-specific information can be in the form of an external call for information. Table 22-25 lists user-defined challenge parameters you can use in Authentication Schemes.

Table 22-25 User-Defined Challenge Parameters for Authentication Schemes

Challenge Parameter	Definition
initial_command=NONE	Required to enable the plug-in to indicate which credentials are to be collected. For example, for Form-based authentication, the framework typically expects to collect "username" and "password" (submitted from the login page). However, you might want credentials from different fields of the login page; "form_username" and "form_password" for example. Setting this challenge parameter shifts initial control from the login page to the plug-in, which decides the parameters to collect from the login page then appropriately forwards or redirects to the page. Default: blank (not set)
action=	The actions parameter identifies the URL to which the HTML form is posting when you do not want to use the hard coded ECC default /oam/server/auth_cred_submit. Note: ECC does not use the action= parameter. When the action= challenge parameter is not specified, both the DCC and ECC use the default: /oam/server/auth_cred_submit. See Also: "Configuring the PasswordPolicyValidationScheme"
creds= DCC Only	Supported by the detached credential collector (DCC) only. In the following 11g example, username and password are the names of relevant fields in the login form: creds=username password NOTE: Format of this challenge parameter has changed since the 10g release. The Web server source (server parameter) takes precedence over other sources. This prevents the request data, which is under control of the user, from overriding Web server data. For example, a remote_user cookie sent from a user will not override a remote_user variable set by the Web server Generally, when the user submits a login form that is protected by an authentication scheme with a Form-based challenge method, the DCC processes the credentials that were specified with this creds= parameter. For forms using METHOD=POST processing, the browser sends a POST request to the Web server with the credential data from the form in the body of the request. If the form uses METHOD=GET, the browser sends a GET request with query string parameters with the same names as those specified on the creds parameter. Oracle recommends that you use POST processing, if possible. Note: You can specify the creds parameter with the other types of challenge methods. For a plug-in to make use of the creds parameter, you specify what is passed in the obMap credentials parameter of the ObUserSession object, as described in the Developing Applications with Oracle Access Management. See Also: "Configuring the PasswordPolicyValidationScheme"
extracreds= DCC Only	Supported by the DCC only. Specifies optional parameters which, if present, are made available to the authentication plug-in for collection during each iteration of a multi-step authentication using the DCC. The extracreds parameter uses the same syntax as the creds parameter: extracreds= separated qualified or unqualified names [{any | cookie | header | server | query | post}:] <name>. However, the value any is used by extracreds only. For example: extracreds=[{any | cookie | header | server | query | post}:] <name> See Also: "Configuring the PasswordPolicyValidationScheme"
OverrideRetryLimit=0	The number of tries that can override the RetryLimit for login. The value must be a positive integer. A value of zero (0) disables this function. See Also: "Configuring the PasswordPolicyValidationScheme"
ChallengeRedirectMethod	Authentication POST data preservation parameter for both the embedded credential collector (ECC) and the detached credential collector (DCC). Value: GET|POST|DYNAMIC Note: Preference is given first to the Authentication Scheme containing this parameter; second to the Webgate providing this user defined parameter. Otherwise, default behavior is Dynamic. See Also: "Configuring Authentication POST Data Handling" Table 15-2
MaxPreservedPostDataBytes	Configure this Authentication Scheme challenge parameter (or user-defined Webgate parameter) for authentication POST-data preservation. Default: 8192 bytes Note: Preference is given first to the Authentication Scheme containing this parameter; second to the Webgate providing this user-defined parameter. Otherwise, default behavior is 8192 bytes. This parameter defines the maximum length of POST data that Webgate can preserve. If the size of inbound raw user POST data (or encrypted post data after processing), crosses this limit, POST data is dropped and the existing authentication flow continues. The event is logged as usual. See Also: "Configuring Authentication POST Data Handling" Table 15-2
MaxPostDataBytes= DCC Only	Configure this Authentication Scheme challenge parameter to restrict the maximum number of bytes of POST data that is submitted as user credentials and sent to the OAM Server. Configure this challenge parameter for POST-data preservation by the DCC only to limit the maximum size of the POST data that can be posted as credentials on the form and sent to the OAM Server. DCC compares the value of the content-length header with the limit set. Default: 8192 bytes This challenge parameter requires a positive integer value. See Also: Table 15-2 "Configuring the PasswordPolicyValidationScheme" "Configuring Authentication POST Data Handling"
ssoCookie=	Controls the OAMAuthnCookie cookie, as described in "Configuring Challenge Parameters for Encrypted Cookies". Default: ssoCookie=httponly ssoCookie=Secure Disable either setting: ssoCookie=disablehttponly ssoCookie=disableSecure Note: These parameters are configured differently depending on your credential collector configuration. For detached credential collector-enabled OAM Webgates, set these parameters directly in the agent registration page. For non-DCC agents (Resource Webgates), these parameters are configured through user-defined challenge parameters in authentication schemes. See Also: Table 22-32
miscCookies=	Controls other miscellaneous Access Manager internal cookies. By default, httponly is enabled for all other (miscellaneous) cookies. Default: miscCookies=httponly miscCookies=Secure Disable either setting: miscCookies=disablehttponly miscCookies=disableSecure Note: These parameters are configured differently depending on your credential collector configuration. For detached credential collector-enabled Webgates, set these parameters directly in the agent registration page. For non-DCC agents (Resource Webgates), these parameters are configured through challenge parameters of the same name. See Also: Table 22-32 "Configuring the PasswordPolicyValidationScheme"
DCCCtxCookieMaxLength= DCC Only	Defines the maximum length of the DCC cookie. Default: 4096 See Also: TempStateMode in this table for more information.
TempStateMode=	Controls how the DCC stores the OAM Server state (cookie or form) as specified with the parameter's value: form: This is the default, and is required for retaining authentication POST data. The OAM Server state stored and passed through the form parameter "OAM_REQ", to avoid the case when the OAM Server configuration serverRequestCacheType=COOKIE, bloated server state causes DCCCtxCookie to explode beyond limit resulting in incorrect behavior. The cookie cache mode can be changed to FORM mode from default COOKIE mode. FORM mode works with long URLs. The only difference in behavior is for programmatic authentication, which requires a proper form Submit to pass the OAM_REQ parameter set to the form. Custom credential collection pages need to handle the OAM_REQ parameter that is submitted with the form. cookie: Adding this parameter and value stores the OAM Server state through part of the DCCCtxCookie (encdata=… svrctx=…). However, when serverRequestCacheType=COOKIE or =FORM, this could cause incorrect behavior if the resulting cookie length is beyond browser limit. Note: When serverRequestCacheType=COOKIE, Oracle recommends TempStateMode=form. When serverRequestCacheType=BASIC, either mode is fine. To update serverRequestCacheType, use the WLST command configRequestCacheType as described in the WLST Command Reference for WebLogic Server. Editing serverRequestCacheType is not supported using the Oracle Access Management Console. With ECC: The serverRequestCacheType dictates whether OAM Server stores its state in memory(BASIC) or not (FORM or COOKIE). serverRequestCacheType = COOKIE or FORM only makes difference when ECC is used. OAM Server stores its state in a request token, which ECC keeps in a cookie or hidden form field as specified with the parameter: serverRequestCacheType=COOKIE, for example. With DCC: There is no difference between serverRequestCacheType=COOKIE or FORM. TempStateMode controls how the DCC stores the OAM Server state (cookie or form) as specified with the parameter's value: TempStateMode=cookie, for example. With the DCC, POST data restoration with a Form-based Authentication Scheme requires the challenge parameter TempStateMode=form. See Also: Configuring OAM WebGate and Authentication Policy for DCC Table 15-2 "Table 22-34" "Configuring the PasswordPolicyValidationScheme"
allowedAccessGateList=	Authentication Scheme challenge parameter configured with SPACE separated list of WebGate IDs defining those WebGates that are allowed to enforce authentication by this scheme. For example: allowedAccessGateList=WebgateID1 WebgateID2
TunneledUrls	For OAM : TunneledUrls=/oam For OIF : TunneledUrls=/oamfed For OIG : TunneledUrls=/oam

22.9.2 Understanding Multi-Level and Step-Up Authentication

This section provides the following topics:

• About Multi-Level and Step-Up Authentication

• Detection of Insufficient Authentication Level by OAM Agent

• Changing Security Level of an Authentication Scheme during the Authentication Process

22.9.2.1 About Multi-Level and Step-Up Authentication

Every authentication scheme requires a strength level. The higher the number, the more secure the authentication mechanism; the lower the number, the less stringent the scheme.

For example:

• LDAPScheme authLevel=1

• KerbScheme authLevel=3

Note:

Multi-level authentication does not affect, negate, or alter X.509 certificate authentication.

SSO capability enables users to access more than one protected resource or application with a single sign in. After a successful user authentication at a specific level, the user can access one or more resources protected by one or more Application Domains. However, the authentication schemes used by the Application Domains must be at the same level (or lower). When a user accesses a resource protected with an authentication level that is greater than the level of his current SSO token, he is re-authenticated. In the step-up case, the user maintains his current level of access even if failing the challenge presented for the higher level. This is "additional authentication".

Note:

A user who is authenticated to access resources at level 3, is eligible to access resources protected at levels less than or equal to 3. However, if the user is authenticated to access resources at level 2 and then attempts to access resources protected by level 3, the user is asked to re-authenticate (this is known as step-up authentication).

Access Manager policies allow different resources of the same application to be protected with different authentication levels.

Agent types redirect the user to the OAM Server to authenticate again. The challenge is presented according to the level of the authentication scheme configured in the policy for the resource.

22.9.2.2 Changing Security Level of an Authentication Scheme during the Authentication Process

You can write a custom plug-in to change the security level of an authentication scheme during the authentication process.

In some cases, you may want to increase the security level of an authentication scheme during the authentication process depending on certain conditions. You may want the security level of an authentication scheme to depend on the application the user logged in from. For example, Active Directory and a reverse proxy are among the sources your users can log in from. During the authentication process, you may want to dynamically set one authentication security level to be used for users who log in from Active Directory and another security level to be used for users who log in from the reverse proxy.

Enable custom authentication plug-ins to set the authentication level as a plug-in response. Write a new custom authentication plug-in where a configurable authentication level is set as a plug-in step parameter in the plug-in response. For example, PLUGIN_AUTHN_LEVEL is configured in the plug-in response. It helps set the authentication level dynamically based on the authentication mechanism used.

To avoid any security implications resulting from the custom plug-in, use an optional authentication scheme challenge parameter, MAX_AUTHN_LEVEL. The value of MAX_AUTHN_LEVEL is the maximum authentication level that can be set by a custom authentication plug-in protecting resources. In the custom authentication scheme, this parameter is disabled by default. You need to set this mandatory parameter with a higher value than the PLUGIN_AUTHN_LEVEL for the plug-in to dynamically change the value of authentication level during the authentication process.

Write a custom authentication plug-in and configure KEY_AUTHN_LEVEL with a value lower than MAX_AUTHN_LEVEL. Create a custom authentication module that uses the new authentication plug-in and associate it with the Custom Authentication Scheme. Specify the Scheme in Authentication policy protecting the resource. When the user session is created, warning message about the plug-in overriding the maximum authentication value set by the administrator is logged by OAM server. When MAX_AUTHN_LEVEL is not configured or the plug-in tries to set value greater than MAX_AUTHN_LEVEL, the authentication succeeds with the authentication level set in the authentication scheme.

Following is the sample code to set authentication level as a plug-in response:

String stepName = context.getStringAttribute(PluginConstants.KEY_STEP_NAME);
String pluginLevel = PlugInUtil.getFlowParam(stepName, " PLUGIN_AUTH_LEVEL ", context);
PluginResponse rsp = new PluginResponse();
rsp.setName(PluginConstants.KEY_AUTHN_LEVEL);
rsp.setType(PluginAttributeContextType.LITERAL);
rsp.setValue(pluginLevel);
context.addResponse(rsp);

22.9.3 Creating an Authentication Scheme

Users with valid Administrator credentials can add a new authentication scheme for use in an Application Domain.

Prerequisites

The authentication module must be defined and ready to use as described in "Deploying and Managing Individual Plug-ins for Authentication".

See Also:

• "Authentication Schemes and Pages"

• Configuring OAM WebGate and Authentication Policy for DCC if needed

1. In the Oracle Access Management Console, click Application Security at the top of the window.

2. In the Application Security Console, click Authentication Schemes in the Access Manager section.

3. Click the Create Authentication Scheme.

4. Fill in the fresh Authentication Scheme page (Table 22-22) by supplying information based on your deployment:

   1. Name: LDAPSimpleFormScheme

   2. Authentication Level

   3. Challenge Method: FORM

   4. Challenge Redirect URL: http://CredentialCollectorhost:port

   5. Authentication Module: LDAP

   6. Challenge URL: /CredentialCollector/loginform...

   7. Challenge Parameters: Table 22-24, Table 22-25, Table 22-32

   8. Context Type

5. Click Apply to submit the new scheme (or close the page without applying changes).

6. Dismiss the Confirmation window.

7. Optional: Click the Set as Default button to automatically use this with new Application Domains, then close the Confirmation window.

8. Confirm the new scheme appears in the list of schemes (refresh if needed).

9. Proceed to "Defining Authentication Policies for Specific Resources".

22.9.4 Searching for an Authentication Scheme

Users with valid Administrator credentials can search for a specific authentication scheme.

See Also:

"SSO Agent Search Page"

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security Console, click Authentication Schemes in the Access Manager section.
3. In the Name field, enter the target scheme name (with or without wild card *). For example:

   OA*
   

4. Click the Search button to initiate the search.
5. Click the Search Results tab to display the results table, and then:

   • Edit: Click the Edit button in the tool bar to display the configuration page.

   • Delete: Click the Delete button in the tool bar to remove the instance; confirm removal in the Confirmation window.

   • Detach: Click Detach in the tool bar to expand the table to a full page.

   • View: Select a View menu item to alter the appearance of the results table.

22.9.5 Viewing, Editing, or Deleting an Authentication Scheme

Users with valid Administrator credentials can view or modify an existing authentication scheme.

Note:

During a delete operation, if the Authentication Scheme is associated with any authentication policy, she is prompted with association details. Without policy associations, the scheme is deleted.

See Also:

• "Authentication Schemes and Pages"

• "Configuring the PasswordPolicyValidationScheme"

1. Search for the target scheme, as described in the previous section.

2. In the list of search results, select the target scheme and click Edit.

3. Edit:

   1. On the Authentication Scheme page, modify values for your environment (Table 22-22).

   2. Click Apply to submit the changes (or close the page without applying changes).

   3. Dismiss the Confirmation window.

4. Set as Default: Click the Set as Default button to automatically use this scheme when creating policies in fresh Application Domains, then close the Confirmation window.

5. Delete:

   1. Review any Application Domain using this authentication scheme and assign a different scheme.

   2. Review the Authentication Scheme page to confirm this is the scheme to remove, then close the page.

   3. In the navigation tree, click the name of the scheme and then click the Delete button in the tool bar.

   4. Confirm removal (or dismiss the Confirmation window).

22.10 Extending Authentication Schemes with Advanced Rules

Advanced Rules have been added to allow for extending an existing authentication policy.

Both Pre-Authentication and Post-Authentication rules can be applied although the following configurations are not supported by Post-Authentication Rules.

• Two or more resources front ended by the same OHS/WebGate and protected by the same Authentication Scheme.

• A Post-Authentication rule configured for one of the resources defined in step up authentication.

• A user accesses a resource for which no Post-Authentication rule is configured followed by a resource for which a Post-Authentication rule is configured for step up authentication. In this case, the Post-Authentication rule configured for the resource is not effective.

Note:

Advanced Rules are part of the Adaptive Authentication Service for which a license is required. See About Adaptive Authentication Service.

Advanced Rules contain Boolean expressions. If there is more than one triggered outcome to an Authentication Scheme, the lowest execution order outcome will be chosen as the final outcome. Table 22-26 documents the attributes that need be defined when creating an Advanced Rule.

Table 22-26 Advanced Rules Attributes

Name	Description
Name	AuthnRule name. Name has to be unique within the checkpoint
Description	Description of the rule
Execution Order	Order in which the outcome will be executed in cases of more than 1 outcome
Condition	Script; the user can configure condition based on the HTTP request header's availability and set the desired outcome
Outcome	ID of the Authentication Scheme to which the rule applies. Access / Deny. Note: If the Deny Access option is selected, an error message, The requested URL was not found, is displayed.

See the following sections for details.

• Advanced Rules Use Cases

• Context Data for Advanced Rules

22.10.1 Advanced Rules Use Cases

You can configure advance rules for certain scenarios.

For the following use cases, configure Advanced Rules:

• Non Browser Client - For user authentication, a form-based login page is presented through the browser for the user to complete. In some cases, a non-browser client (switches, routers and the like) might need to do basic authentication based on credentials passed via the request header. Non-browser client authentication can be configured as a pre-authentication Advanced Rule only. To support non-browser client authentication, configure the desired condition in an Authentication Rule (based on the HTTP request header's availability) and set the desired outcome.

• Windows Native Authentication Option - An Advanced Rule can be configured to allow for switching between Windows Native Authentication (WNA) and form-based user authentication depending on whether the user comes thru VPN or a corporate network.

• User Authentication Scheme Option - An Advanced Rule can be configured to allow administrator to choose the method of users authentication. The choice would be passed as stored in users attribute from custom LDAP attribute.

• Second Factor Authentication - An Advanced Rule can be configured to allow for Second Factor Authentication (SFA) based on defined user or request attributes. For details on SFA, see Introducing the Adaptive Authentication Service.

Table 22-27 contains examples of how the conditions might be configured in these Advanced Rules use cases.

Table 22-27 Sample Advanced Rules

Sample Rule	Sample Jython Script-based Condition	Notes
Switching authentication scheme based on private or public IP rule	location.clientIP.startswith('10.') or location.clientIP.startswith('172.16') or location.clientIP.startswith('192.168')	This rule can be used in Pre and Post authentication checkpoints
Black listed IP	location.clientIP in ['130.35.50.115', '130.35.50.112', '130.35.50.113']	This rule can be used in Pre and Post authentication checkpoints
Client Browser Type	request.userAgent.lower().find('firefox') > 0	This rule can be used in Pre and Post authentication checkpoints
Blocking access to user having user attribute 'description' equals 'test'	user.userMap['description'] == 'test'	This rule can be used only in Post authentication checkpoints
Non browser client	request.authorization.lower().startswith('basic')	This rule can be used only in Pre authentication checkpoints
Customer HTTP Header value	request.requestMap['param'] == 'test'	This rule can be used in Pre and Post authentication checkpoints
Switching authentication scheme based on IP address in range	location.isIPinRange('192.35.50.180','192.35.50.188')	This rule can be used in Pre and Post authentication checkpoints

22.10.2 Context Data for Advanced Rules

Before executing the Authentication Condition, the Access Manager server prepares a request context using the available data (to construct a Boolean expression based condition).

The following tables describe the various context data details.

• Table 22-28

• Table 22-29

• Table 22-30

• Table 22-31

Table 22-28 Request Context Data

Attribute Name	Description
requestMap	Map of all the request headers, parameters and post data values. This example can get the custom-header key from request header and compare it with value 'test'. request.requestMap['custom-header'].lower().find('test') > 0
resourceMap	Map of matched resource details
accept	Returns 'Accept' header value
acceptCharset	Returns 'Accept-Charset' header value
acceptEncoding	Returns 'Accept-Encoding' header value
acceptLanguage	Returns 'Accept-Language' header value
authorization	Returns 'Authorization' header value
connection	Returns 'Connection' header value
contentLength	Returns 'ContentLength' header value
cookie	Returns 'Cookie' header value
host	Returns 'Host' header value
ifModifiedSince	Returns 'ifModifiedSince' header value
pragma	Returns 'Pragma' header value
referer	Returns 'Referer' header value
userAgent	Returns 'UserAgent' header value
resourceHost	Returns matched Resource's Host value
resourcePost	Returns matched Resource's Port value
resourceOperation	Returns matched Resource's Operation value
resourceQueryString	Returns matched Resource's QueryString
resourceName	Returns matched Resource's name
resourceType	Returns matched Resource's Type
resourceURL	Returns matched Resource's URL; for example, if 'landingPage' is in request.resourceURL, condition will evaluate to true if resourceURL has landingPage in it.
isIPinRange('start IP' ,'end IP')	Evaluates to true if location.clientIP is in the specified range. Example: location.isIPinRange('192.35.50.180','192.35.50.188')

Table 22-29 Location Context Data

Attribute Name	Description
locationMap	Map of all the location data values; for example: location.locationMap['CLIENT_IP'] == '10.1.23.4'
clientIP	Returns client IP address; for example: location.clientIP.startswith('10.2')
proxyIP	Returns Proxy IP address

Table 22-30 Session Context Data

Attribute Name	Description
sessionMap	Map of all the session data values; for example: session.sessionMap['count'] > 2;
count	Returns number of sessions for the current user; for example:session.count > 2

Table 22-31 User Context Data

Attribute Name	Description
userMap	Map of all the user profile data; for example: user.userMap['email'] == '[e-mail]'

22.11 Configuring Challenge Parameters for Encrypted Cookies

OAM provides challenge parameters that you can use within any authentication scheme to control flags of the encrypted cookies.

• Challenge Parameters for Encrypted Cookies

• Configuring Challenge Parameters for Security of Encrypted Cookies

• Setting Challenge Parameters for Persistence of Encrypted Cookies

22.11.1 Challenge Parameters for Encrypted Cookies

In addition to the OAM Server cookie (OAM_ID), Access Manager implements single sign-on through an encrypted cookie

• OAM Webgate, One per agent: OAMAuthnCookie_<host:port>_<random number> set by Webgate using the authentication token received from the OAM Server after successful authentication

  Note: A valid OAMAuthnCookie is required for a session.

Access Manager provides the ssoCookie challenge parameter that you can use within any authentication scheme to control how Webgates set the flags of the encrypted cookie. For example:

• Securing Encrypted Cookie: Ensures that the encrypted cookie is sent only over an SSL connection and prevents the encrypted cookie from being sent back to a non-secure Web server.

• Persisting Encrypted Cookie: Allows the user to log in for a time period rather than a single session. Persistent cookie functionality works with Internet Explorer and Mozilla browsers.

Note:

The value of the challenge parameter is note case sensitive. Syntax is the same regardless of your Webgate release. A single value is specified after the equal sign (=):

ssoCookie=value

Multiple values must be separated by a semicolon (;). For example:

ssoCookie=value1;value2;...

• For detached credential collector-enabled Webgates, set these parameters directly in the agent registration page (Table 15-2).

• For non-DCC agents (Resource Webgates), these parameters are configured through Authentication Scheme challenge parameters (Table 22-32).

Table 22-32 describes specific challenge parameters that control how Webgates set encrypted cookie flags for single sign-on.

Table 22-32 Challenge Parameters for 11g Encrypted Cookies

OAM Webgate Challenge Parameter Syntax for Encrypted Cookies	Description
ssoCookie=	Parameter that controls flags for the SSO cookie OAMAuthnCookie.
miscCookies=	Parameter that controls flags for all other Access Manager encrypted cookies.
Secure	Ensures that the encrypted cookie is sent only when the resource is accessed through HTTPS. A secure cookie is required only when a browser is visiting a server using HTTPS. ssoCookie=Secure miscCookies=Secure
disableSecure	Explicitly disables Secure cookies. ssoCookie=disableSecure miscCookies=disableSecure
httponly	Enabled by default with OAM Webgate SSO OAMAuthnCookie and miscellaneous cookies. ssoCookie=httponly miscCookies=httponly
disablehttponly	Explicitly disables httponly functionality, making the encrypted cookies accessible to client-side scripts. ssoCookie=disablehttponly miscCookies=disablehttponly
ssoCookie=max-age=time-in-seconds	Creates a persistent cookie in browsers, rather than one that lasts for a single session, and specifies the time interval in-seconds when the cookie expires. For example, to set the cookie to expire in 30 days (2592000 seconds): max-age=2592000

22.11.2 Configuring Challenge Parameters for Security of Encrypted Cookies

The challenge parameter is not case sensitive.

See Also:

"Creating an Authentication Scheme"

1. Create an authentication scheme.
2. In the Challenge Parameter field, enter your specification for the desired encrypted cookies (Table 22-32).
3. Confirm that the OAM Servers and clients (OAM Agents) are communicating securely across the Oracle Access Protocol channel, as described in Securing Communication.

22.11.3 Setting Challenge Parameters for Persistence of Encrypted Cookies

The challenge parameter is not case sensitive.

See Also:

"Creating an Authentication Scheme"

1. Define an authentication scheme.
2. In the challenge parameter for this scheme, add the following (Table 22-32):

   WebGate ssoCookie=max-age=time-in-seconds

22.12 Configuring Authentication POST Data Handling

Post data preservation and restoration functions apply to both credential collectors (ECC or DCC).

This section provides the following topics:

• Authentication POST Data Preservation and Restoration

• Authentication POST Data Handling

• Configuring Authentication POST Data Handling

• Testing POST Data Handling Configuration

22.12.1 Authentication POST Data Preservation and Restoration

POST data preservation and restoration functions come into play when an application has a form wherein the user has entered a credential (or other data) but the session has expired, an idle session timeout has occurred, or the token validity period has ended by the time the user submits the form. If this scenario occurs, the user is presented with a fresh login form (depending on the authentication scheme) unless POST data is preserved and restored.

Administrators can configure the Resource Webgate to perform POST data preservation when the expired user and newly authenticated user are the same. Table 22-33 describes Resource Webgate support and behavior for post data.

Note:

Authentication POST data preservation and restoration is not supported when Access Manager performs authentication through custom agents.

Table 22-33 Resource Webgate Support of POST Data Preservation and Restoration

Resource Webgate	Description
Supports Authentication Schemes	LDAP, Basic, Sessionless Basic, X509, WNA
Supports form encoding	with text/html, text/plain, multipart/form-data, and application/x-www-form-urlencoded type data posted by the application form.
Preserves	The encoding type of the data posted by the original application form, except the input field of file type.
Ensures	The downstream application sees the same post data that was posted by the original application form.
Constrains	The overall size of the inbound request data or the inbound front channel message. There shall be a configuration parameter to override the code default value. This shall be per application.
Maintains application data confidentiality and integrity	Neither the Resource Webgate nor credential collector will interpret, nor log, application post data. If, after expiration and during re-authentication, the user authenticates with different credentials, then the post data of the previous user is cleared by the Resource Webgate and not restored. However, Webgate will post to the downstream application URL that was posted by the original application form.
Ignores Preservation if ... Logs a Message when ... Performs Standard Authentication if ... Shows an Error when ...	Post data is larger than the configured or hard-coded limit, preservation is ignored. Post data is skipped because it is bigger than the allowed limit, a message is logged. Post data size is larger than the hard-coded limit (or the configured value), the standard authentication flow is used. Together, if both front channel message data and application post data are large an error occurs.

Credential Collector Support for POST Data Handling

• ECC and DCC

• Compatible with earlier 11g Webgates

• Supports post data preservation for Form based authentication scheme with the default login form provided out of the box.

• Preserves application post data during authentication processing by:

  • Challenging the user

  • Re-challenging the user if invalid credentials are provided

  Does not interpret application post data.

• Constrains the overall size of inbound front-channel messages using a configuration parameter to override the default value, per application.

• Logs a warning when post data is skipped because it is larger than the allowed limit.

• Does not preserve application post data when:

  • Authentication policy is configured with Success or Failure authentication URLs

  • Password management (password expiration and so on) is involved

  • Access Manager is used for performing authentication through custom agents.

• ECC Only

  • The embedded credential collector does not support POST data handling with the external login page.

• DCC Only

  • POST data is preserved through the HTTP header, and the amount of POST data that can be handled to 8192 characters.

  • POST data restoration with a Form-based Authentication Scheme requires the challenge parameter TempStateMode=form.

  • DCC does not support custom login pages.

  • DCC does not support POST data restoration during password management operations (password expiration, for instance) when the URL_ACTION in the password policy plug-in is set to anything other than FORWARD.

22.12.2 Authentication POST Data Handling

Authentication Schemes such as WNA, Basic and X509 are supporting POST Data Handling.

The following are the Authentication Schemes Supporting POST Data Handling:

• FORM challenge method, supported with the out of the box login page.

• WNA

• Basic

• Basic+Sessionless

• X509

• OIF

Table 22-34 summarizes complete configuration requirements for authentication POST data handling. All requirements described in Table 22-34 are supported end to end with the specified authentication schemes.

Table 22-34 Parameters Required for Authentication POST Data Handling

Parameter	Description
MaxPostDataBytes	Configure this Authentication Scheme challenge parameter for POST-data preservation used by the DCC only to limit the maximum size of the POST data that can be posted as on the login form. DCC compares the value of the content-length header with the limit set. Default: unlimited This Authentication Scheme challenge parameter requires a positive integer value that restricts the maximum number of bytes of POST data that is submitted as user credentials and sent to the OAM Server.
MaxPreservedPostDataBytes	Configure this Authentication Scheme challenge parameter (or user-defined Webgate parameter) for authentication POST-data preservation. Default: 8192 bytes Note: Preference is given first to the Authentication Scheme containing this parameter; second to the Webgate providing this user-defined parameter. Otherwise, default behavior is 8192 bytes. This parameter defines the maximum length of POST data that Webgate can preserve. If the size of inbound raw user POST data (or encrypted post data after processing), crosses this limit, POST data is dropped and the existing authentication flow continues. The event is logged as usual. See Also: "Configuring Authentication POST Data Handling" Table 15-2
TempStateMode=form DCC Only	With the DCC, a Form-based Authentication Scheme requires the challenge parameter TempStateMode=form for POST data restoration For Form authentication scheme, if this parameter is not defined, the value will be "form". See Also: "Configuring Authentication POST Data Handling" Table 15-2
ChallengeRedirectMaxMessageBytes	Configure this user-defined Webgate parameter to limit the size of the message data received as obrareq.cgi and obrar.cgi. Message data is comprised of query string length (if present) or POST data length (if POST data is present). If message size exceeds this limit, the message is not processed and the existing message is shown in the browser. The event is logged as usual. Default: 8192 bytes Notes: obrareq.cgi is the authentication request in the form of a query string redirected from Webgate to the credential collector (OAM Server or DCC). obrar.cgi is the authentication response string redirected from the credential collector (OAM Server or DCC) to Webgate. See Also: "Configuring Authentication POST Data Handling" Table 15-2
PostDataRestoration	Configure this user-defined Webgate parameter to initiate authentication POST-data preservation for the resource Webgate. This parameter requires a value of true or false. Default: false When set to true, Webgate initiates POST data preservation. See Also: "Configuring Authentication POST Data Handling" Table 15-2
serverRequestCacheType ECC Only	Configure this OAM parameter to define the mechanism used to remember the request context by the embedded credential collector (ECC). This OAM Server parameter in $DOMAIN_HOME/config/fmwconfig/oam-config.xml indicates mechanism to be used to remember the request context. Possible values are FORM, COOKIE, or CACHE. Default: COOKIE FORM is the required value for POST data preservation, Long URL handling and Form-based authentication schemes. See Also: TempStateMode in this table. "Configuring Authentication POST Data Handling"

22.12.3 Post Data Size Limits

Assuming the usual form data entered by users is about several kilobytes, putting a limit on data comsumption from the incoming request is a general requirement. The data transferred in the front channel protocol (either request or response) must also go through the size check.

Considering these situations:

• Limit the size of data passed to the OAM Server on the back channel using the maxpostdatabytes authentication challenge parameter

  In cases where the DCC is used, the maxpostdatabytes authentication challenge parameter performs this check on the overall POST data.

• Limit the size of the POST data from the end user application using MaxPreservedPostDataBytes authentication scheme challenge parameter.

  The MaxPreservedPostDataBytes authentication scheme challenge parameter handles this. Additionally, this can be set as a user-defined Webgate parameter.

• Limit size of the front channel payload on obrar.cgi or obrareq.cgi with a Webgate user-defined parameter ChallengeRedirectMaxMessageBytes.

22.12.4 Configuring Authentication POST Data Handling

Be sure to read all POST data topics in this section before attempting this procedure. There is no need to make any explicit change in your authentication scheme.

1. Configure the Authentication Scheme:

   1. Use the Oracle Access Management Console to create or find the desired scheme (Authentication POST Data Handling).

   2. On the Authentication Scheme page, modify values for POST data handling.

      This example uses the embedded credential collector (Table 22-22) and values for POST data handling (Table 22-25):

      • Name: DesiredScheme
      • Authentication Level 2
      • Challenge Method: Form
      • Challenge Redirect URL: /oam/server/
      • Authentication Module: LDAP
      • Challenge URL: /pages/login.jsp
      • Context Type: External
      • Challenge Parameters

      Authentication Scheme Challenge Parameters for Post Data with ECC	Authentication Scheme Challenge Parameters for Post Data with DCC
      MaxPreservedPostDataBytes=9000	MaxPreservedPostDataBytes=9000 TempStateMode=form

   3. Click Apply to submit the changes.

2. ECC: Configure serverRequestCacheType, the OAM parameter in oam-config.xml, if using ECC.

   1. Stop the managed server.

   2. Stop the administration server.

   3. Open oam-config.xml and modify the value of serverRequestCacheType.

      See Updating OAM Configuration.

   4. Restart the administration server.

   5. Restart the managed server.

3. Configure Webgate Parameters for POST data handling:

   1. From the System Configuration tab, Access Manager section, create or find the desired OAM Agent registration.

   2. On the agent registration page, submit values for POST data handling (Table 22-25):

      • Name: DesiredAgent
      • User-Defined Parameters

      User-Defined Webgate Post Data Parameters with ECC	User-Defined Webgate Post Data Parameters with DCC
      PostDataRestoration=true	PostDataRestoration=true

   3. Click Apply to submit the changes.

22.12.5 Testing POST Data Handling Configuration

The following actions can be performed in sequence to test your POST data handling configuration.

1. Complete all configurations as documented.
2. Develop a simple script to print the POST data and the URL protected by Webgate.
3. Use a browser to access the protected resource.
4. Provide credentials and establish SSO. Wait for the idle session timeout period.
5. With the same browser, use the form to post data to the same Webgate using the URL which can print the POST data. You will be redirected to credential collector.
6. Enter the same credentials previously used.

   From the HTTP headers you can see, after getting obrar.cgi from the credential collector, the protected resource Webgate will give a 200 response (previously it was 302) and the POST data can be printed by your script.

22.13 Long URL Handling During Authentication

Long URL handling applies to both credential collectors (ECC or DCC) and is a default operation.

22.13.1 About Long URLs and Authentication Handling

Authentication involves redirecting the user's request to a centralized component that performs authentication, known as a Credential Collector. The mechanism used to redirect user from the policy enforcement point (OAM Agent) to the Credential Collector, is a proprietary front channel protocol over HTTP. This protocol currently provides the context of the request and the authentication response on the query string. In situations where the URL of the requested page is larger, the overall context becomes larger and can go beyond the browser's permissible size. This is referred to as Long URL Handling.

By default, the Resource Webgate checks the payload size of the front channel protocol message to determine if it is larger than the coded limit. When long URL handling is explicitly enabled, the limit is ignored and has no impact.

The credential collector determines if the front channel response payload is to be sent as HTTP Post data when:

• The incoming request indicates that the agent is capable of handling HTTP POST or REDIRECT type of response

• The credential collector is configured to always send the payload as HTTP post data

• The credential collector is configured to always send the payload as a query string

If no explicit configuration is present, then if the payload size is greater than predefined limit, then it shall send payload as the HTTP post data. But if the payload size is lower than the predefined limit, then it shall send it on the query string.

Note:

If application post data is also preserved there is no impact.

Table 22-35 identifies Long URL handling functionality with both the ECC and DCC.

Table 22-35 ECC and DCC: Long URL Handling

ECC Long URL Handling	DCC Long URL Handling
ECC is compatible with all OAM Webgates.	Same as ECC.
N/A	Long URL handling is limited to the maximum allowed size of the DCCContextCookie. The DCC does not perform explicit long URL handling. There is no support to preserve the front channel payload on the form.

22.13.2 Configuration Requirements for Long URL Handling

The following are the Authentication Schemes Supporting Long URL Handling:

• FORM challenge method, supported with the out of the box login page.

• WNA

• Basic

• Basic+Sessionless

• X509

• OIF

Table 22-36 summarizes the parameters and complete configuration requirements for authentication Long URL handling. All requirements described in Table 22-36 are supported end to end with the specified authentication schemes.

Table 22-36 Parameters Required for Long URL Handling

Parameter	Description
ChallengeRedirectMethod	Configure this as either as an Authentication Scheme challenge parameter (or as a user-defined Webgate parameter) for POST-data preservation for both the embedded credential collector (ECC) and the detached credential collector (DCC). Note: Preference is given first to the Authentication Scheme containing this parameter; second to the Webgate providing this user-defined parameter. Otherwise, default behavior is Dynamic. Value: GET|POST|DYNAMIC Behavior when value is: POST: Webgate sends encquery as POST data and credential collectors send encreply as POST data. GET: Webgate sends encquery as query string and expects encreply as query string. DYNAMIC: Default behavior, based on the length of the encquery/encreply. Webgate/credential collector sends data either as a query string or as POST data. Code default maximum length is 2000 characters. See Also: "Configuring Authentication POST Data Handling" Table 15-2
ChallengeRedirectMaxMessageBytes	Configure this user-defined Webgate parameter to limit the size of the message data received as obrareq.cgi and obrar.cgi. Message data is comprised of query string length (if present) or POST data length (if POST data is present). If message size exceeds this limit, the message is not processed and the existing message is shown in the browser. The event is logged as usual. Default: 8192 bytes Notes: obrareq.cgi is the authentication request in the form of a query string redirected from Webgate to the credential collector (OAM server or DCC). obrar.cgi is the authentication response string redirected from the credential collector (OAM server or DCC) to Webgate. See Also: "Configuring Authentication POST Data Handling" Table 15-2
serverRequestCacheType ECC Only	Configure this OAM parameter to define the mechanism used to remember the request context by the embedded credential collector (ECC). This OAM Server parameter indicates mechanism to be used to remember the request context. Possible values are FORM, COOKIE, or CACHE. Default: COOKIE FORM is the required value for POST data preservation, Long URL handling and Form-based authentication schemes. See Also: TempStateMode in this table. "Configuring Authentication POST Data Handling"

Long URL handling is enabled by default. The Webgate/credential collector sends data either as a query string or a POST. The length of the querystring parameter sent with obrareq.cgi and obrar.cgi is 2000 characters maximum.

22.14 Using Application Initiated Authentication

Access Manager exposes a Reauthentication URL that applications may choose to invoke if the user is accessing a sensitive URL or operation. This re-authentication will be triggered irrespective of whether or not the user already has a valid session.

An application can trigger re-authentication by invoking the /oamreauthenticate URL at:

http://<ohs_host>:<ohs_port>/oamreauthenticate

Access Manager will expect the /oamreauthenticate to be registered and associated with an authentication policy. Re-authentication will be performed using the scheme associated with this policy. The re-authentication URL takes the redirection URL as a query parameter. After re-authentication is complete, Access Manager redirects the user to this URL. A request to re-authenticate the user might look like the following:

http://<host>:<port>/oamreauthenticate?
  redirect_url=http://<host>:<port>/<redirection_resource_url>

If the redirection URL is not specified, a 404 error code is returned. If the incorrect credentials are specified during re-authentication, the user will remain on the login page and, after the maximum retry limit, the user will be redirected to an appropriate error page. The following process is how to configure for application initiated authentication.

1. Create an http://<ohs_host>:<ohs_port>/oamreauthenticate resource and assign the desired authentication scheme to it.
2. In the redirect URL, set the appropriate responses to verify that re-authentication has been successful and to communicate back to the application about the re-authentication responses.

Access Manager sets the last re-authentication time as a "OAM_LAST_REAUTHENTICATION_TIME" header and this value is updated every time the user is re-authenticated.