9 Configuring Single Sign-On in Oracle Fusion Middleware

The chapter outlines a set of recommended single sign-on solutions for Oracle Fusion Middleware. It also provides some general guidelines and common use cases for configuring authentication and single sign-on in the Oracle Fusion Middleware environment. This chapter includes the following major sections:

• Choosing the Right SSO Solution for Your Deployment

• Introduction to the OAM Authentication Provider

• Deploying the Oracle Access Manager 11g SSO Solution

• Deploying SSO Solutions with Oracle Access Manager 10g

• Deploying the OracleAS 10g Single Sign-On (OSSO) Solution

• Synchronizing the User and SSO Sessions: SSO Synchronization Filter

• Setting Up Debugging in the WebLogic Administration Console

9.1 Choosing the Right SSO Solution for Your Deployment

Oracle Platform Security Services comprise Oracle WebLogic Server's internal security framework. A WebLogic domain uses a separate software component called an Authentication Provider to store, transport, and provide access to security data. Authentication Providers can use different types of systems to store security data. The Authentication Provider that WebLogic Server installs uses an embedded LDAP server.

Oracle Fusion Middleware 11g supports new single sign-on solutions that applications can use to establish and enforce perimeter authentication:

• Oracle Access Manager solutions

• Oracle Single Sign-On (OSSO) solution

Customers must carefully choose the solution appropriate to their needs. Selecting the right SSO solution requires careful consideration and depends upon your requirements. This section outlines some general information and guidelines to help you choose the best solution for your needs.

Note:

Oracle recommends that you consider upgrading to Oracle Access Manager 11g Single Sign on solution to take advantage of additional functionality and architecture.

See Also:

Oracle Fusion Middleware Security Overview

• Development or Small Stand-Alone Environment: Oracle recommends a light-weight SSO solution when deployed applications are not integrated into an enterprise-level single sign-on framework.

  In such cases, a SAML-based solution that uses the Oracle WebLogic Server SAML Credential Mapping Provider is best. The embedded LDAP server is used as the default user repository. Alternatively, an LDAP Authenticator can be configured to leverage an external LDAP server as a user repository.

  See Also:

  "Configuring Single Sign-On with Web Browsers and HTTP Clients" in Oracle Fusion Middleware Securing Oracle WebLogic Server

• Enterprise-Level SSO with Oracle Fusion Middleware 11g: Oracle Access Manager supports:

  • A wide variety of LDAP vendors as the user and group repository and also works with Oracle Virtual Directory

  • Integration with non-Oracle application server vendors and Web Tier components on a large variety of OS platforms to provide a flexible solution.

  • Oracle Access Manager 11g supports out-of-the-box integration with Oracle Fusion Middleware applications

  Oracle Access Manager 11g (Release 1): Oracle recommends Oracle Access Manager 11g whether:

  • You are new to Oracle Fusion Middleware

  • You are considering a migration from OSSO

  • You are considering an enterprise-level SSO solution

  Oracle Access Manager 10g (10.1.4.3): You can continue using this when you have:

  • Existing Oracle Access Manager 10g implementations

  • An enterprise-level SSO solution

  Selecting the right Oracle Access Manager solution (11g versus 10g (10.1.4.3)) as your enterprise-level Single-Sign-on solution depends upon your requirements. Refer to product documentation in this chapter and in the respective administration guides to evaluate the release that best meets your overall requirements.

  See Also:

  "Introduction to the OAM Authentication Provider"

• Existing OSSO 10g Customers: Oracle Single Sign-On is part of the 10g Oracle Application Server suite. OSSO is an enterprise-level single sign-on solution that works with the OC4J application server in conjunction with Oracle Internet Directory and Oracle HTTP Server 11g.

  If OSSO is already in place as the enterprise solution for your existing Oracle deployment, Oracle Fusion Middleware continues to support the existing OSSO as a solution. However, Oracle recommends that you consider upgrading to Oracle Access Manager 11g Single Sign on solution, which is a strategic Oracle SSO solution. For more information when planning your upgrade, check the Lifetime Support Middleware Policy for the OSSO end of support dates at: http://www.oracle.com/support/lifetime-support-policy.html

  See Also:

  • "Introduction to the OAM Authentication Provider"

  • Oracle Fusion Middleware Upgrade Planning Guide

  • Oracle Fusion Middleware Upgrade Guide for Oracle Identity Management—For information about the types of Java EE environments available in 10g and instructions for upgrading those environments to Oracle Fusion Middleware 11g

• Portal, Forms, Reports, and Discoverer 11g: Oracle Access Manager 11g is certified with Oracle Portal, Forms, Reports, and Discover 11g. With Oracle classic components, Oracle Delegated Administration Services 10g is a required and important feature of the Oracle Identity Management infrastructure.

  See the Oracle Identity Management Guide to Delegated Administration in the Oracle Identity Management 10g (10.1.4.0.1) Online Documentation Library at:

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

  See the Oracle Fusion Middleware Supported System Configurations page for more details:

  http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
  

  See Also:

  The following topics in this chapter and other 11g manuals:

  • "Introduction to the OAM Authentication Provider"

  • "Deploying the OracleAS 10g Single Sign-On (OSSO) Solution"

  • Oracle Fusion Middleware Administrator's Guide for Oracle Portal

  • Oracle Fusion Middleware Forms Services Deployment Guide

  • Oracle Fusion Middleware Publishing Reports to the Web with Oracle Reports Services

  • Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Discoverer

• Oracle Access Manager Integration with OSSO: Oracle recommends Oracle Access Manager 11g as the recommended enterprise-wide solution. If applications (Oracle Portal for example) are deployed that previously required OracleAS Single Sign-On, you can delegate the authentication (from OSSO 10g) to Oracle Access Manager 11g. Oracle Internet Directory is needed for applications that require integrating Oracle Access Manager and OSSO.

  See Also:

  • "Introduction to the OAM Authentication Provider"

  • Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager for details about registering OSSO (mod_osso) Agents with Oracle Access Manager 11g to delegate authentication and for details about co-existence with Oracle Access Manager 11g during the OSSO 10g upgrade.

  • Oracle Fusion Middleware Upgrade Guide for Java EE—For information about the types of Java EE environments available in 10g and instructions for upgrading those environments to Oracle Fusion Middleware 11g

  • "Integrating with Oracle Application Servers" in the 10g (10.1.4.3) Oracle Access Manager Integration Guide.

• Windows Native Authentication for Microsoft Clients: OSSO and Oracle Access Manager 11g both support this integration. Oracle WebLogic Server can be configured to use the Simple and Protected Negotiate (SPNEGO) mechanism for authentication to provide Windows Native Authentication support.

  See Also:

  • The chapter on configuring Oracle Access Manager 11g to use Windows Native Authentication for Microsoft Clients in the Oracle Fusion Middleware Integration Guide for Oracle Access Manager

  • "Configuring Single Sign-On with Microsoft Clients" in Oracle Fusion Middleware Securing Oracle WebLogic Server

9.2 Introduction to the OAM Authentication Provider

Unless explicitly stated, information here applies equally to both Oracle Access Manager 11g and 10g deployments.

The Oracle Access Manager Authentication Provider is one of several Providers that operate with Oracle WebLogic Server. The Oracle Access Manager Authentication Provider does not require the entire Oracle WebLogic Suite nor Oracle Java Required Files (JRF) to operate with Oracle Access Manager 11g or 10g.

In a WebLogic Server domain where JRF is installed, the JRF template is present as part of the domain in an Oracle Fusion Middleware product. In this case, the OAM Identity Asserter and OAM Authentication Provider are automatically available for configuration. If JRF is not installed in your WebLogic domain, you must add the OAMAuthnProvider.jar to a specific location in your domain as described later.

Note:

The JRF template is present as part of the domain in an Oracle Fusion Middleware product.

You can use the Authentication Provider when you have:

• Applications that are (or will be) deployed in a WebLogic container outside the Identity Management domain

• WebGate is (or will be) deployed in front of the Authentication Provider

The Authentication Provider can be configured to provide either (or both) of the following functions for WebLogic users:

• Identity Asserter for Single Sign-on

• Authenticator

Identity Asserter for Single Sign-on Function

A Web-only applications implementation handles nearly all SSO use cases. The exception is when you have Oracle Web Services Manager protected Web services. In this case, there is no trusted WebGate. Instead the AccessGate provided with the Identity Asserter is contacted and interacts with the OAM 10g Access Server (or 11g OAM Server); all other processing is essentially the same.

The Identity Asserter only asserts the incoming identity (OAM_REMOTE_USER) and passes control to the configured Authentication Providers to continue with the rest of the authentication process (populating the subject with the right principals).

The Identity Asserter must be configured differently depending on which WebGate release (10g versus 11g) serves the request. For instance, when the application is protected by:

• 10g WebGate: The Identity Asserter is triggered for the token (ObSSOCookie)

  The Identity Asserter can also be triggered for the token OAM_REMOTE_USER which is present for applications protected by OAM 10g WebGate. See "About Using Identity Asserter for SSO with OAM 11g and 10g WebGates" for details.

• 11g WebGate: The Identity Asserter is triggered for the token (OAM_REMOTE_USER) and there is no ObSSOCookie.

Authenticator Function

The Authenticator does not provide single sign-on. The Authenticator requests credentials from the user based on the authentication method specified in the application configuration file, web.xml, not according to the Oracle Access Manager authentication scheme. However, an Oracle Access Manager authentication scheme is required for the application domain.

For more information, see the following topics:

• About Using the Identity Asserter for SSO with OAM 11g and 11g WebGates

• About Using Identity Asserter for SSO with OAM 11g and 10g WebGates

• About Using the Authenticator with Oracle Access Manager

• Applications for Oracle Access Manager SSO Scenarios and Solutions

9.2.1 About Using the Identity Asserter for SSO with OAM 11g and 11g WebGates

This topic describes and illustrates the use of the Identity Asserter for single sign-on with Oracle Access Manager 11g and OAM 11g WebGates.

All requests are first routed to a reverse proxy Web server and requests are intercepted by WebGate. The user is challenged for credentials based on the authentication scheme that is configured within Oracle Access Manager 11g. Oracle recommends Form (form-based login) as the authentication scheme.

Note:

This chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs; the actual binary name is mod_wl_ohs.so. Examples show exact syntax for implementation.

When used with Oracle Access Manager 11g WebGate, the Identity Asserter for SSO relies on perimeter authentication performed by WebGate on the Web Tier. The Identity Asserter must be configured to use OAM_REMOTE_USER as the chosen Active Type to be triggered by the presence of the OAM_REMOTE_USER.

The Identity Asserter subsequently invokes any of the configured Authentication Providers (Login Modules) for constructing the Subject and populating it with the appropriate Principals.

Note:

The only difference between using the Identity Asserter for SSO with 11g WebGates versus 10g WebGates is the chosen active type.

Provider Chosen Active Types: OAM 11g and 11g WebGates

The Identity Asserter's Active Type configuration parameter lists two values under the Available UI section: ObSSOCookie and OAM_REMOTE_USER. One of the two must be selected as the "Chosen" type to trigger the Identity Asserter to the presence of the ObSSOCookie or OAM_REMOTE_USER.

Note:

With OAM 11g, the Identity Asserter must be configured with OAM_REMOTE_USER as the chosen Active Type. In contrast, OAM 10g uses ObSSOCookie.

OAM_REMOTE_USER header includes the uid of the logged in user. Configuring OAM_REMOTE_USER as the chosen active type for the Identity Asserter requires Oracle Access Manager policies that set OAM_REMOTE_USER as part of the authorization success response headers.

The high-level process once WebGate, using the configured authentication scheme, authenticates the user is listed here:

• After WebGate 11g sets OAMAuthnCookie, the OHS Web server mod_weblogic module forwards the request to Oracle WebLogic Server

• The configured IdentityAsserter is invoked by the presence of the OAM_REMOTE_USER header and subsequently asserts this

• After the assertion process, the Authentication Providers configured in the security realm are invoked to populate the 'Subject' with Principals (Users and Groups)

Figure 9-1 and the following overview describe processing between components when the Identity Asserter for single sign-on is used with Web-only applications. This implementation handles nearly all SSO use cases. Exception: Oracle Web Services Manager protected Web services. In this case, there is no trusted WebGate. Instead the AccessGate provided with the Identity Asserter is contacted and interacts with the 11g OAM Server; all other processing is essentially the same (see the dotted line in the diagram).

For more information, see "Oracle Access Manager Authentication Provider Parameter List".

Figure 9-1 Identity Asserter for SSO with Oracle Access Manager 11g and 11g WebGates

Process overview: Identity Asserter with OAM 11g, 11g WebGate, and Web-only applications

1. A user attempts to access an Oracle Access Manager 11g protected Web application that is deployed on the Oracle WebLogic Server.

2. WebGate 11g on a reverse proxy Web server intercepts the request and queries the 11g OAM Server to determine whether the requested resource is protected.

3. If the requested resource is protected, WebGate 11g challenges the user for credentials based on the type of Oracle Access Manager authentication scheme configured for the resource (Oracle recommends Form Login). The user presents credentials such as user name and password.

4. WebGate 11g forwards the authentication request to the 11g OAM Server.

5. OAM Server validates the user credentials against those stored in the primary user identity store and returns the response back to WebGate. Processing continues based on:

   • Successful Authentication: Processing continues with Step 6.

   • Authentication Not Successful: The login form appears asking the user for credentials again; no error is reported.

6. OAM Server 11g generates the session token and sends it to the WebGate:

   11g WebGate sets and returns OAMAuthn cookie.

   The Web server forwards this request to the proxy, which in turn forwards the request to the Oracle WebLogic Server using the mod_weblogic plug-in.

   mod_weblogic forwards requests as directed by its configuration.

7. WebLogic Server security service invokes the Oracle Access Manager Identity Asserter which is configured to accept the tokens of type "OAM_REMOTE_USER". The Identity Asserter initializes a CallbackHandler with the header. In addition, the Identity Asserter sets up NameCallback with the username for downstream LoginModules.

8. Oracle WebLogic Security service authorizes the user and allows access to the requested resource.

9. A response is sent back to the reverse proxy Web server.

10. A response is sent back to the browser.

9.2.2 About Using Identity Asserter for SSO with OAM 11g and 10g WebGates

This topic describes and illustrates the use of the Identity Asserter for single sign-on with Oracle Access Manager 11g and 10g WebGates. This is similar to processing that occurs with OAM 10g and 10g WebGates.

All requests are first routed to a reverse proxy Web Server; requests are intercepted by WebGate. The user is challenged for credentials based on the authentication scheme that is configured within Oracle Access Manager. Oracle recommends Form (form-based login) as the authentication scheme.

Note:

This chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs; the actual binary name is mod_wl_ohs.so. Examples show exact syntax for implementation.

When used with Oracle Access Manager 10g WebGate, the Identity Asserter for SSO relies on perimeter authentication performed by WebGate on the Web Tier. The Identity Asserter must be configured to use ObSSOCookie as the chosen Active Type to be triggered by the presence of the ObSSOCookie.

The Identity Asserter subsequently invokes any of the configured Authentication Providers (Login Modules) for constructing the Subject and populating it with the appropriate Principals.

Note:

The only difference between using the Identity Asserter for SSO with 10g WebGates versus 11g WebGates is the chosen active type, as described here.

Provider Chosen Active Types: OAM (10g or 11g) and 10g WebGates

The Identity Asserter's Active Type configuration parameter lists two values under the Available UI section: ObSSOCookie and OAM_REMOTE_USER. One of the two must be selected as the "Chosen" type to trigger the Identity Asserter to the presence of the ObSSOCookie or OAM_REMOTE_USER.

Note:

The Identity Asserter can be configured with OAM_REMOTE_USER as the chosen Active Type because the request coming into the WebLogic Server from a 10g WebGate most likely contains OAM_REMOTE_USER header.

OAM_REMOTE_USER header includes the uid of the logged in user. Configuring OAM_REMOTE_USER as the chosen active type for the Identity Asserter requires Oracle Access Manager policies that set OAM_REMOTE_USER as part of the authorization success response headers. For details, see Oracle Access Manager Authentication Provider Parameter List.

The high-level process once WebGate, using the configured authentication scheme, authenticates the user is listed here:

• After WebGate sets an ObSSOCookie, the OHS Web server mod_weblogic module forwards the request to Oracle WebLogic Server

• The configured Identity Asserter is invoked by the presence of the ObSSOCookie and subsequently asserts the OAM_REMOTE_USER header

• After the assertion process, the Authentication Providers configured in the security realm are invoked to populate the 'Subject' with Principals (Users and Groups)

Figure 9-2 illustrates the distribution of components and the flow of information when Oracle Access Manager Identity Asserter for single sign-on is configured with Oracle Fusion Middleware. A detailed description follows the figure.

Note:

In Oracle Access Manager 11g, the Access Server is known as the OAM Server. Otherwise, processing is the same for OAM 11g with 10g WebGates and OAM 10g with 10g WebGates.

Figure 9-2 Identity Asserter Single Sign-On Solution for Web Resources Only

Description of "Figure 9-2 Identity Asserter Single Sign-On Solution for Web Resources Only "

This implementation handles nearly all SSO use cases. Exception: Oracle Web Services Manager protected Web services. In this case, the AccessGate provided with the Identity Asserter is contacted and interacts with the Access Server (or 11g OAM Server); all other processing is essentially the same.

The following overview describes the processing that occurs between components when the Identity Asserter for single sign-on is used with Web-only applications and 10g WebGates.

Note:

Identity Asserter processing is the same whether the implementation relies on a trusted WebGate or the custom AccessGate provided in oamAuthnProvider.jar.

Process overview: Identity Asserter with 10g WebGate and Web-only applications

1. A user attempts to access an Oracle Access Manager protected Web application that is deployed on the Oracle WebLogic Server.

2. WebGate 10g on a reverse proxy Web server intercepts the request and queries the Oracle Access Manager Access Server (or 11g OAM Server) to check if the requested resource is protected.

3. If the requested resource is protected, WebGate challenges the user for credentials based on the type of Oracle Access Manager authentication scheme configured for the resource (Oracle recommends Form Login). The user presents credentials such as user name and password.

4. WebGate 10g forwards the authentication request to the Access Server (or 11g OAM Server).

5. Access Server (or 11g OAM Server) validates the user credentials against those stored in user directory and returns the response back to WebGate. Processing continues based on:

   • Successful Authentication: Processing continues with Step 6.

   • Authentication Not Successful: The login form appears asking the user for credentials again; no error is reported.

6. Access Server (or 11g OAM Server) generates the session token and sends it to the WebGate:

   10g WebGate sets the ObSSOCookie and value as that returned.

   11g WebGate sets and returns OAMAuthn_<Host:port> cookie.

   The Web server forwards this request to the proxy, which in turn forwards the request to the Oracle WebLogic Server using the mod_weblogic plug-in.

   mod_weblogic forwards requests as directed by its configuration.

7. WebLogic Server security service invokes the Oracle Access Manager Identity Asserter which is configured to accept the tokens of type "ObSSOCookie" or "OAMAuthn_<Host:port> cookie". The Identity Asserter initializes a CallbackHandler with the cookie. In addition, the Identity Asserter sets up NameCallback with the username for downstream LoginModules.

8. Oracle WebLogic Security service authorizes the user and allows access to the requested resource.

9. A response is sent back to the reverse proxy Web server.

10. A response is sent back to the browser.

See Also:

"Applications for Oracle Access Manager SSO Scenarios and Solutions"

9.2.3 About Using the Authenticator with Oracle Access Manager

This topic describes and illustrates use of the Authenticator configured to protect access to Web and non-Web resources with Oracle Access Manager.

Note:

Unless explicitly stated, information applies equally to Oracle Access Manager 11g and 10g.

The Authenticator relies on Oracle Access Manager authentication services to authenticate users who access applications deployed in WebLogic Server. Users are authenticated based on their credentials, such as a user name and password.

When a user attempts to access a protected resource, the Oracle WebLogic Server challenges the user for credentials according to the authentication method specified in the application's web.xml file. Oracle WebLogic Server then invokes the Authentication Provider, which passes the credentials to Oracle Access Manager Access Server for validation through the enterprise directory server.

Figure 9-3 illustrates the distribution of components and flow of information for Oracle Access Manager authentication for Web and non-Web resources. Details follow the figure. In this case, the Authenticator communicates with the 11g OAM Server (or the OAM 10g Access Server) through a custom AccessGate.

Figure 9-3 Authenticator for Web and non-Web Resources

Description of "Figure 9-3 Authenticator for Web and non-Web Resources"

Process overview: Authenticator for Web and non-Web Resources

