DCC HTTP Reverse Proxy with OAM and OAM

This article discusses the Detached Credential Collector (DCC) HTTP Reverse Proxy feature that has been introduced in the 11.1.2.2.0 release.

In a deployment where this feature is enabled, a WebGate SSO Agent:

In this mode, all interactions between the users/clients and OAM is done via the WebGate DCC HTTP Reverse Proxy: no users will access directly the OAM servers anymore.

This new DCC HTTP Reverse Proxy capability is different from the previous DCC for HTTPBasic/FORM based login, with the latter not working for the Federation SSO flows (IdP or SP mode).

Overview

This article does not include any topologies containing HTTP reverse proxies or load balancer fronting the various OAM components (the OAM server itself or the WebGate agents) but, includes a use case towards the end indicating how to use DCC HTTP Reverse Proxy in HA deployments, fronted by a load balancer.

Authentication without DCC

The authentication flow without DCC is the most common use case, where the user is redirected from the SSO agents protecting resources in the security domain to the OAM for challenge and authentication. A typical OAM deployment is made of the following entities:

The following diagram describes such an environment:

Description of the illustration local_security_domain.jpg

In the test flow, use the LDAPScheme OOTB as the scheme to protect the resources of the local security domain.

A local authentication flow using the LDAPScheme consists of the following:

  1. User requests access to a protected resource, defined in OAM to be protected by the LDAPScheme.

  2. The WebGate SSO agent intercepts the HTTP request, determines that the user needs to be authenticated and redirects the user to the OAM server for authentication.

  3. User accesses the OAM server; the server initiates an authentication flow using the LDAPScheme and displays the login page

Description of the illustration local_authentication_flow.jpg

Once the user enters its credentials and clicks the login button the following occurs:

  1. The OAM server validates the credentials, creates a session for the user, sets a cookie in the user’s browser and redirects the user to the protected resource.

  2. The user requests access to the resource. This time the WebGate SSO Agent detects that the user is authenticated and grants access to the resource

Description of the illustration local_security_workflow.jpg

DCC for HTTP-Basic/FORM based login

DCC for HTTP-Basic/FORM based login was introduced in previous releases of OAM 11g, and it provides a way for an administrator to designate a WebGate SSO Agent as the entity which:

In the test flow, use the DCCLDAPScheme that is based on the LDAPScheme OOTB, but with the Challenge URL updated to reference the DCC WebGate. This scheme is used to protect the resources of the local security domain.

A local authentication flow using that custom DCCLDAPScheme consists of the following:

  1. User requests access to a protected resource, defined in OAM to be protected by the DCCLDAPScheme.

  2. The WebGate SSO agent intercepts the HTTP request, determines that the user needs to be authenticated and redirects the user to the DCC WebGate’s login page for authentication.

  3. User accesses the DCC WebGate’s login page and provides credentials.

  4. The DCC WebGate interacts directly with the OAM server other the OAM NAP protocol to validate the credentials and to create a session for the user. The DCC WebGate then redirects the user to the protected resource.

  5. The user requests access to the resource. This time the WebGate SSO Agent detects that the user is authenticated and grants access to the resource.

DCC HTTP Reverse Proxy

DCC HTTP Reverse Proxy was introduced in the 11.1.2.2.0 release of OAM and allows the administrator to configure a WebGate SSO Agent to act as the public endpoint for the OAM and OAM server:

Note: Basically, the DCC WebGate becomes the public endpoint for OAM and OAM and acts as an HTTP Reverse Proxy, over the OAM NAP protocol.

In this test, after OAM and the WebGate have been configured for DCC HTTP Reverse Proxy, and uses the LDAPScheme OOTB as the scheme to protect the resources of the local security domain (the scheme won’t have been changed).

Note: Any authentication scheme with a Challenge URL containing a relative path can be used in this DCC mode, such as the FederationScheme. Also, IdP feature is compatible with that DCC mode

A local authentication flow using the LDAPScheme consists of the following:

  1. User requests access to a protected resource, defined in OAM to be protected by the LDAPScheme.

  2. The WebGate SSO agent intercepts the HTTP request, determines that the user needs to be authenticated and redirects the user to the DCC WebGate for authentication.

  3. User accesses the DCC WebGate and forwards the request to the OAM server; the server initiates an authentication flow using the LDAPScheme, returns a login page to be displayed to the DCC WebGate, and the DCC WebGate displays the login page to the user.

Description of the illustration local_authentication_flow_LDAP.jpg

