1. Administering Oracle Access Management
  2. Managing Access Manager SSO, Policies, and Testing
  3. Configuring Centralized Logout for Sessions Involving OAM WebGates

27 Configuring Centralized Logout for Sessions Involving OAM WebGates

You can use the Access Manager single logout (also known as global logout) for sessions that involve OAM WebGates. With Access Manager, single logout refers to the process of terminating an active session. Oracle recommends that you use the logout mechanism that is provided by Access Manager in the manner described in the following topics (not custom logout scripts).

The following topics describe how to configure centralized logout for sessions with OAM WebGates:

27.1 Prerequisites for the Configuration of Centralized Logout Sessions Involving OAM WebGates

Before you proceed with the logout sessions configuration ensure the system level requirements are met.

Following are the requirements to perform tasks in this chapter:

  • The application must be deployed on the Web server where the agent is configured and registered with Access Manager.

  • One OAM Agent, on any supported Web server and platform, must be running and registered with Access Manager 12c.

  • Policies must be configured to protect the resource in an Access Manager 12c Application Domain.

27.2 Introduction to Centralized Logout for Access Manager

Centralized logout refers to the process of terminating an active session. OAM provides centralized logout for sessions.

Unless explicitly stated, information in this chapter applies to OAM WebGate Agents using the default embedded credential collector (ECC).

This section provides the following topics:

27.2.1 About Centralized Logout for OAM WebGates

Access Manager provides centralized logout (also known as global log out) for sessions.

Centralized logout refers to the process of terminating an active session, which means that:

  • 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 WebGate Administrator.

Note:

Oracle strongly recommends that applications use the ADF Authentication servlet, which 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.

Unlike partner applications, external applications (Yahoo! Mail, for example), do not delegate authentication to OAM and do not cede logout control to the OAM single sign-on server. It is the user's responsibility to log out of each of these applications.

Table 27-1 describes the circumstances under which centralized logout occurs. When the logout URL is encountered and the OAMAuthnCookie cookie for OAM Webgates is removed Webgate logs out the user and requires user re-authentication.

Table 27-1 Centralized Logout Circumstances

Circumstance Description

Explicitly

The client state is invalidated and the session ends. If a new attempt is made to access the resource, the client must re-authenticate.

  • When the user logs out.

  • When the Administrator terminates the session

  • When the session is terminated based on changes on the identity side

Implicitly

When no user activity occurs within the defined session timeout period, the user is logged out automatically and redirected back to the partner with a new session ID and a new prompt for credentials. This occurs if no lower-level authentication is configured for the resource.

With Access Manager, the user is not logged out if OAM Webgate simply encounters a logout URL unless the logout.html provides an explicit redirection to the Server logout. The Webgate redirects the user to the Server logout.

27.2.2 About Logout Parameters for OAM WebGates

Generally speaking, during centralized logout, the SSO Engine receives a user-session-exists request and sends out a Session Cleared response.

When the SSO Engine receives a user-session-exists request, the Session Management Engine looks up the session and responds with the-session-exists response. The SSO engine sends a Clear Session request. The Session management engine clears the token and session context. The SSO engine then sends a Session Cleared response.

Clearing the user token and the session context clears the server-side state, which includes clearing the OAM_ID cookie set on the server side. When the agent is notified, the agent clears the client-side state of the application.

Configuring OAM WebGates for logout against OAM Servers requires a Logout Callback URL (Table 15-3). Centralized logout for 12c agents sets the cookie from loggedout to empty and expires OAMAuthnCookie_<host:port>_<random number> to explicitly clear it during logout, (rather than leaving behind an empty or logged out cookie).

The SSO Engine supports the central logout page on the OAM Server and:

  • Calls back to Logout Callback URL of OAM WebGates during logout

    The WebGate parameter Logout Callback URL can be configured using a URI format (recommended), without host:port. OAM Server dynamically constructs the full URL based on the host:port in the original request and calls back on it. This can also be a full URL format with a host:port, where OAM Server calls back directly without reconstructing callback URL.

  • Lands on end_url (passed in as query parameter) after logout

