21.5 Understanding SSO Cookies

Here is an overview of single sign-on with Access Manager 11g.

It includes the following topics:

21.5.1 Single Sign-On Cookies During User Login

Single Sign-On Cookies can be set or cleared during user login.

Table 21-6 describes the cookies in detail.

Table 21-6 SSO Cookies

SSO Cookie Set at User Login Set By Description

OAM_ID cookie

OAM Server Embedded Credential Collector

When a user attempts to access a protected application, the request comes to the SSO Engine and the controller checks for the existence of the cookie.

See Also: "OAM_ID cookie".

OAMAuthnCookie

11g Webgate

Set by each 11g Webgate that is contacted. Protected by the key known to the respective 11g Webgate and the OAM Server. A valid OAMAuthnCookie is required for a session.

Note: If the user accesses applications protected by different 11g Webgates, you will have multiple OAMAuthnCookies.

See "OAMAuthnCookie for OAM Webgates".

   

A domain-based cookie for 10g Webgates is set only when a 10g Webgate is contacted. Protected with keys known to the OAM Server only. One global shared secret key for all Webgates.

Note: This cookie enables backward compatibility and inter-operability between Access Manager 11g and older agents.

See "ObSSOCookie for 10g Webgates"

OAM_REQ

OAM Server Embedded Credential Collector

A transient cookie that is set or cleared by the OAM Server if the Authentication request context cookie is enabled. Protected with keys known to the OAM Server only.

Note: This cookie is configured as a high availability option to store the state about user's original request to a protected resource while his credentials are collected and authentication performed.

See "OAM_REQ Cookie".

OAMRequestContext

11g Webgate

Set or cleared by the 11g Webgate and protected by the key known to the respective 11g Webgate and the OAM Server.

With Internet Explorer browser:

--When RequestContextCookieExpTime is not set, OAMRequestContext is a transient cookie.

--When RequestContextCookieExpTime is set, the OAMRequestContext cookie expires by the time set using the "Expires" directive. This requires a time sync between the client host and Web server host.

With all other (non-IE) browsers, when RequestContextCookieExpTime is not set OAMRequestContext expires in 5 minutes by default or by the time set using the "Max-Age" directive.

See Also: "OAMRequestContext"

Table 15-2

DCCCtxCookie

Detached Credential Collector

For detached credential collector (DCC)--similar to OAM_REQ created by embedded credential collector (ECC).

See "DCCCtxCookie"

OHS-host-port

Oracle HTTP Server

Set only when OSSO Agents (mod_osso) are contacted on Oracle HTTP Server (OHS). Protected with the key known to the respective mod_osso agent and the OAM Server.

Note: This cookie enables backward compatibility and inter-operability between Access Manager 11g and older agents.

See "mod_osso Cookies".

OAM_GITO cookie

OAM Server

Provides backward compatibility and inter-operability between OSSO 10g and Access Manager 11g. The cookie is created by the OAM Server and accessed or modified by the OAM Server or mod_osso agent.

See "mod_osso Cookies".

OpenSSO cookie

OpenSSO Proxy

See "OpenSSO Cookie (iPlanetDirectoryPro)".

For details about configuring authentication and authorization policies, see Managing Policies to Protect Resources and Enable SSO.

21.5.2 Single Sign-On Server and Agent Cookies

The following sections provide information on the SSO server and agent cookies.

21.5.2.1 OAM_ID cookie

The OAM_ID cookie is scoped to the OAM Server. OAM_ID is generated by the OAM Server when the user is challenged for credentials, and submitted to the server on every redirect to the server. OAM_ID is protected by keys known to the OAM Server only.

When a user attempts to access a protected application, the request comes to the SSO Engine and the controller checks for the existence of the cookie:

  • If the cookie does not exist, user authentication begins. After successful authentication, the user context and token are set by the SSO Engine. The cookie is set with the global user ID (GUID), creation time, and idle timeout details. Information in the cookie is encrypted with the SSO Server key and can be decrypted only by the SSO Engine.

  • If the cookie exists, then the cookie is decrypted and the sign in flow completes with the authenticated user.

21.5.2.2 OAMAuthnCookie for OAM Webgates

There is one OAMAuthnCookie_<host:port>_<random number> set by each OAM Webgate using the authentication token received from the OAM Server after successful authentication. A valid OAMAuthnCookie is required for a session.