Once the user enters credentials and clicks the login button the following occurs:

  1. The DCC WebGate sends the HTTP request containing the credentials to the OAM server which validates them, creates a session for the user, creates a cookie and returns an HTTP Response with the cookie and a redirection command to the DCC WebGate; the DCC WebGate sets the cookie in the user’s browser and redirects the user to the protected resource.

  2. The user requests access to the resource. This time the WebGate SSO Agent detects that the user is authenticated and grants access to the resource

Description of the illustration local_security_LDAPworkflow.jpg

Setting Up DCC HTTP Reverse Proxy

Initial Setup

The steps required to configure an OAM deployment for DCC HTTP Reverse Proxy are divided into:

To configure a specific WebGate SSO Agent as a DCC WebGate, perform the following steps:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

  2. Navigate to Access Manager , SSO Agents.

  3. Search for the WebGate entry you already registered.

  4. Click and open the WebGate entry.

  5. Check the Allow Credentials Collector Operations box.

  6. In the User Defined Parameter box, add the following line: TunneledUrls=/oam,/oamfed.

  7. Click Apply.

Description of the illustration Setting_DCC.jpg

To update the Authentication Policies for the OAM and OAM services, perform the following steps:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

  2. Navigate to Access Manager , Application Domains.

  3. Search for the Application Domain related to the DCC WebGate.

  4. Open the Application Domain.

  5. Click on the Resources tab.

  6. Configure the following resource as Public resources, by marking the resources as Unprotected and setting a public authentication policy and a public authorization policy:

  7. Click Apply

Description of the illustration Authentication_Policies.jpg

To update the OAM configuration to specify the DCC WebGate as the new public endpoint for OAM

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

  2. Navigate to Configuration , Access Manager Settings.

  3. In the OAM Server Host, enter the hostname that is used to access the DCC WebGate via the browser.

  4. In the OAM Server Port, enter the port that is used to access the DCC WebGate via the browser.

  5. In the OAM Server Protocol, enter the http protocol that is used to access the DCC WebGate via the browser.

  6. Once done, those three fields should reference the DCC WebGate HTTP/HTTPS endpoint.

  7. Click Apply.

Description of the illustration OAM_configuration.jpg

Once the three configuration changes are done, OAM and OAM is configured to use the DCC WebGate as the HTTP Reverse Proxy over the NAP protocol.

As a test, if federation has been enabled in the OAM Administration Console , Configuration Available Services section, you can access the OAM metadata via the DCC WebGate URL: http(s)://dcc-webgatehost:dcc-webgate-port/oamfed/idp/metadata, and it should display the SAML 2.0 Metadata for OAM. In my setup, the Metadata showed up without having to restart any services, and the URLs of the Federation services reference the DCC WebGate location, not the OAM server anymore.

Note: If the Federation ProviderID needs to be updated, you can do so via the OAM Administration Console , Configuration , Federation, and the change is reflected in the Metadata’s entityID attribute.

An example of the metadata is (entityID is derived from the OAM Administration Console , Configuration , Federation section):

<md:EntityDescriptor entityID="hUp://oam.acme.com
/oam/fed" ...>
  ...
  <md:IDPSSODescriptor>
    ...
    <md:ArtifactResolutionService ...
Location="hUp://dcc-webgate.acme.com:7777
/oamfed/idp/soap"/>
    <md:SingleLogoutService ... Location="hUp://dccwebgate.acme.com:7777/oamfed/idp/samlv20"/>     <md:SingleSignOnService ... Location="hUp://dccwebgate.acme.com:7777/oamfed/idp/samlv20"/>
    ...
  </md:IDPSSODescriptor>
  ...
</md:EntityDescriptor>

Local Authentication

In my test deployment, I have the following deployed:

The LDAPScheme is the OOTB one and has not been modified, specifically the Challenge URL parameter does not reference WebGate DCC:

Description of the illustration Local_Authentication.jpg

Prior to configuring OAM, OAM and the WebGate2 for DCC HTTP Reverse Proxy, requesting access to the /cgi-bin/printenv protected resource on OHS1 was resulting in WebGate1 intercepting the request and redirecting the browser to the OAM server for authentication:

Description of the illustration Access_Manager_Screen.jpg

Upon entering the correct credentials, OAM was validating the username/password and redirecting the browser to the protected resource.