1. A user attempts to access a J2EE application (secured with the authentication mechanism in the application's web.xml file) that is deployed on the Oracle WebLogic Server.

2. Oracle WebLogic Server intercepts the request.

3. Oracle Access Manager Authentication Provider LoginModule is invoked by the Oracle WebLogic security service. The LoginModule uses the OAP library to communicate with the 11g OAM Server (or 10g Access Server) and validate the user credentials.

   • If the user identity is authenticated successfully, WLSUserImpl and WLSGroupImpl principals are populated in the Subject.

   • If Oracle Access Manager LoginModule fails to authenticate the identity of the user, it returns a LoginException (authentication failure) and the user is not allowed to access the Oracle WebLogic resource.

4. Oracle Access Manager Authenticator supports Oracle WebLogic Server UserNameAssertion.

5. Oracle Access Manager Authenticator can be used with any Identity Asserter. In this case, the Oracle Access Manager Authenticator performs user name resolution and gets the roles and groups associated with the user name.

See Also:

• "Configuring the Authenticator for Oracle Access Manager 11g"

• "Configuring the Authenticator for Oracle Access Manager 10g" for set up details

9.2.4 Applications for Oracle Access Manager SSO Scenarios and Solutions

This section introduces choosing applications to use Oracle Access Manager and the Authentication Provider according to current application setup. Details are similar whether you plan to use Oracle Access Manager 11g or 10g with the Authentication Provider:

• Applications Using Oracle Access Manager for the First TIme

• Applications Migrating from Oracle Application Server to Oracle WebLogic Server

• Applications Using OAM Security Provider for WebLogic SSPI

9.2.4.1 Applications Using Oracle Access Manager for the First TIme

If your application is to use Oracle Access Manager Authentication Provider for the first time, proceed based on the functionality that you want to use:

• Identity Asserter for Single Sign-On: The Web-only applications implementation handles nearly all SSO use cases. See "Installing the Authentication Provider with Oracle Access Manager 11g".

  Oracle Web Services Manager-Protected Web Services: These require the AccessGate provided with the Identity Asserter to interact with the OAM Server. See "Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g".

• Authenticator: No single sign-on is provided. The Authenticator requests credentials from the user based on the authentication method specified in the application configuration file, web.xml. See "Configuring the Authenticator for Oracle Access Manager 11g".

9.2.4.2 Applications Migrating from Oracle Application Server to Oracle WebLogic Server

If your application has been deployed on the old Oracle Application Server (OC4J), you can perform a few steps to make the application use the Authentication provider with Oracle WebLogic Server, proceed as follows:

• Remove all OC4J-specific settings from the application configuration

• Identity Asserter for Single Sign-On: The Web-only applications implementation handles nearly all SSO use cases. See the appropriate topic for your environment:

  —OAM 11g: Configuring Identity Assertion for SSO with Oracle Access Manager 11g

  —OAM 10g: Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g

• Oracle Web Services Manager-Protected Web Services: Require the AccessGate provided with the Identity Asserter. See the appropriate topic for your environment:

  —OAM 11g: Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g

  —OAM 10g: Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g

• Authenticator: No single sign-on is provided. The Authenticator requests credentials from the user based on the authentication method specified in the application configuration file, web.xml. See the appropriate topic for your environment:

  —OAM 11g: Configuring the Authenticator for Oracle Access Manager 11g

  —OAM 10g: Configuring the Authenticator for Oracle Access Manager 10g

9.2.4.3 Applications Using OAM Security Provider for WebLogic SSPI

The Oracle Access Manager Security Provider for WebLogic SSPI provides authentication, authorization, and single sign-on across J2EE applications that are deployed in the WebLogic platform. The Security Provider for WebLogic SSPI enables WebLogic administrators to use Oracle Access Manager to control user access to business applications.

Note:

Security Provider for WebLogic SSPI is also known as "Security Provider" in the 10g (10.1.4.3) Oracle Access Manager Integration Guide.

The Oracle Access Manager Security Provider for WebLogic SSPI provides authentication to Oracle WebLogic Portal resources and supports single sign-on between Oracle Access Manager and Oracle WebLogic Portal Web applications. Apart from this, the Security Provider for WebLogic SSPI also offers user and group management functions.

The Oracle Access Manager Authentication Provider is more easily installed and configured than the Security Provider for WebLogic SSPI. The Authentication Provider offers authentication and single sign-on (SSO) services, and also works with all platforms supported by Oracle WebLogic Server.

If your application has been using the Oracle Access Manager Security Provider for WebLogic SSPI for only authentication and SSO, the deployment is a good candidate for the latest Authentication Provider. However, if your application relies on features other than those offered by the latest Oracle Access Manager Authentication Provider, you can continue to use the Oracle Access Manager 10g Security Provider for WebLogic SSPI.

Note:

WebLogic SSPI connector can be used with Oracle Access Manager 10g but is not supported with Oracle Access Manager 11g

See Also:

"Applications Using OAM Security Provider for WebLogic SSPI"

9.2.5 Implementation: Authentication Provider with OAM 11g versus OAM 10g

With a few differences, implementing solutions is similar whether you are using OAM 11g or OAM 10g to protect for applications in a WebLogic container.

Table 9-1 outlines the differences when deploying the Authentication Provider with OAM 11g versus OAM 10g. Topic headings are highlighted.

Table 9-1 Differences in Authentication Provider Implementation Tasks for OAM 11g versus OAM 10g

OAM 11g Implementation Details

OAM 10g Implementation Details

Included in the OAM 11g implementation are the following tasks, which are described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager: Installing the Authentication Provider with Oracle Access Manager 11g Reviewing Pre-Seeded OAM 11g Policies for Use by the OAM 10g AccessGate Provisioning a WebGate with Oracle Access Manager 11g Note: The OAM 11g remote registration tool automates provisioning WebGates and policies. For WebLogic Server resources, a wl_authen resource type is created by default. The remote registration tool is used for all OAM 11g scenarios. Configuring Identity Assertion for SSO with Oracle Access Manager 11g Configuring the Authenticator for Oracle Access Manager 11g Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g Configuring Centralized Log Out for Oracle Access Manager 11g

Tasks for implementing SSO solutions with OAM 10g are described in this chapter: Installing and Setting Up Authentication Providers for OAM 10g Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g Note: OAM 10g OAMCfgTool automates provisioning WebGates and policies. Install 10g WebGate: Oracle Access Manager Installation Guide. Configuring the Authenticator for Oracle Access Manager 10g requires manual policy domain creation Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

9.2.6 Requirements for Using the Authentication Provider with Oracle Access Manager

The required components and files for implementing the Authentication Provider are nearly identical whether you have OAM 11g or OAM 10g as the SSO solution. The few exceptions are noted in the following list of requirements:

• An enterprise directory server (Oracle Internet Directory or Oracle Sun One directory server) for Oracle Access Manager and Oracle WebLogic Server.

• Oracle WebLogic Server 10.3.1+ to be configured to use the Oracle Access Manager Authentication Provider as described later in this chapter.

• Optional: A Fusion Middleware product (Oracle Identity Manager, Oracle SOA Suite, or Oracle Web Center for example).

• Authentication Provider: For applications deployed in a WebLogic container, Oracle Access Manager JAR are WAR files are available when you install an Oracle Fusion Middleware product (Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter).

  Note:

  With a stand-alone Oracle WebLogic Server (no Fusion Middleware), you must obtain the Authentication Provider JAR and WAR files from Oracle Technology Network as described in Step 1 of procedures later in this chapter.

  • oamAuthnProvider.jar: Includes files for both the Oracle Access Manager Identity Asserter for single sign-on and the Authenticator for Oracle WebLogic Server 10.3.1+. A custom Oracle Access Manager AccessGate is also provided to process requests for Web and non-Web resources (non-HTTP) from users or applications.

  • oamauthenticationprovider.war: Restricts the list of providers that you see in the Oracle WebLogic Server Console to only those needed for use with Oracle Access Manager.

    When you deploy the extension, the WebLogic Administration Console creates an in-memory union of the files and directories in its WAR file with the files and directories in the extension WAR file. Once the extension is deployed, it is a full member of the WebLogic Administration Console: it is secured by the WebLogic Server security realm, it can navigate to other sections of the Administration Console, and when the extension modifies WebLogic Server resources, it participates in the change control process For more information, see the Oracle Fusion Middleware Extending the Administration Console for Oracle WebLogic Server.

  • Oracle Access Manager 11g: A remote registration command-line utility streamlines WebGate provisioning and creates a fresh application domain with security policies. Administrators can specify WebGate parameters and values using a template.

  • Oracle Access Manager 10g: The platform-agnostic OAMCfgTool and scripts (oamcfgtool.jar) automate creation of the Oracle Access Manager form-based authentication scheme, policy domain, access policies, and WebGate profile for the Identity Asserter for single sign-on. OAMCfgTool requires JRE 1.5 or 1.6.

• OHS 11g must be configured as a reverse proxy for the WebGate (required by the Oracle Access Manager Identity Asserter)

• Oracle Access Manager:

  OAM 11g: Deployed with initial configuration using the Oracle Fusion Middleware Configuration Wizard, as described in Oracle Fusion Middleware Installation Guide for Oracle Identity Management. See "Deploying the Oracle Access Manager 11g SSO Solution".

  OAM 10g: Installed with initial setup as described in Oracle Access Manager Installation Guide. See "Deploying SSO Solutions with Oracle Access Manager 10g".

• WebGate/AccessGate: Whether you need to provision a WebGate or an AccessGate with Oracle Access Manager depends on your use of the OAM Authentication Provider:

  Identity Asserter for Single Sign-On: Requires a separate WebGate for each application to define perimeter authentication.

  Authenticator (or Oracle Web Services Manager): Requires the custom 10g AccessGate that is available with the Authentication Provider.

9.3 Deploying the Oracle Access Manager 11g SSO Solution

This section introduces how to implement OAM 11g with the Authentication Provider when you have applications that are (or will be) deployed in a WebLogic container.

This section provides the following topics to help you implement OAM 11g SSO when you have applications deployed in a WebLogic container. Aside from these uniquely OAM 11g methods, implementing OAM solutions are the same whether you have OAM 11g or OAM 10g:

• Introduction to Oracle Access Manager 11g SSO

• Installing the Authentication Provider with Oracle Access Manager 11g

• Reviewing Pre-Seeded OAM 11g Policies for Use by the OAM 10g AccessGate

• Provisioning an OAM Agent with Oracle Access Manager 11g

• Configuring Identity Assertion for SSO with Oracle Access Manager 11g

• Configuring the Authenticator for Oracle Access Manager 11g

• Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g

• Configuring Centralized Log Out for Oracle Access Manager 11g

9.3.1 Introduction to Oracle Access Manager 11g SSO

Oracle Access Manager 11g is part of Oracle's enterprise class suite of security products. Intended for use in new and existing SSO deployments, Oracle Access Manager 11g provides a full range of Web perimeter security functions that include Web single sign-on; authentication and authorization; policy administration, and more.

Oracle Access Manager 11g single sign-on (SSO) and single log-out (SLO) supports a variety of application platforms including:

• SOA

• WebCenter

• Fusion Applications

Oracle Access Manager 11g supports integration with a variety of applications, as described in the Oracle Fusion Middleware Integration Guide for Oracle Access Manager.

• Oracle Identity Navigator

• Oracle Identity Federation

• Oracle Identity Manager

• Oracle Adaptive Access Manager

As described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager, Oracle Access Manager 11g differs from Oracle Access Manager 10g in that identity administration features have been transferred to Oracle Identity Manager 11g. This includes user self-service and self registration, workflow functionality, dynamic group management, and delegated identity administration.

Console Protection for Oracle Identity Management Applications

Oracle Access Manager 11g and other Oracle Identity Management applications are deployed in a WebLogic container. Individual administration consoles include Oracle Access Manager, Oracle Adaptive Access Manager, Oracle Identity Navigator, Oracle Identity Manager, Oracle WebLogic Server, and Oracle Authorization Policy Manager.

These are protected by default using pre-configured Authentication Providers in the WebLogic Administration Console and a pre-registered IDM Domain Agent with Oracle Access Manager 11g. OAM 11g SSO policies are pre-seeded. No further configuration is needed for the consoles.

Preview of OAM 11g Deployments

You can configure Oracle Access Manager in a new WebLogic administration domain or in an existing WebLogic administration domain using the Oracle Fusion Middleware Configuration Wizard.

See "Requirements for Using the Authentication Provider with Oracle Access Manager"

See Also:

Oracle Fusion Middleware Installation Guide for Oracle Identity Management

Oracle Access Manager 11g provides new server-side components that maintain backward compatibility with new or existing policy-enforcement agents. Dynamic Server-initiated updates are performed for any policy or configuration changes.

• OAM Administration Console (installed on WebLogic Administration Server) replaces the OAM 10g Policy Manager

• OAM Server (installed on a WebLogic Managed Sever) replaces the OAM 10g Access Server

Oracle Access Manager 11g provides single sign-on (SSO), authentication, authorization, and other services to registered Agents (in any combination) protecting resources:

• 11g WebGates

• 10g WebGates

• Java-based IDM Domain Agent

• OSSO Agents (10g mod_osso)

You can integrate with Oracle Access Manager 11g, any Web applications currently using Oracle ADF Security and the OPSS SSO Framework.

Only users with sufficient privileges can log in to the Oracle Access Manager Administration Console or use OAM administrative command-line tools. Your enterprise might require independent sets of administrators: one set of users responsible for OAM administration and a different set for WebLogic administration. For more information, see "Defining a New OAM Administrator Role" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Overview of OAM 11g

The following outlines some of the basic features of Oracle Access Manager 11g:

Provisioning/Remote Registration: A new remote registration tool enables administrators inside or outside the network to register agents and policies. A username and password must be set in the primary User Identity Store for OAM 11g.

Authentication: Oracle Access Manager 11g application domains aggregate resources and security policies (one policy per resource). Oracle Access Manager 11g authentication policies include a specific scheme. Supported authentication modules include LDAP, X.509, and Kerberos. Authentication user mapping is performed against the primary user-identity provider by the centralized credential collector.

Authorization: Oracle Access Manager 11g performs authorization based on security policies defined in the application domain and persisted in the database. Authorization policies define the resource and constraint evaluation.

Responses: Administrators can set session attributes using authentication and authorization Responses. Aside from session attributes, a Response can also obtain user-related data and request-related data. Responses, once set, are then sent as either HTTP Headers or Cookies to the agent that helps manifest them. For cookie values and header variables, Responses can retrieve session attributes previously set by another Response. For example, session attributes set by a Response upon authentication can be retrieved as a header value during authorization.

Session Management: Oracle Access Manager 11g session management services track active user sessions through a high performance distributed cache system based on technology from Oracle Coherence. Each Oracle Access Manager runtime instance is a node within the distributed cache system. Secure communication between the nodes is facilitated using a symmetric key. The Oracle Access Manager runtime instances move user session data in the local cache into the distributed cache for other nodes to pick up. Each Oracle Access Manager runtime instance can also configure the replication factor and determine how session data is distributed. Administrators can configure the session lifecycle, locate and remove specific active sessions, and set a limit on the number of concurrent sessions a user can have at any time. Out-of-band session termination prevents unauthorized access to systems when a user has been terminated.

Keys: The Oracle Access Manager 11g runtime is deployed as an application to a WebLogic Managed Server or Cluster. New Oracle Access Manager 11g WebGates support a shared secret per agent trust model. 11g WebGates use agent/host specific cookies, which offers superior security. Oracle Access Manager 11g WebGates are all trusted at the same level; a cookie specific for the WebGate is set and cannot be used to access any other WebGate-protected applications on a user's behalf. Cookie-replay types of attacks are prevented.

SSO and SLO: The Oracle Access Manager 11g Server Session Token forms the basis for SSO between Oracle Access Manager and OSSO Agents. Logout is driven through Oracle Access Manager 11g Server Global Logout, which terminates the central session and logs out the user from each agent that was visited.

• With Oracle Access Manager 10g WebGates, logout removes the ObSSOCookie and then redirects to the Global Logout page.

• With Oracle Access Manager 11g WebGates and mod_osso agents, logout redirects to the Global Logout page and each agent is called back to remove the agent-specific cookie.

Logging and Auditing: Oracle Access Manager 11g components use the same logging infrastructure and guidelines as any other component in Oracle Fusion Middleware 11g. Oracle Access Manager 11g provides agent and server monitoring functions. Oracle Access Manager 11g auditing functions are based on the Common Audit Framework; audit-report generation is supported using Oracle Business Intelligence Publisher.

Access Tester: The new Oracle Access Manager 11g Access Tester enables IT professionals and administrators to simulate interactions between registered Oracle Access Manager Agents and Servers. This is useful when testing security policy definitions or troubleshooting issues involving agent connections.

Transition from Test to Production: Oracle Access Manager 11g enables moving configuration or policy data from one Oracle Access Manager 11g deployment to another (from a small test deployment to a production deployment, for example). Support for the creation of new topologies is based on templates. You can also copy and move policy changes.

Co-existence and Upgrades for OSSO 10g: The Oracle-provided Upgrade Assistant scans the existing OracleAS 10g SSO server configuration, accepts as input the 10g OSSO policy properties file and schema information, and transfers configured partner applications into the destination Oracle Access Manager 11g SSO.

See Also:

• Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager for an "Introduction to Post-Upgrade Co-existence Between Oracle Access Manager 11g and OSSO 10g Servers"

• Oracle Fusion Middleware Upgrade Planning Guide

• Oracle Fusion Middleware Upgrade Guide for Oracle Identity Management

9.3.2 Installing the Authentication Provider with Oracle Access Manager 11g

The following overview outlines the tasks that must be completed to install the required components and files for the Oracle Access Manager 11g SSO solution using the Authentication Provider. While many of these tasks are nearly the same for Oracle Access Manager 11g and Oracle Access Manager 10g, there are a few differences.

See Also:

Oracle Fusion Middleware Installation Guide for Oracle Identity Management for installation and initial configuration details for Oracle Access Manager 11g.

Task overview: Installing components for use with the Authentication Provider and OAM 11g

1. Install and set up Oracle Internet Directory for Oracle Access Manager.

   See Also:

   • Oracle Fusion Middleware Installation Guide for Oracle Identity Management

   • Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

2. Install and set up Oracle WebLogic Server 10.3.1+.

   See Also:

   Item 3 in this list, and the Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server

3. Optional: Install a Fusion Middleware product (Oracle Identity Manager, Oracle SOA Suite, or Oracle Web Center for example):

   Note:

   Without a Fusion Middleware application, you must acquire the required JAR and WAR files as described in later procedures.

4. Install OHS 11g for the Oracle Access Manager WebGate, if needed:

   • Identity Asserter: Requires Oracle HTTP Server 11g Web server configured as a reverse proxy in front of Oracle WebLogic Server.

   • Authenticator or Oracle Web Services Manager: No Web server is required for the custom AccessGate. The protected resource is accessed using its URL on the Oracle WebLogic Server.

5. Authentication Provider Files: Confirm the required JAR and WAR files as follows:

   1. Confirm the location of required JAR files in the following Fusion Middleware path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamAuthnProvider.jar
      

   2. Locate the console-extension WAR file in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprov 
      ider.war
      

   3. Copy the WAR file to the following path in the WebLogic Server home:

      WL_HOME/server/lib/console-ext/autodeploy/oamauthenticationprovider.war
      

6. Oracle Access Manager 11g:

   Install Oracle Access Manager and perform initial configuration as described in Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

   Include one primary and one secondary OAM Server for WebGate. Only one secondary server is supported.

7. WebGate (for Identity Asserter for Single Sign-On): In an existing Web Tier with one or more WebGates, provisioning is all you need. In a new Web Tier, you must install a fresh WebGate.

   In either case, see "Provisioning an OAM Agent with Oracle Access Manager 11g".

8. AccessGate for the Authenticator (or for Oracle Web Services Manager):

   • You can provision the 10g AccessGate as described in "Provisioning an OAM Agent with Oracle Access Manager 11g" (or refer to an existing OAM Agent registration when configuring the Authentication Provider).

   • Deploy the custom 10g AccessGate available in oamAuthnProvider.jar

9. Proceed as follows for your implementation:

   • Identity Asserter for Single Sign-On: See "Configuring Identity Assertion for SSO with Oracle Access Manager 11g".

   • Authenticator: See "Configuring the Authenticator for Oracle Access Manager 11g".

   • Oracle Web Services Manager: See "Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g".

   • "Troubleshooting Tips for OAM Provider Deployments".

9.3.3 Reviewing Pre-Seeded OAM 11g Policies for Use by the OAM 10g AccessGate

The Application Authenticator application domain is delivered with OAM 1g. It is pre-seeded with the policy objects that enables integration with applications deployed in WebLogic environments using the OAM Authentication Provider as the security provider. It is not associated with WebGate provisioning. When you provision a WebGate or AccessGate to use this (or another existing application domain), you will decline having policies created automatically.

The Application Authenticator application domain comes into play with the custom 10g AccessGate used with the OAM Authenticator (and the Identity Asserter for Oracle Web Services Manager). In this case, the custom AccessGate (not WebGate) contacts the WebLogic Server directly with a token to authenticate the user before OAM 11g is contacted.

The Application Authenticator application domain protects only resources of type wl_authen and is seeded with two authentication policies and one authorization policy. The following wl_authen resources are also seeded in this domain:

• /Authen/Basic

• /Authen/SSOToken

• /Authen/UsernameAssertion protected by LDAPNoPasswordValidationScheme

Note:

Only resources of type wl_authen are allowed in this domain; no other resource types can be added. Policies and Responses for wl_authen resources can be added. However, ideally, you will not need to modify this domain.

Figure 9-4 illustrates details of the seeded Application Authenticator application domain in the OAM 11g Administration Console. The page shown describes the pre-seeded User ID Assertion authentication policy, which protects the /Authen/UsernameAssertion resource. The authentication scheme for this policy is also shown along with the resources that are protected by the policy.

Figure 9-4 Pre-seeded Resources in the User ID Assertion Authentication Policy

Figure 9-5 illustrates pre-seeded Responses for the User ID Assertion authentication policy. For more information about Responses, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Figure 9-5 Pre-seeded Responses in the User ID Assertion Policy

Figure 9-6 illustrates the pre-seeded Application SSO authentication policy, the resources protected by this policy, and the authentication scheme.

Figure 9-6 Pre-seeded Application SSO Authentication Policy and Resources

Figure 9-7 illustrates Pre-seeded Responses for the Application SSO authentication policy in the application domain.

Figure 9-7 Pre-seeded Responses for the Application SSO Authentication Policy

Figure 9-8 illustrates the pre-seeded Application SSO authorization policy and Resources in the application domain.

Figure 9-8 Pre-seeded Application SSO Authorization Policy and Resources

Authorization Constraints: There are no pre-seeded Application SSO authorization policy Constraints in this application domain. However, you can add constraints as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Authorization Responses: There are no pre-seeded Application SSO authorization policy Responses in the application domain. However, you can add responses as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

See Also:

• Configuring the Authenticator for Oracle Access Manager 11g

• Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g

9.3.4 Provisioning an OAM Agent with Oracle Access Manager 11g

Provisioning is the process of registering an agent and creating an application domain to use OAM 11g authentication and authorization services.You must provision a WebGate with OAM 11g whether you are preparing to install a fresh 11g or 10g instance or you have a legacy 10g WebGate installed.

The term WebGate is used for WebGates (and for the custom 10g AccessGates used with the Authenticator and the Identity Asserter for Oracle Web Services Manager). Unless explicitly stated, topics apply equally to both.

When you have multiple agents, each one can be provisioned independently or you can use a single OAM Agent registration for multiple agents.

Note:

The Application Authenticator application domain is pre-seeded and delivered with OAM 11g. When you provision an OAM Agent to use this (or another existing) application domain, decline the option of having policies automatically created.

The following topics are provided:

• About WebGate Provisioning Methods for Oracle Access Manager 11g

• Provisioning a WebGate with Oracle Access Manager 11g

9.3.4.1 About WebGate Provisioning Methods for Oracle Access Manager 11g

Table 9-2 outlines the methods and tools you can use to provision WebGates for use with OAM 11g. The remote registration tool enables you to specify a small amount or all WebGate parameters using templates.

Table 9-2 Provisioning Methods for OAM 11g

Method	Description
Oracle Access Manager Administration Console	Enables OAM Administrators to manually enter information and set parameters directly in Oracle Access Manager. This method is required if you are using the Authenticator, or if you have Oracle Web Services Manager policies protecting Web services.
Remote Registration	Application administrators who are implementing the Identity Asserter for single sign-on, can register the WebGate using the command line. This also creates a new application domain with security policies for a fresh or existing Web Tier. Required parameters are provisioned using values for your environment specified in a template. Default values are accepted for non-required parameters. After registration, values can be modified in the OAM Administration Console.

During remote registration, you must provide the details discussed in Table 9-3.

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager for a complete list of WebGate parameters

Table 9-3 Required Registration Details for OAM Agents

OAM Agent Element	Description
<serverAddress>	Points to a running instance of the Oracle Access Manager Administration Console, including the host and port.
<webDomain> OSSO requests only	Defines the Web server domain under which the Agent Base URL is stored internally.
<agentName>	Defines a unique identifier for the agent on the OAM (Administration) Server. For every agent on the same server instance, this tag must be unique to avoid re-registering the same agent. Re-registering an agent on the same server instance is not supported.
<hostIdentifier>	This identifier represents the Web server host. The field is filled in automatically when you specify a value for the OAM Agent Name. If the agent name or host identifier of the same name already exists, an error occurs during registration.
<protectedResourcesList>	Specifies the resource URLs that you want the OAM Agent to protect with some authentication scheme. The resource URLs should be relative paths to the agentBaseUrl.
<publicResourcesList>	Specifies the resource URLs that you want to keep public (not protected by the OAM Agent). The resource URLs should be relative paths to the agentBaseUrl. For instance, you might want to specify the Home page or the Welcome page of your application

9.3.4.2 Provisioning a WebGate with Oracle Access Manager 11g

Provisioning a WebGate or AccessGate involves the same steps. You can provision a new instance for use with the Authentication Provider or you can refer to an existing registration when configuring the provider.

In this example, an OAM 10g WebGate is provisioned using the OAMRequest_short.xml template. The registered agent is named my-wl-agent1, protecting /.../*, and declaring a public resource, /public/index.html. Your values will be different.

Note:

When provisioning an OAM 11g WebGate, use the OAM11gRequest_short.xml template.

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

To provision a WebGate with OAM 11g

1. Acquire the Tool: On the computer to host the WebGate, acquire the remote registration tool and set up the script for your environment. For example:

   1. Locate RREG.tar.gz file in the following path:

      WLS_home/Middleware/domain_home/oam/server/rreg/client/RREG.tar.gz 
      

   2. Untar RREG.tar.gz file to any suitable location. For example: rreg/bin/oamreg.

   3. In the oamreg script, set the following environment variables based on your situation (client side or server side) and information in Table 6–7 in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager:

      
      OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
      JDK_HOME = Java_location_on_the_computer
      

2. Create the registration request:

   1. Locate the *Request_short.xml file and copy it to a new location and name. For example:

      WLS_home/Middleware/domain_home/oam/server/rreg/bin/oamreg/
      

      Copy: OAMRequest_short.xml (or OAM 11gRequest.xml)

      To: my-wl-agent1.xml

   2. Edit my-wl-agent1.xml to include details for your environment, and set automatic policy creation to false. For example:

      <OAMRegRequest>
          <serverAddress>http://sample.us.oracle.com:7001</serverAddress>
          <hostIdentifier>my-wl</hostIdentifier>
          <agentName>my-wl-agent1</agentName>
          <primaryCookieDomain>.us.example.com</primaryCookieDomain>
          <autoCreatePolicy>false</autoCreatePolicy>
          <logOutUrls><url>/oamsso/logout.html</url></logOutUrls>
      </OAMRegRequest>
      

      See Also:

      "Creating the Registration Request"in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

3. Provision the agent. For example:

   1. Locate the remote registration script.

      
      Linux: rreg/bin/oamreg.sh
      Ensure the script has executable permission: chmod +x oamreg.sh
      

      Windows: rreg\bin\oamreg.bat

   2. From the directory containing the script, execute the script using inband mode. For example:

      $ ./bin/oamreg.sh inband input/my-wl-agent1.xml

      Welcome to OAM Remote Registration Tool!
      Parameters passed to the registration tool are:
      Mode: inband
      Filename: ...
      

   3. When prompted, enter the following information using values for your environment:

      Enter your agent username: userame
         Username:  userame
      Enter agent password: ********
      Do you want to enter a Webgate password?(y/n)
          n
      iv.Do you want to import an URIs file?(y/n)
          n
      

   4. Review the final message to confirm that this was a successful registration:

      Inband registration process completed successfully! Output artifacts are 
      created in the output folder"
      

4. Confirm in the Console: Log in to the OAM Administration Console and review the new registration:

   1. From the OAM 11g Console System Configuration tab, navigation pane, expand the Agents nodes to locate the agent you just provisioned:

      
      Agents
      OAM Agents
      10g Agents
      

   2. Double-click the agent's name to display the registration page and review the details, which you will use later. For example:

      Agent Name—During WebGate installation, enter this as the WebGate ID. If you deploy the custom 10g AccessGate, enter this as the AccessGate Name when configuring the OAM Authentication Provider in the WebLogic Administration Console.

      Access Client Password—During WebGate installation, enter this as the WebGate password. If no password was entered, you can leave the field blank.

      Access Server Host Name—Enter the DNS host name for the primary OAM 11g Server with which this WebGate is registered.

   3. OAM Proxy Port—From the OAM Administration Console, System Configuration tab, navigation pane, double click Server Instances and locate the port on which the OAM Proxy is running.

5. Ignore the Obaccessclient.xml file, which is created during provisioning, for now.

6. Proceed as needed for your environment:

   • Agent is Installed: Go to the appropriate topic for your implementation:

     • Configuring Identity Assertion for SSO with Oracle Access Manager 11g

     • Configuring the Authenticator for Oracle Access Manager 11g

     • Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g

     • Configuring Centralized Log Out for Oracle Access Manager 11g

   • Agent is Not Installed:

     11g WebGate: See Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

     10g WebGate: See Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

9.3.5 Configuring Identity Assertion for SSO with Oracle Access Manager 11g

This section describes the unique steps needed to configure Oracle Access Manager 11g Identity Assertion for Single Sign-On.

Prerequisites

Installing the Authentication Provider with Oracle Access Manager 11g

Provisioning an OAM Agent with Oracle Access Manager 11g

To configure Oracle Access Manager Identity Asserter for single sign-on with your application, perform the tasks as described in the following task overview.

Task overview: Deploying the Identity Asserter for SSO with OAM 11g includes

1. Ensuring that all prerequisite tasks have been performed

2. Establishing Trust with Oracle WebLogic Server

3. Configuring Providers in the WebLogic Domain

4. Reviewing the Login Page for the Oracle Access Manager Identity Asserter

5. Configuring Centralized Log Out for Oracle Access Manager 11g

6. Testing Oracle Access Manager Identity Assertion for Single Sign-on

9.3.5.1 Establishing Trust with Oracle WebLogic Server

The following topics explain the tasks you must perform to set up the application for single sign-on with the Oracle Access Manager Identity Asserter:

Note:

This task is the same for both OAM 11g WebGates and OAM 10g WebGates.

• Setting Up the Application Authentication Method for Identity Asserter for Single Sign-On

• Confirming mod_weblogic for Oracle Access Manager Identity Asserter

• Establishing Trust between Oracle WebLogic Server and Other Entities

9.3.5.1.1 Setting Up the Application Authentication Method for Identity Asserter for Single Sign-On

This topic describes how to create the application authentication method for Oracle Access Manager Identity Assertion.

See Also:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

When you use the Oracle Access Manager Identity Asserter, all web.xml files in the application EAR file must specify CLIENT-CERT in the element auth-method for the appropriate realm.

You can add comma separated values here when you want applications accessed directly over the WebLogic Server host:port to be authenticated by the container. For instance: <auth-method>CLIENT-CERT,FORM</auth-method>.

The auth-method can use BASIC, FORM, or CLIENT-CERT values. While these look like similar values in Oracle Access Manager, the auth-method specified in web.xml files are used by Oracle WebLogic Server (not Oracle Access Manager).

To specify authentication in web.xml for the Identity Asserter

1. Locate the web.xml file in the application EAR file:

   my_app/WEB-INF/web.xml  
   

2. Locate the auth-method in login-config and enter CLIENT-CERT.

   <login-config>
     <auth-method>CLIENT-CERT</auth-method>
   </login-config>
   

3. Save the file.

4. Redeploy and restart the application.

5. Repeat for each web.xml file in the application EAR file.

6. Proceed to "Confirming mod_weblogic for Oracle Access Manager Identity Asserter".

9.3.5.1.2 Confirming mod_weblogic for Oracle Access Manager Identity Asserter

Oracle Oracle HTTP Server includes the mod_weblogic plug-in module (mod_wl_ohs.so in 11g) which is already enabled. You can perform the following procedure to confirm this or skip this procedure.

With Oracle HTTP Server 11g, the mod_weblogic configuration is present in mod_wl_ohs.conf by default, and the path of this file is included in httpd.conf. If the mod_weblogic configuration is not present then you must edit httpd.conf.

To configure mod_weblogic for the Oracle Access Manager Identity Asserter

1. Locate httpd.conf. For example:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

2. Confirm that the following statement is in the file with appropriate values for your deployment (add or uncomment this, if needed):

   <IfModule mod_weblogic.c>
      WebLogicHost myHost.myDomain.com
        WebLogicPort myWlsPortNumber
   </IfModule>
    
   <Location http://request-uri-pattern>
      SetHandler weblogic-handler
   </Location>
   

3. Save the file.

4. Proceed to "Establishing Trust between Oracle WebLogic Server and Other Entities".

9.3.5.1.3 Establishing Trust between Oracle WebLogic Server and Other Entities

The Oracle WebLogic Connection Filtering mechanism must be configured for creating access control lists and for accepting requests from only the hosts where Oracle HTTP Server and the front-end Web server are running.

Note:

This topic is the same whether you are using OSSO or Oracle Access Manager.

A network connection filter is a component that controls the access to network level resources. It can be used to protect resources of individual servers, server clusters, or an entire internal network. For example, a filter can deny non-SSL connections originating outside of a corporate network. A network connection filter functions like a firewall since it can be configured to filter protocols, IP addresses, or DNS node names. It is typically used to establish trust between Oracle WebLogic Server and foreign entities.

To configure a connection filter to allow requests from only mod_weblogic and the host where OHS 11g is running, perform the procedure here.

Note:

This chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs; the actual binary name is mod_wl_ohs.so. Examples show exact syntax for implementation.

WebLogic Server provides a default connection filter: weblogic.security.net.ConnectionFilterImpl. This filter accepts all incoming connections and also provides static factory methods that allow the server to obtain the current connection filter. To configure this connection filter to deny access, simply enter the connection filters rules in the WebLogic Server Administration Console.

You can also use a custom connection filter by implementing the classes in the weblogic.security.net package. Like the default connection filter, custom connection filters are configured in the WebLogic Server Administration Console.

Connection Filter Rules: The format of filter rules differ depending on whether you are using a filter file to enter the filter rules or you enter the filter rules in the Administration Console. When entering the filter rules on the Administration Console, enter them in the following format:

targetAddress localAddress localPort action protocols

Table 9-4 provides a description of each parameter in a connection filter.

Table 9-4 Connection Filter Rules

Parameter	Description
target	Specifies one or more systems to filter
localAddress	Defines the host address of the WebLogic Server instance. (If you specify an asterisk (*), the match returns all local IP addresses.)
localPort	Defines the port on which the WebLogic Server instance is listening. (If you specify an asterisk, the match returns all available ports on the server.)
action	Specifies the action to perform. This value must be allow or deny
protocols	Is the list of protocol names to match. The following protocols may be specified: http, https, t3, t3s, giop, giops, dcom, ftp, ldap. If no protocol is defined, all protocols match a rule.

The Connection Logger Enabled attribute logs successful connections and connection data in the server. This information can be used to debug problems relating to server connections.

See Also:

"Configuring Security in a WebLogic Domain" in Oracle Fusion Middleware Securing Oracle WebLogic Server

To configure a connection filter to allow requests from the host of the 11g Oracle HTTP Server

1. Log in to the Oracle WebLogic Administration Console.

2. Click Domain under Domain Configurations.

3. Click the Security tab, click the Filter tab.

4. Click the Connection Logger Enabled attribute to enable the logging of accepted messages for use when debugging problems relating to server connections.

5. Specify the connection filter to be used in the domain:

   • Default Connection Filter: In the Connection Filter attribute field, specify weblogic.security.net.ConnectionFilterImpl.

   • Custom Connection Filter: In the Connection Filter attribute field, specify the class that implements the network connection filter, which should also be specified in the CLASSPATH for Oracle WebLogic Server.

6. Enter the appropriate syntax for the connection filter rules.

7. Click Save.

8. Restart the Oracle WebLogic Server.

9. Proceed to "Configuring Providers in the WebLogic Domain".

9.3.5.2 Configuring Providers in the WebLogic Domain

The information here applies equally to OAM 11g and OAM 10g. This topic is divided as follows:

• About Oracle WebLogic Server Authentication and Identity Assertion Providers

• About the Oracle WebLogic Scripting Tool (WLST)

• Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO

• Setting Up Providers for Oracle Access Manager 11g Identity Assertion

9.3.5.2.1 About Oracle WebLogic Server Authentication and Identity Assertion Providers

This topic introduces only a few types of Authentication Providers for a WebLogic security realm, if you are new to them.

Each WebLogic security realm must have one at least one Authentication Provider configured. The WebLogic Security Framework is designed to support multiple Authentication Providers (and thus multiple LoginModules) for multipart authentication. As a result, you can use multiple Authentication Providers as well as multiple types of Authentication Providers in a security realm. The Control Flag attribute determines how the LoginModule for each Authentication Provider is used in the authentication process.

Oracle WebLogic Server offers several types of Authentication and Identity Assertion providers including, among others:

• The default WebLogic Authentication Provider (Default Authenticator) allows you to manage users and groups in one place, the embedded WebLogic Server LDAP server. This Authenticator is used by the Oracle WebLogic Server to login administrative users.

• Identity Assertion uses token-based authentication; the Oracle Access Manager Identity Asserter is one example. This must be configured to use the appropriate action for the installed WebGate (either 10g or 11g). For details, see "Oracle Access Manager Authentication Provider Parameter List".

• LDAP Authentication Providers store user and group information in an external LDAP server. They differ primarily in how they are configured by default to match typical directory schemas for their corresponding LDAP server.

  Oracle WebLogic Server 10.3.1+ provides OracleInternetDirectoryAuthenticator.

When you configure multiple Authentication Providers, use the JAAS Control Flag for each provider to control how the Authentication Providers are used in the login sequence. You can choose the following the JAAS Control Flag settings, among others:

• REQUIRED—The Authentication Provider is always called, and the user must always pass its authentication test. Regardless of whether authentication succeeds or fails, authentication still continues down the list of providers.

• SUFFICIENT—The user is not required to pass the authentication test of the Authentication Provider. If authentication succeeds, no subsequent Authentication Providers are executed. If authentication fails, authentication continues down the list of providers.

• OPTIONAL—The user is allowed to pass or fail the authentication test of this Authentication Provider. However, if all Authentication Providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.

When additional Authentication Providers are added to an existing security realm, the Control Flag is set to OPTIONAL by default. You might need to change the setting of the Control Flag and the order of providers so that each Authentication Provider works properly in the authentication sequence.

See Also:

"Configuring Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server for a complete list of Authentication Providers and details about configuring the Oracle Internet Directory provider to match the LDAP schema for user and group attributes

9.3.5.2.2 About the Oracle WebLogic Scripting Tool (WLST)

This topic introduces WLST, if you are new to it.

You can add providers to a WebLogic domain using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

WLST is a Jython-based command-line scripting environment that you can use to manage and monitor WebLogic Server domains. Generally, you can use this tool online or offline. You can use this tool interactively on the command line in batches supplied in a file (Script Mode, where scripts invoke a sequence of WLST commands without requiring your input), or embedded in Java code.

When adding Authentication Providers to a WebLogic domain, you can use WLST online to interact with an Authentication Provider and add, remove, or modify users, groups, and roles.

When you use WLST offline to create a domain template, WLST packages the Authentication Provider's data store along with the rest of the domain documents. If you create a domain from the domain template, the new domain has an exact copy of the Authentication Provider's data store from the domain template. However, you cannot use WLST offline to modify the data in an Authentication Provider's data store.

Note:

You cannot use WLST offline to modify the data in an Authentication Provider's data store.

See Also:

• "Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference "Infrastructure Security Commands" chapter

9.3.5.2.3 Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO

On the Oracle WebLogic Server, you can run a Web application that uses Oracles Application Development Framework (Oracle ADF) security, integrates with Oracle Access Manager Single Sign On (SSO), and uses Oracle Platform Security Services (OPSS) SSO for user authentication. However before the Web application can be run, you must configure the domain-level jps-config.xml file on the application's target Oracle WebLogic Server for the Oracle Access Manager security provider.

The domain-level jps-config.xml file is in the following path and should not be confused with the deployed application's jps-config.xml file:

domain_home/config/fmwconfig/jps-config.xml 

You can use an Oracle Access Manager-specific WLST script to configure the domain-level jps-config.xml file, either before or after the Web application is deployed. This Oracle JRF WLST script is named as follows:

Linux: wlst.sh

Windows: wlst.cmd

The Oracle JRF WLST script is available in the following path if you are running through JDev:

     $JDEV_HOME/oracle_common/common/bin/

In a standalone JRF WebLogic installation, the path is:

     $Middleware_home/oracle_common/wlst

Note:

The Oracle JRF WLST script is required. When running WLST for Oracle Java Required Files (JRF), do not use the WLST script under $JDEV_HOME/wlserver_10.3/common/bin.

Command Syntax

addOAMSSOProvider(loginuri, logouturi, autologinuri)

Table 9-9 defines the expected value for each argument in the addOAMSSOProvider command line.

Table 9-5 addOAMSSOProvider Command-line Arguments

Argument	Definition
loginuri	Specifies the URI of the login page
autologinuri	Specifies the URI of the autologin page.
logouturi	Specifies the URI of the logout page

See Also:

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference "Infrastructure Security Commands" chapter

Prerequisites

Configuring Providers in the WebLogic Domain

To modify domain-level jps-config.xml for a Fusion Web application with Oracle ADF Security enabled

1. On the computer hosting the Oracle WebLogic Server and the Web application using Oracle ADF security, locate the Oracle JRF WLST script. For example:

   cd $ORACLE_HOME/oracle_common/common/bin
   

2. Connect to the computer hosting the Oracle WebLogic Server:

   connect login_id password hostname:port
   

   For example, the Oracle WebLogic Administration Server host could be localhost using port 7001. However, your environment might be different.

3. Enter the following command-line arguments with values for the application with ADF security enabled:

   addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication", 
   logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
   

4. Stop and start the Oracle WebLogic Server.

5. Perform the following tasks as described in this chapter:

   • Setting Up Providers for Oracle Access Manager 11g Identity Assertion

   • Configuring Centralized Log Out for Oracle Access Manager 11g

   • Testing Oracle Access Manager Identity Assertion for Single Sign-on

9.3.5.2.4 Setting Up Providers for Oracle Access Manager 11g Identity Assertion

This topic describes how to configure providers in the WebLogic security domain to perform single sign-on with the Oracle Access Manager Identity Asserter. Several Authentication Provider types must be configured and ordered:

• OAM Identity Asserter: REQUIRED (also specify a chosen Action Type based on the WebGate release you are using with OAM 11g (Table 9-10))

• OID Authenticator: SUFFICIENT

• DefaultAuthenticator: SUFFICIENT

See Also:

"About Oracle WebLogic Server Authentication and Identity Assertion Providers"

The following procedure uses the WebLogic Administration Console.

Note:

With an Oracle Fusion Middleware application installed, you have the required provider JAR file. Skip Step 1.

To set up Providers for Oracle Access Manager single sign-on in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider:

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0):

      oamAuthnProvider<version number>.zip  
      

   3. Extract and copy oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
      

2. With Oracle Fusion Middleware Application Installed:

   1. Locate oamauthenticationprovider.war in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprovi
      der.war
      

   2. Copy oamauthenticationprovider.war to the following location:

      BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      

3. Log in to the WebLogic Administration Console.

4. Click Security Realms, Default Realm Name, and click Providers.

5. OAM Identity Asserter: Perform the following steps to add this provider:

   1. Click New, and then enter a name and select a type:

      Name: OAM Identity Asserter

      Type: OAMIdentityAsserter

      OK

   2. In the Authentication Providers table, click the newly added authenticator.

   3. Click the Common tab, set the Control Flag to REQUIRED.

   4. Click the Common tab, specify the chosen Action Type for your installed WebGate, (Table 9-10).

   5. Save.

6. OID Authenticator: Perform the following steps to add this provider.

   1. Click Security Realms, Default Realm Name, and click Providers.

   2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      OK

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

   5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Oracle Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Do not set the All Groups filter as the default works fine as is.

      Save.

7. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

   1. Go to Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

   3. Click the Common tab and set the Control Flag to SUFFICIENT.

   4. Save.

8. Reorder Providers:

   1. Click Security Realms, Default Realm Name, Providers.

   2. On the Summary page where providers are listed, click the Reorder button

   3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

   4. Click OK to save your changes

9. Activate Changes: In the Change Center, click Activate Changes

10. Reboot Oracle WebLogic Server.

11. Proceed as follows:

    • Successful: See "Reviewing the Login Page for the Oracle Access Manager Identity Asserter".

    • Not Successful: Confirm that all providers have the proper specifications for your environment, are in the proper order, and that oamAuthnProvider.jar is in the correct location.

9.3.5.3 Reviewing the Login Page for the Oracle Access Manager Identity Asserter

As mentioned earlier, a login form shipped with 10g WebGate is used only with OAM 10g Access Server. For OAM 11g, neither the 10g WebGate nor 11g WebGate provide a login page.

Note:

The OAM 11g Server displays a login page. No set up is needed.

Proceed as Follows

1. Configuring Centralized Log Out for Oracle Access Manager 11g

2. Testing Oracle Access Manager Identity Assertion for Single Sign-on

9.3.5.4 Testing Oracle Access Manager Identity Assertion for Single Sign-on

The following procedure describes how to test your Oracle Access Manager Identity Assertion setup.

Alternatively, you can run Access Tester in Oracle Access Manager to test your policy domain, as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

To validate Oracle Access Manager Identity Assertion for Single Sign-on

1. Enter the URL to access the protected resource in your environment. For example:

   http://ohs_server:port/<protected url>
   

2. Provide appropriate credentials when the login form appears.

   • Successful: The implementation works.

   • Not Successful: See "Troubleshooting Tips for OAM Provider Deployments".

9.3.6 Configuring the Authenticator for Oracle Access Manager 11g

With the Authenticator, the user is challenged for credentials based on the authentication method that is configured within the application web.xml. However, an Oracle Access Manager authentication scheme is required and available in the pre-seeded application domain that is delivered with Oracle Access Manager 11g. It protects the following resources (resource type wl_authen):

• /Authen/Basic

• /Authen/SSOToken

• /Authen/UsernameAssertion

You can add Responses and Constraints to policies. However, no other configuration is needed.

For more information about the pre-seeded application domain, see "Reviewing Pre-Seeded OAM 11g Policies for Use by the OAM 10g AccessGate".

Prerequisites

• Installing the Authentication Provider with Oracle Access Manager 11g

• Provisioning an OAM Agent with Oracle Access Manager 11g

  Note:

  You can provision the custom 10g AccessGate for the Authenticator or simply refer to an existing OAM Agent registration when configuring providers for the Authenticator. In either case, the Authenticator implementation uses policies in the pre-seeded Fusion Apps Integration domain.

Tasks to configure the Oracle Access Manager Authenticator are described in the following overview.

Task overview: Configuring the Oracle Access Manager Authenticator includes

1. Ensuring that all prerequisite tasks have been performed

2. Configuring Providers for the Authenticator in a WebLogic Domain

3. Configuring the Application Authentication Method for the Authenticator

4. Mapping the Authenticated User to a Group in LDAP

5. Configuring Centralized Log Out for Oracle Access Manager 11g

6. Testing the Oracle Access Manager Authenticator Implementation

9.3.6.1 Configuring Providers for the Authenticator in a WebLogic Domain

This topic includes a procedure that you can use to add and configure the appropriate Authentication providers in a WebLogic domain.

The Oracle Access Manager Authenticator must be configured along with the Default Authentication Provider in a WebLogic domain.

• DefaultAuthenticator: SUFFICIENT

• OAM Authenticator: OPTIONAL

The following procedure describes this task using the WebLogic Administration Console. You can also add these using the Oracle WebLogic Scripting Tool (WLST).

See Also:

• "About Oracle WebLogic Server Authentication and Identity Assertion Providers"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference

Note:

When an Oracle Fusion Middleware application is installed, you have the required files and can skip Step 1.

To configure providers for the Oracle Access Manager Authenticator in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider if you have no Oracle Fusion Middleware application.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0). For example:

      oamAuthnProvider<version>.zip 
      

   3. Extract and copy the oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
       
      

2. Go to the Oracle WebLogic Administration Console.

3. With Oracle Fusion Middleware Application Installed:

   1. Locate oamauthenticationprovider.war in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprovi
      der.war 
      

   2. Copy oamauthenticationprovider.war to the following location:

      BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      

4. Go to the Oracle WebLogic Administration Console.

5. Click Lock & Edit, if desired.

6. OAM Authenticator:

   1. Click Security Realms and select the realm you want to configure.

   2. Select Providers, Authentication, and click New to display the Create a New Authentication Provider page

   3. Enter a name and select a type:

      Name OAMAuthN

      Type: OAMAuthenticator

      OK

   4. Click the name of the Authentication provider you have just created to display the Provider Configuration page.

   5. In the Provider Configuration page, set the required values as follows:

      Access Gate Name: The name of the AccessGate used by the Provider. This must match exactly the name of an OAM Agent registration in the OAM Administration Console.

      Note:

      You can have one or more 10g OAM Agents registered with OAM 11g. Be sure to choose the correct Agent registration name.

      Access Gate Password: The same password, if any, that is as defined for the Agent registration (see the OAM Administration Console).

      Primary Access Server: The host:port of the primary Access Server that is associated with this AccessGate in the OAM Administration Console.

      Advanced Configuration: Following are several advanced configuration values.

      Transport Security: The communication mode between Access Server and AccessGate: open, simple, or cert.

      If transport security is Simple or Cert, include the following parameters and values:

      Trust Store: The absolute path of JKS trust store used for SSL communication between the provider and the OAM Server.

      Key Store: The absolute path of JKS key store used for SSL communication between the provider and the OAM Server.

      Key Store Pass Phrase: The password to access the key store.

      Simple mode pass phrase: The password shared by AccessGate and OAM Server for simple communication modes.

      Secondary OAM Server: The host:port of the secondary OAM Server that is associated with this AccessGate in the OAM Administration Console.

      Maximum OAM Server Connections in Pool: The maximum number of connections that the AccessGate opens to the OAM Server. The default value is 10.

      Note:

      The Maximum OAM Server Connections in Pool (or Minimum OAM Server Connections in Pool) settings in the WebLogic Administration Console are different from the Maximum (or Minimum) Connections specified in the OAM Administration Console.

      Minimum Access Server Connections in Pool: The minimum number of connections that the Authentication provider uses to send authentication requests to the Access Server. The default value is 5.

      See Also:

      "Oracle Access Manager Authentication Provider Parameter List" for descriptions and values of the common and provider-specific parameters

   6. Ensure that the parameter Control Flag is set to OPTIONAL initially.

      Note:

      Do not set the parameter Control Flag to REQUIRED until you have verified that the Authentication Provided is operational and configured correctly.

7. In the Change Center, click Activate Changes.

8. DefaultAuthenticator: Under the Providers tab, select DefaultAuthenticator, which changes its control flag to SUFFICIENT.

9. Reorder: Under the Providers tab, reorder the providers so that DefaultAuthenticator is first (OAMAuthenticator follows DefaultAuthenticator).

   Note:

   If the Oracle Access Manager Authenticator flag is set to REQUIRED, or if Oracle Access Manager Authenticator is the only Authentication provider, perform the next step to ensure that the LDAP user who boots Oracle WebLogic Server is included in the administrator group that can perform this task. By default the Oracle WebLogic Server Admin Role includes the Administrators group.

10. Oracle Access Manager Authenticator REQUIRED or the Only Authenticator: Perform the following steps to set user rights for booting Oracle WebLogic Server.

    1. Create an Administrators group in the directory server, if one does not already exist (or any other group for which you want boot access).

       Note:

       To provide access to any other group, you must create that group in the directory server and add the user who boots WebLogic Server in that group.

    2. Confirm that the LDAP user who boots Oracle WebLogic Server is included in the Administrators (or other) group.

    3. From the WebLogic Administration Console, go to Security Realms, myrealm, Roles and Policies, Global Roles.

    4. Select View Conditions for the Admin Role.

    5. Add the group and click Save.

11. Reboot the WebLogic Server.

12. Once the server has started, reset the Authentication Provider parameter Control Flag to the appropriate value (REQUIRED, OPTIONAL, or SUFFICIENT).

    Note:

    The recommended value is REQUIRED. To prevent a known issue, see "JAAS Control Flag".

13. Proceed with "Configuring the Application Authentication Method for the Authenticator".

9.3.6.2 Configuring the Application Authentication Method for the Authenticator

This topic describes how to create the application authentication method for Oracle Access Manager Authenticator.

See Also:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

When you use the Oracle Access Manager Authenticator, all web.xml files in the application EAR file must specify BASIC in the element auth-method for the appropriate realm.

The auth-method can use BASIC or FORM values. While these look like similar values in Oracle Access Manager, the auth-method specified in web.xml files are used by Oracle WebLogic Server (not Oracle Access Manager).

Note:

For the Oracle Access Manager Authenticator, Oracle recommends auth-method BASIC in login-config within web.xml.

To configure the application authentication method for the Authenticator

1. Locate the web.xml file in the application EAR file:

   WEB-INF/web.xml 
   

2. Locate the auth-method in login-config and enter BASIC. For example:

   <security-constraint>
   <web-resource-collection>
   <web-resource-name>protected</web-resource-name>
   <url-pattern>/servlet</url-pattern>
   </web-resource-collection>
   <auth-constraint>
   <role-name>auth-users</role-name>
   </auth-constraint>
   </security-constraint>
   <login-config>
   <auth-method>BASIC</auth-method>
   </login-config>
   <security-role>
   <description>Authenticated Users</description>
   <role-name>auth-users</role-name>
   </security-role>
   

3. Save the file.

4. Redeploy and restart the application.

5. Repeat for each web.xml file in the application EAR file.

6. Proceed with "Mapping the Authenticated User to a Group in LDAP".

9.3.6.3 Mapping the Authenticated User to a Group in LDAP

This topic describes how to map the authenticated user to a group in LDAP. To do this, you must edit the weblogic.xml file. For example, you might need to map your role-name auth-users to a group named managers in LDAP.

To map the authenticated user to a group in LDAP for the Oracle Access Manager Authenticator

1. Go to the application's weblogic.xml file.

2. Add the following information for your environment anywhere in the file:

   <weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app
   http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd" 
   xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
   <security-role-assignment>
   <principal-name>managers</principal-name>
   <role-name>auth-users</role-name>
   </security-role-assignment>
   </weblogic-web-app>
   

3. Save the file.

4. Restart the WebLogic Server.

5. Configure centralized logout as described in "Configuring Centralized Log Out for Oracle Access Manager 11g" and then return here to perform "Testing the Oracle Access Manager Authenticator Implementation".

9.3.6.4 Testing the Oracle Access Manager Authenticator Implementation

After performing all tasks to implement the Authenticator, you can test it by attempting to log in to the application using valid credentials. If the configuration is incorrect, a valid user is denied access.

The following procedure describes how to test your Authenticator setup. Alternatively, you can run Access Tester in Oracle Access Manager to test your policy domain, as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

To validate the Oracle Access Manager Authenticator implementation

1. Enter the URL to access the protected resource in your environment. For example:

   http://yourdomain.com:port
   

2. Provide appropriate credentials when the login form appears.

   • Successful: The implementation works.

   • Not Successful: See "Troubleshooting Tips for OAM Provider Deployments".

9.3.7 Configuring Identity Assertion for Oracle Web Services Manager and OAM 11g

This section describes how to set up the Oracle Access Manager Identity Asserter to enable validation of the token when you have Oracle Web Services Manager protecting Web services.

As discussed earlier, the Oracle Access Manager Identity Asserter works in two modes. The default mode of operation simply asserts the header that is set by WebGate at the perimeter, which handles most SSO situations. The alternate mode uses the custom AccessGate in oamAuthnProvider.jar. In this case, and with the absence of the header, the Identity Asserter contacts the OAM Server to validate the token. For more information about the token, see "Installing the Authentication Provider with Oracle Access Manager 11g".

Note:

The 10g custom AccessGate provided with the Authentication Provider is required for Identity Assertion for Oracle Web Services Manager.

With OAM 10g, you would need to manually create the policy domain and policies for this configuration. However, with OAM 11g, a pre-seeded application domain is delivered with policies that protect the following resources (resource type wl_authen):

• /Authen/Basic

• /Authen/SSOToken

• /Authen/UsernameAssertion

You can add policies, Responses, or Constraints for resources of type wl_authen only. Ideally, however, you can use this application domain with no further configuration. For more information, see "Reviewing Pre-Seeded OAM 11g Policies for Use by the OAM 10g AccessGate".

When the Oracle Access Manager Identity Asserter is configured for both header and token validation modes, preference is given to the presence of the header. If the header is not present, the Identity Asserter contacts the OAM Server to validate the token. For more information on the token, see "Oracle Access Manager Authentication Provider Parameter List".

Prerequisites

Installing the Authentication Provider with Oracle Access Manager 11g

Provisioning an OAM Agent with Oracle Access Manager 11g

Task overview: Deploying the Identity Asserter with Oracle Web Services Manager includes

1. Configuring Oracle Web Services Manager Policies for Web Services

2. Configuring Providers in a WebLogic Domain for Oracle Web Services Manager

3. Configuring Centralized Log Out for Oracle Access Manager 11g

4. Testing the Identity Asserter with Oracle Web Services Manager

9.3.7.1 Configuring Oracle Web Services Manager Policies for Web Services

This section provides an overview of configuring Oracle Web Services Manager policies to protect Web services.

To use the Identity Asserter with Oracle Web Services Manager, you must set up a Web service with the oracle/wss_oam_token_service_policy and a corresponding client with the oracle/wss_oam_token_client_policy in Oracle Web Services Manager.

See Also:

"Introduction to the OAM Authentication Provider"

About oracle/wss_oam_token_service_policy

This Oracle Web Services Manager policy contains the policy assertion oracle/wss_oam_token_service_template. This template uses the credentials in the WS-Security header's binary security token to authenticate users against the Oracle Access Manager identity store.

The Oracle Access Manager Identity Asserter uses the ObSSOCookie token to assert the identity of users who try to access a Web service protected by the oracle/wss_oam_token_service_policy policy. A Web service that is protected by this policy must be presented with an ObSSOCookie token in a SOAP header. That is, the Web service consumes the ObSSOCookie token; it is not involved in how the token is generated. Specifically, the WebLogic Server security service detects the token type and invokes the Oracle Access Manager Identity Asserter. The Oracle Access Manager Identity Asserter then validates the ObSSOCookie token against the Oracle Access Manager Access Server and obtains the username. The username is populated as the principal in the authenticated subject.

The Web service client, for example the Web application, must obtain the ObSSOCookie token to send it to the Web service. This is typically done using an AccessGate. AccessGate challenges the Web service client user for credentials (depending on the authentication scheme configured in Oracle Access Manager) and authenticates the user. The WebGate sends the ObSSOCookie to the user's browser upon successful authentication

The Web service client then sends the ObSSOCookie token in the SOAP request to the Web service.

Note:

Settings for the wss_oam_token_service_template are identical to the client version of the assertion: wss_oam_token_client_template. Identity store configuration for the service template is identical to the client version of the assertion.

About oracle/wss_oam_token_client_policy

This Oracle Web Services Manager policy contains the following policy assertion: oracle/wss_oam_token_client_template. This template inserts Oracle Access Manager credentials into the WS-Security header as part of the binary security token.

oracle/wss_oam_token_client_policy is the analogous client policy to the oracle/wss_oam_token_service_policy service endpoint policy. This policy can be enforced on any SOAP-based endpoint.

The following task overview outlines the procedures you must perform.

Task overview: Setting policies in Oracle Web Services Manager

1. Using Oracle Web Services Manager, set up a Web service with the oracle/wss_oam_token_service_policy policy.

2. Using Oracle Web Services Manager, set up a corresponding client for the Web service with the oracle/wss_oam_token_client_policy policy.

3. Configuring Providers in a WebLogic Domain for Oracle Web Services Manager.

See Also:

• Oracle Fusion Middleware Security and Administrator's Guide for Web Services

  "Configuring Policies"

  "Predefined Assertion Templates"

9.3.7.2 Configuring Providers in a WebLogic Domain for Oracle Web Services Manager

To use Oracle Access Manager Identity Asserter with Oracle Web Services Manager protected Web services, several Authentication providers must be configured and ordered in a WebLogic domain:

• OAM Identity Asserter: REQUIRED

• OID Authenticator: SUFFICIENT

• DefaultAuthenticator: SUFFICIENT

This procedure is nearly identical to the one for the Oracle Access Manager Identity Asserter with OAM 11g. The difference in this case is that Oracle Web Services Manager requires the custom 10g AccessGate and additional provider-specific values:

• Primary Access Server: Specify the host and part. For example: mnop:8888

• Access Gate Name: The name of the AccessGate registration protecting the application. For example: AG1

• Access Gate Password: The AccessGate password as specified in the OAM Administration Console.

You can add these using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

See Also:

• "About Oracle WebLogic Server Authentication and Identity Assertion Providers"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference

Note:

With a Oracle Fusion Middleware application installed, you have the required provider file. Skip Step 1.

To set up providers in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider if you have no Oracle Fusion Middleware application.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0). For example:

      oamAuthnProvider<version>.zip 
      

   3. Extract and copy the oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
       
      

2. Log in to the Oracle WebLogic Administration Console.

3. OAM Identity Asserter: Perform the following steps to add this provider:

   1. Click Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, click New, and then enter a name and select a type:

      Name: OAM Identity Asserter

      Type: OAMIdentityAsserter

      OK

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Common tab, set the Control Flag to REQUIRED, and click Save.

   5. Click the Common tab, specify ObSSOCookie as the chosen Action type for the 10g custom AccessGate, and click Save.

   6. Click the Provider Specific tab and configure these parameters:

      Primary Access Server: Specify the host and part. For example: abcd:7777

      Access Gate Name: The name of the OAM Agent registration protecting the application. For example: AG1

      Access Gate Password: The AccessGate password, if any, that was specified in during provisioning.

      Save.

4. OID Authenticator: Perform the following steps to add this provider.

   1. Click Security Realms, Default Realm Name, and click Providers

   2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      Click OK.

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

   5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Oracle Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Note:

      Do not set the All Groups filter as the default works fine as is.

      Click Save.

5. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

   1. Go to Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

   3. Click the Common tab and set the Control Flag to SUFFICIENT.

   4. Click Save.

6. Reorder Providers:

   1. Click Security Realms, Default Realm Name, Providers.

   2. On the Summary page where providers are listed, click the Reorder button

   3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

   4. Click OK to save your changes

7. Activate Changes: In the Change Center, click Activate Changes

8. Reboot Oracle WebLogic Server.

9. Proceed as follows:

   • Successful: Go to "Configuring Centralized Log Out for Oracle Access Manager 11g", and then return here to perform "Testing the Identity Asserter with Oracle Web Services Manager".

   • Not Successful: Confirm the all providers have the proper specifications for your environment, are in the proper order, and that oamAuthnProvider.jar is in the correct location as described in "Installing the Authentication Provider with Oracle Access Manager 11g".

9.3.7.3 Testing the Identity Asserter with Oracle Web Services Manager

To validate the use of the Oracle Access Manager Identity Asserter with Oracle Web Services Manager, you can access the Web service protected by the Identity Asserter and Oracle Web Services Manager policies. If access is granted, the implementation works. If not, see "Troubleshooting Tips for OAM Provider Deployments".

9.3.8 Configuring Centralized Log Out for Oracle Access Manager 11g

This section introduces Centralized logout for Oracle Access Manager 11g.

With OAM 11g, centralized logout refers to the process of terminating an active user session. Guidelines include:

• Applications must not provide their own logout page for use in an SSO environment.

• Applications must make their logout links configurable with a value that points to the logout URL specified by the OAM WebGate Administrator.

Note:

Oracle strongly recommends that applications use the ADF Authentication servlet, which in turn interfaces with OPSS, where a domain wide configuration parameter can be used to specify the logout URL. This way applications need not be modified or redeployed to change logout configuration.

For more information, see:

• Logout for 11g WebGate and OAM 11g

• Logout for 10g WebGate with Oracle Access Manager 11g

9.3.8.1 Logout for 11g WebGate and OAM 11g

Several elements in the OAM 11g Agent registration page enable centralized logout for OAM 11g WebGates. After agent registration, the ObAccessClient.xml file is populated with the information.

11g WebGate logout options that you must have in the agent registration include the following:

• Logout URL: Triggers the logout handler, which removes the cookie (ObSSOCookie for 10g WebGates; OAMAuthnCookie for 11g WebGates) and requires the user to re-authenticate the next time he accesses a resource protected by Oracle Access Manager.

• Logout Callback URL: The URL to oam_logout_success, which clears cookies during the call back. This can be a URI format without host:port (recommended), where the OAM Server calls back on the host:port of the original resource request.

• Logout Redirect URL: This parameter is automatically populated after agent registration completes.By default, this is based on the OAM Server host name with a default port of 14200.

• Logout Target URL: The value for this is name for the query parameter that the OPSS applications passes to WebGate during logout. This query parameter specifies the target URL of the landing page after logout.

For more information, see "Configuring Centralized Logout for 11g WebGate with OAM 11g Server" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

9.3.8.2 Logout for 10g WebGate with Oracle Access Manager 11g

Logout is initiated when an application causes the invocation of the logout.html file configured for the OAM Agent (in this case, a 10g WebGate). The application might also pass end_url as a query string to logout.html. The end_url parameter could either be a URI or a URL.

Task overview: Configuring centralized logout for 10g WebGates

1. Create a default logout page (logout.html) and make it available on the WebGate installation directory: For example, WebGate_install_dir/oamsso/logout.html.

2. In your logout.html, confirm that the logOutUrls parameter is configured for each resource WebGate and that <callBackUri> is the second value as part of 'logOutUrls'.

3. Ensure that the logout.html (from Step 1) redirects the user to this central logout URI, "/oam/server/logout' on the OAM 11g Server.

4. Optional: Allow the application to pass the end_url parameter indicating where to redirect the user after logout.

5. Check the OHS Web server configuration file, httpd.conf, on which the 10g WebGate is configured and if the following lines exist delete them.

   <LocationMatch "/oamsso/*">
   Satisfy any
   </LocationMatch>
   

For more information, see "Configuring Centralized Logout for 10g WebGate with OAM 11g Servers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

9.4 Deploying SSO Solutions with Oracle Access Manager 10g

This section provides the following topics:

• Installing and Setting Up Authentication Providers for OAM 10g

• Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g

• Configuring the Authenticator for Oracle Access Manager 10g

• Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g

• Oracle Access Manager Authentication Provider Parameter List

• Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

• Known Issues: JAR Files and OAMCfgTool

• Troubleshooting Tips for OAM Provider Deployments

9.4.1 Installing and Setting Up Authentication Providers for OAM 10g

This topic provides an overview of Oracle Access Manager installation and initial setup and additional information about installing components and files for use when you deploy the Oracle Access Manager Authentication Provider.

Unless explicitly stated, these topics describe requirements for both the Oracle Access Manager Identity Asserter and the Oracle Access Manager Authenticator:

• About Oracle Access Manager 10g Installation and Setup

• Installing Components and Files for Authentication Providers and OAM 10g

• Creating Resource Types in Oracle Access Manager 10g

9.4.1.1 About Oracle Access Manager 10g Installation and Setup

This topic provides a brief installation and setup overview if you are new to Oracle Access Manager.

See Also:

"Requirements for Using the Authentication Provider with Oracle Access Manager"

Access Servers: For the Oracle Access Manager Authentication Provider, you need two Access Servers for WebGates or AccessGates: one primary server and one secondary server. Currently, only one secondary Access Server is supported. Installing Access Servers includes:

• Adding an Access Server configuration profile in the Access System Console for the primary server. Ensure that the Access Management Service is On (also known as Policy Manager API Support Mode).

• Adding a secondary Access Server configuration profile with the Access Management Service On.

• Installing the primary Access Server instance.

• Installing the secondary Access Server instance.

WebGate/AccessGate: Whether you need a WebGate or an AccessGate depends on your use of the Oracle Access Manager Authentication Provider. For instance, the:

• Identity Asserter for Single Sign-On: Requires a separate WebGate and configuration profile for each application to define perimeter authentication. Ensure that the Access Management Service is On.

• Authenticator or Oracle Web Services Manager: Requires a separate AccessGate and configuration profile for each application. Ensure that the Access Management Service is On.

About OAM 10g WebGate/AccessGate Profiles and Policy Domains

This topic introduces the WebGate/AccessGate profiles, policy domains, and the methods you can use the create these.

While there are subtle differences between WebGates and AccessGates, these terms are often used interchangeably. In the Access System Console, the configuration profile for WebGates or AccessGates is known as an AccessGate profile. The Policy Manager is where an Oracle Access Manager policy domain is created.

Access System Console Method: Enables users with specific Oracle Access Manager administration rights to enter information and set parameters directly in Oracle Access Manager. This method is required if you are using the Authenticator, or if you have Oracle Web Services Manager policies protecting Web services.

OAMCfgTool Method: Application administrators who are implementing the Identity Asserter for single sign-on, can use OAMCfgTool to create a new WebGate profile for a fresh Web Tier. Required parameters are provisioned using values for your environment specified on the command line. Default values are accepted for non-required parameters; the Access Management Service is set to On. After creating a profile, values can be modified in the Access System Console.

Each AccessGate profile must include the following parameters; those marked with an asterisk, *, are provisioned with OAMCfgTool:

• *AccessGate Name—A unique name without spaces. With OAMCfgTool the name is derived from the app_domain value, appended with _AG.

• *Hostname—The name of the computer where the WebGate/AccessGate is or will be installed. With OAMCfgTool the app_domain value is used as the host name.

• *AccessGate Password—A unique password to verify and identify the component. This prevents unauthorized AccessGates from connecting to Access Servers and obtaining policy information. With OAMCfgTool, this is specified with the app_agent_password parameter. This should differ for each WebGate/AccessGate instance.

• Transport Security—The level of transport security between the Access Server and associated WebGates (these must match). The default value is Open. You can specify a different value with OAMCfgTool oam_aaa_mode value.

• *Preferred HTTP Host—The host name as it appears in all HTTP requests as users attempt to access the protected Web server. The host name in the HTTP request is translated into the value entered into this field, regardless of the way it was defined in a user's HTTP request. With OAMCfgTool the Preferred HTTP Host is the app_domain value.

  The Preferred Host function prevents security holes that can be inadvertently created if a host's identifier is not included in the Host Identifiers list. However, it cannot be used with virtual Web hosting. For virtual hosting, you must use the Host Identifiers feature.

• *Primary HTTP Cookie Domain: The Web server domain on which the WebGate is deployed. The cookie domain is required to enable single sign-on among Web servers; each must have the same Primary HTTP Cookie Domain value. Use the cookie_domain parameter with the OAMCfgTool to set this value.

See Also:

• "About Administrative Requirements for AccessGate Profiles and Policy Domains"

• "About Using OAMCfgTool"

• "Configuring WebGates and Access Servers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

About Administrative Requirements for AccessGate Profiles and Policy Domains

This topic introduces the administrative rights needed for the methods you can use when creating new WebGate and AccessGate profiles and policy domains for Oracle Access Manager.

An Oracle Access Manager Master Access Administrator must create the first policy domain after the policy domain root is defined. He or she can then create policy domains for URLs beneath the first one and delegate administration of those policy domains to other administrators.

Access System Console Method: You must be a Master or Delegated Access Administrator can use the Access System Console to create a new AccessGate profile, associate it with an Access Server, and create an authentication scheme. Master or Delegated Access Administrators can also use the Policy Manager to create a policy domain. The following deployments require this method:

• Authenticator

• Identity Asserter when Oracle Web Services Manager is protecting Web services

OAMCfgTool Method: You do not need specific Oracle Access Manager administration rights for OAMCfgTool, which automates creating and associating a WebGate profile and creating a new policy domain. However, this method can be used for only Identity Assertion. In a:

• Fresh Web Tier: Use OAMCfgTool to streamline creating a new WebGate profile and policy domain for Identity Asserter only.

  After creating the profile and policy domain with OAMCfgTool, these can be modified in the Access System Console.

  See Also:

  "About Using OAMCfgTool"

• Existing Web Tier: When one or more WebGates exist in the Web Tier, no new WebGate is needed. However, you can specify an existing host identifier to make newly established policies enforceable by an existing WebGate.

See Also:

• "Installing Components and Files for Authentication Providers and OAM 10g"

• "Configuring WebGates and Access Servers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

9.4.1.2 Installing Components and Files for Authentication Providers and OAM 10g

The following task overview outlines the components and files that must be installed and where to locate more information.

Note:

If you already have components installed and set up, you do not need to install new ones. Skip any steps that do not apply to your deployment.

Unless specifically stated, all details apply whether you intend to deploy the Identity Asserter for single sign-on, or the Authenticator, or if Oracle Web Services Manager policies are protecting Web services.

Task overview: Installing required components and files for Oracle Access Manager 10g Authentication Provider

1. An Oracle Internet Directory or Oracle Sun One LDAP directory server configured to be used by the Oracle Access Manager Access Server. Ensure that the directory server is tuned for your deployment.

   See Also:

   The following Release 11g (11.1.1.1.0) manuals

   • Oracle Fusion Middleware Installation Guide for Oracle Identity Management

   • Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

2. Install and set up Oracle WebLogic Server 10.3.1+.

   See Also:

   Item 3 in this list, and the Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server

3. Optional: Install a Fusion Middleware product (Oracle Identity Manager, Oracle SOA Suite, or Oracle Web Center for example):

   Note:

   Without a Fusion Middleware application, you must acquire the required JAR and WAR files as described in later procedures.

   1. Confirm the location of required JAR files in the following Fusion Middleware path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamAuthnProvider.jar
      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamcfgtool.jar
      

   2. Locate the console-extension WAR file in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprov 
      ider.war
      

   3. Copy the WAR file to the following path in the WebLogic Server home:

      WL_HOME/server/lib/console-ext/autodeploy/oamauthenticationprovider.war
      

4. Install OHS 11g for the Oracle Access Manager 10g (10.1.4.3) WebGate, if needed:

   • Authenticator or Oracle Web Services Manager: No Web server is required for the custom AccessGate. The protected resource is accessed using its URL on the Oracle WebLogic Server.

   • Oracle Access Manager Identity Asserter: Requires Oracle HTTP Server 11g Web server configured as a reverse proxy in front of Oracle WebLogic Server.

5. Install Oracle Access Manager 10g (10.1.4.3) components and perform initial setup as follows:

   See Also:

   "About Oracle Access Manager 10g Installation and Setup"

   1. Install an Identity Server; install a WebPass; set up the Identity System.

   2. Install and set up Policy Manager. Ensure that the policy protecting the Policy Manager, /access, is created and enabled, as well as the default authentication schemes.

   3. Install Access Servers (one as a primary server and one as a secondary server for WebGate).

      • Add an Access Server configuration profile in the Access System Console for the primary server for WebGate. Ensure that the Access Management Service is On (also known as Policy Manager API Support Mode).

      • Add a secondary Access Server configuration profile with the Access Management Service On.

      • Install the primary Access Server instance and then install the secondary Access Server instance.

        Note:

        Only one secondary Access Server is supported

   4. WebGate for Identity Asserter for Single Sign-On: In an existing Web Tier with one or more WebGates, no new WebGates or profiles are needed.

      See Also:

      "About Using OAMCfgTool"

      In a fresh Web Tier, you must create a profile to define the WebGate for perimeter authentication, as follows:

      • Create an AccessGate configuration profile to define the WebGate for perimeter authentication. Ensure that the Access Management Service is On. You can use the OAMCfgTool or Access System Console.

      • Associate the WebGate profile with a primary and a secondary Access Server.

      • Install a WebGate for Oracle HTTP Server 11g configured as a reverse proxy for every application.

      • Repeat until you have a profile and a WebGate protecting each application.

   5. AccessGate: For the Authenticator, or when you have Oracle Web Services, Manager you must add a new profile for custom AccessGates in the Access System Console

      See Also:

      "About OAM 10g WebGate/AccessGate Profiles and Policy Domains"

      • Add an AccessGate configuration profile in the Access System Console and ensure that the Access Management Service is On.

      • Associate the AccessGate profile with a primary and a secondary Access Server.

      • Deploy the custom AccessGate in oamAuthnProvider.jar.

      • Repeat until you have a profile and a AccessGate protecting each application.

6. Proceed as follows:

   • Create Resource Types: "Creating Resource Types in Oracle Access Manager 10g" must be performed if you use the Oracle Access Manager Authenticator or if you have Oracle Web Services Manager policies protecting Web services.

   • Identity Asserter for Single Sign-On: Perform tasks in "Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g".

   • Authenticator: Perform tasks in "Configuring the Authenticator for Oracle Access Manager 10g".

   • Oracle Web Services Manager: Perform tasks in "Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g".

   • "Troubleshooting Tips for OAM Provider Deployments".

9.4.1.3 Creating Resource Types in Oracle Access Manager 10g

This section describes how to create resource types in Oracle Access Manager to identify the types of resources that you want the policy domain to protect. You use the Oracle Access Manager Access System Console to define resource types as described here.

Note:

If you are using the Oracle Access Manager Identity Asserter for single sign-on, you can skip this task. In this case, only the default http resource type is used.

Defining the wl_authen resource type in Oracle Access Manager is required only when you are using:

• Oracle Access Manager Authenticator

• Identity Asserter with Oracle Web Services Manager

To define resource types in Oracle Access Manager 10g

1. Go to the Access System Console and log in.

2. Select the Access System Configuration tab, and then click Common Information Configuration, Resource Type Definitions, to display the List All Resource Types page.

3. On the List All Resource Types page, click Add, to display the Define a new Resource Type page.

4. Define the resource type with the following details:

   • Name: wl_authen

   • Display name: wl_authen

   • Resource matching: Case insensitive

   • Resource operation: LOGIN

5. Save the resource type you just defined.

6. Proceed as follows:

   • Authenticator: "Configuring the Authenticator for Oracle Access Manager 10g"

   • Oracle Web Services Manager: "Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g"

9.4.2 Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g

This section describes the unique steps needed to configure Oracle Access Manager Identity Assertion for Single Sign-On.

Prerequisites

Unless explicitly noted for the Authenticator or Oracle Web Services Manager, all tasks described in "Installing and Setting Up Authentication Providers for OAM 10g" should be performed, including:

• Installing Components and Files for Authentication Providers and OAM 10g

  Note:

  If you are implementing:

  • OAM 11g: Provision WebGates and security policies using the remote registration tool as described in "Provisioning an OAM Agent with Oracle Access Manager 11g".

  • OAM 10g: Add WebGate profiles and policies with OAMCfgTool as described in the following Task 3.

To configure Oracle Access Manager Identity Asserter for single sign-on with your application, perform the tasks as described in the following task overview.

Task overview: Deploying and configuring the Oracle Access Manager Identity Asserter for single sign-on includes

1. Ensuring that all prerequisite tasks have been performed

2. Establishing Trust with Oracle WebLogic Server

3. Configuring the Authentication Scheme for the Identity Asserter

4. Configuring Providers in the WebLogic Domain

5. Setting Up the Login Form for the Identity Asserter and OAM 10g

6. Testing Identity Assertion for SSO with OAM 10g

7. Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

9.4.2.1 Establishing Trust with Oracle WebLogic Server

The following topics explain the tasks you must perform to set up the application for single sign-on with the Oracle Access Manager Identity Asserter:

Note:

This task is the same for both OAM 11g and OAM 10g.

• Setting Up the Application Authentication Method for Identity Asserter for Single Sign-On

• Confirming mod_weblogic for Oracle Access Manager Identity Asserter

• Establishing Trust between Oracle WebLogic Server and Other Entities

9.4.2.1.1 Setting Up the Application Authentication Method for Identity Asserter for Single Sign-On

This topic describes how to create the application authentication method for Oracle Access Manager Identity Assertion.

See Also:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

When you use the Oracle Access Manager Identity Asserter, all web.xml files in the application EAR file must specify CLIENT-CERT in the element auth-method for the appropriate realm.

The auth-method can use BASIC, FORM, or CLIENT-CERT values. While these look like similar values in Oracle Access Manager, the auth-method specified in web.xml files are used by Oracle WebLogic Server (not Oracle Access Manager).

Note:

You can specify CLIENT-CERT, FORM if you are also planning to access the applications directly over WebLogic and want the WebLogic authentication scheme to be invoked.

To specify authentication in web.xml for the Identity Asserter and OAM 10g

1. Locate the web.xml file in the application EAR file:

   your_app/WEB-INF/web.xml  
   

2. Locate the auth-method in login-config and enter CLIENT-CERT.

   <login-config>
     <auth-method>CLIENT-CERT</auth-method>
   </login-config>
   

3. Save the file.

4. Redeploy and restart the application.

5. Repeat for each web.xml file in the application EAR file.

6. Proceed to "Confirming mod_weblogic for Oracle Access Manager Identity Asserter".

9.4.2.1.2 Confirming mod_weblogic for Oracle Access Manager Identity Asserter

Oracle Oracle HTTP Server includes the mod_weblogic plug-in module (mod_wl_ohs.so in 11g) which is already enabled. You can perform the following procedure to confirm this or skip this procedure.

With Oracle HTTP Server 11g, the mod_weblogic configuration is present in mod_wl_ohs.conf by default, and the path of this file is included in httpd.conf. If the mod_weblogic configuration is not present then you must edit httpd.conf.

To configure mod_weblogic for the Identity Asserter and OAM 10g

1. Locate httpd.conf. For example:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

2. Confirm that the following statement is in the file with appropriate values for your deployment (add or uncomment this, if needed):

   <IfModule mod_weblogic.c>
      WebLogicHost yourHost.yourDomain.com
        WebLogicPort yourWlsPortNumber
   </IfModule>
    
   <Location http://request-uri-pattern>
      SetHandler weblogic-handler
   </Location>
   

3. Save the file.

4. Proceed to "Establishing Trust between Oracle WebLogic Server and Other Entities".

9.4.2.1.3 Establishing Trust between Oracle WebLogic Server and Other Entities

The Oracle WebLogic Connection Filtering mechanism must be configured for creating access control lists and for accepting requests from only the hosts where Oracle HTTP Server and the front-end Web server are running.

Note:

This topic is the same whether you are using OSSO or Oracle Access Manager.

A network connection filter is a component that controls the access to network level resources. It can be used to protect resources of individual servers, server clusters, or an entire internal network. For example, a filter can deny non-SSL connections originating outside of a corporate network. A network connection filter functions like a firewall since it can be configured to filter protocols, IP addresses, or DNS node names. It is typically used to establish trust between Oracle WebLogic Server and foreign entities.

To configure a connection filter to allow requests from only mod_weblogic and the host where OHS 11g is running, perform the procedure here.

Note:

This chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs; the actual binary name is mod_wl_ohs.so. Examples show exact syntax for implementation.

WebLogic Server provides a default connection filter: weblogic.security.net.ConnectionFilterImpl. This filter accepts all incoming connections and also provides static factory methods that allow the server to obtain the current connection filter. To configure this connection filter to deny access, simply enter the connection filters rules in the WebLogic Server Administration Console.

You can also use a custom connection filter by implementing the classes in the weblogic.security.net package. Like the default connection filter, custom connection filters are configured in the WebLogic Server Administration Console.

Connection Filter Rules: The format of filter rules differ depending on whether you are using a filter file to enter the filter rules or you enter the filter rules in the Administration Console. When entering the filter rules on the Administration Console, enter them in the following format:

targetAddress localAddress localPort action protocols

Table 9-16 provides a description of each parameter in a connection filter.

Table 9-6 Connection Filter Rules

Parameter	Description
target	Specifies one or more systems to filter
localAddress	Defines the host address of the WebLogic Server instance. (If you specify an asterisk (*), the match returns all local IP addresses.)
localPort	Defines the port on which the WebLogic Server instance is listening. (If you specify an asterisk, the match returns all available ports on the server.)
action	Specifies the action to perform. This value must be allow or deny
protocols	Is the list of protocol names to match. The following protocols may be specified: http, https, t3, t3s, giop, giops, dcom, ftp, ldap. If no protocol is defined, all protocols match a rule.

The Connection Logger Enabled attribute logs successful connections and connection data in the server. This information can be used to debug problems relating to server connections.

See Also:

"Configuring Security in a WebLogic Domain" in Oracle Fusion Middleware Securing Oracle WebLogic Server

To configure a connection filter to allow requests from the host of the 11g Oracle HTTP Server

1. Log in to the Oracle WebLogic Administration Console.

2. Click Domain under Domain Configurations.

3. Click the Security tab, click the Filter tab.

4. Click the Connection Logger Enabled attribute to enable the logging of accepted messages for use when debugging problems relating to server connections.

5. Specify the connection filter to be used in the domain:

   • Default Connection Filter: In the Connection Filter attribute field, specify weblogic.security.net.ConnectionFilterImpl.

   • Custom Connection Filter: In the Connection Filter attribute field, specify the class that implements the network connection filter, which should also be specified in the CLASSPATH for Oracle WebLogic Server.

6. Enter the appropriate syntax for the connection filter rules.

7. Click Save.

8. Restart the Oracle WebLogic Server.

9. Proceed to "Configuring the Authentication Scheme for the Identity Asserter".

9.4.2.2 Configuring the Authentication Scheme for the Identity Asserter

This topic focuses on using OAMCfgTool for OAM 10g. If you are using OAM 11g, skip this topic and instead perform tasks in "Provisioning an OAM Agent with Oracle Access Manager 11g".

After setting up your application, you must protect it with Oracle Access Manager. To help automate this task, Oracle provides the command-line tool: OAMCfgTool in the Fusion Middleware application-provided oamcfgtool.jar file for OAM 10g.

While you can perform steps manually in the Access System Console and Policy Manager, you can optionally use OAMCfgTool to setup and validate a form-based authentication scheme, a policy domain for the application, and Oracle Access Manager access policies required for Identity Assertion for single sign-on. Additionally, you can create a new WebGate profile in a fresh Web Tier or modify a WebGate profile in an existing Web Tier.

For more information, see:

• About Using OAMCfgTool

• OAMCfgTool Process Overview

• Using OAMCfgTool to Create an Authentication Scheme, Policy Domain, and a WebGate Profile for Identity Assertion

9.4.2.2.1 About Using OAMCfgTool

This topic introduces OAMCfgTool, which can be used only if you are deploying the Oracle Access Manager Identity Asserter for single sign-on.

OAMCfgTool launches a series of scripts to request information and set up the required profiles and policies in Oracle Access Manager. OAMCfgTool runs in the following modes:

• CREATE mode

  java -jar oamcfgtool.jar mode=CREATE param=value 
  

• VALIDATE mode

  java -jar oamcfgtool.jar mode=VALIDATE param=value   
  

Unless you specify an LDIF output file, configuration changes are written directly in the LDAP directory server that is configured with Oracle Access Manager. When configuration changes are written to an LDIF file, it can be loaded into the directory server for Oracle Access Manager at a later time. Without an LDIF file, Oracle Access Manager cache flush is triggered so that changes are implemented immediately.

You can also specify a log level and an output file for logging details. If errors occur when running OAMCfgTool, these are reported on the command line.

Table 9-7 provides both required and optional OAMCfgTool parameters and values for CREATE mode. You can specify multiple parameters at one time. See also, "Known Issues: JAR Files and OAMCfgTool".

Note:

• By default, OAMCfgTool will prompt for required passwords on the command line in a secure way if you do not enter them. For example:

  Enter app_agent_password:
  Enter ldap_userpassword: 
  Enter oam_aaa_passphrase: 
  Processed input parameters 
  

• A -noprompt option is available to avoid the password prompt

Table 9-7 OAMCfgTool CREATE Mode Parameters and Values

Parameters	CREATE Mode Values
Required Parameters	Values
app_domain	Name of the Oracle Access Manager policy domain to protect the application. Within the Policy Manager this is known as the policy domain name.
protected_uris	URIs for the protected application in a comma separated list (with or without spaces): /myapp/login, for example.
app_agent_password	Password to be provisioned for the WebGate. In the AccessGate Profile within the Access System Console, this parameter is known as the AccessGate Password. Your entry appears in clear text on the command line but is not captured in a log file.
ldap_host	DNS name of the computer hosting the LDAP directory server for Oracle Access Manager Note: SSL-enabled communication with the directory server is not supported.
ldap_port	Port of the LDAP directory server
ldap_userdn	The valid DN of the LDAP administrative user, entered as a quoted string. In Oracle Access Manager this is known as the Root DN or Bind DN.
ldap_userpassword	Password of LDAP administrative user. Passwords appear in clear text but are not captured in a log file.
oam_aaa_host	DNS name of the computer hosting an accessible Access Server. OAMCfgTool does not recognize primary and secondary Access Server designations. Set up the WebGate profile with a single accessible Access Server. Oracle Access Manager can later associate the profile with designated Access Servers.
oam_aaa_port	Listening port on the accessible Access Server
Optional	Values
-help	Provides a list of parameters and descriptions.
web_domain	Fresh Web Tier: Omit web_domain to create a new WebGate profile. The profile is populated with a WebGate name, Host name, and Preferred HTTP host all using the same app_domain value as follows: app_domain=ABC (without web_domain) WebGate name: ABC_AG (here _AG is appended to the app_domain) Host: ABC Preferred HTTP Host: ABC Existing Web Tier: Include web_domain to specify the name of an existing host identifier in Oracle Access Manager to tie new policies to an existing host ID. For example: web_domain=existing_host_Identifier When WebGate intercepts a request, it checks the request for an address. If the address is on the host identifiers list, this address is mapped to the official host name, and the Access System can apply the rules and policies that protect the resource. If virtual Web hosting is supported, you supply a reserved name in the Preferred HTTP Host field instead of a host name variation. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.
cookie_domain	Name of the domain to use for the ObSSOCookie. Within the AccessGate Profile in the Access System Console, this is known as the Primary HTTP Cookie Domain. Use this parameter when you create a new WebGate profile in a fresh Web Tier.
public_uris	URIs that must be unprotected using the Anonymous authentication scheme. You can identity public URIs by providing a comma separated list: "uri1,uri2,uri3", for example. The default URL pattern that is part of the URIs is created: /.../public/.../. For example "uri1,uri2,uri3" creates 3 public URLs which include "/.../public/.../" as a default URL pattern. Users can log in to Policy Manager and change the URL patterns, if needed.
ldap_base	Base from which all LDAP searches are performed. Note: If Oracle Access Manager user data and configuration data are stored in different directory servers, the following information is required for each: ldap_host= ldap_port= ldap_userdn= ldap_userpassword= ldap_base=
oam_aaa_mode	Transport security mode of the accessible Access Server: OPEN, SIMPLE, or CERT. Default presumes OPEN.
oam_aaa_passphrase	Passphrase required for SIMPLE mode transport security mode only. The passphrase appears in clear text but is not captured in a log file.
log_file	Name of the OAMCfgTool log file. Output to the screen is the default.
log_level	Level for OAMCfgTool logging: ALL, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, OFF (the default).
output_ldif_file	Name of the LDIF file in which to store details from OAMCfgTool operations to load into the LDAP directory server later. If none is specified, changes are written immediately to the LDAP directory server and caches in Oracle Access Manager are flushed to make new information available.

Master or Delegated Access Administrators can check Oracle Access Manager directly to validate policy domain and WebGate profile setup.

Note:

You cannot use OAMCfgTool mode to validate AccessGate profile creation.

Using OAMCfgTool in VALIDATE mode, you can ensure that the policy domain for single sign-on configuration is correct. In this case, a set of requests are sent automatically to protected resources.

Table 9-8 provides both required and optional OAMCfgTool parameters and values for VALIDATE mode.

Table 9-8 OAMCfgTool VALIDATE Mode Parameters and Values

VALIDATE Mode Parameters	VALIDATE Mode Values for Required Parameters
Required Parameters	Values
app_domain	Name of the Oracle Access Manager policy domain that was created to protect the Application.
ldap_host	DNS name of the computer hosting the LDAP directory server for Oracle Access Manager.
ldap_port	Port of the LDAP directory server.
ldap_userdn	The valid DN of the LDAP administrative user, entered as a quoted string. In Oracle Access Manager this is known as the Root DN or Bind DN.
ldap_userpassword	Password of the LDAP administrative user. Passwords appear in clear text but are not captured in a log file.
oam_aaa_host	DNS name of the computer hosting the Access Server.
oam_aaa_port	Listening port on the Access Server host.
test_username	User name to be used for policy validation.
test_userpassword	User password to be used for policy validation. Passwords appear in clear text but are not captured in a log file
Optional Parameters	Values
web_domain	Host identifier
ldap_base	Base from which all LDAP searches are done. In Oracle Access Manager this is known as the search base or configuration base. For example: dc=company,c=us. Note: If Oracle Access Manager user data and configuration data are stored in different directory servers, the following information is required for each: ldap_host= ldap_port= ldap_userdn= ldap_userpassword= ldap_base=
oam_aaa_mode	Transport security mode of the accessible Access Server: OPEN, SIMPLE, or CERT. Default presumes OPEN.
oam_aaa_passphrase	Passphrase required for SIMPLE mode transport security mode only. Your entry appears in clear text. However, it is not captured in a log file.
log_file	Name of the OAMCfgTool log file. Output to the screen is the default.
log_level	Level for OAMCfgTool logging: ALL, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, OFF (the default).

9.4.2.2.2 OAMCfgTool Process Overview

This topic describes the processing that occurs when you use OAMCfgTool with various parameters and values for your environment.

This topic focuses on using OAMCfgTool for OAM 10g. If you are using OAM 11g, skip this topic and instead refer to the chapter on remote registration in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Process overview: OAMCfgTool creates the authentication scheme, policy domain, and WebGate profile

1. The app_domain parameter creates a policy domain in the Policy Manager to enable authentication for the application.

2. The web_domain parameter creates a host identifier that connects the WebGate host sending requests to your application and links the policy to the existing WebGate. If no existing access policy uses this host identifier, a new policy is set up.

   Note:

   In a fresh Web Tier the web_domain parameter should be omitted in CREATE mode to create new WebGate profile. In this case, as described in Table 9-7:

   • app_domain specifies the WebGate name, host name, and Preferred HTTP Host

   • app_agent_password specifies the AccessGate password

   • cookie_domain specifies the Primary HTTP Cookie Domain

   • oam_aaa parameters associate the profile with the Access Server

3. The protected_uris parameter defines application-specific URL's to protect HTTP resources using the host identifier (or the new WebGate/AccessGate profile created in Step 2).

4. The public_uris parameter creates a Public_URI_Policy to unprotect certain URIs for http resources (GET and POST operations) in app_domain name.

5. The LDAP parameters specify the directory server used by Oracle Access Manager to identity the searchbase from which all LDAP queries are performed. For more information, see Table 9-7

6. The log file and level parameters specify an output file and logging level for OAMCfgTool.

7. The output_ldif_file parameter defines the name of the LDIF file that is created to be loaded later in the directory server, if specified. Otherwise, configuration changes are written to the directory server

9.4.2.2.3 Sample Policy Domain and AccessGate Profile Created with OAMCfgTool

This topic describes and illustrates the results of running OAMCfgTool when viewed in Oracle Access Manager:

• My Policy Domains

• Policy Domain, General Tab

• Policy Domain, Resources Tab

• Policy Domain, Authorization Rules Tab

• Policy Domain, Default Rules Tab

• Policy Domain, Policies Tab

• Policy Domain, Delegated Access Admins Tab

• Host Identifiers

• AccessGate Profile

Note:

This topic focuses on using OAMCfgTool for OAM 10g. If you are using OAM 11g, see the chapter on remote registration in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

My Policy Domains

Name: app_domain value specified with OAMCfgTool

Policy Domain, General Tab

Figure 9-9 illustrates the General tab in a sample policy domain created with OAMCfgTool. The Description is provided automatically.

Name: app_domain value specified with OAMCfgTool
Description: includes the app_domain value created by user@hostname ...

Note:

For descriptions only, the Java API retrieves the current user from the operative platform and the name of the computer host: user@hostname.

Figure 9-9 Sample OAMCfgTool Policy Domain General Tab

Description of "Figure 9-9 Sample OAMCfgTool Policy Domain General Tab"

Policy Domain, Resources Tab

Figure 9-10 illustrates the Resources tab in a sample policy domain created with OAMCfgTool. The http resource type is the default. The host identifier and URL prefixes are derived from OAMCfgTool parameters and the values you enter. The Description is provided automatically.

Host Identifier: app_domain value
URL Prefix: protected_uris values

Figure 9-10 Sample OAMCfgTool Policy Domain Resources Tab

Description of "Figure 9-10 Sample OAMCfgTool Policy Domain Resources Tab"

Policy Domain, Authorization Rules Tab

Figure 9-11 illustrates the Authorization Rules tab in a sample policy domain created with OAMCfgTool. Details found on sub tabs follow the figure. Authorization rules are automatically configured for the policy domain when you use OAMCfgTool.

Figure 9-11 Sample OAMCfgTool Policy Domain Authorization Rules Tab

Description of "Figure 9-11 Sample OAMCfgTool Policy Domain Authorization Rules Tab"

Timing Conditions: There are no timing conditions defined. This rule is always valid.
Actions: There are no actions defined.
Allow Access: Role: Anyone
Deny Access: No one is denied access.

Policy Domain, Default Rules Tab

Figure 9-12 illustrates the Default Rules tab in a sample policy domain created with OAMCfgTool. All values are configured automatically for the policy domain; details on sub tabs follow the figure.

Authentication Rule
General, see Figure 9-12.
Actions: There are no actions defined.

Figure 9-12 Sample OAMCfgTool Policy Domain Default Rules Tab

Description of "Figure 9-12 Sample OAMCfgTool Policy Domain Default Rules Tab"

Authorization Expression
Authorization Expression: Default_Authorization
Duplicate Actions: No policy defined for this Authorization Expression. The
Access System level default policy for dealing with duplicate
action headers are employed.
Actions
Authorization Success
Return Type Name Attribute
HeaderVar REMOTE_USER uid
HeaderVar OAM_REMOTE_USER uid

Policy Domain, Policies Tab

Figure 9-13 illustrates the Policies tab, General sub tab, in a sample policy domain created using parameters and values that you specify with OAMCfgTool. The host identifiers are based on your app_domain value. Details on other sub tabs follow the figure.

Figure 9-13 Sample OAMCfgTool Policy Domain Policies Tab

Description of "Figure 9-13 Sample OAMCfgTool Policy Domain Policies Tab"

Authentication Rule
General
Name: Anonymous
Description: Authentication scheme allows un-authenticated access to some
URIs
Authentication Scheme: Anonymous Authentication (Default)
Actions: There are no actions defined.

Authorization Expression
There is no Authorization Expression defined.

Audit Rule
There is no Master Audit Rule defined.
If you would like to add an auditing rule to this Policy, please contact your
Access System Administrator.

Policy Domain, Delegated Access Admins Tab

Figure 9-14 illustrates the Delegated Access Admins tab in a sample policy domain created using OAMCfgTool. No parameters are specified with the tool to set up delegated rights for Master Web resource Admins.

Figure 9-14 OAMCfgTool Policy Domain Delegated Access Admins Tab

Description of "Figure 9-14 OAMCfgTool Policy Domain Delegated Access Admins Tab"

See Also:

"Protecting Resources with Policy Domains" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Host Identifiers

You can find the Host Identifiers created with OAMCfgTool in the Access System Console, under the Access System Configuration tab.

Figure 9-15 illustrates a sample host identifiers created using OAMCfgTool. As described here, required parameters are derived from the value entered with OAMCfgTool app_domain parameter. A Description is provided by OAMCfgTool.

Figure 9-15 Sample OAMCfgTool Host Identifiers

Description of "Figure 9-15 Sample OAMCfgTool Host Identifiers"

AccessGate Profile

Figure 9-16 illustrates a sample AccessGate profile created using OAMCfgTool when the web_domain parameter is omitted. The profile is in the Access System Console. As described here, required profile parameters are derived from values entered with OAMCfgTool. Other profile parameters use default values. A Description is provided by OAMCfgTool.

Name: app_domain value _AG
Hostname: app_domain value
Access Gate Password: app_agent_password value
ASDK Client
Access Management Service: On
Web Server Client
Primary HTTP Cookie Domain: cookie_domain value
Preferred HTTP Host: app_domain value

Figure 9-16 Sample OAMCfgTool AccessGate Profile

Description of "Figure 9-16 Sample OAMCfgTool AccessGate Profile"

9.4.2.2.4 Using OAMCfgTool to Create an Authentication Scheme, Policy Domain, and a WebGate Profile for Identity Assertion

This topic provides a procedure that you can use as a model when you run OAMCfgTool.

This example presumes a fresh Web Tier that requires a new WebGate profile. Therefore, the web_domain= parameter is omitted. A new profile is created and named with the app_domain value (appended with _AG).

The following procedure is only an example to illustrate how to use the tool. Values for your environment will be different.

Note:

If you have an Oracle Fusion Middleware application installed you already have the OAMCfgTool. In this case, skip Step 1.

To create a form authentication scheme, policy domain, and access polices with OAMCfgTool

1. No Oracle Fusion Middleware Application: Obtain the OAMCfgTool if you have no Oracle Fusion Middleware application.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the OAMCfgTool ZIP file with Access Manager Core Components (10.1.4.3.0):

      oamcfgtool<version>.zip  
      

   3. Extract and copy oamcfgtool.jar to the computer hosting WebGate.

2. Confirm that JDK 1.6 (or the latest version) is installed and configured.

3. Log in to the computer that is hosting the application to protect, change to the file system directory containing OAMCfgTool.

   Note:

   • Fresh Web Tier: Omit web_domain parameter to create and associate a new a profile. Include the cookie_domain parameter.

   • Existing Web Tier: Include web_domain parameter with the value of an existing host identifier.

4. Create a WebGate Profile, Authentication Scheme, and Policy Domain: Run the following command using values for your environment as described in Table 9-7. For example:

   java -jar oamcfgtool.jar mode=CREATE app_domain=IASSO_App1 
   protected_uris=/myapp/login
   app_agent_password=<WebGate_password> 
   cookie_domain=<preferred_http_cookie_domain>
   ldap_host=wxyz
   ldap_port=6633
   ldap_userdn=orcladmin
   ldap_userpassword=<ldap_userpassword>
   oam_aaa_host=abcd
   oam_aaa_port=7789
   oam_aaa_mode=cert
   log_file=OAMCfg_date.log
   log_level=INFO
   output_ldif_file=<LDIF_filename>
   

5. Review the information provided by the tool. For example, the parameters and values in Step 3 would provide the following information:

   Processed input parameters
   Initialized Global Configuration
   Successfully completed the Create operation.
    Operation Summary:
        Policy Domain  : IASSO_App1
        Host Identifier: IASSO_App1
        Access Gate ID : IASSO_App1_AG
   

6. Output LDIF Created: Import the LDIF to write information to the directory server. Otherwise, skip this step.

7. Validate: Run OAMCfgTool to validate the policy domain that was created (see Table 9-8). For example:

   java -jar oamcfgtool.jar mode=VALIDATE app_domain=IASSO_App1 
   protected_uris=/myapp/login
   ldap_host=wxyz
   ldap_port=6633
   ldap_userdn=orcladmin
   ldap_userpassword=<ldap_userpassword> 
   oam_aaa_host=abcd
   oam_aaa_port=7789
   log_file=OAMCfg_date.log
   log_level=INFO
   test_username=gcf
   test_userpassword=<test_userpassword> 
   

8. Fresh WebGate Profile/WebGate Not Installed: Specify the same values when you install the WebGate as you specified when creating the profile (plus additional values to properly finish the installation).

9. Fresh WebGate Profile with Installed WebGate: Using output from the OAMCfgTool Create command, run the Oracle Access Manager configureWebgate tool to set up the installed WebGate. For example:

   1. Go to:

      WebGate_install_dir\access\oblix\tools\configureWebGate

      where WebGate_install_dir is the directory where WebGate is installed.

   2. Run the following command to configure the WebGate using values specified with OAMCfgTool and other values needed to finish the profile. For example:

      configureWebGate -i WebGate_install_dir -t WebGate WebGate_Name -P 
      WebGate_password
      -m <open|simple|cert>
      -h Access_Server_Host_Name
      -p Access_Server_Port
      -a Access_Server_ID
      -r Access_Server_Pass_Phrase (must be the same as the WebGate_password)
      -Z Access_Server_Retry count
      

      See Also:

      "Configuring AccessGates and WebGates" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

10. Confirm Profile in the Access System Console: Perform the following steps to view or modify the WebGate profile.

    1. Log in to the Access System Console as a Master or Delegated Access Administrator. For example:

            http://hostname:port/access/oblix
       

       hostname refers to computer that hosts the WebPass Web server; port refers to the HTTP port number of the WebPass Web server instance; /access/oblix connects to the Access System Console.

    2. Click Access System Configuration, and then click AccessGate Configuration.

    3. Click the All button to find all profiles (or select the search attribute and condition from the lists) and then click Go.

    4. Click a WebGate's name to view its details.

    5. Click Cancel to dismiss the page without changes, or click Modify to change values as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

11. Repeat Steps 3 through 8 for each application that you are protecting.

12. Proceed to "Configuring Providers in the WebLogic Domain".

9.4.2.3 Configuring Providers in the WebLogic Domain

This topic is divided as follows:

• About Oracle WebLogic Server Authentication and Identity Assertion Providers

• About the Oracle WebLogic Scripting Tool (WLST)

• Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO

• Setting Up Providers for Oracle Access Manager Identity Assertion

9.4.2.3.1 About Oracle WebLogic Server Authentication and Identity Assertion Providers

This topic introduces only a few types of Authentication Providers for a WebLogic security realm, if you are new to them.

Each WebLogic security realm must have one at least one Authentication Provider configured. The WebLogic Security Framework is designed to support multiple Authentication Providers (and thus multiple LoginModules) for multipart authentication. As a result, you can use multiple Authentication Providers as well as multiple types of Authentication Providers in a security realm. The Control Flag attribute determines how the LoginModule for each Authentication Provider is used in the authentication process.

Oracle WebLogic Server offers several types of Authentication and Identity Assertion providers including, among others:

• The default WebLogic Authentication Provider (Default Authenticator) allows you to manage users and groups in one place, the embedded WebLogic Server LDAP server. This Authenticator is used by the Oracle WebLogic Server to login administrative users.

• Identity Assertion providers use token-based authentication; the Oracle Access Manager Identity Asserter is one example.

• LDAP Authentication Providers store user and group information in an external LDAP server. They differ primarily in how they are configured by default to match typical directory schemas for their corresponding LDAP server.

  Oracle WebLogic Server 10.3.1+ provides the OracleInternetDirectoryAuthenticator.

When you configure multiple Authentication Providers, use the JAAS Control Flag for each provider to control how the Authentication Providers are used in the login sequence. You can choose the following the JAAS Control Flag settings, among others:

• REQUIRED—The Authentication Provider is always called, and the user must always pass its authentication test. Regardless of whether authentication succeeds or fails, authentication still continues down the list of providers.

• SUFFICIENT—The user is not required to pass the authentication test of the Authentication Provider. If authentication succeeds, no subsequent Authentication Providers are executed. If authentication fails, authentication continues down the list of providers.

• OPTIONAL—The user is allowed to pass or fail the authentication test of this Authentication Provider. However, if all Authentication Providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.

When additional Authentication Providers are added to an existing security realm, the Control Flag is set to OPTIONAL by default. You might need to change the setting of the Control Flag and the order of providers so that each Authentication Provider works properly in the authentication sequence.

See Also:

"Configuring Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server for a complete list of Authentication Providers and details about configuring the Oracle Internet Directory provider to match the LDAP schema for user and group attributes

9.4.2.3.2 About the Oracle WebLogic Scripting Tool (WLST)

This topic introduces WLST, if you are new to it.

You can add providers to a WebLogic domain using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

WLST is a Jython-based command-line scripting environment that you can use to manage and monitor WebLogic Server domains. Generally, you can use this tool online or offline. You can use this tool interactively on the command line in batches supplied in a file (Script Mode, where scripts invoke a sequence of WLST commands without requiring your input), or embedded in Java code.

When adding Authentication Providers to a WebLogic domain, you can use WLST online to interact with an Authentication Provider and add, remove, or modify users, groups, and roles.

When you use WLST offline to create a domain template, WLST packages the Authentication Provider's data store along with the rest of the domain documents. If you create a domain from the domain template, the new domain has an exact copy of the Authentication Provider's data store from the domain template. However, you cannot use WLST offline to modify the data in an Authentication Provider's data store.

Note:

You cannot use WLST offline to modify the data in an Authentication Provider's data store.

See Also:

• "Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference "Infrastructure Security Commands" chapter

9.4.2.3.3 Configuring Oracle WebLogic Server for a Web Application Using ADF Security, OAM SSO, and OPSS SSO

On the Oracle WebLogic Server, you can run a Web application that uses Oracles Application Development Framework (Oracle ADF) security, integrates with Oracle Access Manager Single Sign On (SSO), and uses Oracle Platform Security Services (OPSS) SSO for user authentication. However before the Web application can be run, you must configure the domain-level jps-config.xml file on the application's target Oracle WebLogic Server for the Oracle Access Manager security provider.

The domain-level jps-config.xml file is in the following path and should not be confused with the the deployed application's jps-config.xml file:

domain_home/config/fmwconfig/jps-config.xml 

You can use an Oracle Access Manager-specific WLST script to configure the domain-level jps-config.xml file, either before or after the Web application is deployed. This Oracle JRF WLST script is named as follows:

Linux: wlst.sh

Windows: wlst.cmd

The Oracle JRF WLST script is available in the following path if you are running through JDev:

     $JDEV_HOME/oracle_common/common/bin/

In a standalone JRF WebLogic installation, the path is:

     $Middleware_home/oracle_common/wlst

Note:

The Oracle JRF WLST script is required. When running WLST for Oracle Java Required Files (JRF), do not use the WLST script under $JDEV_HOME/wlserver_10.3/common/bin.

Command Syntax

addOAMSSOProvider(loginuri, logouturi, autologinuri)

Table 9-9 defines the expected value for each argument in the addOAMSSOProvider command line.

Table 9-9 addOAMSSOProvider Command-line Arguments

Argument	Definition
loginuri	Specifies the URI of the login page
logouturi	Specifies the URI of the logout page
autologinuri	Specifies the URI of the autologin page

See Also:

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference "Infrastructure Security Commands" chapter

Prerequisites

Before starting this task, ensure that all previous tasks have been performed as described in:

• Establishing Trust with Oracle WebLogic Server

• Configuring the Authentication Scheme for the Identity Asserter

To modify domain-level jps-config.xml for a Fusion Web application with Oracle ADF Security enabled

1. On the computer hosting the Oracle WebLogic Server and the Web application using Oracle ADF security, locate the Oracle JRF WLST script. For example:

   cd $ORACLE_HOME/oracle_common/common/bin
   

2. Connect to the computer hosting the Oracle WebLogic Server:

   connect login_id password hostname:port
   

   For example, the Oracle WebLogic Administration Server host could be localhost using port 7001. However, your environment might be different.

3. Enter the following command-line arguments with values for the application with ADF security enabled:

   addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication", 
   logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
   

4. Stop and start the Oracle WebLogic Server.

5. Perform the following tasks as described in this chapter:

   • Setting Up the Login Form for the Identity Asserter and OAM 10g

   • Testing Identity Assertion for SSO with OAM 10g

   • Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

6. Run the application.

9.4.2.3.4 Setting Up Providers for Oracle Access Manager Identity Assertion

This topic describes how to configure providers in the WebLogic security domain to perform single sign-on with the Oracle Access Manager Identity Asserter. Several Authentication Provider types must be configured and ordered:

• OAM Identity Asserter: REQUIRED

• OID Authenticator: SUFFICIENT

• DefaultAuthenticator: SUFFICIENT

See Also:

"About Oracle WebLogic Server Authentication and Identity Assertion Providers"

The following procedure uses the WebLogic Administration Console.

Note:

With an Oracle Fusion Middleware application installed, you have the required provider JAR file. Skip Step 1.

To set up Providers for Oracle Access Manager single sign-on in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider:

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0):

      oamAuthnProvider<version number>.zip  
      

   3. Extract and copy oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
      

2. With Oracle Fusion Middleware Application Installed:

   1. Locate oamauthenticationprovider.war in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprovi
      der.war
      

   2. Copy oamauthenticationprovider.war to the following location:

      BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      

3. Log in to the WebLogic Administration Console.

4. Click Security Realms, Default Realm Name, and click Providers.

5. OAM Identity Asserter: Perform the following steps to add this provider:

   1. Click Authentication, click New, and then enter a name and select a type:

      Name: OAM Identity Asserter

      Type: OAMIdentityAsserter

      OK

   2. In the Authentication Providers table, click the newly added authenticator.

   3. Click the Common tab, set the Control Flag to REQUIRED, and click Save

6. OID Authenticator: Perform the following steps to add this provider.

   1. Click Security Realms, Default Realm Name, and click Providers

   2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      OK

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

   5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Oracle Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Do not set the All Groups filter as the default works fine as is.

      Save.

7. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

   1. Go to Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

   3. Click the Common tab and set the Control Flag to SUFFICIENT.

   4. Save.

8. Reorder Providers:

   1. Click Security Realms, Default Realm Name, Providers.

   2. On the Summary page where providers are listed, click the Reorder button

   3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

   4. Click OK to save your changes

9. Activate Changes: In the Change Center, click Activate Changes

10. Reboot Oracle WebLogic Server.

11. Proceed as follows:

    • Successful: Go to "Setting Up the Login Form for the Identity Asserter and OAM 10g".

    • Not Successful: Confirm that all providers have the proper specifications for your environment, are in the proper order, and that oamAuthnProvider.jar is in the correct location as described in "Installing Components and Files for Authentication Providers and OAM 10g".

9.4.2.4 Setting Up the Login Form for the Identity Asserter and OAM 10g

This topic introduces the login form provided for the Oracle Access Manager Identity Asserter for single sign-on and provides a procedure that you can use to deploy the form.

The form shown in Figure 9-17 is provided with the WebGate installation for Oracle HTTP Server 11g Web server. The form contains two fields (UserID and Password) and a Login button. The variables in this form are required by the Form Login authentication scheme that was generated by the OAMCfgTool and used in the policy domain protecting resources for Identity Assertion.

Figure 9-17 Default Login Form for Single Sign-On with 10g WebGates

Description of "Figure 9-17 Default Login Form for Single Sign-On with 10g WebGates"

Note:

Do not alter any variables in this login form. Variables are required for use with Oracle Access Manager Identity Asserter.

The following information is added to the Oracle HTTP Server 11g Web server httpd.conf file during WebGate installation and configuration. It ensures that WebGate for Oracle HTTP Server 11g can find the default login form.

Alias /oamsso "/oam/webgate/access/oamsso"

Delete the following three lines if they exist:

<LocationMatch "/oamsso/*">
Satisfy any
</LocationMatch>

The following procedure guides as you set up the login form for your environment.

Note:

The Login form is for only 10g WebGates with OAM 10g.

To set up the login form for Identity Assertion and OAM 10g

1. Verify that the login form is located in the following Oracle HTTP Server11g WebGate path on the computer hosting the application:

   WebGate_install_dir/access/oamsso/login.html

2. From your browser, go to the following URL:

   http://WebGatehost:port/oamsso/login.html

3. Confirm that the /access policy was created and enabled to protect Policy Manager resources to ensure that the login process can redirect authenticated users to the originally requested application URL.

4. Proceed to:

   • Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

   • Testing Identity Assertion for SSO with OAM 10g

9.4.2.5 Testing Identity Assertion for SSO with OAM 10g

The following procedure describes how to test your Oracle Access Manager Identity Assertion setup.

Alternatively, you can run Access Tester within Oracle Access Manager 10g to test your policy domain, as described in the 10g Oracle Access Manager Access Administration Guide.

To validate Identity Assertion for SSO with OAM 10g

1. Enter the URL to access the protected resource in your environment. For example:

   http://ohs_server:port/<protected url>
   

2. Provide appropriate credentials when the login form appears.

   • Successful: The implementation works.

   • Not Successful: See "Troubleshooting Tips for OAM Provider Deployments".

9.4.3 Configuring the Authenticator for Oracle Access Manager 10g

To configure the Oracle Access Manager Authentication Provider as the Authenticator, you must perform the tasks in this section.

Prerequisites

Unless explicitly labeled Identity Assertion, all tasks described in "Installing and Setting Up Authentication Providers for OAM 10g" must be completed:

• Installing Components and Files for Authentication Providers and OAM 10g which includes manually creating AccessGate profiles in the Access System Console and accepting defaults during Policy Manager setup

  See Also:

  • "About Oracle Access Manager 10g Installation and Setup"

  • "About OAM 10g WebGate/AccessGate Profiles and Policy Domains"

• Creating Resource Types in Oracle Access Manager 10g

Remaining tasks to configure the Oracle Access Manager Authenticator are described in the following task overview.

Note:

You must be either a Master or Delegated Access Administrator in Oracle Access Manager to perform tasks here. There is no tool available to automate tasks outside Oracle Access Manager.

Task overview: Configuring the Oracle Access Manager Authenticator includes

1. Ensuring that all prerequisite tasks have been performed

2. Creating an Authentication Scheme for the Authenticator

3. Configuring a Policy Domain for the Oracle Access Manager Authenticator

4. Configuring Providers for the Authenticator in a WebLogic Domain

5. Configuring the Application Authentication Method for the Authenticator

6. Mapping the Authenticated User to a Group in LDAP

7. Testing the Oracle Access Manager Authenticator Implementation

9.4.3.1 Creating an Authentication Scheme for the Authenticator

This topic describes how to create an authentication scheme for the policy domain you will define for the Authenticator later. The Oracle Access Manager authentication scheme must be available before you create the policy domain.

With the Authenticator, the user is challenged for credentials based on the authentication method that is configured within the application web.xml. However, an Oracle Access Manager authentication scheme is required for the policy domain.

9.4.3.2 Configuring a Policy Domain for the Oracle Access Manager Authenticator

After creating an authentication scheme for the Authenticator, you must create a policy domain in Oracle Access Manager to user the scheme.

A policy domain in Oracle Access Manager includes several types of information. Individual tabs are provided where you can enter specific details, as shown in Figure 9-18.

Figure 9-18 Create Policy Domain Page in the Oracle Access Manager Policy Manager

Description of "Figure 9-18 Create Policy Domain Page in the Oracle Access Manager Policy Manager"

For more information, see the following topics:

• About Creating a Policy Domain

• Creating a Policy Domain and Access Policies for the Authenticator

9.4.3.2.1 About Creating a Policy Domain

This topic describes the tabs in the Policy Manager that you use to enter details for your policy domain and access policies. While you might not use every tab in your policy domain, the following general information is provided:

• General Tab: Enter a short alphanumeric string to name this policy domain. You can use spaces in the Name field. A description is optional. Do not enable this policy domain until all details are saved and you are ready to use the domain.

• Resources Tab: Add resources to be protected by this policy domain. You use URL prefixes to define the policy domain content. A description is optional.

• Authorization Rules Tab: specify an authorization rule that consists of general information, Allow Access and Deny Access conditions, and actions for the rule, if any, to be used in an Authorization Expression later. You must specify an authorization scheme for every authorization rule you define.

• Default Rules Tab: Create default rules that apply to the resources protected by the policy domain, unless the resource is protected by a specific policy. From this tab you add the authentication rule, authorization expression, and audit rule for this policy domain.

  Authentication Rule: A policy domain must have at least one authentication rule, which specifies one authentication scheme and authentication actions.

  Authorization Expression: These include authorization rules and the operators used to combine them.

  Audit Rule: If there is no Master Audit Rule defined, you are instructed to contact your Access System Administrator.

• Policies Tab: If no rules are defined, the default rules for the policy domain remain in effect. For each policy you create, you can assign a specific authentication rule, authorization expression, and auditing rule. You can create policies with granular URL patterns. Before setting up a policy, decide the level of access control needed for the URL you to be protected.

• Delegated Administrators Tab: When adding URL prefixes to a policy domain, the Delegated Access Administrator must specify a server hosting the URL prefix.

See Also:

"Creating a Policy Domain and Access Policies for the Authenticator" and the following topics in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager:

• "Creating an Authentication Rule for a Policy Domain"

• "Creating an Audit Rule for a Policy Domain"

9.4.3.2.2 Creating a Policy Domain and Access Policies for the Authenticator

The Authenticator implementation requires several default and some unique values in the policy domain. You must be a Master or Delegated Access Administrator in Oracle Access Manager to create, view, or modify a policy domain.

In the following procedure, you create a policy domain for the Authenticator to:

• Use the default Basic Authentication scheme (set up with Policy Manager) internally to authenticate users and to protect URL resources prefixed with /Authen/Basic.

• Protect resources of type wl_authen, which was defined earlier. See also, "Creating Resource Types in Oracle Access Manager 10g"

• Request user credentials using the Oracle Access Manager authentication scheme created earlier.

  Note:

  The Authenticator requires the BASIC authentication method defined in the application web.xml file, which you will set up later as described in "Configuring the Application Authentication Method for the Authenticator".

• Require a default authentication rule and actions, which you configure in the following procedure to return users and groups on authentication success.

• Require a default Authorization rule with no actions, which you configure in the following procedure.

  Note:

  The Authenticator does not perform authorization. Therefore no authorization expression is required.

Examples in the following procedure are for illustration only. Be sure to enter appropriate values for your environment.

To create a policy domain for the Oracle Access Manager Authenticator

1. Go to the Policy Manager and log in. For example:

   http://Webserver:port/access/oblix
   

   where Webserver refers to computer that hosts the Policy Manager Web server; port refers to the HTTP port number of the Web server instance; /access/oblix connects to the Access System.

2. Click Policy Manager.

3. Click Create Policy Domain in the left navigation pane to display the Create Policy Domain page.

4. General Tab: Fill in the name and optional description that appear in pages showing lists of policy domains, and then click Save. For example:

   Name: Default OAM Authenticator

   Description: For Username Resolution

   Note:

   Do not enable this policy domain until you finish all specifications.

5. Resources Tab: Click the Resources tab, click the Add button, select resource types, enter URL prefixes, and save as follows:

   Resource Type: wl_authen

   Host Identifier (optional): Select the Preferred HTTP host for the AccessGate.

   URL prefix: /Authen/Basic

   Description: OAM Authenticator validates user name, password

   Click Add.

   Resource Type: wl_authen

   URL prefix: /Authen/UsernameAssertion

   Description: Authenticator Resource to validate user name

   Click Save.

6. Default Rules Tab: From this tab you add the authentication rule, authorization expression, and audit rule for this policy domain. The policy domain's default rules apply to the resources it contains, unless the resource is protected by a specific policy.

   1. Click Default Rules, and then click Add to create the rule for the Basic Authentication scheme.

   2. Authentication Rule: A policy domain must have at least one authentication rule, which specifies one authentication scheme and authentication actions. Enter a Name, optional description, and choose an Authentication Scheme.

      Click Authentication Rule and fill in the General tab as follows.

      Name: Basic Authentication Scheme

      Description: User name and password based authentication

      Authentication Scheme: Basic over LDAP

      Click Save.

      Note:

      For the Authenticator you need only an Authentication Success Return Action in the rule for the ObMyGroups attribute. This Access Server-specific attribute returns all the groups to which the user belongs. Two other implementations require this action, as described in Step C.

   3. Authentication Rule, Actions: For the Authenticator (or to boot Oracle WebLogic with Administrator users who exist in Oracle Access Manager, or if you are using Oracle Web Services Manager).

      Click the Actions tab, click Add.

      Enter the following for Authentication Success:

      Redirection URL: Leave blank

      Return

      Type: WL_REALM

      Name: obmygroups

      Return Attribute: obmygroups

      This return attribute directs the Access Server to return all groups to which the user belongs.

      Next, enter the name of the login parameter for user name to help in identifying the user uniquely in the LDAP directory server

      Type: WL_REALM

      Name: uid

      Return Attribute: uid

      This return attribute should be the name of the login parameter for the user name. This helps in identifying the user uniquely in the LDAP directory server used by Oracle Access Manager.

7. Policies Tab: Click the Policies tab, click Add.

   Fill in and save General details:

   Name: Default Username Resolution Policy

   Description: Default Username Policy for Authenticator

   Resource Type: wl_authen

   Resource operation(s): LOGIN

   Resource: /Authen/UsernameAssertion

   Leave other items as they are.

   Click Save.

   Click the Authentication Rule sub tab, click Add, and fill in General details (Name, optional Description, Authentication Scheme).

   Name: Username Resolution Authentication Rule

   Authentication Scheme: UsernameAssertion Authentication Scheme

   See "Creating an Authentication Scheme for the Authenticator".

   Click Save.

   Click the Actions sub tab and add the following details for Authentication Success:

   • Return Type: WL_REALM

   • Return Name: uid

   • Return Attribute: uid

     Note:

     Be sure to enter Return Attribute. uid is the name of the login attribute in the LDAP ObjectClass that helps to identity the user uniquely in the directory server used by Oracle Access Manager.

   Click the Actions sub tab and add the following details for Authentication Success:

   • Return Type: WL_REALM

   • Return Name: obmygroups

   • Return Attribute: obmygroups

   Note:

   obmygroups returns all groups to which a member belongs.

8. Delegated Access Admins: When adding URL prefixes to a policy domain, the Delegated Access Administrator must specify a server hosting the URL prefix.

   See Also:

   Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager, "Delegating Policy Domain Administration"

9. Proceed with "Configuring Providers for the Authenticator in a WebLogic Domain".

9.4.3.3 Configuring Providers for the Authenticator in a WebLogic Domain

This topic includes a procedure that you can use to add and configure the appropriate Authentication Providers in a WebLogic domain.

The Oracle Access Manager Authenticator must be configured along with the Default Authentication Provider in a WebLogic domain.

• DefaultAuthenticator: SUFFICIENT

• OAM Authenticator: OPTIONAL

The following procedure describes this task using the WebLogic Administration Console. You can also add these using the Oracle WebLogic Scripting Tool (WLST).

See Also:

• "About Oracle WebLogic Server Authentication and Identity Assertion Providers"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference

Note:

When a Oracle Fusion Middleware application is installed, you have the required files and can skip Step 1.

To configure providers for the Oracle Access Manager Authenticator in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider if you have no Oracle Fusion Middleware application.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0). For example:

      oamAuthnProvider<version>.zip 
      

   3. Extract and copy the oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
       
      

2. Go to the Oracle WebLogic Administration Console.

3. With Oracle Fusion Middleware Application Installed:

   1. Locate oamauthenticationprovider.war in the following path:

      ORACLE_INSTANCE/modules/oracle.oamprovider_11.1.1/oamauthenticationprovi
      der.war 
      

   2. Copy oamauthenticationprovider.war to the following location:

      BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      

4. Go to the Oracle WebLogic Administration Console.

5. Click Lock & Edit, if desired.

6. OAM Authenticator:

   1. Click Security Realms and select the realm you want to configure.

   2. Select Providers, Authentication, and click New to display the Create a New Authentication Provider page

   3. Enter a name and select a type:

      Name OAMAuthN

      Type: OAMAuthenticator

      OK

   4. Click the name of the Authentication Provider you have just created to display the Provider Configuration page.

   5. In the Provider Configuration page, set the required values as follows:

      Access Gate Name: The name of the AccessGate profile used by the provider. This must match exactly the name in the AccessGate configuration profile in the Access System Console.

      Note:

      You might have only one AccessGate configuration profile for the Authenticator.

      Access Gate Password: The same password, if any, that is as defined for the AccessGate configuration profile in the Access System Console.

      Primary Access Server: The host:port of the primary Access Server that is associated with this AccessGate in the Access System Console.

      Advanced Configuration: Following are several advanced configuration values.

      Transport Security: The communication mode between Access Server and AccessGate: open, simple, or cert.

      If transport security is Simple or Cert, include the following parameters and values:

      Trust Store: The absolute path of JKS trust store used for SSL communication between the provider and the Oracle Access Server.

      Key Store: The absolute path of JKS key store used for SSL communication between the provider and the Oracle Access Server.

      Key Store Pass Phrase: The password to access the key store.

      Simple mode pass phrase: The password shared by AccessGate and Access Server for simple communication modes.

      Secondary Access Server: The host:port of the secondary Access Server that is associated with this AccessGate in the Access System Console.

      Maximum Access Server Connections in Pool: The maximum number of connections that the AccessGate opens to the Access Server. The default value is 10.

      Note:

      The Maximum Access Server Connections in Pool (or Minimum Access Server Connections in Pool) settings in the WebLogic Administration Console are different from the Maximum (or Minimum) Connections specified in profiles within the Access System Console.

      Minimum Access Server Connections in Pool: The minimum number of connections that the Authentication Provider uses to send authentication requests to the Access Server. The default value is 5.

      See Also:

      "Oracle Access Manager Authentication Provider Parameter List" for descriptions and values of the common and provider-specific parameters

   6. Ensure that the parameter Control Flag is set to OPTIONAL initially.

      Note:

      Do not set the parameter Control Flag to REQUIRED until you have verified that the Authentication Provided is operational and configured correctly.

7. In the Change Center, click Activate Changes.

8. DefaultAuthenticator: Under the Providers tab, select DefaultAuthenticator, which changes its control flag to SUFFICIENT.

9. Reorder: Under the Providers tab, reorder the providers so that DefaultAuthenticator is first (OAMAuthenticator follows DefaultAuthenticator).

   Note:

   If the Oracle Access Manager Authenticator flag is set to REQUIRED, or if Oracle Access Manager Authenticator is the only Authentication Provider, perform the next step to ensure that the LDAP user who boots Oracle WebLogic Server is included in the administrator group that can perform this task. By default the Oracle WebLogic Server Admin Role includes the Administrators group.

10. Oracle Access Manager Authenticator REQUIRED or the Only Authenticator: Perform the following steps to set user rights for booting Oracle WebLogic Server.

    1. Create an Administrators group in the directory server, if one does not already exist (or any other group for which you want boot access).

       Note:

       To provide access to any other group, you must create that group in the directory server and add the user who boots WebLogic Server in that group.

    2. Confirm that the LDAP user who boots Oracle WebLogic Server is included in the Administrators (or other) group.

    3. From the WebLogic Administration Console, go to Security Realms, myrealm, Roles and Policies, Global Roles.

    4. Select View Conditions for the Admin Role.

    5. Add the group and click Save.

11. Reboot the WebLogic Server.

12. Once the server has started, reset the Authentication Provider parameter Control Flag to the appropriate value (REQUIRED, OPTIONAL, or SUFFICIENT).

    Note:

    The recommended value is REQUIRED. To prevent a known issue, see "JAAS Control Flag".

13. Proceed with "Configuring the Application Authentication Method for the Authenticator".

9.4.3.4 Configuring the Application Authentication Method for the Authenticator

This topic describes how to create the application authentication method for Oracle Access Manager Authenticator.

See Also:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

When you use the Oracle Access Manager Authenticator, all web.xml files in the application EAR file must specify BASIC in the element auth-method for the appropriate realm.

The auth-method can use BASIC or FORM values. While these look like similar values in Oracle Access Manager, the auth-method specified in web.xml files are used by Oracle WebLogic Server (not Oracle Access Manager).

Note:

For the Oracle Access Manager Authenticator, Oracle recommends auth-method BASIC in login-config within web.xml.

To configure the application authentication method for the Authenticator

1. Locate the web.xml file in the application EAR file:

   WEB-INF/web.xml 
   

2. Locate the auth-method in login-config and enter BASIC. For example:

   <security-constraint>
   <web-resource-collection>
   <web-resource-name>protected</web-resource-name>
   <url-pattern>/servlet</url-pattern>
   </web-resource-collection>
   <auth-constraint>
   <role-name>auth-users</role-name>
   </auth-constraint>
   </security-constraint>
   <login-config>
   <auth-method>BASIC</auth-method>
   </login-config>
   <security-role>
   <description>Authenticated Users</description>
   <role-name>auth-users</role-name>
   </security-role>
   

3. Save the file.

4. Redeploy and restart the application.

5. Repeat for each web.xml file in the application EAR file.

6. Proceed with "Mapping the Authenticated User to a Group in LDAP".

9.4.3.5 Mapping the Authenticated User to a Group in LDAP

This topic describes how to map the authenticated user to a group in LDAP. To do this, you must edit the weblogic.xml file. For example, you might need to map your role-name auth-users to a group named managers in LDAP.

To map the authenticated user to a group in LDAP for the Oracle Access Manager Authenticator

1. Go to the application's weblogic.xml file.

2. Add the following information for your environment anywhere in the file:

   <weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app
   http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd" 
   xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
   <security-role-assignment>
   <principal-name>managers</principal-name>
   <role-name>auth-users</role-name>
   </security-role-assignment>
   </weblogic-web-app>
   

3. Save the file.

4. Restart the WebLogic Server.

5. Proceed to:

   • Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

   • Testing the Oracle Access Manager Authenticator Implementation

9.4.3.6 Testing the Oracle Access Manager Authenticator Implementation

After performing all tasks to implement the Authenticator, you can test it by attempting to log in to the application using valid credentials. If the configuration is incorrect, a valid user is denied access.

The following procedure describes how to test your Authenticator setup. Alternatively, you can run Access Tester in Oracle Access Manager to test your policy domain, as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

To validate the Oracle Access Manager Authenticator implementation

1. Enter the URL to access the protected resource in your environment. For example:

   http://yourdomain.com:port
   

2. Provide appropriate credentials when the login form appears.

   • Successful: The implementation works.

   • Not Successful: See "Troubleshooting Tips for OAM Provider Deployments"

9.4.4 Configuring Identity Assertion for Oracle Web Services Manager and OAM 10g

This section describes how to set up the Oracle Access Manager Identity Asserter to enable validation of ObSSOCookie token when you have Oracle Web Services Manager protecting Web services.

When the Oracle Access Manager Identity Asserter is configured for both header and ObSSOCookie token validation modes, preference is given to the presence of the header. If the header is not present, the Identity Asserter contacts the Access Server to validate the ObSSOCookie token.

Oracle Access Manager Identity Asserter works in two modes:

• The default mode of operation simply asserts the header that is set by WebGate at the perimeter.

• The alternate mode uses the custom AccessGate in oamAuthnProvider.jar. In this case, and with the absence of the header, the Identity Asserter contacts with the Access Server to validate the ObSSOCookie token.

  Note:

  The AccessGate is required for Oracle Web Services Manager.

Prerequisites

• Installing Components and Files for Authentication Providers and OAM 10g which includes manually creating AccessGate profiles in the Access System Console for the custom AccessGate and accepting defaults during Policy Manager setup

  See Also:

  • "About Oracle Access Manager 10g Installation and Setup"

  • "About OAM 10g WebGate/AccessGate Profiles and Policy Domains"

• Creating Resource Types in Oracle Access Manager 10g

Task overview: Deploying the Identity Asserter with Oracle Web Services Manager includes

1. Ensuring that all prerequisite tasks have been performed

2. Creating an Policy Domain for Use with Oracle Web Services Manager

3. Configuring Oracle Web Services Manager Policies for Web Services

4. Configuring Providers in a WebLogic Domain for Oracle Web Services Manager

5. Testing the Identity Asserter with Oracle Web Services Manager

9.4.4.1 Creating an Policy Domain for Use with Oracle Web Services Manager

This topic describes how to set up a policy domain for use by the Oracle Access Manager Identity Asserter when you have Oracle Web Services Manager protecting Web services. You must be a Master or Delegated Access Administrator in Oracle Access Manager to create, view, or modify a policy domain.

The following unique values are required in this policy domain:

• Requires the default Basic over LDAP Authentication scheme (set up with Policy Manager) internally to authenticate users and to protect URL resources prefixed with /Authen/SSOToken.

• Protects resources of type wl_authen, which were defined in "Creating Resource Types in Oracle Access Manager 10g"

• Requires a default authentication rule with no actions, which you set up in the following procedure

• Requires a default authorization rule with actions, which you set up in the following procedure.

The following procedure walks you through creating a policy domain for use with Oracle Web Services Manager and the Oracle Access Manager Identity Asserter.

To create a policy domain for the Identity Asserter with Oracle Web Services Manager

1. Go to the Policy Manager and log in. For example:

   http://Webserver:port/access/oblix
   

   where Webserver refers to computer that hosts the Policy Manager Web server; port refers to the HTTP port number of the Web server instance; /access/oblix connects to the Access System Console.

2. Click Policy Manager.

3. Click Create Policy Domain in the left navigation pane to display the Create Policy Domain page.

4. General Tab: Fill in a name and optional description that appears in pages showing lists of policy domains, and then click Save. For example:

   Name: OAM IA OWSM

   Description: Used by Identity Asserter with Oracle Web Services Manager

   Note:

   Do not enable this policy domain until you finish all details.

5. Resources Tab: Click the Resources tab, click the Add button, select resource types, enter URL prefixes, and save as follows:

   Resource Type: wl_authen

   URL prefix: /Authen/SSOToken

   Description: Used by IA OWS to validate SSO token

   Save.

6. Authorization Rules Tab: Add an authorization rule to use in an Authorization Expression later.

   Click the Authorization Rules tab, then click the Add button

   1. General Tab: For Authorization Rules, enter a rule name and, optionally, a brief description.

      Name: Default_OAM_IA_OWS_AuthZ_Rule

      Description: For use with OWS and Identity Asserter.

      Enabled: Yes

      Allow takes precedence: No

      Update Cache: Yes (updates all Access Server caches immediately)

   2. Timing Conditions: None required for this scenario.

   3. Actions: None required on this tab. Instead, you set these up under the Default Rules tab.

   4. Allow Access: Add details that define to whom the Allow Access part of the rule applies.

      Role: Any one

   5. Deny Access: Not Needed for this scenario.

   6. Return to the General tab for Authorization Rules and enable the rule so that you can add it to an authorization expression later.

      See Also:

      Chapter 6 in Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager for details about configuring authorization schemes and rules.

7. Default Rules Tab: From here you can add the authentication rule, authorization expression, and audit rule for this policy domain. These default rules apply to the resources it contains, unless the resource is protected by a specific policy.

   Click Default Rules, and then click Add.

   1. Authentication Rule: A policy domain must have at least one authentication rule, which specifies one authentication scheme and optional authentication actions. Enter a Name, optional description, and choose an Authentication Scheme.

      General tab: Fill in the as follows:

      Name: Default AuthN Rule

      Description: Default Rule for OAM IA OSW

      Authentication Scheme: Basic over LDAP

      Click Save.

      Actions tab: No authentication actions are needed in the default rule for Oracle Web Services Manager.

      Note:

      With Oracle Web Services Manager you need an Authorization rule.

   2. Authorization Expression: The authorization expression in the default rules for a policy domain applies to all resources of the domain unless those resources are protected by a policy containing an expression.

      Click the Authorization Expression tab, and then click Add.

      Expression tab: Select the authorization rule you created in Step 6:

      Select Authorization Rule: Default_OAM_IA_OWS_AuthZ_Rule

      Click Add.

      Click Save.

      Actions tab: In Step 6 you defined to whom the Allow Access part of a rule applies. Here, you specify actions for Authorization success for both rules and expressions.

      Click Actions, click Add, and then create a return action on Authorization Success with the following to specify what actions should be invoked when authorization succeeds.

      Authorization Success: Applies to Allow Access conditions.

      Return Type: WL_REALM

      Return Name: uid

      Return Attribute: uid

      Click Save.

      Note:

      Return Attribute uid should match the value of the login parameter for the user name to help identify the user uniquely in the Oracle Access Manager LDAP repository. Here, uid is the canonical name of the login attribute. If your LDAP directory uses a different attribute as the login attribute, the Name should still be "uid". However, the Return Attribute would be whatever your login attribute is configured as (mail, for example). Be careful to put these values under Return Attribute (not Return Value).

8. Policies Tab: No policies are needed. Default Rules apply.

9. Delegated Access Admins: When adding URL prefixes to a policy domain, the Delegated Access Administrator must specify a server hosting the URL prefix.

   See Also:

   Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager, "Delegating Policy Domain Administration"

10. Validate Policy Domain: Click My Policy Domains, click the new policy domain you created, then click View As a Page to see all specifications at once.

11. Proceed with "Configuring Oracle Web Services Manager Policies for Web Services".

9.4.4.2 Configuring Oracle Web Services Manager Policies for Web Services

This section provides an overview of configuring Oracle Web Services Manager policies to protect Web services.

To use the Identity Asserter with Oracle Web Services Manager, you must set up a Web service with the oracle/wss_oam_token_service_policy and a corresponding client with the oracle/wss_oam_token_client_policy in Oracle Web Services Manager.

See Also:

"About Using Identity Asserter for SSO with OAM 11g and 10g WebGates"

About oracle/wss_oam_token_service_policy

This Oracle Web Services Manager policy contains the policy assertion oracle/wss_oam_token_service_template. This template uses the credentials in the WS-Security header's binary security token to authenticate users against the Oracle Access Manager identity store.

The Oracle Access Manager Identity Asserter uses the ObSSOCookie token to assert the identity of users who try to access a Web service protected by the oracle/wss_oam_token_service_policy policy. A Web service that is protected by this policy must be presented with an ObSSOCookie token in a SOAP header. That is, the Web service consumes the ObSSOCookie token; it is not involved in how the token is generated. Specifically, the WebLogic Server security service detects the token type and invokes the Oracle Access Manager Identity Asserter. The Oracle Access Manager Identity Asserter then validates the ObSSOCookie token against the Oracle Access Manager Access Server and obtains the username. The username is populated as the principal in the authenticated subject.

The Web service client, for example the Web application, must obtain the ObSSOCookie token to send it to the Web service. This is typically done using an AccessGate. AccessGate challenges the Web service client user for credentials (depending on the authentication scheme configured in Oracle Access Manager) and authenticates the user. The WebGate sends the ObSSOCookie to the user's browser upon successful authentication

The Web service client then sends the ObSSOCookie token in the SOAP request to the Web service.

Note:

Settings for the wss_oam_token_service_template are identical to the client version of the assertion: wss_oam_token_client_template. Identity store configuration for the service template is identical to the client version of the assertion.

About oracle/wss_oam_token_client_policy

This Oracle Web Services Manager policy contains the following policy assertion: oracle/wss_oam_token_client_template. This template inserts Oracle Access Manager credentials into the WS-Security header as part of the binary security token.

oracle/wss_oam_token_client_policy is the analogous client policy to the oracle/wss_oam_token_service_policy service endpoint policy. This policy can be enforced on any SOAP-based endpoint.

The following task overview outlines the procedures you must perform.

Task overview: Setting policies in Oracle Web Services Manager

1. Using Oracle Web Services Manager, set up a Web service with the oracle/wss_oam_token_service_policy policy.

2. Using Oracle Web Services Manager, set up a corresponding client for the Web service with the oracle/wss_oam_token_client_policy policy.

3. Configuring Providers in a WebLogic Domain for Oracle Web Services Manager.

See Also:

• "About Using Identity Asserter for SSO with OAM 11g and 10g WebGates"

• Oracle Fusion Middleware Security and Administrator's Guide for Web Services

  "Configuring Policies"

  "Predefined Assertion Templates"

9.4.4.3 Configuring Providers in a WebLogic Domain for Oracle Web Services Manager

To use Oracle Access Manager Identity Asserter with Oracle Web Services Manager protected Web services, several Authentication Providers must be configured and ordered in a WebLogic domain:

• OAM Identity Asserter: REQUIRED

• OID Authenticator: SUFFICIENT

• DefaultAuthenticator: SUFFICIENT

This procedure is nearly identical to the one for the Oracle Access Manager Identity Asserter. The difference in this case is that Oracle Web Services Manager requires a custom AccessGate and additional provider-specific values are required:

• Primary Access Server: Specify the host and part. For example: abcd:7777

• Access Gate Name: The name of the AccessGate protecting the application. For example: mmmm

• Access Gate Password: The AccessGate password as specified in the Access System Console.

You can add these using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

See Also:

• "About Oracle WebLogic Server Authentication and Identity Assertion Providers"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference

Note:

With a Oracle Fusion Middleware application installed, you have the required provider file. Skip Step 1.

To set up providers in a WebLogic domain

1. No Oracle Fusion Middleware Application: Obtain the Oracle Access Manager provider if you have no Oracle Fusion Middleware application.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the oamAuthnProvider ZIP file with Access Manager WebGates (10.1.4.3.0). For example:

      oamAuthnProvider<version>.zip 
      

   3. Extract and copy the oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
       
      

2. Log in to the Oracle WebLogic Administration Console.

3. OAM Identity Asserter: Perform the following steps to add this provider:

   1. Click Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, click New, and then enter a name and select a type:

      Name: OAM Identity Asserter

      Type: OAMIdentityAsserter

      OK

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Common tab, set the Control Flag to REQUIRED, and click Save.

   5. Click Platform-Specific tab and configure these parameters:

      Primary Access Server: Specify the host and part. For example: abcd:7777

      Access Gate Name: The name of the AccessGate protecting the application. For example: mmmm

      Access Gate Password: The AccessGate password as specified in the Access System Console.

      Save

4. OID Authenticator: Perform the following steps to add this provider.

   1. Click Security Realms, Default Realm Name, and click Providers

   2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      Click OK.

   3. In the Authentication Providers table, click the newly added authenticator.

   4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

   5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Oracle Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Note:

      Do not set the All Groups filter as the default works fine as is.

      Click Save.

5. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

   1. Go to Security Realms, Default Realm Name, and click Providers.

   2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

   3. Click the Common tab and set the Control Flag to SUFFICIENT.

   4. Click Save.

6. Reorder Providers:

   1. Click Security Realms, Default Realm Name, Providers.

   2. On the Summary page where providers are listed, click the Reorder button

   3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

   4. Click OK to save your changes

7. Activate Changes: In the Change Center, click Activate Changes

8. Reboot Oracle WebLogic Server.

9. Proceed as follows:

   • Successful: Go to "Testing the Identity Asserter with Oracle Web Services Manager".

   • Not Successful: Confirm the all providers have the proper specifications for your environment, are in the proper order, and that oamAuthnProvider.jar is in the correct location as described in "Installing Components and Files for Authentication Providers and OAM 10g".

9.4.4.4 Testing the Identity Asserter with Oracle Web Services Manager

To validate the use of the Oracle Access Manager Identity Asserter with Oracle Web Services Manager, you can access the Web service protected by the Identity Asserter and Oracle Web Services Manager policies. If access is granted, the implementation works. If not, see "Troubleshooting Tips for OAM Provider Deployments".

9.4.5 Oracle Access Manager Authentication Provider Parameter List

This section enumerates the common and provider-specific parameters relevant to the Oracle Access Manager Authentication Provider. These are specified in the Oracle WebLogic Administration Console. For more information, see:

• Table 9-10, "Oracle Access Manager Authentication Provider Common Parameters"

• Table 9-11, "Provider-Specific Parameters"

• Table 9-12, "Provider-Specific Parameters: Oracle Access Manager Authenticator"

Table 9-10 Oracle Access Manager Authentication Provider Common Parameters

Parameter Name	Parameter Description
Name	The name of the provider. Read-only.
Description	The description of the provider. Read-only.
Version	The version of the provider. Read-only.
Control Flag	The provider JAAS control flag. Set one of the following: REQUIRED, REQUISITE, OPTIONAL, or SUFFICIENT. When configuring multiple Authentication Providers, use this flag to control how they are use in the login sequence. See JAAS Control Flag.
Active Types	This parameter is relevant to only Oracle Access Manager Identity Asserter. This parameter determines the token types that the Identity Asserter Provider processes. Set as follows: OAM 11g with 11g WebGates: OAM_REMOTE_USER OAM 11g and 10g WebGate: ObSSOCookie OAM 10g and 10g WebGate: ObSSOCookie Note: For 10g WebGate with either OAM 10g or 11g, the OAM_REMOTE_USER is also be present and you can configure the Identity Asserter to use OAM_REMOTE_USER as the chosen Active Type.
Base64 Decoding Required	False is Read-only (the default).

The WebLogic Server Administration Console sets the JAAS Control Flag to OPTIONAL when you create a new security provider. The default value for out-of-the-box security providers is REQUIRED. For more details about the control flag, see the online help.

Table 9-11 lists the provider-specific parameters for Oracle Access Manager the Authenticator or the Identity Asserter for Oracle Web Services Manager.

Note:

With OAM 11g, the Access Server is known as the OAM Server.

Table 9-11 Provider-Specific Parameters

Parameter Name	Parameter Description
Transport Security	The mode of communication between AccessGate and Access Server.
Minimum Access Server Connections In Pool	The minimum number of connections allowed. Default is 5.
Access Gate Password	The password of the AccessGate used by the provider.
Key Store Pass Phrase	The password to access the key store.
Access Gate Name	The name of the AccessGate used by the provider. Required.
Primary Access Server	The name of the primary access server. It must conform to the format host:port. Required. See "Installing and Setting Up Authentication Providers for OAM 10g".
Maximum Access Server Connections In Pool	The maximum number of connections allowed. Default is 10. Set to 1.
Simple Mode PassPhrase	The password shared by AccessGate and Access Server for Simple or Cert communication modes.
Trust Store	The absolute path of JKS trust store used for SSL communication between the provider and the Oracle Access Manager Access Server.
SSOHeader Name	OAM_REMOTE_USER
Secondary Access Server	The name of the secondary access server. It must conform to the format host:port. See "Installing and Setting Up Authentication Providers for OAM 10g".
Key Store	The absolute path of JKS key store used for SSL communication between the provider and the Oracle Access Manager Access Server.

Table 9-12 lists provider-specific parameters for the Oracle Access Manager Authenticator.

Table 9-12 Provider-Specific Parameters: Oracle Access Manager Authenticator

Parameter Name	Parameter Description
Transport Security	The mode of communication between AccessGate and Access Server.
Maximum Access Server Connections In Pool	The maximum number of connections allowed. Default is 10. Set to 1.
Simple Mode Pass Phrase	The password shared by AccessGate and Access Server for simple or cert communication modes.
Minimum Access Server Connections In Pool	The minimum number of connections allowed. Default is 5.
Trust Store	The absolute path of JKS trust store used for SSL communication between the provider and the Oracle Access Manager Access Server.
Use Retrieved username As Principal	Specifies whether to use the user name retrieved from Oracle Access Manager as the Principal in the Subject.
Access Gate Password	The password of the AccessGate used by the provider.
Key Store Pass Phrase	The password to access the key store.
Access Gate Name	The name of the AccessGate used by the provider. Required.
Secondary Access Server	The name of the secondary access server. It must conform to the format host:port. See: "Installing the Authentication Provider with Oracle Access Manager 11g" "Installing and Setting Up Authentication Providers for OAM 10g"
Key Store	The absolute path of JKS key store used for SSL communication between the provider and the Oracle Access Manager Access Server.
Primary Access Server	The name of the primary access server. It must conform to the format host:port. Required. See: "Installing the Authentication Provider with Oracle Access Manager 11g" "Installing and Setting Up Authentication Providers for OAM 10g"

9.4.6 Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates

This section discusses configuring logout for applications protected by a 10g WebGate with Oracle Access Manager 10g. In Oracle Access Manager 10g, global logout (also known as single log out (SLO) can be handled in various ways. This section describes the recommended method.

Note:

Oracle Access Manager SSO user session tracking is performed using DOMAIN cookies, specifically the ObSSOCookie. WebGates look for the ObSSOCookie. Global or SLO for Oracle Access Manager simply means killing the ObSSOCookie. Without the ObSSOCookie, WebGates enforce a re-authentication workflow.

For more information on killing the ObSSOCookie, see:

• Recommended Process for Configuring Logout

• Alternative Process for Configuring Logout

9.4.6.1 Recommended Process for Configuring Logout

There are two steps in the Oracle-recommended approach to configuring logout:

• Configuring WebGate for Logout using the Sample Logout File

• Configuring Applications for Logout

9.4.6.1.1 Configuring WebGate for Logout using the Sample Logout File

WebGate configuration consist of:

• logout.html: A logout page must be available on the Web server in the WebGate installation directory: WebGate_install_dir/oamsso/logout.html.

  If the file is located elsewhere on the Web server, ensure that the logout link is correctly specified to load logout.html. See the logout.html in Example 9-1, which you can customize further depending on your needs.

• logOutUrls (optional): If this parameter has already been configured for the WebGate, the value "/oamsso/logout.html" must be added to the existing list.

• Web Server Configuration: Check the Oracle HTTP Server Web server configuration file, httpd.conf, on which the 10g WebGate is configured and delete the following lines if they are present

  <LocationMatch "/oamsso/*">
  Satisfy any
  </LocationMatch>
  

Use Example 9-1 when you begin constructing a logout.html for logout configuration for an application protected by 10g WebGate in an OAM 10g deployment.

Example 9-1 logout.html Script

<html>
<head>
<script language="javascript" type="text/javascript">

function handleLogout() {

    //get protocol used at the server (http/https)
    var webServerProtocol = window.location.protocol;
    //get server host:port
    var webServerHostPort = window.location.host;
    //get query string present in this URL
    var origQueryString = window.location.search.substring(1);

    //vars to parse the querystring
    var params = new Array();
    var par = new Array();
    var val;

    if (origQueryString != null && origQueryString != "") {

        params = origQueryString.split("&");

        //search for end_url and redirect the user to this
        for (var i=0; i<params.length; i++) {

        par = params[i].split("=");

        if ("end_url" == par[0]) {

          endUrlVal = par[1];

        //check if val (value of end_url) begins with "/" or "%2F" (is it an URI?)
        if (endUrlVal.substring(0,1) == "/" || endUrlVal.substring(0,1) == "%") {

          if (endUrlVal.substring(0,1) == "%")
            endUrlVal = "/" + endUrlVal.substring(3);

         //modify the end_url value now
           endUrlVal = webServerProtocol + "//" + webServerHostPort + endUrlVal;
         }
    //redirect the user to this URL
    window.location.href = endUrlVal;
         }
       }
   }
}
</script>
</head>

<body onLoad="handleLogout();">

<h3>You have been logged out<h3>

</body>
</html>

9.4.6.1.2 Configuring Applications for Logout

Application configuration for logout depends on whether it is an ADF application integrated with OPSS or if it is not integrated with OPSS.

Note:

The logout configuration assumes that the applications are present in a single DNS domain. If you would like SLO (single log out) across applications deployed in different DNS domains, you must customize the logout script to ensure processing for each WebGate. If you have a multi DNS domain deployment, see the Oracle Access Manager Access Administration Guide.

One of the following must be done to configure the application for logout:

• A non-ADF application must be coded to invoke the logout link: "/oamsso/logout.html?end_url=<target uri>".

• An ADF application that has been integrated with OPSS requires configuring OPSS for the OAM SSO provider and the application must send the 'end_url' parameter.

Non-ADF Application

A non-ADF application must be coded to invoke the link for logout: "/oamsso/logout.html?end_url=<target uri>".

The application can pass a parameter (named end_url) indicating the location where the user should eventually be redirected to after logout. The value that is part of end_url could either be a URL or a URI. For example, the logout link for the application might be specified as

/oamsso/logout.html?end_url=<someUri> 

or

/oamsso/logout.html?end_url=<someUrl> 

If the end_url querystring is a URI, then the logout.html must construct the URL by determining the host:port of the server where logout.html is hosted.

ADF-Coded Applications

If the Application is an ADF application that has been integrated with OPSS, then you can use the following procedure to configure logout.

To configure centralized logout for ADF-coded applications

1. Check with the OAM Administrator to confirm the location of the logout.html script configured with the Agent, which you need in following steps.

2. Configure OPSS for OAM as the SSO provider to update jps-config.xml for the WebLogic administration domain, as follows:

   1. Run wlst.sh (Linux) or wlst.cmd (Windows) from the following directory path:

      WLST_install_dir/middleware/oracle_common/common/bin 
      

   2. At the WLS prompt, enter the OAM administrator ID and password and the WebGate host and port:

      wls:/> /connect("admin_ID", "admin_pw", "hostname:port" 
      

      The last parameter is optional if the server is running on localhost at the default port (7001).

   3. Enter the loginuri for ADF authentication and the logouturi (location of the logout.html script configured with the agent); the host and port are not needed.

      wls:/>addOAMSSOProvider(loginuri="/$<loginuri>",    
      logouturi="<logouturival>," autologinuri=None")
      

      Here, logouturival is the URI of the logout script /oamsso/logout.html. The logouturl could either begin with "logout." (exceptions are logout.gif and logout.jpg) or it could be any other value configured by the OAM Administrator.

3. Required: The ADF application must pass the end_url parameter indicating where to redirect the user after logout. For ADF applications, logout is initiated when the application causes the following URI to be invoked:

    /<app context root>/adfAuthentication?logout=true&end_url=<any uri>
   

9.4.6.2 Alternative Process for Configuring Logout

Oracle does not recommend this method unless your application already has a custom logout page that you do not wish to change for any reason.

WebGate logs out of any request for a URL that has the string "logout." in it. Exception: Image files such as logout.gif and logout.jpg. This is the simplest way to integrate an application with OAM SLO. If your logout page begins with "logout." (for example, logout.jsp) then you do not need to do any thing.

Note:

If your logout page begins with "logout." (for example, logout.jsp) then you do not need to do any thing.

If your logout page does not begin with "logout.", then you must add your logout URL to the WebGate LogOutUrls parameter. For instance: LogOutUrls = "/myapplication /customscript.jsp".

9.4.7 Known Issues: JAR Files and OAMCfgTool

Table 9-13 identifies known issues with this release. For more information about the tool, parameters, and values, see "About Using OAMCfgTool".

Table 9-13 OAMCfgTool Known Issues

Bug Number	Description
n/a	The location where you obtain Oracle Access Manager Authentication Provider and OAMCfgTool JAR files when you do not have an Oracle Fusion Middleware application installed could change. If the location is different than the one stated in this chapter, see the Release Notes for the latest information.
8362080	OAMCfgTool provides Create and Validate options. It does not provide Delete or Overwrite options.
8362039	OAMCfgTool does not provide explicit options to specify the Web Tier host and port. Instead, without web_domain specified the app_domain value specifies the WebGate name, host, and Preferred HTTP Host. For example: app_domain=ABC (without web_domain specified) AccessGate Name: ABC_AG Hostname: ABC Port: Not specified Preferred HTTP Host: ABC
n/a	With OAMCfgTool, if web_domain parameter is included in the command line, you must provide a WebGate password. Otherwise, the command can fail. The app_agent_password parameter accepts as the password whatever follows the equal sign, =. For instance, if you enter app_agent_password= and then enter a space character and web_domain=value, the app_agent_password is presumed to be a space character followed by web_domain.
n/a	SSL-enabled communication with the directory server is not supported by OAMCfgTool.

9.4.8 Troubleshooting Tips for OAM Provider Deployments

This section contains the following topics:

• About Using IPv6

• Apache Bridge Failure: Timed Out

• Authenticated User with Access Denied

• Browser Back Button Results in Error

• Cannot Reboot After Adding OAM and OID Authenticators

• Client in Cluster with Load-Balanced WebGates

• Error 401: Unable to Access the Application

• Error 403: Unable to Access the Application

• Error 404: Not Found ... Anything Matching the Request URI

• Error Issued with the Action URL in Form Login Page

• Error or Failure on Oracle WebLogic Server Startup

• JAAS Control Flag

• Login Form is Shown Repeatedly Upon Credential Submission: No Error

• Logout and Session Time Out Issues

• Not Found: The requested URL or Resource Was Not Found

• Oracle WebLogic Server Fails to Start

• Oracle ADF Integration and Cert Mode

See Also:

"Setting Up Debugging in the WebLogic Administration Console"

9.4.8.1 About Using IPv6

Oracle Fusion Middleware and Oracle Access Manager support Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6.) Among other features, IPv6 supports a larger address space (128 bits) than IPv4 (32 bits), providing an exponential increase in the number of computers that can be addressable on the Web.

See Also:

Oracle Fusion Middleware Administrator's Guide for details about using IPv6.

9.4.8.2 Apache Bridge Failure: Timed Out

If you experience a failure of the Apache bridge, you might see a message stating that there is no back-end server available for connection. In this case, the connection times out.

The Oracle WebLogic Server might be down or there might be incorrect values set in mod_weblogic.

To recover from an Apache Bridge Failure

1. Check the Oracle WebLogic Server to ensure that it is available.

2. Confirm that host and port information is specified correctly in the WebGate's Web server httpd.conf. For example:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

            <IfModule mod_weblogic.c>
                WebLogicHost yourHost.yourDomain.com
                  WebLogicPort yourWlsPortNumber
             </IfModule>
   

9.4.8.3 Authenticated User with Access Denied

It is possible that an authenticated user does not have access rights to the requested resource.

If a user login is inconclusive or invalid, the user can be authenticated but not recognized as authorized for the requested resource. In this case, no explicit error message states the issue. Instead, the user is prompted to log in again.

9.4.8.4 Browser Back Button Results in Error

After successful authentication, if you click the Back button in the browser window, you might get an error for access/oblix/apps/webgate/bin/webgate.so.

When form-based authentication is used, Oracle Access Manager creates a form login cookie that holds information about the requested resource. On successful authentication, the state of the cookie changes. When the user clicks the Back button, the login form appears. When re-posted, the form login cookie no longer holds redirection details.

The ObSSOCookie is also sent with the form login cookie.The ObSSOCookie is correctly checked. As the form login cookie state changes, the form-based authentication does not occur and the form action is considered as a request for the resource.

Solution

Retry the request using the original URL.

9.4.8.5 Cannot Reboot After Adding OAM and OID Authenticators

If the Oracle Access Manager Authenticator flag is set to REQUIRED, or if Oracle Access Manager Authenticator is the only Authentication Provider, perform the next step to ensure that the LDAP user who boots Oracle WebLogic Server is included in the administrator group that can perform this task. By default the Oracle WebLogic Server Admin Role includes the Administrators group.

To provide access to any other group, you must create that group in the directory server and add the user who boots WebLogic Server in that group.

To ensure you can restart the WebLogic Server

1. Create an Administrators group in the directory server, if one does not already exist (or any other group for which you want boot access).

2. Confirm that the LDAP user who boots Oracle WebLogic Server is included in the Administrators (or other) group.

3. From the WebLogic Administration Console, go to Security Realms, myrealm, Roles and Policies, Global Roles.

4. Select View Conditions for the Admins Role.

5. Add the group and click Save.

9.4.8.6 Client in Cluster with Load-Balanced WebGates

Out of the box, Oracle Access Manager does not support load balanced AccessGates; you must use a third-party load balancer.

Suppose you have two WebGates: WebGateA and WebGateB. You can use the OAMCfgTool to create the profile to be shared by the two WebGates.

See Also:

"About Using OAMCfgTool"

If you have an Oracle Fusion Middleware Application installed you already have the OAMCfgTool. In this case, skip Step 1.

Solution:

1. No Oracle Fusion Middleware Application: Obtain the OAMCfgTool if you have no Oracle Fusion Middleware application installed.

   1. Log in to Oracle Technology Network at:

      http://www.oracle.com/technology/software/products/middleware/htdocs/111110_fmw.html   
      

   2. Locate the OAMCfgTool ZIP file with Access Manager Core Components (10.1.4.3.0):

      oamcfgtool<version>.zip  
      

   3. Extract and copy oamcfgtool.jar to the computer hosting WebGate:

2. Log in to the computer for WebGateA (even if WebGate is not yet installed).

3. Change to the file system directory containing OAMCfgTool and run a command like the following one to create one AccessGate Profile to be shared by the two WebGates. For example:

   java -jar oamcfgtool.jar mode=CREATE app_domain=SharedA_B 
   app_agent_password=<WebGate_password> 
   cookie_domain=<preferred_http_cookie_domain>
   ldap_host=wxyz
   ldap_port=6633
   ldap_userdn=orcladmin
   ldap_userpassword=<ldap_userpassword>
   oam_aaa_host=abcd
   oam_aaa_port=7789
   oam_aaa_mode=cert
   log_file=OAMCfg_date.log
   log_level=INFO
   output_ldif_file=<LDIF_filename>
   

4. Review the information provided by the tool. For example, the parameters and values in Step 3 would provide the following information:

   Processed input parameters
   Initialized Global Configuration
   Successfully completed the Create operation.
    Operation Summary:
        Policy Domain  : SharedA_B
        Host Identifier: SharedA_B_WD
        Access Gate ID : SharedA_B_AG
   

   Note:

   • Perform Step 5 if you have WebGate installed.

   • Perform Step 6 if WebGate is not yet installed.

5. Output LDIF Created: Import the LDIF to write information to the directory server. Otherwise, skip this step.

6. WebGates Not Installed: Install WebGateA and WebGateB and specify the same values as you did when creating the profile (plus additional values to properly finish the installation).

7. Installed WebGates: Using output from the OAMCfgTool Create command, run the Oracle Access Manager configureWebGate tool to set up the WebGate. For example:

   1. Go to:

      WebGate_install_dir\access\oblix\tools\configureWebGate

      where WebGate_install_dir is the directory where WebGate is installed.

   2. Run the following command to configure the WebGate using values specified with OAMCfgTool and other values needed to finish the installation. For example:

      configureWebGate -i WebGate_install_dir -t WebGate SharedA_B_AG  
      -P WebGate_password
      -m <open|simple|cert>
      -h Access_Server_Host_Name
      -p Access_Server_Port
      -a Access_Server_ID
      -r Access_Server_Pass_Phrase (must be the same as the WebGate_password)
      -Z Access_Server_Retry count
      

      See Also:

      "Configuring AccessGates and WebGates" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager

   3. Repeat these steps to configure WebGateB.

8. Confirm Profile in the Access System Console: Perform the following steps to view or modify the WebGate profile.

   1. Log in to the Access System Console as a Master or Delegated Access Administrator. For example:

           http://hostname:port/access/oblix
      

      hostname refers to computer that hosts the Web server; port refers to the HTTP port number of the Web server instance; /access/oblix connects to the Access System Console.

   2. Click Access System Configuration, and then click AccessGate Configuration.

   3. Click the All button to find all profiles (or select the search attribute and condition from the lists) and then click Go.

   4. Click a WebGate's name to view its details.

   5. Click Cancel to dismiss the page without changes, or click Modify to change values as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

9. In the load balancer host identifiers, add host name variations for both WebGates: WebGateA and WebGateB.

9.4.8.7 Error 401: Unable to Access the Application

An error message like the following:

401 Authorization Required

This typically means that the Oracle Access Manager Authentication Provider is incorrectly configured. For a listing of correct configurations, see "Oracle Access Manager Authentication Provider Parameter List".

9.4.8.8 Error 403: Unable to Access the Application

An error message like the following:

403 Forbiden

This typically means that the post-authenticate actions are incorrectly configured in the policy domain. Under the policy domain's authentication success actions, ensure that you have set obmygroups and uid in the Return Attribute field (not in the Return Value field).

For more information, see "Configuring a Policy Domain for the Oracle Access Manager Authenticator".

9.4.8.9 Error 404: Not Found ... Anything Matching the Request URI

Generally, this error indicates that the server has not found anything matching the Request-URI. This message informs that the Oracle WebLogic Server is not able to find a resource.

There is no indication of whether the condition is temporary or permanent:

• If the server cannot make temporary or permanent information available to the client, the status code 403 (Forbidden) can be used.

• If, through some internally configurable mechanism, the server could state that an old resource is permanently unavailable and has no forwarding address, the 410 (Gone) status code should be used.

To recover from Error 404

Confirm that the resource is deployed on the Oracle WebLogic Server. For example, if the pattern is /private1/Hello, confirm that Hello is accessible on the server with private1 as the root.

9.4.8.10 Error Issued with the Action URL in Form Login Page

This issue occurs if Form Authentication scheme is not properly configured in Oracle Access Manager. However, this cannot occur if you use the OAMCfgTool to set up a policy domain. For example:

Symptoms include:

• The user name and password fields in the login form must match the details in the Form authentication scheme

• The credential_mapping filter must be specified correctly in the Form authentication scheme

• The login form action URL must be protected with a policy

• The login form action URL must match the Action value specified in the authentication scheme's challenge parameter

9.4.8.11 Error or Failure on Oracle WebLogic Server Startup

If the WebLogic Server user is not part of the administrator's group in Oracle Access Manager, Oracle WebLogic Server restart and Authentication Provider initialization can fail. In this case, one of the following messages might appear in the AdminServer.log in $DOMAIN_HOME/servers/AdminServer/logs/AdminServer.log:

)<Failed ---- FatalError:InvalidSchemeMapping 
...
Authentication Failed.
...
Login failed.
...

Solution

1. Confirm that the implementation is using the Oracle-provided default login form.

2. Create a group named "Administrators" in the Oracle Access Manager Identity System, and include the Oracle WebLogic Server user.

   See Also:

   Oracle Access Manager Identity and Common Administration Guide

3. Login to Oracle WebLogic Server using the credentials of the user in the Administrators group defined within the Oracle Access Manager Identity System.

4. Restart the Oracle WebLogic Server.

9.4.8.12 JAAS Control Flag

If this flag is set to REQUIRED and any other parameter is set to an incorrect value, the server does not start.

To prevent this issue, ensure that the Oracle Access Manager Authentication Provider is properly configured while this parameter value is set to OPTIONAL. Only after you have validated proper behavior in this way, should you reset the control flag to REQUIRED.

For more information, see "Configuring Providers for the Authenticator in a WebLogic Domain".

9.4.8.13 Login Form is Shown Repeatedly Upon Credential Submission: No Error

This issue typically points to an incorrect user name or password. No error is shown.

Ensure that you are supplying the correct user name and password. The user login name must be the value of the attribute that is configured in the Form Login authentication scheme. For example, Challenge Parameter creds: userid.

9.4.8.14 Logout and Session Time Out Issues

When a user logs out, or a user session times out, the user should be challenged for reauthentication. However, the following might occur instead:

• Logout: After logging out, if the user attempts to access the application in the same browser window the application is still accessible without reauthenticating.

• Session Time Out: After a user session time out, the user is challenged to reauthenticate. However, if the user gives a different user ID he is granted the same privileges as the previous user.

The ObSSOCookie is still present. Some configuration must be done at the application level to kill the ObSSOCookie. For proper behavior, WebLogic application session time out values should be the same as WebGate session time out values.

If setting up an Identity Asserter in the WebLogic Application Console, the Web application using the Identity Asserter must have its auth-method set to CLIENT-CERT. For more information, see "Configuring OAM Identity Assertion for SSO with Oracle Access Manager 10g".

9.4.8.15 Not Found: The requested URL or Resource Was Not Found

If you receive a message stating that the requested URL or resource was not found on this server, the reverse proxy Web server might not be forwarding requests to the Oracle WebLogic Server.

To ensure that the reverse proxy is forwarding requests to Oracle WebLogic Server

1. Locate the httpd.conf file on the reverse proxy WebGate Web server. For example:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

2. Confirm the correct settings to forward requests to the correct host and port of the Oracle WebLogic Server:

     #httpd.conf
         <IfModule mod_weblogic.c>
           WebLogicHost <host>
             WebLogicPort yourWlsPortNumber
         </IfModule>
   
         <Location /request-uri-pattern>
            SetHandler weblogic-handler
         </Location>
   

9.4.8.16 Oracle WebLogic Server Fails to Start

If the Oracle WebLogic Server fails to start, you can take the following actions.

1. Determine whether the Oracle Access Manager Authentication Provider is the only provider configured in the Oracle WebLogic Server realm. If it is, continue with Step 2.

2. Confirm whether the Oracle Access Manager Authentication Provider is configured correctly and make any changes needed.

3. Determine whether the Oracle Access Manager Authentication Provider control flag is set to REQUIRED. In this case, perform the following steps:

   1. Create an Administrators group in the directory server, if one does not already exist (or any other group for which you want boot access).

      Note:

      To provide access to any other group, you must create that group in the directory server and add the user who boots WebLogic Server in that group.

   2. Confirm that the LDAP user who boots Oracle WebLogic Server is included in the Administrators (or other) group.

   3. From the WebLogic Administration Console, go to Security Realms, Your Realm, Roles and Policies, Global Roles.

   4. Select View Conditions for the Administrators (or other) role.

   5. Add the group and click Save.

9.4.8.17 Oracle ADF Integration and Cert Mode

Problem

WebGate configuration of cache directives might not be compatible with certain browser versions (specifically Internet Explorer v7) when accessing certain URLs that allow you to download Microsoft Office documents (.xls, .doc, and so on).

For example, suppose that you have an Excel workbook deployed along with an Oracle ADF application in an Oracle Access Manager Cert-based environment.

If the ADFDi component is trying to access two URLs, and trying the second URL first, a failure occurs regardless of the ADFDi client side code. It is not able to handle the redirect from Oracle Access Manager WebGate to the SSL enabled endpoint and fails with the following stack trace:

WebException: The request was aborted: Could not create SSL/TLS secure channel

If you attempt to access the workbook, and the following message appears:

Microsoft Office Excel cannot access the file 

The cause could be any of the following:

• The file name or path does not exist.

• The file is being used by another program.

• The workbook you are trying to save has the same name as a currently open workbook.

However, if the message appears when the URL to workbook is explicitly pasted to Internet Explorer v7 address bar it might be due to WebGate default Cache Directives.

WebGates have default Cache Directives (Pragma=no-cache and CacheControl=no-cache) that might cause a problem with Internet Explorer v7 when a URL to an .xls workbook is directly pasted into the browser's address bar.

Solution

If the message appears when the URL to workbook is explicitly pasted to Internet Explorer v7 address bar, Oracle recommends removing the cache directives from respective WebGate configuration pages in the Access System Console.

To remove cache directives from respective WebGate configurations

1. From the Access System Console, click the Access System Configuration tab.

2. Click AccessGate Configuration, click Go on the search page, and then click the link to the desired AccessGate configuration page.

3. On the Details for AccessGate page, click Modify.

4. On the Modify AccessGate page, locate Web Server Client label and clear the following fields:

   • CachePragmaHeader

   • CacheControlHeader

5. Click Save.

9.4.8.18 URL Rewriting and JSESSIONID

In some cases when an application resource (URL) is accessed and the JSESSIONID cookie is not found, WebLogic Server rewrites the URL by including the JSESSIONID as part of the URL. If the URL in question is protected, Oracle Access Manager and OSSO Web agents might have issues matching the re-written URL.

To avoid issues of a mismatch with Oracle Access Manager, you can create a policy for matching the URL with JSESSIONID. For this example, suppose the protected URL is:

/myapp/login

You can create a policy within the appropriate policy domain to match the URL with JSESSIONID.

To avoid issues matching a re-written URL

1. Go to the Policy Manager and log in. For example:

   http://Webserver:port/access/oblix
   

   where Webserver refers to computer that hosts the Policy Manager Web server; port refers to the HTTP port number of the Web server instance; /access/oblix connects to the Access System.

2. Click Policy Manager., click My Policy Domains, and click the link to the desired policy domain.

3. Click the Policies tab, and then click Add.

   Fill in and save General details:

   Name: JSESSIONID Matching Policy

   Resource operation(s): Select all applicable HTTP operations

   Resource: Select the context root (create it if needed). For example: /myapp

   URL Pattern: login

   Click Save.

9.5 Deploying the OracleAS 10g Single Sign-On (OSSO) Solution

The OracleAS Single Sign-On solution provides single sign-on access to Web Applications. Oracle Internet Directory is the LDAP-based repository.

This solution is intended for applications that have been deployed on Oracle WebLogic Server but do not yet have single sign-on implemented. Requirements and steps to configure the OSSO solution are explained in "New Users of the OSSO Identity Asserter".

Note:

Oracle recommends using Oracle Access Manager 11g, as described in "Introduction to Oracle Access Manager 11g SSO".

Applications that are already using the OracleAS Single Sign-On solution with the JPS login module and dynamically re-directing requests to OSSO are unaffected by the new OSSO solution. In this case, there is no need to configure the new OSSO Authentication Provider described in this section.

This section is divided as follows:

• Using the OSSO Identity Asserter

• New Users of the OSSO Identity Asserter

• Troubleshooting for an OSSO Identity Asserter Deployment

9.5.1 Using the OSSO Identity Asserter

This section describes the expected behavior when you implement the OracleAS Single Sign-On Identity Asserter. This section is divided as follows:

• Oracle WebLogic Security Framework

• OSSO Identity Asserter Processing

• Consumption of Headers with OSSO Identity Asserter

9.5.1.1 Oracle WebLogic Security Framework

Figure 9-19 illustrates the location of components in the Oracle WebLogic Security Framework, including the OSSO Identity Asserter. Additional details follow.

Figure 9-19 Location of OSSO Components in the Oracle WebLogic Security Framework

Description of "Figure 9-19 Location of OSSO Components in the Oracle WebLogic Security Framework"

At the top of the figure, Oracle HTTP Server is installed. This installation includes mod_weblogic and mod_osso, which are required to pass the identity token to the Providers and Oracle WebLogic Server. The Oracle WebLogic Server includes the partner application and the Identity Asserter (also known as the Identity Assertion Provider). The 10g OracleAS Single Sign-On server (OSSO Server), on the right side of the figure, communicates directly with the directory server and Oracle HTTP Server.

Note:

For simplicity in text, this chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server, the name of this plug-in differs from release 10g to 11g:

• Oracle HTTP Server 10g: mod_wl (actual binary name is mod_wl_20.so)

• Oracle HTTP Server 11g: mod_wl_ohs (actual binary name is mod_wl_ohs.so)

9.5.1.2 OSSO Identity Asserter Processing

Figure 9-20 illustrates the processing that occurs when you have OSSO implemented with the Identity Asserter. Additional details follow the figure.

Figure 9-20 OSSO Identity Asserter Processing

Description of "Figure 9-20 OSSO Identity Asserter Processing"

The first time a request for a protected resource arrives at the mid-tier Web server, the request is redirected to the 10g OracleAS Single Sign-On server, which requires user credentials For a certificate-based authentication, no login page is displayed. After the user has been successfully authenticated, all further requests from that user require only that the user identity be asserted by the OSSO Identity Asserter before the population of a JAAS Subject takes place. The Subject is consumed by the downstream applications.

For example, suppose you have an application residing on an Oracle WebLogic Server that is front-ended with the Oracle HTTP Server. The application is protected using resource mappings in the mod_osso configuration. This case is described in the following process overview.

Process overview: OSSO Identity Asserter

1. The user requests a protected application.

2. The Oracle HTTP Server intercepts the request and processes it using mod_osso to check for an existing, valid Oracle HTTP Server cookie.

3. If there is no valid Oracle HTTP Server cookie, mod_osso redirects to the OracleAS SSO Server, which contacts the directory during authentication.

4. After successful authentication mod_osso decrypts the encrypted user identity populated by the OSSO server and sets the headers with user attributes.

5. mod_weblogic completes further processing and redirects the request to the Oracle WebLogic Server.

6. The WebLogic security layer invokes providers depending on their settings and the order specified. For example: the security layer invokes the:

   • Identity Asserter, which makes the identity assertion based on retrieved tokens

   • Oracle Internet Directory Authenticator (OID Authenticator), which populates the Subject with necessary Principals

   See Also:

   "Consumption of Headers with OSSO Identity Asserter"

7. A response is sent to the user through the Oracle HTTP Server, and access to the application is granted.

9.5.1.3 Consumption of Headers with OSSO Identity Asserter

This topic describes the headers sent by Oracle HTTP Server and the tokens set in the header and the headers consumed by the OSSO Identity Asserter. If the application needs to use the JAAS subject, configure OSSO Identity Asserter.

Table 9-14 provides the list of headers set by Oracle HTTP Server (mod_osso and mod_weblogic). An application whose logic consumes the JAAS subject for identifying user information, should be configured to use the OSSO Identity Asserter. which uses the OracleAS SSO token type set in bold in the table (Proxy-Remote-User). The OSSO Identity Asserter looks for the Proxy-Remote-User header and asserts the user's identity. The follow up OID Authenticator populates the JAAS subject.

Table 9-14 Headers Sent by Oracle HTTP Server

Attribute	Sample Value	Description
Cookie	OHS-Stads42.us.oracle.com:7777=.......	Cookies
Osso-User-Guid	4F4E3D2BF4BFE250E040548CE9816D7E	GUID of the authenticated user
Osso-User-Dn	cn=orcladmin,cn=users, dc=us,dc=oracle,dc=com	DN of the authenticated user
Osso-Subscriber	DEFAULT COMPANY	Subscriber name
Osso-Subscriber-Dn	dc=us,dc=oracle,dc=com	Base DN of the subscriber
Osso-Subscriber-Guid	4F4E3D2BF410E250E040548CE9816D7E	GUID of the subscriber
Proxy-Remote-User	ORCLADMIN	The authenticated user
Proxy-Auth-Type	Basic SSO	Authentication type

Applications that do not require the JAAS subject for identifying user information, can read the headers directly using the request.getHeader() API. Such applications are free to read any header they need. Headers with user info are Osso-User-Dn, Osso-User-Guid, and Proxy-Remote-User.

9.5.2 New Users of the OSSO Identity Asserter

The new OracleAS Single Sign-On solution includes the OSSO Identity Asserter, one of the two new Authentication Providers for the Oracle WebLogic Server.

To have your application use the OSSO solution, you need the components described in the following task.

Note:

If you already have components installed and set up, you do not need more. You can skip any steps that do not apply to your deployment.

Task overview: Deploying and configuring the OSSO Identity Asserter

1. Install the following components:

   1. OracleAS Single Sign-On Server 10g (10g OSSO server

      See Also:

      Oracle Application Server Installation Guide on Oracle Technology Network at: http://www.oracle.com/technology/documentation/oim1014.html

   2. An Oracle Internet Directory repository configured to be used by the 10g OSSO server. Ensure that the directory server is tuned for your deployment.

      See Also:

      The following manuals for Release 11g (11.1.1.1.0)

      • Oracle Fusion Middleware Installation Guide for Oracle Identity Management

      • Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

   3. One of the following Web servers (based on Apache 2):

      • Oracle HTTP Server 11g as a front end to the Oracle WebLogic Server. This installation includes mod_osso and mod_weblogic.

      • OHS 10g, available in the companion CD release Oracle HTTP Server 10.1.3. This includes mod_osso. However, mod_weblogic must be added.

        See Also:

        The following manuals for Release 11g (11.1.1.1.0)

        • Oracle Fusion Middleware Installation Guide for Web Tier

        • Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server

   4. Oracle WebLogic Server 10.3.1+

      See Also:

      Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server

   5. An Oracle Fusion Middleware product such as Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter is required; it includes the provider required for OSSO by Oracle WebLogic Server in the following path:

      ORACLE_INSTANCE/modules/oracle.ossoiap_11.1.1/ossoiap.jar
      

      See Also:

      • Oracle Fusion Middleware Installation Guide for Oracle Identity Management

      • Oracle Fusion Middleware Installation Guide for Oracle SOA Suite

      • Oracle Fusion Middleware Installation Guide for Oracle WebCenter

2. Configure mod_weblogic so that it forwards requests to Oracle WebLogic Server, as explained in section "Configuring mod_weblogic".

3. Register the module mod_osso with the 10g SSO Server as a partner application, as described in "Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4".

4. Configure mod_osso, as described in "Configuring mod_osso to Protect Web Resources".

5. Add the OSSO Identity Asserter to the appropriate domain, as explained in section "Adding Providers to a WebLogic Domain for OSSO".

6. Configure a connection filter, as explained in section "Establishing Trust Between Oracle WebLogic Server and Other Entities".

7. Configure the use of the solution by the application, as explained in section "Configuring the Application for the OSSO Identity Asserter".

8. Identify and resolve issues with your OSSO Identity Asserter implementation, see "Troubleshooting for an OSSO Identity Asserter Deployment".

9.5.2.1 Configuring mod_weblogic

You can either edit the Oracle HTTP Server httpd.conf file directly or add mod_weblogic configuration in a separate file and include that file in httpd.conf.

The following procedure includes steps for two different Web server releases. Perform steps as needed for your deployment:

• OHS 11g ships with mod_wl_ohs.so. In this case, skip Step 1.

• OHS 10g does not ship with mod_weblogic (mod_wl_.so). If Oracle HTTP Server 10g is installed, start with Step 1 to copy mod_wl_20.so before configuration.

Note:

For Oracle HTTP Server, the name of this plug-in differs from release 10g to 11g:

• Oracle HTTP Server 10g: mod_wl (actual binary name is mod_wl_20.so)

• Oracle HTTP Server 11g: mod_wl_ohs (actual binary name is mod_wl_ohs.so)

To install and configure mod_weblogic

1. Oracle HTTP Server 10.1.3: Copy mod_wl_20.so to the Oracle HTTP Server modules directory: For example:

   From: WL_HOME/wlserver_10.0/server/plugin/linux/i686

   To: ORACLE_HOME/ohs/modules

2. Locate the Oracle HTTP Server httpd.conf file. For example:

   Oracle HTTP Server 10.1.3:

   ORACLE_HOME/ohs/conf/httpd.conf
   

   Oracle HTTP Server 11g:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

3. Verify that mod_weblogic configuration is in httpd.conf, either by inclusion of the appropriate configuration file or the configuration itself directly. For example, for Oracle HTTP Server 10g:

   LoadModule weblogic_module ${ORACLE_INSTANCE}/ohs/modules/mod_wl_20.so
   <IfModule mod_weblogic.c>
      WebLogicHost yourHost.yourDomain.com
        WebLogicPort yourWlsPortNumber
   </IfModule>
    
   <Location /request-uri-pattern>
      SetHandler weblogic-handler
   </Location>
   

9.5.2.2 Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4

The mod_osso module is an Oracle HTTP Server module that provides authentication to OracleAS applications. This module resides on the Oracle HTTP Server that enables applications protected by OracleAS Single Sign-On to accept HTTP headers in lieu of a user name and password once the user has logged into the OracleAS Single Sign-On server. The values for these headers are stored in a mod_osso cookie.

The mod_osso module enables single sign-on for Oracle HTTP Server by examining incoming requests and determining whether the requested resource is protected. If it is, then it retrieves the Oracle HTTP Server cookie.

Under certain circumstances, you must register Oracle HTTP Server mod_osso using the 10.1.4 Oracle Identity Manager single sign-on registration tool (ssoreg.sh or ssoreg.bat). Table 9-15 provides a summary of parameters and values for this purpose. Running the tool updates the mod_osso registration record in osso.conf. The tool generates this file whenever it runs.

Table 9-15 ssoreg Parameters to Register Oracle HTTP Server mod_osso

Parameter	Description
-oracle_home_path	Path to the 10.1.4 SSO Oracle_Home
-site_name	Any site name to be covered
-config_mod_osso	TRUE. If set to TRUE, this parameter indicates that the application being registered is mod_osso. You must include config_mod_osso for osso.conf to be generated.
-mod_osso_url	URL for front-ending Oracle HTTP Server Host:port. This is the URL that is used to access the partner application. The value should be specified in the URL format:http://oracle_http_host.domain:port
-update_mode	Optional. CREATE, the default, generates a new record.
-remote_midtier	Specifies that the mod_osso partner application to be registered is at a remote mid-tier. Use this option only when the mod_osso partner application to be configured is at a different ORACLE_HOME, and the OracleAS Single Sign-On server runs locally at the current ORACLE_HOME.
-config_file	Path where osso.conf is to be generated
[-admin_info	Optional. User name of the mod_osso administrator. If you omit this parameter, the Administer Information field on the Edit Partner Application page is left blank.
admin_id	Optional. Any additional information, such as email address, about the administrator. If you omit this parameter, the Administrator E-mail field on the Edit Partner Application page is left blank.
<VirtualHost ...>	Host name. Optional. Include this parameter only if you are registering an Oracle HTTP virtual host with the single sign-on server. Omit the parameter if you are not registering a virtual host. If you are creating an HTTP virtual host, use the httpd.conf file to fill in the directive for each protected URL.

See Also:

The following books on Oracle Technology Network at: http://www.oracle.com/technology/documentation/oim1014.html

• Oracle Application Server Single Sign-On Administrator's Guide 10g (10.1.4.0.1) Part Number B15988-01

• Oracle Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01

The following procedure includes a sample command to register mod_osso. Values for your environment will be different.

To register mod_osso

1. Go to the following 10.1.4 Oracle Identity Manager directory path:

   ORACLE_HOME/sso/bin/ssoreg
   

2. Run ssoreg with the following parameters and values for your environment. For example, on Unix, this might look like:

   ./ssoreg.sh -oracle_home_path \OraHome -site_name wls_server  
   -config_mod_osso TRUE -mod_osso_url http://oracle_http_host.domain:7788 
   -update_mode CREATE -remote_midtier -config_file \tmp\osso.conf
   

3. Verify that the module mod_osso of the required Oracle HTTP Server is registered.

4. Proceed to "Configuring mod_osso to Protect Web Resources".

9.5.2.3 Configuring mod_osso to Protect Web Resources

mod_osso redirects the user to the single sign-on server only if the URL you request is configured to be protected. You can secure URLs in one of two ways: statically or dynamically. Static directives simply protect the application, ceding control over user interaction to mod_osso. Dynamic directives not only protect the application, they also enable it to regulate user access.

For more information, see:

• Configuring mod_osso with Static Directives

• Protecting URLs and Logout Dynamically (without mod_osso)

9.5.2.3.1 Configuring mod_osso with Static Directives

You can statically protect URLs with mod_osso by applying directives to the mod_osso.conf file. You must configure mod_osso to ensure that requests are intercepted properly. In addition, you specify the location of protected URIs, time out interval, and the authentication method. Oracle recommends that you place in the httpd.conf file the include statement for mod_osso.conf before the one wherein the weblogic_module statement is loaded.

The following procedure describes how to configure mod_osso by editing the mod_osso.conf file. This procedure provides details for two different releases. Ensure that you follow instructions for your OHS deployment:

• Oracle HTTP Server 11g: Requires Step 2 and AuthType Osso in Step 4. The path name in Step 5 differs for Oracle HTTP Server 11g.

• Oracle HTTP Server 10g: Requires Step 3 and AuthType Basic in Step 4. The path name in Step 5 differs for Oracle HTTP Server 10g.

To configure mod_osso to protect Web resources

1. Copy osso.conf from the location where it was generated to the following location:

   From: /tmp/osso.conf

   To:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf  
   

2. Oracle HTTP Server 11g: Copy mod_osso.conf from the disabled directory to the moduleconf directory for editing. For example:

   From:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/disabled/mod_osso.conf  
   

   To:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf  
   

3. Oracle HTTP Server 10g: Locate mod_osso.conf for editing. For example:

   ORACLE_HOME/ohs/conf/mod_osso.conf
   

4. Edit mod_osso.conf to add the following information using values for your deployment. For example, using Oracle HTTP Server as an example (paths are different for 10g):

   LoadModule osso_module ${ORACLE_HOME}/ohs/modules/mod_osso.so
   <IfModule mod_osso.c>
   
   OssoIdleTimeout off
   OssoIpCheck on
   OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf   
   
   #Location is the URI you want to protect
   <Location />
   require valid-user
   #OHS 11g AuthType Osso    
   #OHS 10g AuthType Basic    
   AuthType Osso
   
   </Location>
   
   </IfModule>
   

5. Locate the httpd.conf file for editing. For example:

   Oracle HTTP Server 10.1.3:

   ORACLE_HOME/ohs/config/httpd.conf
   

   Oracle HTTP Server 11g:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf 
    
   

6. In the httpd.conf, confirm that the mod_osso.conf file path for your environment is included. For example:

   include /ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf
   

7. Restart the Oracle HTTP Server.

   Tip:

   If the interception of requests is not working properly, consider placing the include statement for mod_osso.conf before the LoadModule weblogic_module statement in the httpd.conf.

8. Proceed to "Adding Providers to a WebLogic Domain for OSSO".

9.5.2.3.2 Protecting URLs and Logout Dynamically (without mod_osso)

Applications that use dynamic directives require no entry in mod_osso.conf because mod_osso protection is written directly into the application as one or more dynamic directives.

Dynamic directives are HTTP response headers that have special error codes that enable an application to request granular functionality from the single sign-on system without having to implement the intricacies of the single sign-on protocol. Upon receiving a directive as part of a simple HTTP response from the application, mod_osso creates the appropriate single sign-on protocol message and communicates it to the single sign-on server.

OracleAS supports dynamic directives for Java servlets and JSPs. The product does not currently support dynamic directives for PL/SQL applications. The JSPs that follow show how such directives are incorporated. Like their "static" counterparts, these sample "dynamic" applications generate user information:

• Example 9-2, "SSO Authentication with Dynamic Directives"

• Example 9-3, "SSO Logout with Dynamic Directives"

Note:

After adding dynamic directives, be sure to restart the Oracle HTTP Server, and the proceed to "Adding Providers to a WebLogic Domain for OSSO".

Example 9-2 SSO Authentication with Dynamic Directives

The home.jsp includes ssodynauth.jsp that uses the request.getUserPrincipal().getName() method to check the user in the session. If the user is absent, it issues dynamic directive 499, a request for simple authentication. The key lines are in boldface.

//home.jsp

<%@ include file="ssodynauth.jsp" %>
<%
//page content goes here
%>

//ssodynauth.jsp

<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "0");
%>
<%
// Check for user
String ssoUser = null;
try
(
//ssoUser = request.getRemoteUser();
ssoUser = request.getUserPrincipal( ).getName( );
ssoUser = ssoUser.trim( );
 }
catch(Exception e)
{
ssoUser = null;
 }

// If user is not authenticated then generate
// dynamic directive for authentication
if((ssoUser == null) || (ssoUser.length() < 1))
{
response.sendError(499, "Oracle SSO");
return;
}%>

See Also:

Oracle Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01 on Oracle Technology network at: http://www.oracle.com/technology/software/products/ias/htdocs/101401.html

Example 9-3 SSO Logout with Dynamic Directives

To achieve global logout (also known as single log-out), applications are expected to first invalidate sessions and then make a call to OSSO logout. The logout.jsp issues dynamic directive 470, a request for OSSO logout. The osso-return-logout is set by the application to specify the return URL after logout.

The key lines for SSO logout with dynamic directives appear in boldface in the following example. In 11g, the SSOFilter handles session synchronization.

//logout.jsp
<%@page session="false"%>
<%
   response.setHeader("Osso-Return-Url", "http://my.oracle.com/");
   HttpSession session =  null;
   session = request.getSession();
   if (null != session )
   {
     // necessary for achieving SLO
     session.invalidate();
   }
   response.sendError(470, "Oracle SSO");
%>

See Also:

• "Synchronizing the User and SSO Sessions: SSO Synchronization Filter"

• Oracle Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01 on Oracle Technology Network at: http://www.oracle.com/technology/software/products/ias/htdocs/101401.html

Note:

After adding dynamic directives, be sure to restart the Oracle HTTP Server, and the proceed to "Adding Providers to a WebLogic Domain for OSSO".

9.5.2.4 Adding Providers to a WebLogic Domain for OSSO

You must add the OSSO Identity Asserter to a WebLogic domain. In addition to the OSSO Identity Asserter, Oracle recommends the following Authentication Providers:

• OSSO Identity Asserter

• DefaultAuthenticator

• OID Authenticator

See Also:

"About Oracle WebLogic Server Authentication and Identity Assertion Providers"

You can add providers using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

See Also:

• "About Oracle WebLogic Server Authentication and Identity Assertion Providers"

• Oracle Fusion Middleware Oracle WebLogic Scripting Tool

• Oracle Fusion Middleware WebLogic Scripting Tool Command Reference

The following procedure illustrates adding Authentication Providers using the Oracle WebLogic Administration Console. Before you begin, there is a condition to pay attention to:

Step 10: If your application requires the user in the same case as in Oracle Internet Directory (uppercase, lowercase, initial capitals), check Use Retrieved User Name as Principal. Otherwise, leave it unchecked.

To add providers to your WebLogic domain for OSSO Identity Assertion

1. Log in to the WebLogic Administration Console.

2. OSSO Identity Asserter: Perform the following steps to add this to the domain:

   1. Click Security Realms, Default Realm Name, Providers.

   2. Select New under the Authentication Providers table.

   3. Enter a name for the new provider, select its type, and then click OK. For example:

      Name: OSSO Identity Asserter

      Type: OSSOIdentityAsserter

      Ok

   4. Click the name of the newly added provider.

   5. On the Common tab, set the appropriate values for common parameters and set the Control Flag to SUFFICIENT and then save the settings.

3. Default Authentication Provider:

   1. Click Security Realms, Default Realm Name, Providers.

   2. Click Default Authentication Provider.

   3. Set the control flag to OPTIONAL, and click Save

4. OID Authenticator: Perform the following steps to add this provider.

   1. Click Security Realms, Default Realm Name, Providers.

   2. Click New, and enter a name and type:.

      Name. OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      Click Save.

   3. Click the newly added authenticator to see the Settings page. Retain the default settings; do not change the Control Flag until you have verified that the Oracle Internet Directory configuration is valid.

      Note:

      If OID Authenticator is the only provider, ensure the WebLogic Server user account and its granted group memberships are created in Oracle Internet Directory. Otherwise the WebLogic domain does not start properly.

   4. Click the Provider Specific tab and specify the following required settings:

      Propagate Cause For Login Exception: Check

      Principal: LDAP administrative user. For example: cn=orcladmin

      Host: The Oracle Internet Directory hostname

      Use Retrieved User Name as Principal: Check

      Credential: LDAP administrative user password. For example: password

      Confirm Credential: For example: password

      Group Base DN: Oracle Internet Directory group search base

      User Base DN: Oracle Internet Directory user search base.

      Port: Oracle Internet Directory port

5. Reorder Providers: The order in which providers populate a subject with principals is significant and you might want to reorder the list of all providers in your realm and bring the newly added provider to the top of the list.

6. Save all configuration settings.

7. Stop and restart the Oracle WebLogic Server for the changes to take effect.

8. Log in to the WebLogic Administration Console:

   1. Click Security Realms, Default Realm Name, Providers.

   2. Select the Users and Groups tab to see a list of users and groups contained in the configured Authentication Providers.

      You should see usernames from the Oracle Internet Directory configuration, which implicitly verifies that the configuration is working.

      --If the Oracle Internet Directory instance is configured successfully, you can change the Control Flag.

      --If the Oracle Internet Directory authentication is sufficient for an application to identify the user, then choose the SUFFICIENT flag. SUFFICIENT means that if a user can be authenticated against Oracle Internet Directory, no further authentication is processed. REQUIRED means that the Authentication Provider must succeed even if another provider already authenticated the user.

9. Application Requires User in Same Case as in Oracle Internet Directory: Check Use Retrieved User Name as Principal. Otherwise, leave it unchecked.

10. Save the changes.

11. Activate the changes and restart Oracle WebLogic Server.

12. Proceed with "Establishing Trust Between Oracle WebLogic Server and Other Entities".

9.5.2.5 Establishing Trust Between Oracle WebLogic Server and Other Entities

The Oracle WebLogic Connection Filtering mechanism must be configured for creating access control lists and for accepting requests from only the hosts where Oracle HTTP Server and the front-end Web server are running.

Note:

This topic is the same whether you are using OSSO or Oracle Access Manager. In the WebLogic Administration Console.

A network connection filter is a component that controls the access to network level resources. It can be used to protect resources of individual servers, server clusters, or an entire internal network. For example, a filter can deny non-SSL connections originating outside of a corporate network. A network connection filter functions like a firewall since it can be configured to filter protocols, IP addresses, or DNS node names. It is typically used to establish trust between Oracle WebLogic Server and foreign entities.

Connection Filter Rules: The format of filter rules differ depending on whether you are using a filter file to enter the filter rules or you enter the filter rules in the Administration Console. When entering the filter rules on the Administration Console, enter them in the following format:

targetAddress localAddress localPort action protocols

See Also:

"Configuring Security in a WebLogic Domain" in Oracle Fusion Middleware Securing Oracle WebLogic Server

Table 9-16 provides a description of each parameter in a connection filter.

Table 9-16 Connection Filter Rules

Parameter	Description
target	Specifies one or more systems to filter
localAddress	Defines the host address of the WebLogic Server instance. (If you specify an asterisk (*), the match returns all local IP addresses.)
localPort	Defines the port on which the WebLogic Server instance is listening. (If you specify an asterisk, the match returns all available ports on the server.)
action	Specifies the action to perform. This value must be allow or deny.
protocols	Is the list of protocol names to match. The following protocols may be specified: http, https, t3, t3s, giop, giops, dcom, ftp, ldap. If no protocol is defined, all protocols match a rule.

The Connection Logger Enabled attribute logs successful connections and connection data in the server. This information can be used to debug problems relating to server connections.

To configure a connection filter to allow requests from the host of the 11g Oracle HTTP Server

1. Log in to the Oracle WebLogic Administration Console.

2. Click Domain under Domain Configurations.

3. Click the Security tab, click the Filter tab.

4. Click the Connection Logger Enabled attribute to enable the logging of accepted messages for use when debugging problems relating to server connections.

5. Specify the connection filter to be used in the domain:

   • Default Connection Filter: In the Connection Filter attribute field, specify weblogic.security.net.ConnectionFilterImpl.

   • Custom Connection Filter: In the Connection Filter attribute field, specify the class that implements the network connection filter, which should also be specified in the CLASSPATH for Oracle WebLogic Server.

6. Enter the appropriate syntax for the connection filter rules.

7. Click Save.

8. Restart the Oracle WebLogic Server.

9. Proceed to "Configuring the Application for the OSSO Identity Asserter".

9.5.2.6 Configuring the Application for the OSSO Identity Asserter

This topic describes how to create the application authentication method for the OSSO Identity Asserter.

See Also:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

Oracle WebLogic Server supports adding multiple auth-methods. If you are setting up an OSSO Identity Asserter in the WebLogic Application Console, the Web application using the OSSO Identity Asserter must have its auth-method set to CLIENT-CERT.

After deploying the application on the Oracle WebLogic Server, all web.xml files in the application EAR file must include CLIENT-CERT in the element auth-method for the appropriate realm, as described in the following procedure.

To edit web.xml for the OSSO Identity Asserter

1. Locate the web.xml file in the application EAR file. For example:

   WEB-INF/web.xml  
   

2. Locate the auth-method for the appropriate realm and enter CLIENT-CERT. For example:

   <login-config>
     <auth-method>CLIENT-CERT</auth-method>
     <realm-name>myRealm</realm-name>
   </login-config>
   

3. Save the file.

4. Redeploy and restart the application.

5. Repeat for each web.xml file in the application EAR file.

9.5.3 Troubleshooting for an OSSO Identity Asserter Deployment

The troubleshooting items described in this section are grouped into the following categories:

• SSO-Related Problems

• OSSO Identity Asserter-Related Problems

• URL Rewriting and JSESSIONID

• About mod_osso, OSSO Cookies, and Directives

• About Using IPv6

See Also:

• "Setting Up Debugging in the WebLogic Administration Console"

• Oracle Application Server Single Sign-On Administrator's Guide for 10g, Troubleshooting, on the Oracle Technology Network at: http://www.oracle.com/technology/documentation/oim1014.html

9.5.3.1 SSO-Related Problems

This section addresses the following troubleshooting items:

• OHS Is Not Redirecting to SSO - Internal Server Error 500

• Is Attribute AuthName Required?

• URL Request not Redirected to SSO

• Error 404 - Not Found is Issued (OHS Side)

• Error 404 - Not Found is Issued (Oracle WebLogic Server Side)

• Oracle SSO Failure - Unable to process request

• OSSO Solution for Applications Deployed on a Stand-alone WebLogic Server

OHS Is Not Redirecting to SSO - Internal Server Error 500

The most likely source of this problem is an incorrect configuration.

The following sample uses Oracle HTTP Server 11g. Path names are different if you have Oracle HTTP Server 10g.

To address it, proceed as follows:

1. Open the file mod_osso.conf and ensure that the resource is protected. For example:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf  
   

   <Location /protected-resource-uri>
   require valid-user
   AuthType Basic
   </Location>
   

2. Ensure that osso.conf is present and included in mod_osso.conf. For example, using Oracle HTTP Server 11g (paths are different for 10g)

   OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf  
   

   Note:

   There is no set location for osso.conf. The value is determined at registration time; it can be any absolute path.

3. Ensure that httpd.conf includes mod_osso.conf. For example, using Oracle HTTP Server 11g (paths are different for 10g):

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

   include /ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf
   

4. If all of the above were correctly specified, the SSO registration did not complete successfully and you must re-register SSO.

   To register SSO, proceed as follows using the appropriate ssoreg tool for your platform. For example:

   1. Run ssoreg.sh in 10.1.4 ORACLE_HOME/sso/bin to produce the file osso.conf. The following is a sample usage of this utility that produces the file in /tmp/osso.conf (the arguments are displayed in different lines only for illustration):

      >ssoreg.sh -oracle_home_path /OraHome 
                 -site_name wls_server 
                 -config_mod_osso TRUE 
                 -mod_osso_url http://host.domain.com:6666 
                 -update_mode CREATE 
                 -remote_midtier 
                 -config_file /tmp/osso.conf
      

   2. Copy the generated osso.confto another file system directory. For example: ORACLE_INSTANCE/config/OHS/<ohs_name>/osso.

   3. Restart OHS.

Is Attribute AuthName Required?

Log messages might suggest that the attribute AuthName is required, and certain versions of Apache do require this attribute.

This example uses Oracle HTTP Server 11g. Path names are different for Oracle HTTP Server 10g.

To include this attribute, edit the file mod_osso.conf and insert a fragment like the following:

LoadModule osso_module modules/mod_osso.so
<IfModule mod_osso.c>
OssoIdleTimeout off
OssoIpCheck on
OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf
 
<Location />
AuthName "Oracle Single Sign On"
require valid-user
AuthType Basic
</Location>
</IfModule>

URL Request not Redirected to SSO

Once a URL request is issued, if a basic pop-up is displayed instead of being redirected to SSO, then, most likely, the URL request has been intercepted by the Apache authorization module.

To address this problem, proceed as follows:

1. Edit the file httpd.conf and comment out the loading authorization modules as illustrated in the following fragment:

   ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
   

   LoadModule access_module modules/mod_access.so
   #LoadModule auth_module modules/mod_auth.so
   #LoadModule auth_anon_module modules/mod_auth_anon.so
   #LoadModule auth_db_module modules/mod_auth_dbm.so
   LoadModule proxy_module modules/mod_proxy.so
   

2. Restart OHS.

Error 404 - Not Found is Issued (OHS Side)

Typically, this error has the following format:

The requested URL <request-uri> was not found on this server

Most likely, the WebLogic redirect is not happening, and the request is attempting to grab an OHS resource not available.

To address this problem, verify that mod_weblogic is included in the file httpd.conf and that the WebLogic handler is set for the request pattern, as illustrated in the following fragment:

#httpd.conf
<IfModule mod_weblogic.c> 
 WebLogicHost <host>
  WebLogicPort yourWlsPortNumber
</IfModule>
 
<Location /request-uri-pattern>
 SetHandler weblogic-handler
</Location>

Error 404 - Not Found is Issued (Oracle WebLogic Server Side)

Typically, this error has the following format:

Error 404--Not Found

Cause

This message informs that the Oracle WebLogic Server is not able to find a resource.

Solution

To address the problem, check that the resource is indeed deployed on the server. For example, if the pattern is /private1/Hello, check that Hello is accessible on the server with private1 as root.

Oracle SSO Failure - Unable to process request

Problem

You receive a message stating:

Oracle SSO Failure - Unable to process request
Either the requested URL was not specified in terms of a fully-qualified host
name or Oracle HTTP Server single sign-on is incorrectly configured.
Please notify your administrator. 

Solution

Modify the Oracle HTTP Server httpd.conf file to include a port number in the ServerName and restart the Web server. For example:

From: ServerName host.domain.com

To: ServerName host.domain.com:port

OSSO Solution for Applications Deployed on a Stand-alone WebLogic Server

This chapter describes how to configure single sign-on (SSO) for applications that are deployed on Oracle Fusion Middleware Oracle WebLogic Server. However, details for applications that are deployed on a stand-alone Oracle WebLogic Server (one without Fusion Middleware) are provided here:

• Oracle Fusion Middleware with OSSO: The required OSSO Identity Asserter (ossoiap.jar) is provided automatically when you install Oracle Fusion Middleware: Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter.

  Note:

  Oracle Fusion Middleware with OSSO enables you to use either the Oracle HTTP Server 10g or 11g Web server.

• Stand-Alone Oracle WebLogic Server with OSSO: The required OSSO Identity Asserter (ossoiap.jar) must be acquired from the Oracle Web Tier, as described here.

  Note:

  Without Fusion Middleware, OSSO requires Oracle HTTP Server 11g.

Whether you use OSSO for Oracle Fusion Middleware applications or other applications, the Identity Asserter performs the same functions as those illustrated and described in "Using the OSSO Identity Asserter".

Included in the following are additional, optional, details that you can use to configure and test Single Logout for session invalidation and synchronization between the SSO cookie and the JSESSIONID cookie. Required files must be acquired from the Oracle Web Tier.

Task overview: Deploying and configuring the OSSO Identity Asserter for applications on a stand-alone WebLogic Server

1. Install Oracle WebLogic Server 10.3.1+ and other required components as follows:

   1. Perform Step 1, a-d as described in the "Task overview: Deploying and configuring the OSSO Identity Asserter for applications on a stand-alone WebLogic Server".

   2. Skip Step 1e and instead deploy your application.

2. Create a WebLogic security domain with the weblogin domain extension template that is supplied with Oracle WebLogic Server and can be used from $WLS_HOME/common/bin/config.sh.

3. Configure mod_weblogic to forward requests to Oracle WebLogic Server, as explained in "Configuring mod_weblogic".

4. Register and configure the module mod_osso with the 10g SSO Server as a partner application, as described in "New Users of the OSSO Identity Asserter".

   1. Perform steps described in "Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4".

   2. Perform steps described in "Configuring mod_osso to Protect Web Resources".

5. Add Authentication Providers to the appropriate security domain as follows:

   1. Acquire the OSSO Identity Asserter (ossoiap.jar from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.ossoiap_11.1.1/ossoiap.jar  
      

   2. Copy ossoiap.jar into $WLS_HOME/wlserver_10.x/server/lib/mbeantype, then restart the Oracle WebLogic Server.

   3. Configure providers as described in "Adding Providers to a WebLogic Domain for OSSO".

6. Configure the Oracle WebLogic Connection Filtering mechanism to create access control lists and accept requests from the hosts where Oracle HTTP Server and the front-end Web server are running, as explained in "Establishing Trust Between Oracle WebLogic Server and Other Entities".

   Note:

   Test the secured application to ensure that it is working with the default authenticator using the Oracle WebLogic Server host and port.

7. Configure the application authentication method for the OSSO Identity Asserter (all web.xml files in the application EAR file must include CLIENT-CERT in the element auth-method), as explained in "Configuring the Application for the OSSO Identity Asserter".

   Note:

   Test the application with users authenticated by OSSO while accessing the application with the Oracle HTTP Server host and port.

8. Optional: You can configure and test Single Logout [Session Invalidation and synchronization between the SSO cookie and JSESSIONID cookie] as follows:

   See Also:

   ""Synchronizing the User and SSO Sessions: SSO Synchronization Filter" for details on SSOFilter

   1. Acquire ssofilter.jar and configure Oracle WebLogic Server to use it as follows:

      1. Acquire ssofilter.jar from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.ssofilter_11.1.1/ssofilter.jar  
      

      2. Copy it to an appropriate directory in Oracle Middleware home: WLS_INSTALL/Oracle/Middleware/modules directory, for example.

      3. Add the absolute path of ssofilter.jar to the Oracle WebLogic Server classpath (by editing the setDomainEnv.sh script POST_CLASSPATH variable or CLASSPATH variable).

   2. Deploy system-filters.war as a system filter, as follows:

      1. Acquire system-filters.war from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.jrf_11.1.1/system-filters.war 
       
      

      2. Copy system-filters.war to an appropriate directory in Oracle Middleware home: WLS_INSTALL/Oracle/Middleware/modules directory, for example.

      3. Deploy system-filters.war as an application library: From the WebLogic Administration Console, click Deployment, select New, and choose the location of file.

      4. Restart the Oracle WebLogic Server, if asked.

   3. Enable Logs to verify that the SSOFilter is working, as follows:

      1. From the WebLogic Administration Console, click Domain, Environment, Servers, AdminServer.

      2. Click the Logging tab.

      3. From the Advanced drop-down, select "Minimum Severity to Log" as "Debug".

      4. From the Advanced drop-down, "Message destinations", select LogFile: Severity Level as "Debug".

      5. Save changes and restart the Oracle WebLogic Server.

   4. Confirm that the SSOFilter is loaded as a system filter:

      1. Open the AdminServer.log file in DomainHome/Servers/AdminServer/log/AdminServer.log.

      2. Search for "SSOFilter" and confirm that you can see <Debug> messages, which indicate SSOFilter initialization nd confirm a filter load

   5. Test the filter functionality to confirm that the SSO and JSESSIONID cookie are cleaned up after user logout and that attempts to access the application after logout require another login.

      Note:

      You must have OSSO Identity Asserter configured in the WebLogic security domain, otherwise the filter will automatically disable during its initialization.

   6. Test logout with applications to confirm that the session is ends cleanly.

SSO Users Specified in "Users to Always Audit" Must Be Uppercase

When you specify SSO users in the Oracle HTTP Server audit configuration "Users to Always Audit" section, the SSO username must be specified in uppercase characters.

A comma-separated list of users can be specified to force the audit framework to audit events initiated by these users. Auditing occurs regardless of the audit level or filters that have been specified. This is true for all authentication types.

For more information, see "Managing Audit Policies" in the chapter "Configuring and Managing Auditing" in the Oracle Fusion Middleware Application Security Guide.

9.5.3.2 OSSO Identity Asserter-Related Problems

This section addresses the following troubleshooting items:

• Error 403 - Forbidden

• Error 401 - Unauthorized

• OSSO Identity Assertion Not Getting Invoked

Error 403 - Forbidden

This message informs that the user does not have the required permission to access a resource. This message is shown, for example, when the application has been configured to allow access to users belonging to WLS Group SSOUsers and the asserted user belongs to a different group.

If you have verified that this is not a permissions issue, then check whether the JAAS Control Flag for the Default Identity Authenticator is set to REQUIRED, and if so, change the setting to OPTIONAL or to SUFFICIENT, as appropriate.

Error 401 - Unauthorized

This message informs that the access to a resource requires the user to be first authenticated.

Solution

1. Check that the user is indeed authenticated.

2. Check whether the server is being hit without first going through authentication using SSO.

OSSO Identity Assertion Not Getting Invoked

Situations in which the OSSO Identity Asserter is not getting invoked for a protected source, typically, involve incorrect configuration. Make sure that your environment accurately includes a configuration as that described in "Configuring the Application for the OSSO Identity Asserter".

9.5.3.3 URL Rewriting and JSESSIONID

In some cases when an application resource (URL) is accessed and the JSESSIONID cookie is not found, WebLogic Server rewrites the URL by including the JSESSIONID as part of the URL. If the URL in question is protected, Oracle Access Manager and OSSO Web agents might have issues matching the re-written URL.

To avoid issues of a mismatch, you can append an asterisk, *, to the end of the protected resource specified in mod_osso.conf. For example, if the protected URL is:

/myapp/login

The location in the mod_osso entry would be:

<Location /myapp/login*>
valid user
AuthType OSSO
</Location>

9.5.3.4 About mod_osso, OSSO Cookies, and Directives

Mod_osso module provides communication between the SSO-enabled login server and the Oracle HTTP Server listener. The mod_osso module is controlled by editing the mod_osso.conf file:

• Oracle HTTP Server 11g installation includes mod_osso and mod_weblogic.

• OHS 10g, available in the companion CD release Oracle HTTP Server 10.1.3, includes mod_osso.

  See Also:

  The following topic and Release 1 (11.1.1) manuals

  • "Configuring mod_osso to Protect Web Resources"

  • Oracle Fusion Middleware Installation Guide for Web Tier

  • Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server

This section provides the following information:

• New OssoHTTPOnly Directive in mod_osso

• OssoSecureCookies Directive in mod_osso

• Mod_osso Does Not Encode the Return URL When Redirecting to OSSO for Logout

9.5.3.4.1 New OssoHTTPOnly Directive in mod_osso

A new configuration directive has been added to mod_osso to configure setting the HTTPOnly flag on OSSO cookies. The new Directive is: OssoHTTPOnly. Values are On (to enable) and Off (to disable) the flag. By default, the HTTPOnly flag is set to On; the directive is not set in the configuration.

This directive appends the HttpOnly flag to the OSSO cookies set in the browser. This purpose of this flag is to prevent cross-site scripting. Cookies that have this flag set are not accessible by javascript code or applets running on the browser. Cookies that have this flag set is only sent to the server that set the cookie for the particular domain across over http or https.

This is a per VirtualHost directive. It can only be set at the global scope or inside a VirtualHost section. The following example shows the new directive:

<VirtualHost *.7778> 
OssoConfigFile  conf/osso.conf
OssoHTTPOnly On
---
---
---
<Location /osso>
AuthType Osso
---
---
</Location> 

</VirtualHost> 

9.5.3.4.2 OssoSecureCookies Directive in mod_osso

In mod_osso 10g, the OssoSecureCookies directive is disabled by default. However, in mod_osso 11g, this behavior is enabled by default. In mod_osso 11g, to disable the OssoSecureCookies directive you must set OssoSecureCookies to Off in the corresponding configuration file. When mod_osso is enabled, the mod_osso.conf file is available at:

ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf

Set the OssoSecureCookies directive as follows:

OssoSecureCookies "Off"

9.5.3.4.3 Mod_osso Does Not Encode the Return URL When Redirecting to OSSO for Logout

Mod_osso does not URL encode the return URL in the query when redirecting to the Oracle SSO Server for logout.

To fix this issue, the encoded URL must be passed. For example: response.setHeader("Osso-Return-Url", encoded-url)

9.5.3.5 About Using IPv6

Oracle Fusion Middleware supports Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6.) Among other features, IPv6 supports a larger address space (128 bits) than IPv4 (32 bits), providing an exponential increase in the number of computers that can be addressable on the Web.

See Also:

Oracle Fusion Middleware Administrator's Guide for details about using IPv6 with the Oracle Single Sign-on Server.

9.6 Synchronizing the User and SSO Sessions: SSO Synchronization Filter

In Fusion Middleware 11g, a new component that synchronizes the container user session and SSO session has been introduced. SSO Sync Filter is an Oracle WebLogic system filter implementation that intercepts all requests to the container, acts on protected resource requests, and attempts to synchronize the container's user session with the user identifying header in OSSO (Proxy-Remote-User) or the user data in the Oracle Access Manager SSO session cookie (ObSSOCookie).

SSO Synchronization Filter (SSO Sync Filter) is an implementation of the Servlet Filter based on Java Servlet Specification version 2.3. SSO sync filter relieves applications from tracking the SSO user session and synchronizing it with their respective sessions. Instead, applications would only need to synchronize with container's user session.

SSO Sync Filter intercepts each request to the container and determines whether to act on it based on certain HTTP headers that are attached to the request. Filter expects SSO agent to have set those headers in the Web Tier. When access is made to unprotected areas of the application, the filter acts as a pass through. Once a protected resource is accessed, SSO agents in the Web Tier, direct user to perform authentication with SSO system such as Oracle Access Manager. After the authentication, Oracle Access Manager Identity Asserter helps establish a user identity in form of JAAS Subject to the container and a user session is created. WebLogic maintains the user session data as part of HTTP Session Cookie (JSESSIONID).

Subsequent access to the application resources provides two pieces of information to the SSO Sync Filter:

• User identifying header in OSSO (Proxy-Remote-User)

• User data in the Oracle Access Manager SSO session cookie (ObSSOCookie)

The job of SSO Sync Filter is to make sure that the user identity in the container matches with that of the SSO session. If there is a mismatch, filter invalidates the container's user session. As a result, the downstream application would only have to track container user session and react in a consistent fashion regardless of SSO environment in use.

Notes:

• Enabled and Active by Default: SSO Sync Filter fetches the user information from the configured tokens, gets the user from existing session (if any), invalidates the session and redirects to the requested URL in case the CurrentSessionUser does not match the incoming SSO User. Otherwise, the request is simply passed through.

  If you have not configured the OSSO or Oracle Access Manager Assertion Providers in your domain, the filter disables automatically during WebLogic Server start-up.

• Active for All URI's by Default (/* ): No changes are required in the application code.

• Configured for the OSSO Tokens/Header: Proxy-Remote-User, and performs a case insensitive match.

• Configured for the Oracle Access Manager SSO Tokens/Header: OAM_REMOTE_USER and REMOTE_USER, and does a case insensitive match.

• Global Logout: SSO Sync Filter is intended to provide the Single Logout Experience to the Oracle Fusion Middleware applications that use the OSSO or Oracle Access Manager Solutions. Is handled similarly to single sign-on. After global logout is performed, SSO filter reconciles the session when subsequent access to an application that has not cleaned up its session is made.

  Any application that use the OSSO or Oracle Access Manager Solutions is expected to invalidate its session before making a call to OSSO logout or Oracle Access Manager logout. For more information on OSSO logout, see "SSO Logout with Dynamic Directives". For details about Oracle Access Manager logout, see "Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates".

• Application Session Time Out: SSO cookies typically track user inactivity/idle times and force users to login when a time out occurs. OSSO and Oracle Access Manager are no exception. Oracle Access Manager takes a sophisticated approach at this and specifically tracks Maximum Idle Session Time and Longest Idle Session Time along with SSO session creation time and time when it was last refreshed.

  The general recommendation for applications that are maintaining their own sessions when integrating with SSO systems is to configure their session time outs close to that of SSO session time outs so as to make user experience remains consistent across SSO and application session time outs.

You can alter the behavior of the SSO Sync Filter for application requirements by passing various over-riding system properties to WebLogic. To do this, you change the Oracle WebLogic startup script and check for EXTRA_JAVA_PROPERTIES in setDomainEnv.sh. The properties and Sync behavior is shown in Table 9-17.

Table 9-17 SSO Sync Filter Properties and Sync Behavior

Area	Overriding System Property	Default value of System property	Default Behavior of the Sync Filter
Status (Active or Inactive)	sso.filter.enable	Not configured	Enabled
Case sensitive matches	sso.filter.name.exact.match	Not configured	Case Ignore Match
Configured Tokens	sso.filter.ssotoken	Not configured	OSSO: Look for Proxy-Remote-User Oracle Access Manager: Look for OAM_REMOTE_USER and REMOTE_USER. OAM_REMOTE_USER takes precedence.
URI Mappings	Not Applicable	Not Applicable	/*

You cannot enable the filter for selected applications. The SSO Sync Filter is a system filter. As such, it is activated for all deployed applications (the URI mapping is /*).

Note:

You cannot enable the filter for selected applications.

The following procedure gives some tips about modifying the SSO Sync filter properties and behavior.

To modify the SSO Sync Filter properties and behavior

1. Disable the Filter: Change the system property "sso.filter.enable" to "false" (pass as -D to the jvm) and restart the Oracle WebLogic Server. This toggles the filter status.

2. User-Identifying Header Differs from Pre-Configured Sync Filter Tokens: Over-ride the SSO token that the Sync Filter looks for using the system property "sso.filter.ssotoken".

   For example, pass to the WebLogic Server jvm in the WebLogic Server startup script -Dsso.filter.ssotoken=HEADERNAME, and restart the server.

When you contact Oracle Support you might be requested to set up debugging. The following procedure describes how to do this.

9.7 Setting Up Debugging in the WebLogic Administration Console

The Authentication Providers use messages with verbose descriptions of low-level activity within the application when Debug mode issued. Ordinarily, you do not need this much information. However, if you must call Oracle Support, you might be advised to set up debugging. When set, Authentication Providers messages appear in the Oracle WebLogic Server default log location.

To set up debugging

1. Log into WebLogic Administration Console.

2. Go to Domain, Environment, Servers, yourserver.

3. Click the Debug tab.

4. Under Debug Settings for this Server, click to expand the following: weblogic, security, atn.

5. Click the option beside DebugSecurityAtn to enable it.

6. Save Changes.

7. Restart the Oracle WebLogic Server.

8. In the Oracle WebLogic Server default log location, search for SSOAssertionProvider. For example:

   ####<Apr 10, 2009 2:32:16 AM PDT> <Debug> <SecurityAtn> <sta00483> <AdminServer> <[ACTIVE] 
   ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> 
   <<WLS Kernel>> <> <> <1239355936490> <BEA-000000> 
   <SSOAssertionProvider:Type          = Proxy-Remote-User>