21 Registering and Managing Legacy OpenSSO Agents

If OpenSSO is already in place as the enterprise solution for your existing Oracle deployment, Oracle Fusion Middleware continues to support this as a solution. Additionally, you can register existing OpenSSO agents for use with Access Manager.

This chapter explains how to register or manage legacy OpenSSO agents for use with Access Manager 11.1.2 and provides the following sections:

21.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 Update, Upgrade, and Migration Guide for Oracle Identity and Access Managementfor 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.

Note:

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 21-1 (authentication features and a subset of authorization features).

Table 21-1 Features: OpenSSO Agents with 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:

21.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

See Also:

Oracle Fusion Middleware Update, Upgrade, and Migration Guide for Oracle Identity and Access Management

OpenSSO Policy Migration

The OpenSSO policy is mapped to Access Manager authentication and authorization policies based on available artifacts in the OpenSSO deployment. Table 21-2 table outlines the mapping that occurs between OpenSSO and Access Manager during Policy migration.

See Also:

"Migrated Artifacts: OpenSSO"

Table 21-2 OpenSSO Policy Migration

Serian OpenSSO Access Manager

1

Policy Realm

Policy Domain

2

Policy

Authentication and Authorization Policies

3

Resources

Resources plus Host Identifier

4

Actions

Not specified (By default only "GET")

5

Subject

Identity Conditions in Authorization Policies

6

Conditions

Authentication Scheme plus Authorization Conditions

7

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.

Note:

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.

Note:

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.

21.1.2 About OpenSSO Agent Reliance on Access Manager

Access Manager supports OpenSSO Agents and processing as outlined in Table 21-3.

Table 21-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"

"Introduction to Access Manager 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.

Cookies

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:

    iPlanetDirectoryPro

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".

21.2 Runtime Processing Between OpenSSO Agents and Access Manager

The OAM Server includes an OpenSSO Proxy to handle communication with the OpenSSO Agent and facilitate interoperability with the OpenSSO server. Single Sign On (SSO) and Single Logout (SLO) between OpenSSO policy agents and the OAM Server, for instance. Interoperability is accomplished by honoring HTML/HTTP Authentication requests for end-user authentication (as an HTTP redirect) and XML/HTTP SSO requests for end-user session validation.

Figure 21-1 shows a deployment that includes OpenSSO and Access Manager. The OpenSSO Agent resides with the Web/Java EE container and the protected resource. The OpenSSO Server resides on a different host.

Figure 21-1 Typical Deployment with OpenSSO and Access Manager

Description of Figure 21-1 follows
Description of "Figure 21-1 Typical Deployment with OpenSSO and Access Manager"

Table 21-4 describes SSO processing between Access Manager and OpenSSO Agents.

Table 21-4 Access Manager Processing with OpenSSO

Functionality Description

OpenSSO Agent Authentication

OpenSSO agents are authenticated and a valid agent session is established before user authentication.

The OpenSSO agent authenticates itself to the OAM Server through the OpenSSO Proxy.