After having configured OAM, OAM and the WebGate2 for DCC HTTP Reverse Proxy, requesting access to the /cgi-bin/printenv protected resource on OHS1 now results in WebGate1 intercepting the request and redirecting the browser to the DCC WebGate for authentication which forwards the HTTP request over the NAP protocol to the OAM server which sends back to the DCC WebGate a page to be displayed:

Description of the illustration Protected_Access_Screen.jpg

Upon entering the correct credentials, the following occurs:

OAM as an SP

This mode slightly differs from the local authentication use case. The only differences are:

Note: No special configuration is necessary to use the FederationScheme with the DCC HTTP Reverse Proxy!

The FederationScheme is the OOTB one and has not been modified, specifically the Challenge URL parameter does not reference WebGate DCC:

Description of the illustration Authentication_Schemes.jpg

When the protected resource is requested, the following occurs:

  1. User requests access to a protected resource, defined in OAM to be protected by the FederationScheme.

  2. The WebGate SSO agent intercepts the HTTP request, determines that the user needs to be authenticated and redirects the user to the DCC WebGate for authentication.

  3. User accesses the DCC WebGate, which packages the HTTP requests and send it over NAP to the OAM server; the server determines that the user needs to be challenged via the FederationScheme, and the OAM/SP module is invoked.

  4. OAM/SP creates a SAML Request and constructs a 302 redirect URL with the SAML message; OAM packages the data and sends the response back to the DCC WebGate which returns the HTTP response to the user’s browser.

  5. The user’s browser is redirected to the IdP with the SAML Request

Description of the illustration Protected_Resource_Request.jpg

Once the user enters its credentials at the IdP, the following occurs:

  1. The IdP creates a SAML Assertion and redirect the user’s browser with the SAML message to the DCC WebGate (which is the Federation endpoint for OAM, published in the SAML 2.0 Metadata).

  2. The user’s browser presents the SAML Assertion to the DCC WebGate, which packages the HTTP requests and send it over NAP to the OAM server, which in turn invokes the OAM/SP module to process the SAML Assertion.

  3. OAM/SP validates the SAML Assertion, OAM creates a user session, builds a 302 redirect to the protected resource and sends the response back to the DCC WebGate which returns the HTTP response to the user’s browser.

  4. The user is redirected to the protected resource

  5. WebGate SSO Agent grants access

Description of the illustration local_security_Webgatedomain.jpg

OAM as an IdP

In this use case, OAM acts as an Identity Provider and the DCC WebGate is the public endpoint for the IdP. In this setup:

Note: No special configuration is necessary to use the IdP with the DCC HTTP Reverse Proxy!

When a user initiates a Federation SSO from the remote SP, the following occurs:

  1. User starts a Federation SSO operation at the remote SP.

  2. The remote SP creates a SAML Request, and redirects the user to the IdP SAML 2.0 endpoint with the SAML Request: this endpoint is the DCC WebGate HTTP Reverse Proxy, as published in the IdP SAML 2.0 Metadata.

  3. The User accesses the IdP public SAML 2.0 endpoint at the DCC WebGate with the SAML Request; the DCC WebGate packages the HTTP Request and the SAML message and forwards it to the IdP server over the OAM NAP protocol.

  4. The IdP server processes the SAML Request, determines that the user needs to be authenticated via the LDAPScheme, invokes internally OAM for authentication, which in turn return to the DCC WebGate the login page to be displayed; the DCC WebGate decodes the response from OAM sent over NAP, and returns the HTTP response to the user’s browser.

Description of the illustration local_security_FedSSO.jpg

After the display of the login page, the following occurs:

  1. The user enters its credentials and click the login button.

  2. DCC WebGate collects the incoming data, packages it and sends it to the OAM server over NAP.

  3. OAM validates the credentials, creates a session for the user, and returns internally the user’s identity to IdP; the Federation server creates a SAML Assertion, and builds a response containing the Assertion, packages it and returns it to the DCC WebGate, which in turn decodes the data, and sends the HTTP Response with the SAML Assertion to the user’s browser.

  4. The user’s browser posts the SAML Response to the SP which successfully validates the Assertion.

Description of the illustration local_security_DCCWebgate.jpg

DCC HTTP Reverse Proxy and HA

In an HA deployment, the steps required to configure the various components (Load balancer, OAM…) still apply when the DCC HTTP Reverse Proxy feature is used.

Let’s take as an example the following deployment (other kinds of HA topologies uses a similar approach):

The topology in this example looks like:

Description of the illustration local_security_Topology.jpg

The steps required in this example is based on:

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.