SSL Connections: Administrators can ensure the ObSSOCookie is only sent over an SSL connection and prevents the cookie from being sent back to a non-secure Web server by configuring SSL and then specifying Simple or Cert mode for Agents and Servers. For details, see About Communication Between OAM Servers and WebGates.

Cookie Expiration: For OAM Webgate and OAMAuthnCookie, expiration is controlled by the tokenValidityPeriodparameter, which controls the valid token (or cookie) time.

This key is known to both the OAM Webgate and SSO Engine and is used for encrypting OAMAuthnCookie. The SSO engine key (only known to the SSO Engine) is used for encrypting the OAM_ID OAM Server cookie.

21.5.2.3 ObSSOCookie for 10g Webgates

Access Manager 11g sets a key-based cookie ObSSOCookie for each user or application that accesses a resource protected by a 10g Webgate. The key is set up during agent registration and is known to both the agent and SSO Engine (shared between them). This key is different from the OAM Server (or SSO Engine) key.

Removing the ObSSOcookie causes the 10g Webgate to log the user out and requires the user to re-authenticate the next time he or she requests a resource that is protected by the Access System.

The WebGate sends the ObSSOCookie to the user's browser upon successful authentication. This cookie can then act as an authentication mechanism for other protected resources that require the same or a lower level of authentication. When the user requests access to a browser or another resource, the request flows to the OAM Server. The user is logged in, and the ObSSOCookie is set. The OAM Server generates a session token with a URL that contains the ObSSOCookie. Single sign-on works when the cookie is used for subsequent authorizations in lieu of prompting the user to supply authorization credentials.

When the cookie is generated, part of the cookie is used as an encrypted session token. The single sign-on cookie does not contain user credentials such as user name and password.

SSL Connections: Administrators can ensure the ObSSOCookie is only sent over an SSL connection and prevents the cookie from being sent back to a non-secure Web server by configuring SSL and then specifying Simple or Cert mode for Agents and Servers. For details, see "About Communication Between OAM Servers and WebGates".

Cookie Expiration: Administrators can specify the desired Cookie Session Time in the OAM Agent registration. For more information, see "Registering an OAM Agent Using the Console".

21.5.2.4 OAM_REQ Cookie

A transient cookie that is set or cleared by the OAM Server if the Authentication request context cookie is enabled. Protected with keys known to the OAM Server only.

This cookie is configured as a high availability option to store the state about user's original request to a protected resource while his credentials are collected and authentication performed.

In high availability configurations, the Request Cache type must be changed from BASIC to COOKIE using Infrastructure Security custom WLST commands.

Note:

You must invoke the WLST script from the Oracle Common home. See How to Launch the Command-Line Interface in Administering Oracle Fusion Middleware.

21.5.2.5 OAMRequestContext

The OAMRequestContext is set or cleared by the 12c Resource WebGate and protected by the key known to the respective 12c WebGate and the OAM Server.

This cookie is configured to store the state about the user's original request to a protected resource while his credentials are collected and authentication performed.

  • With Internet Explorer browser:

    • When RequestContextCookieExpTime is not set, OAMRequestContext is a transient cookie.

    • When RequestContextCookieExpTime is set, the OAMRequestContext cookie expires by the time set using the "Expires" directive. This requires a time sync between the client host and Web server host.

  • With all other (non-IE) browsers, when RequestContextCookieExpTime is not set OAMRequestContext expires in 5 minutes by default or by the time set using the "Max-Age" directive.

See Also:

RequestContextCookieExpTime in Table 15-2

21.5.2.6 DCCCtxCookie

The DCCCtxCookie comes into play only with the Detached Credential Collector (DCC). The DCCCtxCookie is used by DCC to save various context information required during authentication.

It includes information necessary to reconstruct the original request upon completion of authentication, to maintain server affinity, and to perform iterative multi-step authentication.

By default, DCCCtxCookie is set when the DCC is first redirected away to collect credentials based on the authentication scheme (when the browser is first redirected to the login form with a form-based authentication scheme).

With the DCC, once authenticated the OAM server issues a DCC master session token to the DCC in the authenticate response. DCC then sets a host- based DCC cookie using the token and:

  • If DCC cookie Presented During Authentication: DCC decrypts the token using a DCC key, and performs partial token validation locally (integrity check, token validity period check). If it passes, DCC performs complete token validation for timeout aspects over the OAP channel against the OAM Server.

  • If no DCC Cookie: This indicates a first time authentication which initiates credential collection, performs sanity and syntactic checks on the credential and submits to OAM Server for validation.

21.5.2.7 DCCCtxCookie_COUNT

