8 Managing Policy Components

About Resource Types and Their Use

When adding a resource to an application domain, administrators must choose from a list of defined Resource Types. then enter a specific URL. For HTTP type resources, include a host identifier. For non-HTTP resource types, use the type name.

The default resource type, HTTP, is used with HTTP and HTTPS protocols. Operations associated with the HTTP resource type need not be defined by an administrator. Instead, policies developed and applied to the resource apply to all operations.

When adding an HTTP type resource to an application domain, administrators must choose from a list of existing host identifiers and add the resource URL.

Administrators can define a resource type for non-HTTP resources. Non-HTTP resource types have no associated host identifier. When adding non-HTTP resources to an application domain, administrators must enter the type name into the Resource URL field as a pointer. The name cannot match any host Identifier (and vice versa). This is not a relative HTTP URL.

For instance, a non-HTTP resource type named wl_authen is available to use with resources deployed in a WebLogic container. Resources of type wl_authen, require a custom AccessGate. The protected resource is accessed using its URL on the Oracle WebLogic Server.

About the Resource Type Page

In the OAM Administration Console, resource types are organized with other Components under the Policy Configuration tab, as shown in Figure 8-2. The navigation tree on the left shows two default resource types: HTTP for internet protocols and wl_authen for resources deployed in a WebLogic container.

Figure 8-2 The Default wl_authen Resource Type Definition

Description of "Figure 8-2 The Default wl_authen Resource Type Definition"

The HTTP resource type is used for Web applications protected by Oracle Access Manager 11g.

The wl_authen resource type is used for Fusion Middleware application scenarios in combination with in Oracle Access Manager 11g and one of the following OAM Authentication Provider configurations, as described in the Oracle Fusion Middleware Application Security Guide.

• Authenticator

• Identity Asserter with Oracle Web Services Manager

Table 8-1 describes the elements in the resource type definition.

Following topics describe how to create, modify, and delete a resource type.

Creating a Non-HTTP Resource Type

Users with valid OAM Administrator credentials can use the following procedure to create a new resource type definition for non-HTTP resources, as explained in "About Resource Types and Their Use".

In this case, there is no host identifier associated with the resource type. Instead, you must enter a name into the field. Any resource type with name other than HTTP is considered non-HTTP.

To create a non-HTTP resource type

1. From the Policy Configuration tab, navigation tree, Shared Components node, click Resource Type, then click the Create command button in the tool bar.

2. Fill in fields on the Resource Type page to identify this new type:

   1. Name:

   2. Description (optional)

3. Click Apply to submit the new resource type (or close the page without applying changes).

4. Close the Confirmation window.

5. Close the Resource Type page.

Searching for a Specific Resource Type

Users with valid OAM Administrator credentials can use the following procedure to locate a non-HTTP resource type.

To search for a resource type

1. Activate the Policy Configuration tab.

2. From the search type list, choose Resource Type to define your search.

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_resource_type
   

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.

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Deleting Resource Types

Users with valid OAM Administrator credentials can use the following procedure to remove a non-HTTP resource type only. A validation error occurs if you attempt to delete a resource type that is being used by a resource in an application domain.

Prerequisites

Each resource in an application domain has an assigned type. If you intend to delete the assigned resource type you must first modify the resource definition in an application domain that uses this resource type

To remove a resource type

1. From the Policy Configuration tab, Shared Components node, double-click the name of the Resource Type to confirm the definition, and then close the page.

2. Click the name in the navigation tree, click the Delete button in the tool bar, and confirm removal in the Confirmation window.

3. Confirm that the Resource Type is removed.

About Host Identifiers

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

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 OAM 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 OAM Administration 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, 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

About Virtual Web Hosting

A virtual host referees to 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 use 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.

To support virtual Web hosting, you must specify a specific value, described in the following paragraphs, in the Preferred HTTP host field of the OAM Agent registration. The following summarizes configuration for virtual servers:

• To support virtual hosts on most Web servers other than Apache-based servers, you must set the Preferred HTTP Host value to HOST_HTTP_HEADER.

  If you specify this value, when user's browser sends a request, the WebGate sets the value of the Preferred HTTP Host to the host value in the request. For example, suppose a user enters the string myweb2 in a URL:

  http://myweb2

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

• On Apache-based servers, for example, Apache, Apache 2, IBM HTTP Server, Oracle HTTP Server, and so on, the Preferred HTTP Host value must be set to SERVER_NAME.

About the Host Identifier Page

A host identifier is automatically created when an Agent (and application) are registered using either the OAM Administration 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 OAM Administration 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 8-3 illustrates a typical Host Identifier configuration page in the Administration Console, where you enter the canonical name for the host, and every other name by which the same host can be addressed by users.

Figure 8-3 Host Identifier Page