OpenSSO Agent Authentication (Agent authenticating itself to the OpenSSO Proxy occurs based on the Agent type:


J2EE Agents: Upon Agent container startup.
Web Agents: With the first user authentication request to the Web Server.

  1. End user sends a request to access an application or resource protected by the OpenSSO agent.

  2. OpenSSO agent redirects this un-authenticated user to the OAM Server for authentication as follows:


    J2EE Agents: Upon Agent container startup.
    Web Agents: With the first user authentication request to the Web Server.

  3. Agent sends the naming request to the proxy to fetch all the other service URLs (Authentication service, Session Service, and so on).

  4. Agent sends the xml Authentication request to the Proxy with its credentials on the Authentication service endpoint (obtained from the naming request in Step 3).

  5. Proxy authenticates the Agent against an Agent authentication module and creates a non-expiry session in the proxy layer itself.

  6. Proxy sends the Authentication xml Response with the agent session details to the agent over http.

Once the agent is authenticated, a valid agent session is created. The key that is generated following agent authentication is stored in the Partner and Trust store.
   

SSO User Login and Authentication

After the agent is authenticated by the OAM Server, the user request is authenticated by the OAM Server. SSO is then provided to the authenticated user accessing resources protected by the agent.

After the OpenSSO agent is authenticated and logged in, the gent verifies whether the user has an OpenSSO cookie. If not, the user authentication request is initiated from the OpenSSO agent.

User Login

  1. OpenSSO agent intercepts the request to protected application. OpenSSO agent checks if the user has an OpenSSO cookie. If not, OpenSSO agent redirects the user to the OpenSSO Proxy for authentication service. OpenSSO Proxy fetches the requested resource URL and the agent ID.

  2. The OpenSSO Login event in the OpenSSO proxy wraps this request in a way that the core login events can understand. The OpenSSO login event passes the resource URL and the agent ID to the core login event.

  3. Core Login events are performed, which checks if the request object contains an OAM_ID cookie. If yes, OAM Server checks if the session represented by the OAM_ID cookie is a valid session.

  4. If the session represented by the OAM_ID cookie is valid, core login event returns the Login response event, which is wrapped by the OpenSSO Login event and is passed on to the OpenSSO login response handler. Core login event returns the identifier of the validated session.

  5. OpenSSO login response handler (part of OpenSSO proxy) creates an OpenSSO session identifier in the format that the OpenSSO agent understands and extends this identifier with the OAM session identifier. OpenSSO cookie is created, which contains the OpenSSO session identifier and this cookie is set in the user's browser.

End User Session Validation

OpenSSO agents intercept the request to the protected application.

End user Session Validation

  1. OpenSSO agent intercepts the request to the protected application and finds an OpenSSO cookie.

  2. OpenSSO agent constructs an XML/HTTP request to validate this OpenSSO cookie. Here XML request would have Application / Agent token ID and session ID. This request reaches the OpenSSO proxy layer.

  3. OpenSSO Proxy gets the Application Token associated with the request and validates the Application Token with the OAM Server.

  4. OAM Server validates the token and sends the response to the OpenSSO Proxy

  5. If the Application Token is invalid, the OpenSSO proxy communicates that to the OpenSSO agent and OpenSSO agent starts the agent authentication flow to obtain that valid Application Token.

  6. If the Application Token is valid, OpenSSO proxy decrypts the OpenSSO cookie, fetches the OpenSSO session ID and gets the OAM session ID which is stored as the extension in the OpenSSO session ID.

  7. The OpenSSO Proxy triggers the session validation flow.

  8. If the session represented by the OAM session ID valid, the OpenSSO proxy communicates that to the Agent and the protected application is displayed to the user. This session validation returns the session data (session attributes and values) to the proxy layer as the output of session validation event response.

  9. If the session is invalid, authentication flow is initiated by the OAM Server, where the OAM Server collects the user credentials and validates the user.

User profile attributes retrieval for Web Agent types

OpenSSO agents can request user profile attributes once the user is successfully logged in and a valid session is created, by providing the session ID. The OpenSSO proxy layer must receive these requests and fetch the OAM session ID from the OpenSSO session ID extension. OpenSSO Web agents use the Policy service URL for these requests.

OpenSSO proxy then fetches these attributes and passes the session ID to the OAM Server (which uses the responses framework to fetch the User Profile attributes and return the data to the OpenSSO Proxy).

User profile attributes retrieval for J2EE Agent types

OpenSSO J2EE agents use jax-rpc calls to retrieve user profile attributes. The flow is similar as the one for Web agents types to retrieve these properties.

User Single Logout

  1. The OpenSSO Proxy receives a User logout request and forwards the user to the OAM logout URL

  2. 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.

  3. Core logout events are performed, which includes the controller calls to the SSO engine to confirm the session exists. If the session exists, the OAM_ID cookie is deleted, and global logout is performed.

  4. The SSO engine returns the response to the controller indicating the session has been cleared.

  5. The controller sends a request to the proxy to clear tokens.

  6. The Proxy sends the request to the agent to clear tokens through the OpenSSO Logout response handler.

SSO Agent Logout

Access Manager handles single logout requests originating from the OpenSSO agents.

Note: The user must be logged out from resources protected by other agents (WebGate and MOD_OSSO, for instance). Agent logout is not required other than in the multi-domain environment.

  1. The OpenSSO Agent requests logout to OpenSSO Proxy.

  2. The Proxy fetches the Application token from the request and verifies that the request is initiated by an authenticated agent.

  3. Opensso Agent Logout is handled within the proxy as the session is created in an independent Agent Session Management Module.

  4. The decrypted token is returned to the OpenSSO Proxy. If there is no OpenSSO token present, steps 2 and 3 are absent.

  5. The OpenSSO Login event in the OpenSSO proxy wraps this request in a way that the core login events can understand.

  6. Core Login events are performed, which includes forwarding the request to the SSO Engine through the controller and authenticating the user. A new session is created for the authenticated user.

  7. Core login event returns the Login response event, which is wrapped by the OpenSSO Login event and is passed on to the OpenSSO login response handler.

  8. OpenSSO login response handler sends the response to the OpenSSO agent.

Token Generation for OpenSSO Agents

Access Manager processes the tokens generated for, and to be consumed by the OpenSSO agents.

Logging

Enables you to track events during end user access enforcement for following events, using the OAM Server log component:

  • Login success and login failure events

  • Logout success and logout failure events

  • Log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE), each of which indicates severity in descending order.

Auditing

Using the OAM Server audit component to:

  • Audit Login events

  • Audit Logout success events

Polling

Polling is not Supported. Only Session Destroy notifications are supported by the OpenSSO Proxy.

21.3 Understanding OpenSSO Agent Registration Parameters

Whether you migrate existing OpenSSO Agents to Access Manager or register a fresh OpenSSO Agent, the Oracle Access Management Console provides centralized registration and management of OpenSSO Agents.

21.3.1 About OpenSSO Agent Registration Parameters

Figure 21-2 shows the New OpenSSO Agent page where Administrators enter information during new OpenSSO agent registration.

Figure 21-2 New OpenSSO Agent Page

Surrounding text describes Figure 21-2 .

Table 21-5 describes the elements on the New OpenSSO Agent page.

Table 21-5 Elements on the New OpenSSO Agent Page

Element Description

Agent Type

OpenSSO agent types can be either:

  • Web: Use with Web resources and Web resource URLs.

  • J2EE: Default agent type. Use J2EE type agents for Java EE resources and applications.

    For the J2EE Agent, Filter modes must be set by choosing either:

    SSO_ONLY (Access Manager Authentication Only): Enables the least restrictive mode of operation for the filter; the agent simply ensures that all users who try to access protected web resources are authenticated.

    URL_Policy (Access Manager Authentication and Authorization): Enables the agent filter to enforce URL policies. By default, with Web Agents, .com.sun.identity.agents.config.sso.onlyattribute is set to "false".