DCCCtxCookie_COUNT cookie maintains the number of cookies generated after splitting the DCCCtxCookie. While the count is determined by the DCCCtxCookie_COUNT cookie, the configuration parameter, MaxSplittedCookieSize fixes the size of each DCCCtxCookie cookie. By default, the size is set to 4 KB.

This feature enables the Webgate to handle large DCCCtxCookie cookies. When the size of the DCCCtxCookie exceeds 4 KB, some browsers do not support and the user authentication fails. Set appropriate value for the Webgate configuration parameter, MaxSplittedCookieSize in order to split the DCCCtxCookie cookie into multiple cookies each of size 4 KB or less. The number of cookies generated after the split of DCCCtxCookie cookie is tracked by DCCCtxCookie_COUNT cookie.

For example, when the requested URL is too long, the size of DCCCtxCookie cookie becomes 6 KB. With the default setting, the DCCCtxCookie splits into two cookies as follows:

DCCCtxCookie_HOST:PORT_1 (size: 4 KB)

DCCCtxCookie_HOST:PORT_2 (size: 2 KB)

You may encounter a ‘bad request’ error while handling a long URL. To avoid this error, edit httpd.conf file and add LimitRequestFieldSize parameter. The default value for LimitRequestFieldSize is 8 KB.

21.5.2.8 mod_osso Cookies

The mod_osso module is the 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. Located on the application server, mod_osso simplifies the authentication process by serving as the sole application to the single sign-on server. In this way, mod_osso renders authentication transparent to OracleAS applications.

The Administrator for these applications is spared the burden of integrating them with an SDK. After authenticating a user, mod_osso transmits the simple header values that applications may use to authorize the user.

OAM_GITO Cookie

Needed in special cases to support timeout when multiple types of agents (mod_osso and WebGate) are working with Access Manager 11g. Server side session managers can check the validity of the cookie for expiry and timeout during session validation. Global logout is required for OSSO Agents (mod_osso) to ensure that logging out of a session on any entity propagates the logout to all entities.

When a user is authenticated by OSSO 10g, the OSSO Server sets the OAM_GITO cookie. Once the partner cookie (OHS cookie) is set, OHS does not route the request to the server. Instead, on every access, OHS decrypts the OAM_GITO cookie and updates the last activity timestamp. During request processing, if any partner detects that current time has surpassed GITO timeout (last activity time + GITO timeout), the request is sent to OSSO 10g in forced authentication mode. When a request reaches OSSO server in forced authentication mode, server chooses to ignore SSO_ID cookie and challenges user for credentials, considering it as a fresh request. After successful authentication, SSO_ID and OAM_GITO cookie are updated.

This is enabled (using the editGITOValues WLST command), as described in the WLST Command Reference for WebLogic Server.

OssoSecureCookies Directive

Add the OssoSecureCookies directive to set the Secure flag on all cookies. This tells the browser to only transmit those cookies on connections secured by HTTPS. An example of this directive in a mod_osso configuration (mod_osso.conf), is as follows:

<IfModule mod_osso.c>
OssoIpCheck off
OssoIdleTimeout off
OssoSecureCookies on
OssoConfigFile osso/osso.conf
<Location /j2ee/webapp>
require valid-user
AuthType Basic
</Location>
</IfModule>

For more information, see Oracle Application Server Single Sign-On Administrator's Guide.

21.5.2.9 OpenSSO Cookie (iPlanetDirectoryPro)

The agent finds OpenSSO Cookie after the OpenSSO Proxy triggers session validation. The default name of the OpenSSO cookie is iPlanetDirectoryPro.

After the OpenSSO agent is authenticated and logged in, the agent verifies whether the user has an OpenSSO cookie. If not, the user authentication request is initiated from the OpenSSO Agent. During SSO User Login and Authentication flow OpenSSO cookie is created, which contains the OpenSSO session identifier, and this cookie is set in the user's browser.

During End User Session Validation, OpenSSO agent intercepts the request to the protected application and finds an OpenSSO cookie.

During User Single Logout, the OpenSSO Proxy receives a User logout request and forwards the user to the OAM Logout URL OpenSSO Proxy decrypts the OpenSSO cookie, fetches the OpenSSO session identifier and, from that, fetches the OAM session ID. OpenSSO proxy sends the logout request to controller through the OpenSSO logout event with the OAM session ID.

  • SSO User Login and Authentication flow

  • End User Session Validation flow

  • User Single Logout flow