Table 8-2 describes the host identifier definition.

Creating a Host Identifier

Users with valid OAM Administrator credentials can use the following procedure to create a host identifier definition. This is needed if an application and resources were manually added to a host that has no mapped host identifier.

To manually create a Host Identifier

1. From the Policy Configuration tab, navigation tree, expand Shared Components.

2. Click Host Identifiers, then click the Create command button in the tool bar.

   Alternatively: Expand the Host Identifiers node, double-click the name of a definition to use as a template, then click the Duplicate button to create a copy named copyofname.

3. On the Host Identifier page, fill in the:

   1. Name

   2. Description

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

      Add: Click + and enter a new host name and port combination.

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

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

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

6. Close the Confirmation window, and confirm the new definition is listed in the navigation tree.

Searching for a Host Identifier Definition

Users with valid OAM Administrator credentials can perform the following task to search for a specific host identifier.

To search for a host identifier

1. Activate the Policy Configuration tab.

2. From the search type list, choose Host Identifiers to define your search.

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_host_identifier
   

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.

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Viewing or Editing a Host Identifier Definition

Users with valid OAM Administrator credentials can use the following procedure to 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

To view or modify a Host Identifier

1. From the Policy Configuration tab, navigation tree, expand:

   1. Shared Components node

   2. Host Identifiers node

2. Double-click the desired definition name.

3. View the Host Identifier page, and modify information as needed (see Table 8-2):

   1. Name

   2. Description

   3. Operations: Add to or remove host name and port variations in the Operations list.

      Click + to add a new host name and port combination.

      Click an existing host name and click the Delete button to remove it.

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

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

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

Deleting a Host Identifier Definition

Users with valid OAM Administrator credentials can use the following procedure to 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.

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

To delete a Host Identifier

1. From the Policy Configuration tab, navigation tree, expand the:

   1. Shared Components node

   2. Host Identifiers node

2. Optional: In the list, double-click the desired name to view the definition, and then close the page.

3. In the navigation tree, click the desired definition name.

4. Click the Delete button in the tool bar, and confirm removal in the Confirmation window.

5. Check the navigation tree to confirm that the definition was removed.

About Default Authentication Modules Pages

In the Oracle Access Manager Administration Console, pre-configured authentication modules are organized with other system-level components under the System Configuration tab.

Only the following pre-configured authentication module types are allowed in an authentication scheme. However, you can create new modules of an existing type to use in authentication schemes. For more information, see:

• Kerberos Authentication Module

• LDAP Authentication Modules

• X509 Authentication Module

Kerberos Authentication Module

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

Figure 8-4 Pre-configured Kerberos Authentication Module

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

Table 8-3 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).

LDAP Authentication Modules

The pre-configured LDAP authentication module is illustrated in Figure 8-4. Additional details follow the figure.

Figure 8-5 Pre-Configured LDAP Authentication Module

Table 8-4 describes the elements in an LDAP authentication module. The same elements are also used in LDAPNoPasswordAuthnModule.

Table 8-4 LDAP Authentication Module Definition

Element	Description
Name	A unique name for this module.
User Identity Store	The primary user identity store that contains the user credentials required for authentication by this module. The LDAP store must be registered with OAM 11g to appear in this list. See Also: "Managing User Identity Store and OAM Administrator Registrations".

X509 Authentication Module

Oracle Access Manager provides a pre-configured X509 authentication module as a default. Administrators can also create new X509 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.

Oracle 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 Oracle Access Manager, the computer hosting the OAM Administration 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 8-6 Pre-Configured X509 Authentication Module

Table 8-5 describes the requirements of the X509 authentication module.

Table 8-5 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 used. For example: cn.
X509 Cert Attribute	Defines the certificate attribute to be used to bind the public key. For example: SUBJECT.cn.
Cert Validation Enabled	Enables (or disables when not checked) X.509 Certificate validation.
OCSP Enabled	Enables (or disables when not checked) the Online Certificate Status Protocol. 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--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.
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.

Creating a New Authentication Module

Users with valid OAM Administrator credentials can use the following procedure to create a new authentication module of an existing type. You cannot duplicate a pre-configured module to use as a template.

To create a new authentication module

1. From System Configuration tab, navigation tree, expand the Authentication Modules node.

2. From the navigation tree, click the desired module type.

3. Click the Create button in the tool bar.

4. Add details for the new authentication module:

   • Kerberos Module: See Table 8-3

   • LDAP Module: See Table 8-4

   • X509 Module: See Table 8-5

5. Click Apply to submit the new definition and close the Confirmation window (or close the page without applying changes).

6. Check the navigation tree to confirm the entry, and then close the page when you finish.

7. Add the authentication module to one or more authentication schemes, as described in "Creating an Authentication Scheme".