Note: Both agent types provide access protection when you also choose SSO only.

Agent Name

Unique name for this agent.

Password

Re-enter Password

A required, unique password for this OpenSSO agent, which can be assigned during this registration process. The entry will appear in obfuscated format in the console, in oam-config.xml, and in OpenSSOAgentBootstrap.properties.

When a registered agent connects to an OAM Server, the user is prompted for the password. The password is used for authentication to prevent unauthorized agents from connecting and obtaining policy information.

Host Identifier

A name that identifies the host and port for the OpenSSO agent.

Default: Agent Name

See Also: "About Virtual Web Hosting".

Base URL

The protocol, host, and port of the computer on which the OpenSSO agent is installed.

For example, http://host.example.domain.com:port or https://example.domain.com:port.

Auto Create Policies

During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default. The agent name is used as the Application Domain name by default.

Default: Enabled

See Also: "Generated Artifacts: OpenSSO".

Notes: An Application Domain in Access Manager corresponds to a Realm in OpenSSO. If you already have an Application Domain and policies, you can simply add new resources to it. If you clear this option (no check), no Application Domain or policies are generated automatically.

OpenSSO Agent Properties

OpenSSO Agent properties are stored in the following files, which are updated during agent registration and configuration changes and consumed during run time:

  • OpenSSOAgentBootstrap.properties

  • OpenSSOAgentConfiguration.properties

These files are stored on the console host (AdminServer) and must be relocated to the OpenSSO Agent /config directory as shown in Table 21-6.

Table 21-6 Relocating OpenSSO Artifacts

From AdminServer . . . To OpenSSO Agent /config Directory

$MW_HOME/Oracle_IDM1/oam/server/rreg/client/rreg/output
$Policy-Agent-base/AgentInstance-Dir/config/

For details about the generated Application Domain for an Open SSO Agent, see "Generated Artifacts: OpenSSO".

21.3.2 About the Expanded OpenSSO Agent Page and Parameters

This topic describes expanded OpenSSO Agent page that is available when managing the agent using the Oracle Access Management Console.

During registration, only a small subset of available parameters is displayed to streamline the process. Whether you registered the agent using the Oracle Access Management Console or the remote registration utility, you can view the full agent configuration page in the console. Default values populate the page after initial registration and are displayed when you open the Agent's page, as shown in Figure 21-3.

Figure 21-3 Expanded OpenSSO Web Agent Registration Page

Description of Figure 21-3 follows
Description of "Figure 21-3 Expanded OpenSSO Web Agent Registration Page"

Information on the J2EE Agent registration page is nearly the same as details for Web Agents. The J2EE Agent registration page is shown in Figure 21-4.

Figure 21-4 Expanded OpenSSO J2EE Agent Registration Page

Description of Figure 21-4 follows
Description of "Figure 21-4 Expanded OpenSSO J2EE Agent Registration Page"

Table 21-7 describes all elements on expanded OpenSSO Agent registration pages.

Table 21-7 Expanded OpenSSO Agent Registration Elements

Element Description

Status

The state of this agent registration: Enabled or Disabled.

Default: Enabled

See Also: Table 21-5, "Elements on the New OpenSSO Agent Page"

Filter mode

J2EE Agent Type only

The Agent filter is installed within the protected application. It facilitates the enforcement of security policies, governing the access to all resources within the protected application. Every application protected by the J2EE Agent must have its deployment descriptors changed to reflect that it is configured to use the agent filter. Applications that do not have this setting are not protected by J2EE the Agent and might malfunction or become unusable if deployed on a deployment container where the Agent realm is installed.

Filter modes must be set for the J2EE Agent by choosing one of the following options: SSO_ONLY or URL_Policy.

Default: URL_Policy

  • SSO_ONLY (Access Manager Authentication Only): Enables the least restrictive mode of operation for the filter; the agent simply ensures that all users who try to access protected web resources are authenticated.

  • URL_Policy (Access Manager Authentication and Authorization): Enables the agent filter to enforce URL policies. By default, with Web Agents, .com.sun.identity.agents.config.sso.onlyattribute is set to "false".

Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)

  1. End user requests access to an application or resource protected by OpenSSO Agent.

  2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.

  3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource with OpenSSO session ID set in the response cookie.

  4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by OpenSSO Agent.

  5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy and enables SSO for the end user.

  6. End user gets access to the protected application or resource.

Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode

  1. End user requests access to an application or resource protected by OpenSSO agent.

  2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.

  3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource with OpenSSO session ID set in the response cookie.

  4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by OpenSSO Agent.

  5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy.

  6. OpenSSO Agent sends Policy requests to OAM Server through the OpenSSO Proxy to ensure the authenticated user is authorized to access the resource.

  7. OpenSSO Proxy evaluates the Policies for the protected resource (using OAM Policy Engine) and sends the Policy decision to the Agent: Allow or Deny.

  8. End user gets access if the Policy decision is Allow.

Note: The following Filter Modes are not supported: NONE, J2EE_Policy, All.

See Also: "Understanding OpenSSO Agent Registration Parameters".

Session Timeout in seconds (User)

Click the arrows to specify the period, after which the session times out and the user must re-authenticate.

Default: 0

Cookie Name

The default name of the OpenSSO cookie is:

