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:
-
Becomes a reverse HTTP proxy for the OAM and OAM services
-
Interacts with the user over HTTP/HTTPS.
-
Routes the incoming HTTP requests for the OAM servers to the SSO and Federation servers over the secure OAM NAP protocol.
-
Returns to the HTTP client the response sent by OAM over the NAP protocol.
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 local Security Domain
-
An OAM runtime server responsible of
-
User authentication
-
Managing SSO Agents
-
Resources
-
SSO Agent deployed on HTTP servers, protecting resources
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:
-
User requests access to a protected resource, defined in OAM to be protected by the
LDAPScheme
. -
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.
-
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:
-
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.
-
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:
-
Challenges the user for authentication
-
Collects the user’s credentials
-
Sends them to OAM via the secured OAM NAP protocol for validation
-
Redirects the user to the resource once authentication has been successful
-
In this mode, the DCC WebGate is only used for authentication for
-
HTTP Basic Authentication challenges
-
FORM based authentication
-
Is not used for accessing other OAM services
-
Is only invoked as a credential collector when the scheme protecting the resources is configured to redirect the user to the DCC WebGate
-
Cannot be used in conjunction with OAM as an IdP or SP, or with authentication schemes not based on HTTP Basic Authentication or FORM based authentication
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:
-
User requests access to a protected resource, defined in OAM to be protected by the
DCCLDAPScheme
. -
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.
-
User accesses the DCC WebGate’s login page and provides credentials.
-
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.
-
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:
-
The user is redirected to the DCC WebGate for any authentication operation, without requiring the schemes to be updated to reference the WebGate SSO Agent
-
All OAM services is accessed via the DCC WebGate
-
Login
-
Logout
-
All OAM services is accessed via the DCC WebGate
-
Metadata retrieval (/oamfed/idp/metadata or /oamfed/sp/metadata)
-
IdP services
-
IdP Initiated SSO
-
IdP Federation Protocol Endpoints
-
SP services
-
SP Initiated SSO
-
SP Federation Protocol Endpoints
-
Test SP
-
The OAM and OAM servers won’t be accessed directly anymore
-
The WebGate SSO Agent receives the incoming HTTP Request, package it and send it to OAM via the secured OAM NAP protocol; OAM processes the request and send an HTTP response to the DCC WebGate which returns the HTTP response to the client.
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:
-
User requests access to a protected resource, defined in OAM to be protected by the
LDAPScheme
. -
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.
-
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:
-
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.
-
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:
-
Configure the 11.1.2.2.0+ WebGate SSO Agent for DCC HTTP Reverse Proxy
-
Update the Authentication Policies for the OAM and OAM services
-
Update the OAM configuration to specify the DCC WebGate as the new public endpoint for OAM
To configure a specific WebGate SSO Agent as a DCC WebGate, perform the following steps:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
. -
Navigate to Access Manager , SSO Agents.
-
Search for the WebGate entry you already registered.
-
Click and open the WebGate entry.
-
Check the Allow Credentials Collector Operations box.
-
In the User Defined Parameter box, add the following line:
TunneledUrls=/oam,/oamfed
. -
Click Apply.
Description of the illustration Setting_DCC.jpg
To update the Authentication Policies for the OAM and OAM services, perform the following steps:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
. -
Navigate to Access Manager , Application Domains.
-
Search for the Application Domain related to the DCC WebGate.
-
Open the Application Domain.
-
Click on the Resources tab.
-
Configure the following resource as Public resources, by marking the resources as Unprotected and setting a public authentication policy and a public authorization policy:
-
/oamfed/.../
-
/oam/.../
-
/.../
-
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
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
. -
Navigate to Configuration , Access Manager Settings.
-
In the OAM Server Host, enter the hostname that is used to access the DCC WebGate via the browser.
-
In the OAM Server Port, enter the port that is used to access the DCC WebGate via the browser.
-
In the OAM Server Protocol, enter the http protocol that is used to access the DCC WebGate via the browser.
-
Once done, those three fields should reference the DCC WebGate HTTP/HTTPS endpoint.
-
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’sentityID
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:
-
OAM server running on oam.acme.com on port 14100
-
OHS1 with WebGate1 as an SSO Agent on oam.acme.com on port 23777
-
A resource on that OHS server is
/cgibin/printenv
-
This resource is protected by a policy using the
LDAPScheme
-
OHS2 with WebGate2 acting as the DCC HTTP Reverse Proxy on dcc-webgate.acme.com on port 7777
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:
-
DCC WebGate packages the HTTP Request containing the credentials and send it over NAP to the OAM server
-
OAM server validates the username/password, creates an OAM session, constructs an HTTP Response made of a cookie being set and a 302 redirect referencing the protected resource, packages it and sends it to DCC WebGate
-
DCC WebGate receives the response from the OAM and returns it to the user’s browser
-
The user’s browser is redirected to the protected resource and granted access
OAM as an SP
This mode slightly differs from the local authentication use case. The only differences are:
-
OAM has been enabled
-
A Federation agreement has been put into place between OAM/SP and a remote IdP, configured in OAM/SP to be the Default SSO Identity Provider
-
Instead of using the
LDAPScheme
to protect the resource, theFederationScheme
is used
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:
-
User requests access to a protected resource, defined in OAM to be protected by the
FederationScheme
. -
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.
-
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. -
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.
-
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:
-
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).
-
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.
-
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.
-
The user is redirected to the protected resource
-
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:
-
OAM has been enabled
-
A Federation agreement has been put into place between IdP and a remote SP
-
The IdP has been configured to use
LDAPScheme
as the default scheme to authenticate users. -
The LDAPScheme is the OOTB one and has not been modified, specifically the Challenge URL parameter does not reference WebGate DCC (see the snapshot in the previous section if needed)
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:
-
User starts a Federation SSO operation at the remote SP.
-
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.
-
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.
-
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:
-
The user enters its credentials and click the login button.
-
DCC WebGate collects the incoming data, packages it and sends it to the OAM server over NAP.
-
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.
-
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 sample cluster is made of several OAM runtime servers.
-
Each server is fronted by a DCC HTTP Reverse Proxy WebGate deployed on an OHS instance.
-
A load balancer fronts the various DCC HTTP Reverse Proxy WebGate agents and routes the traffic between them.
The topology in this example looks like:
Description of the illustration local_security_Topology.jpg
The steps required in this example is based on:
-
The steps to set up DCC HTTP Reverse Proxy.
-
The OAM public endpoint configured in the OAM Administration Console , Configuration , Access Manager Settings section references the Load Balancer, and not any of the DCC WebGate Agents.
-
The Load Balancer routes the /oam and /oamfed requests to the DCC WebGate agents.
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.
DCC HTTP Reverse Proxy with OAM
F60231-01
September 2022
Copyright © 2022, Oracle and/or its affiliates.