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:
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:
About Migration and Co-existence Between OpenSSO and Access Manager
Runtime Processing Between OpenSSO Agents 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 ManagementThe 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.
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:
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:
|
Authorization Policy for Protected Resources |
Set up the Authorization policy with
|
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:
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:
|
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:
See Also: "Migrated Artifacts: OpenSSO". |
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
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.
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
|
End User Session Validation |
OpenSSO agents intercept the request to the protected application. End user Session Validation
|
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 |
|
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.
|
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:
|
Auditing |
Using the OAM Server audit component to:
|
Polling |
Polling is not Supported. Only Session Destroy notifications are supported by the OpenSSO Proxy. |
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.
Figure 21-2 shows the New OpenSSO Agent page where Administrators enter information during new OpenSSO agent registration.
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:
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 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".
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
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
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
Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)
Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode
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: 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:
Default: Error |
Debug Directory J2EE-type Agent Only |
The filesystem directory path for audit logs from the OAM Server:
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 |
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:
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:
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: Web Agents:
Not Supported, Web Agents: |
See Also: |
|
Element |
Description |
See Also: |
|
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
Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)
Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode
Note: The following Filter Modes are not supported: NONE, J2EE_Policy, All. See Also: "Understanding OpenSSO Agent Registration Parameters". |
This topic provides the following topics:
Registering an OpenSSO Agent using the Oracle Access Management Console
Configuring and Managing Registered OpenSSO Agents Using the 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.
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
To register an OpenSSO agent using the console
From the Oracle Access Management Console, click the 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.
On the New: OpenSSO Agent page, enter required details (with an *) (Table 21-5).
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).
Click Apply to submit the registration (or close the page without submitting it):
Check the Confirmation window for the location of generated artifacts and then close the window.
In the navigation tree, confirm the Agent name is listed.
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/
|
|
To the OpenSSO Agent host Web server $OHS_dir/config. | For example: $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/ |
Restart the OAM Server hosting the Agent.
Proceed to the following topics, as needed:
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".The agent must be registered and the registration visible in the Oracle Access Management Console. The AdminServer and one OAM Server must be running.
To view or modify registration details (or delete a registration)
From the System Configuration tab, Access Manager section, expand the SSO Agents node.
Open the OpenSSO Agents node to display the Search page.
Find a Registration: Fill in the form (Agent Name or Agent Type or both) or simply click the Search button.
Open a Registration: Click the Agent name in the results table to open the page.
Modify Existing Details:
Add or modify agent details as desired (Table 21-5).
Click Apply to submit changes, then dismiss the Confirmation window.
Copy OpenSSO Agent configuration files only if the Agent name, password, or security mode was changed.
Delete OpenSSO Agent Registration: This does not remove the Agent instance itself, only the registration page from the console.
Close the agent's registration page if it is open.
Click the desired agent's name, click the Delete button in the tool bar, and confirm the removal in the Confirmation window.
Confirm the Agent name is absent in the navigation tree.
Restart the OAM Server hosting the Agent.
Proceed to Part V, "Managing Access Manager SSO, Policies, and Testing".
This section provides a brief review of remote registration using the Oracle-provided tool: oamreg. this section provides the following topics:
Understanding Request Templates for OpenSSO Agent Remote Registration
Performing Out-of-Band Remote Registration with OpenSSO Agents
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 |
<agentDebugDir>/scratch/debug</agentDebugDir>
|
<agentAuditDir> |
Defines the directory path for audit logs from the OAM Server:
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
Default:false |
<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:
|
<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> |
This section describes the bootstrap configuration mappings of an OpenSSO Agent.
Table 21-10, "J2EE Request File Mappings to the Properties File"
Table 21-11, "Mapping the Web Request File to the Properties File"
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> |
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.
"Introduction to Remote Registration"
Task overview: In-band Administrators performing remote registration
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
Create your input file with unique values for the agent and Application Domain as described in "Creating Your Remote Registration Request".
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:
Validate the configuration as described in "Validating Remote Registration and Resource Protection".
Perform access checks to validate that the configuration is working, as described in "Validating Authentication and Access After Remote Registration".
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.
"Introduction to Remote Registration"
Task overview: Out-of-band remote registration (Agent is outside the network)
Out-of-band Administrator: Creates a starting request input file containing specific application and agent details and submits it to the 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
Copy and edit a template to input unique values for the agent and Application Domain as described in "Creating Your Remote Registration Request".
$OAM_REG_HOME/input/OpenSSORequest.xml
Submit the starting request input file to the in-band Administrator using a method you choose (email or file transfer).
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.
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
In-band Administrator: Validates the configuration as described in "Validating Remote Registration and Resource Protection".
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".
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:
To remotely update OAM 10g Agent registration
Set up the registration tool as described in, "Acquiring and Setting Up the Remote Registration Tool".
Update Agent:
Create your update request using the OAMUpdateAgentRequest.xml
template.
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
Provide the registration Administrator user name and password when asked.
Confirm success with on-screen messages.
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:
Restart the OAM Server that is hosting this agent
Validating Agent:
On the Agent host, run the following command in agentValidate
mode. For example:
./bin/oamreg.sh agentValidate agentname
Provide the registration Administrator user name and password when asked.
Confirm success with on-screen messages.
Deleting an Agent:
On the computer hosting the Agent, run the following agentDelete
command. For example:
./bin/oamreg.sh agentDelete agentname
Provide the registration Administrator user name and password when asked.
Confirm success with on-screen messages.
Success: On-screen message confirms
AgentDelete process completed successfully
!
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 |
|
Sessions and Session Management |
|
Artifacts |