Default: iPlanetDirectoryPro

Cookie Separator

Defines the character to be used as a separator when multiple values of the same attribute are being set as a cookie. For example, the pipe symbol "|", can be used.

Default:

Enable Cookie Encoding

J2EE-type Agent Only

Identifies whether cookie encoding is enabled or not.

Default: Enabled

SSO Only

Web-type Agent Only

Enables OpenSSO Agent to bootstrap and authenticate with the OAM Server using the OpenSSO proxy provided by Access Manager:

The end user accesses the application or resource protected by the OpenSSO Agent, which redirects the unauthenticated user to the OAM Server for authentication.

After successful authentication, the OpenSSO proxy redirects the user back to the protected application or resource and sets the OpenSSO Session ID in the response cookie.

The authenticated user with a valid OpenSSO session accesses the application or resource protected by the OpenSSO Agent, which validates the session against the OAM Server using the OpenSSO Proxy.

The end user gets access based on Access Manager authorization policy.

Urls

  

Login URLs

Enter the login URL, which must include the appropriate protocol (HTTP or HTTPS), host, domain, and port in the following form:

http://example.domain.com:port

Default: http://oamhost:port/opensso/UI/Login

Note: The port number is optional.

Logout URLs

The Logout URL triggers the logout handler, which requires the user to re-authenticate the next time he accesses a resource protected by Access Manager.

When yo enter the Logout URL, it must include the appropriate protocol (HTTP or HTTPS), host, domain, and port. For example:

http://example.domain.com:port/opensso/UI/Logout

Default: http://oamhost:port/opensso/UI/Logout

Note: The port number is optional. The user must be logged out from resources protected by other agents (WebGate and MOD_OSSO, for instance). Agent logout is not required other than in the multi-domain environment.

Not enforced URLs

Web-type Agent Only

The URLs you enter in this list have no policy enforcement. These equate to Public URLs, with no protection and access is allowed by all.

Access Denied URI

The URI to which the user is directed if access to the requested resource is denied. This is available for both Web and J2EE Agents, each with its own format requirements:

Web Agent (full URL): http://host:port/context/accessDeniedURL.html

J2EE Agent (relative URI): /context/accessDeniedURL.htm

Default: (blank)

Audit

  

Debug Level

J2EE-type Agent Only

