28.1 Introduction to OpenSSO, Agents, Migration and Co-existence

OpenSSO is the open source version of the Sun Access Management, Federation Management, and Web Services Security product.

Each OpenSSO Agent is a filter that is plugged into a container (Oracle WebLogic Server, JBoss, Apache, and so on) that hosts applications. OpenSSO Agents can co-exist together with Webgates, Access Clients, or OSSO Agents. Oracle provides OpenSSO Assessment and OpenSSO Migration tools that you can use to transition existing OpenSSO agents, profiles, and policies in to Access Manager.

See Also:

Oracle Fusion Middleware Upgrade Guide for Oracle Identity and Access Management for details about Oracle-provided tools and processes to assess and transition OpenSSO agents, profiles, and policies in to Access Manager.

Each OpenSSO Agent provides restricted access to applications by intercepting requests to these applications. After provisioning, OpenSSO Agents use OAM Server instead of the OpenSSO Server.


OpenSSO Agents must be registered with Access Manager to use OAM Server instead of the OpenSSO Server.

After provisioning, OpenSSO Agents use OAM Server instead of the OpenSSO Server. Restricted access to applications is provided by intercepting requests to these applications. OAM Server provides an OpenSSO Proxy that enables communication between the agent and OAM Server and facilitates SSO to the agent-protected application.

OAM Server provides an OpenSSO Proxy that enables communication between the agent and OAM Server and facilitates SSO to the agent-protected application. Using registered OpenSSO Agents, Access Manager provides the features outlined in Table 28-1 (authentication features and a subset of authorization features).

Table 28-1 Features: OpenSSO Agents with Access Manager

OpenSSo Agents Access Manager

Agent Authentication

User Authentication

User Single-Sign-On

User Single Logout

SSO in mixed agents case (between OpenSSO agent and WebGate agent)

User Authorization

Self and Sub-tree mode search

Policy Conditions (Identity, LDAP filter, Session attribute, IP Range, Temporal)

User profile attributes retrieval

Centralized Agent configuration with REST request or response

Migration of Agent profiles, Policies, User Stores, Authentication Stores

Migration Assessment tool

For more information, see:

28.1.1 About Migration and Co-existence Between OpenSSO and Access Manager

Access Manager supports co-existence with an existing OpenSSO Server deployment that has been migrated using the OpenSSO to Access Manager upgrade tool.

The OpenSSO to Access Manager Upgrade makes use of OpenSSO Discovery Agents and Policy mapping logic, which fulfills requirements described in following topics:

For System Requirements and Supported Platforms for Access Manager and OpenSSO, see the Oracle Identity and Access Management matrix on the following site:

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html OpenSSO Policy Migration

The OpenSSO policy is mapped to Access Manager authentication and authorization policies based on available artifacts in the OpenSSO deployment.

Table 28-2 table outlines the mapping that occurs between OpenSSO and Access Manager during Policy migration.

Table 28-2 OpenSSO Policy Migration

Serian OpenSSO Access Manager


Policy Realm

Policy Domain



Authentication and Authorization Policies



Resources plus Host Identifier



Not specified (By default only "GET")



Identity Conditions in Authorization Policies



Authentication Scheme plus Authorization Conditions


Response Providers

Policy Responses Application Domain Creation During OpenSSO Migration

If an existing Access Manager Application Domain and policies do not match an OpenSSO policy domain, a new Application Domain is created in Access Manager.

The created Application Domain corresponds to an OpenSSO Realm. With respect to each Realm, (OpenSSO Top-level and Sub -level Realms), an Application Domain is created in Access Manager.

All existing Application Domains are compared against OpenSSO Policy Domains. The policy name is checked against all existing policies. If a policy of the same name exists, an error occurs. Otherwise, a new policy is created in Access Manager.


An OpenSSO policy referral policy is not migrated. OpenSSO Authentication Policy Migration