Several elements in the OAM Webgate registration page enable centralized logout for OAM WebGates. After registration, the ObAccessClient.xml file is populated with the information in Table 27-2.

Table 27-2 Logout Details After Registration (ObAccessClient.xml)

Element Description

Logout URL

OAM WebGates

The Logout URL triggers the logout handler, which removes the cookie (OAMAuthnCookie for OAM WebGates) and requires the user to re-authenticate the next time he accesses a resource protected by Access Manager.

  • If there is a match, the WebGate logout handler is triggered.

  • If Logout URL is not configured the request URL is checked for "logout." and, if found (except "logout.gif" and "logout.jpg"), also triggers the logout handler.

Default = [] (not set)

Note: This is the standard OAM WebGate configuration parameter used to trigger initial logout through a customized local logout page.

Additional Logout for OAM WebGate Only

For OAM WebGate single sign-off behavior, the following elements and values automate the redirect to a central logout URL, callback URL, and end URL. This replaces OAMWebGate single sign-off only through a customized local logout page.

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. For example:

Default = /oam_logout_success

This can also be a full URL format with a host:port, where OAM Server calls back directly without reconstructing callback URL.

When the request URL matches the Logout Callback URL, Webgate clear its cookies and streams an image .gif in the response.

When Webgate redirects to the server logout page, it records an "end" URL as a query parameter (end_url=http://host:port/..."), which becomes the landing page that the OAM Server redirects back to after logout.

Note: In the remote registration template this parameter is named logoutCallbackUrl (Table 15-10).

Other Oracle Access Management services support the central logout page on the server. The end_url relies on the target URL query parameter passed from OPSS integrated applications. See Also: "Configuring Centralized Logout for Oracle ADF-Coded Applications".

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. For example:

Default = http://OAMServer_host:14200/oam/server/logout

The Logout URL triggers the logout handler, which removes the OAMAuthnCookie_<host:port>_<random number> and requires the user to re-authenticate the next time he accesses a resource protected by Access Manager.

  • When Webgate logout handler is triggered, it redirects to the central logout page specified by the Logout Redirect URL parameter if it is configured.

  • If this is explicitly cleared (and not configured), then 12c behavior is triggered. The local logout page can have a customized script to redirect to the central logout page and can clear additional 3rd party cookies if desired.

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.

Default: end_url

Note: The end_url value is configured using param.logout.targeturl in jps-config.xml.

  • If Logout Target URL is configured, Webgate searches for the value passed in the logout request's query parameter and passes it as end_url query parameter in the redirect URL to OAM Server.

  • If Logout Target URL is not configured, Webgate searches for the default name "end_url" and passes that end_url query parameter along.

27.3 Configuring Centralized Logout for OAM WebGates

You can configure centralized logout for both ECC and DCC enabled OAM WebGates.

This section provides the following topics:

See Also:

Configuring Centralized Logout for Oracle ADF-Coded Applications

27.3.1 Configuring Centralized Logout for OAM WebGates When the ECC is Used

During 12c Resource WebGate registration or editing, you configure the logout parameters.

Note:

If the LogOutUrl parameter is already configured for the OAM WebGate (with a value other than /oamsso/logout.html), then ensure that is also present as part of the LogOutUrl parameter.

See Also:

"Configuring Logout When Using Detached Credential Collector-Enabled WebGate"

To configure centralized logout for OAM WebGates:

  1. Choose your method for registration described in Registering and Managing OAM Agents

  2. When creating or editing an agent registration, include appropriate logout values for your environment (Table 27-2):

    • Logout URL

    • Logout Callback URL

    • Logout Redirect URL

    • Logout Target URL

  3. Finish and save your agent registration, as usual.

  4. Multiple DNS Domains: Perform the following steps if you have multiple DNS domains configured for Access Manager 12c SSO.

    Note:

    The Logout Callback URL can be unique for each WebGate; however, to construct the Logout Callback URL for each WebGate, it is sufficient for the OAM Server to know the host and port of each WebGate from each domain. The file that the Logout Callback URL points to must differ from the logout.html script in the WebGate installation directory.

    1. Configure the Logout Callback URL as the second value in the logOutUrls parameter on each resource WebGate.

      Logout Callback URL is the location on WebGate that the request must be sent to, for clearing the SSO Cookie in that domain. The Logout Callback URL cannot be logout.html.

    2. Ensure that a file physically exists on each Web server at the Logout Callback URL location (usually, at the same location as logout.html).

      For example, if you configure a file named logout.png in the same location as logout.html, then the Logout Callback URL of logout.png would be: 

      /oamsso/logout.png

  5. Perform steps in "Validating Global Sign-On and Centralized Logout".

27.3.2 Configuring Logout When Using Detached Credential Collector-Enabled WebGate

When the DCC receives a logout request from the Agent, the DCC:

  • Decrypts the logout request, if needed

  • Retrieves the end_url, constructs the full URL with the Agent's host:port if needed

  • Clears the DCC cookie (DCCCtxCookie)

  • Sends the logout request across the back channel to terminate the session

  • Logout Callback URLLogout Callback URLsGets a logout page containing links to all visited agent from OAM Sever (which has this information), or get only a list of the visited from OAM Sever to construct a logout page locally, and redirect user to this page on DCC.

  • Returns to the end_url after logout completes

To configure logout for Resource Webgates separate from DCC:

  1. Confirm that the Perl scripts for DCC logout include the actual location of the Perl executable on the Webgate host $WEBGATE_HOME/oamsso-bin/*pl.

  2. Resource Webgate: Modify the Logout Redirect URL to point to DCC's logout.pl:

    1. Find the Resource Webgate Registration: See "WebGate Search Controls".

    2. Modify the Logout Redirect URL to point to the DCC's logout.pl. For example:

      • http://DCCWGhost:port/oamsso-bin/logout.pl

      Note:

      The DCC ignores the Logout Redirect URL parameter in the Webgate registration page. However, if the Resource Webgate Logout Redirect URL is anything other than logout.*, then that URL must be defined in DCC Logout URLs. See Table 24-3

  3. Perform steps in "Validating Global Sign-On and Centralized Logout".

27.4 Validating Global Sign-On and Centralized Logout

You can validate single sign-on global login with different applications, and centralized logout for single or two applications.

This section provides the following topics:

27.4.1 Confirming Global Sign-On

You can observe single sign-on global login.

You must meet the following prerequisites:

  • Agents and Servers must be registered with Access Manager and running

  • Resources and policies controlling SSO must be defined within Access Manager Application Domains

To observe global sign-on:

  1. From a browser, enter the URL to a protected resource.
  2. On the login page, sign in using proper credentials.
  3. Verify that the resource is presented; do not log out.
  4. In the same browser window, enter the URL to another protected resource and confirm that the resource is presented without having to re-authenticate.

27.4.2 Observing Centralized Logout

You can observe centralized logout with OAM Agents.

  • With OAM Agents, the logout URL redirects to the server and cookies are cleared and invalidated so that a subsequent request cannot locate the cookie.

You must meet the following prerequisites:

  • Agents must be registered and running

  • Resources must be protected by Access Manager Application Domains

  • Single sign-on must be configured with authentication and authorization policies and responses in Access Manager Application Domains

To observe centralized logout:

  1. Single Application:

    1. From a browser, enter the URL of the protected resource.

    2. Confirm that the login page appears and sign in using proper credentials.

    3. Confirm that the protected resource is served.

    4. Open a new browser tab or window and access the same resource to confirm that the second attempt does not require another login.

    5. Logout from one tab.

    6. Access the resource again to confirm that a login page appears.

  2. Two Applications:

    1. From a browser, enter the URL of the protected resource.

    2. Confirm that the login page appears and sign in using proper credentials.

    3. In a new tab or window, access another protected application and confirm that the second application does not require another login.

    4. Log out of the first application.

    5. Access the second application and confirm that the login page appears.