Searching for a Specific Authentication Module

Users with valid OAM Administrator credentials can perform the following procedure to search for specific authentication module using the Administration Console.

Prerequisites

The authentication module must be registered in the Oracle Access Manager Administration Console.

To locate a specific authentication module

1. Activate the System Configuration tab.

2. From the search type list, choose one of the following module types to define your search, either:

   • LDAP Authentication Modules

   • X509 Authentication Modules

   • Kerberos Authentication Modules

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_authn_module
   

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.

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Viewing or Editing Authentication Modules

Users with valid OAM Administrator credentials can use the following procedure to 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.

To view or edit an authentication module

1. Change to another authentication module in each authentication scheme that references this module.

2. From the System Configuration tab, navigation tree, expand the:

   1. Authentication Modules node

   2. Expand the module type node

3. Double-click the desired module name to display the configuration.

4. Optional: Close the page if you were simply viewing it.

5. On the Authentication Modules page, modify information as needed:

   • Kerberos Module: See Table 8-3

   • LDAP Module: See Table 8-4

   • X509 Module: See Table 8-5

6. Click Apply to submit the changes and close the Confirmation window (or close the page without applying changes).

7. Add the updated authentication module to authentication schemes, as described in "Creating an Authentication Scheme".

Deleting an Authentication Module

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

Prerequisites

In each authentication scheme that references this module, specify another authentication module.

To delete an authentication module

1. In each authentication scheme that references this module, specify another authentication module.

2. From the System Configuration tab, navigation tree, expand the:

   1. Authentication Modules node

   2. Expand the module type node

3. Optional: Double-click the module name to display the configuration and then close the window.

4. Click the desired module name and then click the Delete button.

5. Confirm removal (or dismiss the confirmation window to retain the module).

About the Authentication Schemes Page

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 included a defined authentication module.

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 KerbScheme, the copy is named copyofKerbScheme.

All authentication schemes include the same elements with differing values. Figure 8-7 shows the default LDAPScheme page as an example. The Authentication Schemes navigation tree lists other default schemes that are delivered.

Figure 8-7 Default LDAPScheme Page

Table 8-6 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.

About Custom Login Pages

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

• Custom login pages require exactly two form fields (username and password). Oracle Access Manager supports authentication forms with two fields only.

• 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 Oracle 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

• About Challenge Methods

• About Authentication Modules

• About Multi-Level Authentication

Creating an Authentication Scheme

Users with valid OAM Administrator credentials can use the following procedure to add a new authentication scheme for use in an application domain.

Prerequisites

The authentication module must be defined and ready to use.

To create an authentication scheme

1. From the Policy Configuration tab, navigation tree, expand the Shared Components node.

2. Click the Authentication Schemes node, then click the Create button in the tool bar.

3. Fill in the fresh Authentication Scheme page, as described in Table 8-6:

   1. Name

   2. Description

   3. Authentication Level

   4. Default

   5. Challenge Method

   6. Challenge Redirect

   7. Authentication Module

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

5. Dismiss the Confirmation window.

6. Optional: Click the Set as Default button to automatically use this with new application domains, then close the Confirmation window.

7. In the navigation tree, confirm the new scheme is listed, and then close the page

Searching for a Authentication Scheme

Users with valid OAM Administrator credentials can perform the following task to search for a specific authentication scheme.

To search for an authentication scheme

1. Activate the Policy Configuration tab.

2. From the search type list, choose Authentication Schemes to define your search.

3. In the text field, enter the exact name of the instance you want to find. For example:

   my_AuthnScheme
   

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.

6. Click the Browse tab to return to the navigation tree when you finish with the Search results.

Viewing or Editing a Authentication Scheme

Users with valid OAM Administrator credentials can use the following procedure to view or modify an existing authentication scheme.

Prerequisites

Review any application domain using this authentication scheme and specify a different scheme.

To view or modify an authentication scheme

1. From the Policy Configuration tab, navigation tree, expand the:

   1. Shared Components node

   2. Authentication Schemes node

2. Double-click the name of the scheme to change.

3. On the Authentication Scheme page, modify values as needed (Table 8-6).

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

5. Dismiss the Confirmation window.

6. Optional: Click the Set as Default button to automatically use this with new application domains, then close the Confirmation window.

7. Close the page when you finish.

Deleting an Authentication Scheme

Users with valid OAM Administrator credentials can use the following procedure to delete an existing authentication scheme.

Prerequisites

Review any application domain using this authentication scheme and specify a different scheme.

To delete an authentication scheme

1. From the Policy Configuration tab, navigation tree, expand the:

   1. Shared Components node

   2. Authentication Schemes node

2. Optional: Double-click the name of the scheme to confirm it is the one to delete, 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).

5. In the navigation tree, confirm the instance has been removed.