When set, the OAM Server logs messages for:

  • Login success and login failure events

  • Logout success and logout failure events

  • Log messages at different logging levels (ERROR, WARNING, MESSAGE, each of which indicates severity in descending order.

Default: Error

See Also: Chapter 6, "Logging Component Event Messages"

Debug Directory

J2EE-type Agent Only

The filesystem directory path for audit logs from the OAM Server:

  • Audit Login events

  • Audit Logout success events

See Also: Chapter 8, "Auditing Administrative and Run-time Events"

Debug File

Web-type Agent Only

Defines the filesystem directory path to the local component event logging file.

Default:

Local Log File

Defines the filesystem directory path to the local component event logging file.

Default:

User Mapping

  

Mapping Mode

  • HTTP_HEADER

  • USER_ID

  • PROFILE_ATTRIBUTE

  • SESSION_PROPERTY

Default: User_ID

User Identity

Default: User ID

User Attribute Name

Default:

Attribute Mapping

Attribute retrieval fetches and sets user attributes in the HTTP request for consumption by the applications.

The following Attribute Mapping panels are available:

  • Profile Attributes

  • Response Attributes

  • Session Attributes

Fetch Mode: Certain applications rely on the presence of user-specific profile information in some form to process user requests appropriately. The agent can make these attributes from the user's profile available in various forms. when you specify a Fetch Mode for Profile, Response, or Session Attributes:

  • NONE: No attributes are fetched.

  • HTTP_HEADER: When the agent is configured to provide the LDAP attributes as HTTP headers, these attributes can be retrieved.

  • REQUEST_ATTRIBUTE: When the agent is configured to provide the LDAP attributes as request attributes, the agent populates these attribute values into HttpServletRequest as attributes that can later be used by the application as necessary. For example, fetch profile attributes, assign a mode to the profile attribute property, and map the profile attributes to be populated under specific names for the currently authenticated user.

  • HTTP_COOKIE: When the agent is configured to provide the LDAP attributes as cookies, the necessary values are set as server specific cookies by the agent with the path specified as "/." Multi-valued attributes are set as a single cookie value such that all values of the attribute are concatenated into a single string using a separator character that can be specified by the property labeled Cookie Separator.

Default: None

Profile Attributes

User profile information can be populated under specific names for the currently authenticated user. For example:

Fetch Mode: REQUEST_ATTRIBUTE

Name (Map key): cn

Value: CUSTOM-Common-Name

Name (Map key): mail

Value: CUSTOM-Email

Default: No data

Response Attributes

Obtains user-specific information by fetching policy response attributes, assigns a mode to the policy response attribute property, and maps the policy response attributes to be populated under specific names for the currently authenticated user.

Fetch Mode: REQUEST_ATTRIBUTE

Name (Map key): cn

Value: CUSTOM-Common-Name

Name (Map key): mail

Value: CUSTOM-Email_Addr

Default: No data

Session Attributes

The attributes in the session object maintained by the OAM Server. These are sent as part of a session validation response to the Agents.

Fetch Mode: REQUEST_ATTRIBUTE

Name (Map key): UserToken

Value: CUSTOM-userid

Default: No data

Miscellaneous

Most agent properties are hot-swap enabled. Changing configuration properties can have unexpected results. Hot-swappable properties take effect immediately. Therefore, mistakes are instantly implemented.Most agent properties are presented in a format that is most useful for configuring using Oracle Access Management Console. However, this format is not used in the OpenSSOAgentBootstrap.properties file.

List Properties: Certain properties are specified as lists composed of a key that represents the property name; a positive number (starting from 0) that increments by 1 for every value specified in the list; and a value. For example:

com.sun.identity.agents.config.notenforced.uri[0]=/agentsample/public/*
com.sun.identity.agents.config.notenforced.uri[1]=/agentsample/images/*
com.sun.identity.agents.config.notenforced.uri[2]=/agentsample/index.html

Map Constructs: Certain properties are specified as map constructs composed of a key that represents the property name; a name string that forms the lookup key as available in the map; and the value associated with the name in the map. For example:

com.sun.identity.agents.config.filter.mode[app1]=ALL
com.sun.identity.agents.config.filter.mode[app2]=SSO_ONLY

Note: For a given name, there can only be one entry in the configuration for a given configuration key. If multiple entries with the same <name> for a given configuration key are present only one of the values will be loaded in the system and the other values are discarded.

Application-Specific Properties: Certain properties can be configured for specific applications. Thee agent can use different values of the same property for different applications as defined in the configuration file. Application Specific configuration properties must follow the rules and syntax of the map construct. The following settings for a single property serve as an example which illustrates that for applications other than the ones deployed on the root context and the context /Portal, the value of the property defaults to value3.

com.sun.identity.agents.config.example[Portal] = value1
com.sun.identity.agents.config.example[DefaultWebApp] = value2
com.sun.identity.agents.config.example = value3

Global Properties: Properties that are not configured for specific applications apply to all the applications on that deployment container. Such properties are called global properties.

Serial number: Assigned automatically

Name: Select from one of the following

Value: Enter the appropriate value for the Name you chose.

Note: To enable OpenSSO Agent configuration hotswap, make sure the opensso agents have the following properties in the Miscellaneous properties section of their profile in the OpenSSO Proxy on OAM Server, and the agent servers are restarted:

J2ee Agents: com.sun.identity.client.notification.url =http://<AGENT_SERVER_HOST>:<AGENT_SERVER_PORT>/agentapp/notification

Web Agents:

com.sun.identity.client.notification.url =http://AGENT_SERVER_HOST:AGENT_SERVER_PORT/UpdateAgentCacheServlet?shortcircuit=false

Not Supported, Web Agents: com.sun.identity.agents.config.change.notification.enable = true OpenSSO Agent Miscellaneous Attributes

See Also:

"Reviewing OpenSSO Bootstrap Configuration Mappings"

Element

Description

See Also:

Table 21-5, "Elements on the New OpenSSO Agent Page"

Status

The state of this agent registration: Enabled or Disabled.

Default: Enabled

Filter mode

J2EE Agent Type only

The Agent filter is installed within the protected application. It facilitates the enforcement of security policies, governing the access to all resources within the protected application. Every application protected by the J2EE Agent must have its deployment descriptors changed to reflect that it is configured to use the agent filter. Applications that do not have this setting are not protected by J2EE the Agent and might malfunction or become unusable if deployed on a deployment container where the Agent realm is installed.

Filter modes must be set for the J2EE Agent by choosing one of the following options: SSO_ONLY or URL_Policy.

Default: URL_Policy

  • SSO_ONLY (Access Manager Authentication Only): Enables the least restrictive mode of operation for the filter; the agent simply ensures that all users who try to access protected web resources are authenticated.

  • URL_Policy (Access Manager Authentication and Authorization): Enables the agent filter to enforce URL policies. By default, with Web Agents, .com.sun.identity.agents.config.sso.onlyattribute is set to "false".

Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)

  1. End user requests access to an application or resource protected by OpenSSO Agent.

  2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.

  3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource with OpenSSO session ID set in the response cookie.

  4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by OpenSSO Agent.

  5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy and enables SSO for the end user.

  6. End user gets access to the protected application or resource.

Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode

  1. End user requests access to an application or resource protected by OpenSSO agent.

  2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.

  3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource with OpenSSO session ID set in the response cookie.

  4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by OpenSSO Agent.

  5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy.

  6. OpenSSO Agent sends Policy requests to OAM Server through the OpenSSO Proxy to ensure the authenticated user is authorized to access the resource.

  7. OpenSSO Proxy evaluates the Policies for the protected resource (using OAM Policy Engine) and sends the Policy decision to the Agent: Allow or Deny.

  8. End user gets access if the Policy decision is Allow.

Note: The following Filter Modes are not supported: NONE, J2EE_Policy, All.

See Also: "Understanding OpenSSO Agent Registration Parameters".

21.4 Registering and Managing OpenSSO Agents Using the Console

This topic provides the following topics:

21.4.1 Registering an OpenSSO Agent using the Oracle Access Management Console

Users with Oracle Access Management Administrator credentials can either use Oracle-provided tools to analyze and migrate an OpenSSO environment or use the Oracle Access Management Console, as described here, to manually provision OpenSSO Agents.

Registration steps are the same regardless of the OpenSSO agent type you choose: Web or J2EE. You can register an OpenSSO agent before you deploy it. Users with valid Administrator credentials can perform the following task to register an OpenSSO agent using the Oracle Access Management Console.

Note:

Only centralized configuration mode is supported for new OpenSSO Agent creation.

After agent registration, you can change the communication mode of the OAM Server if needed. Communication between the agent and server continues to work as long as the Agent uses SSO Only filter mode.

Prerequisites

Confirm that at least one OAM Server is running in the same mode as the agent to be registered. Install the Agent, as described in:

  • Oracle Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

  • Oracle Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents

See Also:

"Understanding OpenSSO Agent Registration Parameters"

To register an OpenSSO agent using the console

  1. From the Oracle Access Management Console, click the New OpenSSO Agent link:


    Welcome page
    SSO Agent panel
    New OpenSSO Agent link

    Alternatively: Open the System Configuration tab, Access Manager section, SSO Agents node, OpenSSO Agent node, then click the Create ... OpenSSO Agent button in the upper-right corner.

  2. On the New: OpenSSO Agent page, enter required details (with an *) (Table 21-5).

  3. Confirm that the Auto Create Policies box is checked (or clear the box to disable this function if you do not need a new Application Domain).

  4. Click Apply to submit the registration (or close the page without submitting it):

  5. Check the Confirmation window for the location of generated artifacts and then close the window.

  6. In the navigation tree, confirm the Agent name is listed.

  7. Copy OpenSSO Agent bootstrap and configuration files from the console host (AdminServer) to the Agent host Web server:


    		 OpenSSO Properties Files From ... Path ...
      From the AdminServer (Console) host $DOMAIN_HOME/output/$Agent_Name/

    • OpenSSOAgentBootstrap.properties

    • OpenSSOAgentConfiguration.properties
      To the OpenSSO Agent host Web server $OHS_dir/config. For example:
    $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/

  8. Restart the OAM Server hosting the Agent.

  9. Proceed to the following topics, as needed:

21.4.2 Configuring and Managing Registered OpenSSO Agents Using the Console

Steps in this procedure are the same whether you are editing (view, modify, or delete) a J2EE or Web type OpenSSO agent. Users with valid Administrator credentials can change any setting for a registered agent using the Oracle Access Management Console.

After changes, updated details are propagated through a runtime configuration update process. There is usually no need to copy the artifacts over to OpenSSO agent configuration area. Artifacts need only be copied to the OpenSSO agent directory path if the agent name, password, or security mode is changed.

Note:

Deleting an agent registration removes only the registration (not the associated host identifier, Application Domain, resources, or the agent instance itself), which prevents registering the same agent again if required. However, deleting the Application Domain and its content removes all referenced objects including the Agent registration, as described in "Deleting an Application Domain and Its Content".

Prerequisites

The agent must be registered and the registration visible in the Oracle Access Management Console. The AdminServer and one OAM Server must be running.

See Also:

"About the Expanded OpenSSO Agent Page and Parameters"

To view or modify registration details (or delete a registration)

  1. From the System Configuration tab, Access Manager section, expand the SSO Agents node.

    1. Open the OpenSSO Agents node to display the Search page.

    2. Find a Registration: Fill in the form (Agent Name or Agent Type or both) or simply click the Search button.

    3. Open a Registration: Click the Agent name in the results table to open the page.

  2. Modify Existing Details:

    1. Add or modify agent details as desired (Table 21-5).

    2. Click Apply to submit changes, then dismiss the Confirmation window.

    3. Copy OpenSSO Agent configuration files only if the Agent name, password, or security mode was changed.

  3. Delete OpenSSO Agent Registration: This does not remove the Agent instance itself, only the registration page from the console.

    1. Close the agent's registration page if it is open.

    2. Click the desired agent's name, click the Delete button in the tool bar, and confirm the removal in the Confirmation window.

    3. Confirm the Agent name is absent in the navigation tree.

  4. Restart the OAM Server hosting the Agent.

  5. Proceed to Part V, "Managing Access Manager SSO, Policies, and Testing".

21.5 Performing Remote Registration for OpenSSO Agents

This section provides a brief review of remote registration using the Oracle-provided tool: oamreg. this section provides the following topics:

21.5.1 Understanding Request Templates for OpenSSO Agent Remote Registration

Each OpenSSO Agent provides restricted access to applications by intercepting requests to these applications. OpenSSO Agent provisioning is the process of registering an OpenSSO agent to use Access Manager.

Both inband and outofband remote registration modes require a request file with the input argument, as listed in Table 21-8

Table 21-8 OpenSSO Request Files for Remote Registration

Templates for . . . Description

Register OpenSSO Agents

$OAM_REG_HOME/input/OpenSSORequest.xml
 

$OAM_REG_HOME/input/OpenSSORequest_short.xml

When you run oamreg with the short request, default values are applied automatically for elements found only in the extended request.

Other Templates

  

Update Agent:

$OAM_REG_HOME/input/OpenSSOUpdateAgentRequest.xml

See Also: "Updating Agents Remotely"

Create Policies:

Create New Host Identifiers and an Application Domain without Registering an Agent

$OAM_REG_HOME/input/CreatePolicyRequest.xml

See Also: "Managing Policies and Application Domains Remotely"

Update Policies:

Existing Host Identifiers and Application Domain (not associated with an Agent Registration)

$OAM_REG_HOME/input/UpdatePolicyRequest.xml

See Also: "Managing Policies and Application Domains Remotely"

Remote OpenSSO Agent registration automatically:

  • Creates the agent page for the Oracle Access Management Console

  • Creates an Application Domain and basic policies to protect applications

  • Produces OpenSSO properties files on the client to be consumed by the agent at run time

Table 21-9 identifies the elements in OpenSSO Agent request templates. Unless explicitly stated, all elements are found in both the short and the extended request files.

Table 21-9 OpenSSO Agent Remote Registration Request

Element Description Example

<serverAddress>

<agentName>

<hostIdentifier>

<agentBaseUrl>

<autoCreatePolicy>

<applicationDomain>

<virtualhost>

Elements common to all remote registration request templates.

See Table 14-8, "Common Elements in Remote Registration Requests"

<agentType>

Choose between J2EE or Web type OpenSSO agents.

 
<agentType>WEB</agentType>

Password

Re-enter Password

A required, unique password for this OpenSSO agent, which can be assigned during this registration process. The entry will appear in obfuscated format in the console, in oam-config.xml, and in OpenSSOAgentBootstrap.properties.

When a registered agent connects to an OAM SServer, the user is prompted for the password. The password is used for authentication to prevent unauthorized agents from connecting and obtaining policy information.

You are asked to supply a password during remote registration. This does not appear in the template.

Extended OpenSSO Template Only

    

<agentDebugDir>

With <debug> set to true, you can configure the directory path for logged agent messages.

Default: None

See Also: Chapter 6, "Logging Component Event Messages"

 
<agentDebugDir>/scratch/debug</agentDebugDir>

<agentAuditDir>

Defines the directory path for audit logs from the OAM Server:

  • Audit Login events

  • Audit Logout success events

See Also: Chapter 8, "Auditing Administrative and Run-time Events"

 
<agentAuditDir>/scratch/audit</agentAuditDir>

<agentAuditFileName>

Defines the audit log file name.

 
<agentAuditFileName>audit.log</agentAuditFileName>

<debug>

When set to true, the OAM Server logs messages for:

  • Login success and login failure events

  • Logout success and logout failure events

  • Log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE), each of which indicates severity in descending order.

Default:false

See Also: Chapter 6, "Logging Component Event Messages"

 
<debug>false</debug>

<cookieName>

The name of the cookie, which the agent finds this cookie after the OpenSSO Proxy triggers session validation

The end user has the following valid cookies:

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

  • OpenSSO cookie

 
<cookieName>iPlanetDirectoryPro</cookieName>

<accessDeniedUrl>

If access is denied, the user is redirected to this URL.

 
<accessDeniedUrl></accessDeniedUrl>

<protectedAuthnScheme>

Specifies the Authentication Scheme to use in the Authentication Policy.

In an upgraded environment, use SSOCoExistMigrateScheme for the Protected Resource Policy for any new OSSO Agents you register.

 
<protectedAuthnScheme></protectedAuthnScheme>

21.5.2 Reviewing OpenSSO Bootstrap Configuration Mappings

This section describes the bootstrap configuration mappings of an OpenSSO Agent.

Table 21-10 J2EE Request File Mappings to the Properties File

Property Name Default Value Sample Value

com.iplanet.am.naming.url

from input xml as <serverAddress>/opensso/namingservice

http://example.com:7575/opensso/namingservice

com.sun.identity.agents.app.username

from input xml as <agentName>

<Agent registration ID>

com.iplanet.am.service.secret

from input xml as <agentPassword>

Note: This is not collected as part of the input XML file but is prompted for by the remote registration tool.

<Encrypted Agent registration ID password>

com.iplanet.services.debug.directory

from input xml as <agentDebugDir>

/opt/30j2ee/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug

com.sun.identity.agents.config.local.logfile

from input xml as <agentAuditDir>/<agentAuditFileName>

/opt/30j2ee/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit/amAgent_example_com_7676.log

com.sun.identity.agents.config.organization.name

from input xml as <realmName>

Note: This is the <hostIdentifier> value collected from the input xml file. By default it is taken as the <agentName> unless explicitly provided.

  

com.sun.identity.agents.config.profilename

from input xml as <agentName>

<Agent registration ID>

Not included in the remote registration file ...

    

com.iplanet.am.naming.url

N/A

N/A

com.sun.identity.agents.config.service.resolver

N/A

N/A

com.sun.services.debug.mergeall

N/A

N/A

com.sun.identity.agents.config.lock.enable

FALSE

N/A

N/A

am.encryption.pwd

N/A

N/A

Table 21-11 shows the mappings between a Web Agent request file and properties file.

Table 21-11 Mapping the Web Request File to the Properties File

Property Name Default Value Sample Value

com.iplanet.am.naming.url

from input xml as <serverAddress>/<serverAddress>/opensso/namingservice

http://example.com:7575/opensso/namingservice

com.sun.identity.agents.config.username

from input xml as <agentName>

<Agent profile ID>

com.sun.identity.agents.config.password

from input xml as <agentPassword>

Note: This is not collected as part of the input XML file but is prompted for by the remote registration tool.

<Encrypted Agent registration ID password>

com.iplanet.services.debug.directory

from input xml as <agentDebugDir>

/opt/30j2ee/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug

com.sun.identity.agents.config.local.logfile

from input xml as <agentAuditDir>/<agentAuditFileName>

/opt/30j2ee/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit/amAgent_redsky_red_iplanet_com_7676.log

com.sun.identity.agents.config.organization.name

from input xml as <realmName>

Note: It is the <hostIdentifier> value collected from the input xml. Status: Open Fixed or Closed

  

com.sun.identity.agents.config.profilename

from input xml as <agentName>

  

21.5.3 Performing In-Band Remote Registration with OpenSSO Agents

This is a brief summary of tasks required to perform in-band remote registration for your OpenSSO agent. Full details are provided in other chapters, as described here.

Prerequisites

"Introduction to Remote Registration"

Task overview: In-band Administrators performing remote registration

  1. Acquire the registration tool and set environment variables as described in "Acquiring and Setting Up the Remote Registration Tool".

    $ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz

  2. Create your input file with unique values for the agent and Application Domain as described in "Creating Your Remote Registration Request".


    From: OpenSSORequest.xml
    To: myopenssoagent_request.xml

  3. Run the registration tool to configure the Agent, create a default Application Domain for the resources, and copy the updated agent configuration file as described in "Performing In-Band Remote Registration".

    From the console host (AdminServer):

    /rreg/output/Agent_Name/

    • OpenSSOAgentBootstrap.properties

    • OpenSSOAgentConfiguration.properties

    To the OpenSSO Agent host Web server $OHS_dir/config. For example:


    $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/

  4. Validate the configuration as described in "Validating Remote Registration and Resource Protection".

  5. Perform access checks to validate that the configuration is working, as described in "Validating Authentication and Access After Remote Registration".

21.5.4 Performing Out-of-Band Remote Registration with OpenSSO Agents

This is a brief summary of tasks required to perform out-of-band remote registration for your OpenSSO agent. Full details are provided in other chapters, as described here.

Prerequisites

"Introduction to Remote Registration"

Task overview: Out-of-band remote registration (Agent is outside the network)

  1. Out-of-band Administrator: Creates a starting request input file containing specific application and agent details and submits it to the in-band Administrator.

  2. In-band Administrator:

    • Acquire the registration tool and set environment variables as described in "Acquiring and Setting Up the Remote Registration Tool".

      $ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz

    • Use the out-of-band starting request with the registration tool to register the agent and create the response and native agent configuration files to return to the out-of-band Administrator. See "Performing Out-of-Band Remote Registration":

      • opensso_Response.xml is generated for the out of band Administrator to use in Step 3.

      • OpenSSO properties files are modified for the out-of-band Administrator to bootstrap the OSSO module.

  3. Out-of-band Administrator: Use the registration tool with the response file and copy artifacts to the appropriate file system directory.

    • opensso_Response.xml.

    • opensso....properties files

  4. In-band Administrator: Validates the configuration as described in "Validating Remote Registration and Resource Protection".

  5. Out-of-band Administrator: Performs several access checks to validate that the configuration is working, as described in "Validating Authentication and Access After Remote Registration".

21.6 Updating Registered OpenSSO Agents Remotely

This section describes how to update, validate, and delete OSSO Agents using remote registration templates and modes described in "Introduction to Updating Agents Remotely".

The update request file passes specific values to the remote registration tool, oamreg. The primary differences between the update template and the original registration template is that the update template.

Table 21-12 Delta: OpenSSO Remote Registration versus Remote Updates

Delta Element

Adds

<startDate>yyyy_mm_dd</startDate> element to track changes

Adds

<homeUrl> element that specifies the agent_base_url_port

Omits

<hostidentifier>

Omits

<agentbaseURL>

See Also:

21.6.1 Updating OpenSSO Agents Remotely

To remotely update OAM 10g Agent registration

  1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote Registration Tool".

  2. Update Agent:

    1. Create your update request using the OAMUpdateAgentRequest.xml template.

    2. On the computer hosting the Agent, run the following command with agentUpdate mode specify your own *Request*.xml as the input file. For example:

      ./bin/oamreg.sh agentUpdate input/OpenSSOUpdateAgentRequest.xml

    3. Provide the registration Administrator user name and password when asked.

    4. Confirm success with on-screen messages.

    5. Relocate to the agent host OpenSSOAgentBootstrap and OpenSSOAgentConfiguration.properties files:

      From the AdminServer (Console) host: /rreg/output/Agent_Name/

      To the OpenSSO Agent host Web server $OHS_dir/config. For example:


      $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/*.properties

    6. Restart the OAM Server that is hosting this agent

  3. Validating Agent:

    1. On the Agent host, run the following command in agentValidate mode. For example:

      ./bin/oamreg.sh agentValidate agentname

    2. Provide the registration Administrator user name and password when asked.

    3. Confirm success with on-screen messages.

  4. Deleting an Agent:

    1. On the computer hosting the Agent, run the following agentDelete command. For example:

      ./bin/oamreg.sh agentDelete agentname

    2. Provide the registration Administrator user name and password when asked.

    3. Confirm success with on-screen messages.

      Success: On-screen message confirms

      AgentDelete process completed successfully!

21.7 Locating Other OpenSSO Agent Information

See Table 21-13 for additional information on legacy OpenSSO agents with Access Manager.

Table 21-13 Other OpenSSO Information in this Guide

Topic Location

Component Loggers

Table 6-3, "Oracle Access Management Server-Side Component Loggers"

OpenSSO Metrics in the DMS Console

"Reviewing OpenSSO Metrics in the DMS Console"

Sessions and Session Management

"About OpenSSO Agents"

Artifacts

"Generated Artifacts: OpenSSO"

"Migrated Artifacts: OpenSSO"