An OpenSSO policy containing valid rules and conditions is migrated to an Access Manager Authentication Policy: either a new policy to be created or an existing policy to be updated.

During policy creation, the OpenSSO policy rule host:port information is used to create the host identifier and exact resource URL (or URI) to the Application Domain.


An OpenSSO policy containing artifacts with no rules is not a valid policy.

A policy with conditions is valid for OpenSSO. However, these are migrated based on the default Authentication Policy for Access Manager. Such policies with IP or Temporal conditions can be migrated to Access Manager Authorization Policy conditions.

If the OpenSSO policy is a non-referral policy, an Access Manager Authentication Policy is created containing an authentication scheme with the corresponding authentication module from OpenSSO, host identifier, and resources from OpenSSO policy. In the Access Manager Authorization policy, corresponding OpenSSO constraints and subjects are set.

Limitation: Authentication policy creation exception if the resource already exists (in one of the policy in same Application Domain or Realm. If the resource is already protected by another policy (already exists under the host identifier), new policy creation for the same resource causes an exception. This new policy is not created. The errors are logged in a log file and also displayed in the Oracle Access Management Console. Host Identifier Creation in Access Manager

One Host Identifier is created within Access Manager for each unique host:port combination from OpenSSO.

Need to retrieve all the host:port from each policy rules in each realm and will create the number of hostIdentifiers = number of unique host:port combinations.

Top Realm: By default, OpenSSO has only one top-level realm (/). All other realms can be created under this top-level realm. Ideally, the top-level realm will contain all the host:port combinations for which Host Identifiers are created in Access Manager.

Sub Realm: host:port combinations in policy rules within sub realms depend on the host:port in the Referral policy created under the top realm. The host:port in referral policy is not necessarily from any of the host:port in other non-referral policies in top realm (also referral policy is not applicable for migration). Hence, the host:port in sub realm's policies can be different from the host:port in top realm's policies which are applicable for migration.The host:port from each realm's policies is checked.

Limitation: In OpenSSO, if there are 2 (or more) policies with same rule yet with different authentication schemes to protect the same resource, then only one (the first one in occurrence) can be migrated to Access Manager; the others are ignored and are not created in Access Manager. There are rare chances for such an occurrence.

28.1.2 OpenSSO Agent Reliance on Access Manager

The Oracle Access Manager supports OpenSSO Agents and processing.

The OAM components for OpenSSO are outlined in "Table 28-3".

Table 28-3 OpenSSO Reliance on Access Manager

Component Description

OpenSSO Agent

OpenSSO agents must be registered with Access Manager to establish trust by authenticating themselves. The OAM Server:

  • Authenticates the agents with the credentials provided.

  • Creates a session for the agent.

  • Stores this information in the cache so that any server in the group/cluster can service the next request from the agent.

  • Passes the session identifier to the agent so that it can present this to OAM Server during subsequent interactions.

This agent session does not expire, which enables the Agent to maintain trust continuity with the OAM Server.

The agent registration can be enabled or disabled. When disabled, the Agent does not respond.

Multiple OpenSSO agents can share same centralized configuration (if required and if registered in centralized configuration mode). Even so, each agent has its own unique session and session ID. The agent registration can be configured for the "maximum number of agent sessions allowed" per registration.

It might have a session timeout property that defines whether the agent's session should expire or not.

See Also:

"Registering and Managing OpenSSO Agents Using the Console"

"Understanding Credential Collection and Login"

OpenSSO Proxy

This Oracle-provided proxy is bundled and installed with Access Manager 11.1.2. OpenSSO Proxy enables communication between the OpenSSO Agent and OAM Server. OpenSSO Proxy serves all OpenSSO Agent requests and responses for Authentication, Authorization, and SSO. OpenSSO Proxy provides protocol binding and message (request or response) conversion functionality.

See Also: "Runtime Processing Between OpenSSO Agents and Access Manager"

Protocol Binding Layer

This Oracle-provided framework is responsible for agent-specific protocol handling and mapping authentication protocol messages. This framework also unmarshals incoming protocol-specific requests to protocol agnostic requests and marshals back protocol-agnostic responses to protocol-specific responses.

Partner and Trust Store

Stores OpenSSO Agent centralized configuration. The Access Manager Partner and Trust Store also supports Agent authentication by providing GET APIs for the Agent ID and Agent Password.

OpenSSO Application Domain

This can be generated automatically by using the Auto Create Policies option during OpenSSO Agent registration.


The end user has the following valid cookies:

  • OAM_ID cookie (represents the end session after agent authentication); see

  • OpenSSO cookie (the agent finds this cookie after the OpenSSO Proxy triggers session validation). The default name of the OpenSSO cookie is:


Authorization Policy for Protected Resources

Set up the Authorization policy with

  • An IP Range Condition that allows access to only the specified range of IP Addresses.

  • A Temporal Condition that allows access to only during the specified time period.

  • An Identity Condition that allows only the configured Identity (user or group) to access the protected resource.

  • An LDAP Filter condition that allows access only if the filter condition is satisfied.

  • A Session attribute condition that allows access only if the session has the configured session attribute with required value

  • An attribute condition for namespaces Request, User, and Session that allows access only if the attribute has been configured with required values

SSO Controller

Fulfills protocol requests by invoking functional components (SSO Engine, Authentication Engine, and so on):

SSO Engine

Provides enterprise and same domain Sign-on and Single logout (SLO) during an online session.

Manages the session lifecycle. Facilitates Global logout by orchestrating logout across all Relying Parties in the valid session. Communicates with the Token Processing Engine to create a valid session and persist the user.

Session Management Engine

Manages session and token context information with support for user- and Administrator-initiated and time-out based events. The SSO Engine uses Session Management Engine capabilities for session management:

  • Create Session

  • Read Session

  • Update Session

  • Delete Session

  • Validate Session

  • Get Session Id

  • Set/Get creation instant

  • Set/Get expiry instant

  • Set/Get Last access time

  • Set/Get Session state

  • Purge Sessions

Note: There is no support for viewing or managing OpenSSO agent sessions using the Oracle Access Management Console. The OpenSSO engine controller layer invokes the appropriate session management interfaces as required. Session manager invokes the agent session cache manager internally to manage the distributed cache for the agent session.

A unique session is created for each registered OpenSSO agent, which becomes the trust mechanism between the Agent and the OAM Server. The unique session ID accompanies all XML/HTTP requests for session validation, user authorization, and so on, as the agent token that must be validated by the OAM Server before it can serve any user requests.

By default, the agent session does not expire. Agent sessions are stored within the in-memory session cache. Agent sessions are not required to be persisted if the OAM Server restarts.

The agent session resides on the OAM Server and the unique agent session ID is passed back to Agent in a form it can use. The agent session supports two states: Invalid (unauthenticated), and Valid (authenticated). The OAM Server can successfully communicate with only an agent with a Valid session state.

Token Processing Engine

Responsible for token generation and token validation in response to token issuance and validation protocol requests. Default capability manages (issues, validates, renews, cancels) Username, SAML, and X509 tokens. This can also be extended to handle custom tokens beyond out-of-box/default supported security token types.

Oracle Access Management Console

Administrators use the console to:

  • Provision/register OpenSSO Agents

  • Manage an Application Domain and authentication and authorization policies for protected resources.

Remote registration utility

Administrators can use the remote registration utility to provision the agent and generate configuration files to be consumed by the agent in Centralized mode. The agent has a copy of all required configuration information and does not contact the OAM Server for this.

Note: If you are migrating an OpenSSO agent profile to Access Manager, both localized and centralized modes are supported.

WLST commands

Administrators can use WLST commands to:

  • Migrate OpenSSO Agents to the OAM Server

See Also: "Migrated Artifacts: OpenSSO".