If legacy OracleAS SSO 10g is already in place as the enterprise solution for an existing deployment, Oracle Fusion Middleware continues to support this as a solution. Additionally, you can register existing OSSO 10g mod_osso modules as agents for Access Manager as described in Chapter 15.
This chapter explains how to register or manage legacy OSSO agents for use with Access Manager 11.1.2 and provides the following sections:
Registering OSSO Agents Using Oracle Access Management Console
Configuring and Managing Registered OSSO Agents Using the Console
Configuring Logout for OSSO Agents with Access Manager 11.1.2
This section provides the following topics:
The mod_osso module is an Oracle HTTP Server module that simplifies the authentication process by serving as the sole application to the single sign-on server. In this way, mod_osso renders authentication transparent to OracleAS applications. It enables applications protected by OracleAS Single Sign-On to accept HTTP headers in lieu of a user name and password once the user has logged in. The values for these headers are stored in a mod_osso cookie.
The Administrator for these applications is spared the burden of integrating them with an SDK. After authenticating a user, mod_osso transmits the simple header values that applications may use to authorize the user:
User name
User GUID (global user identity)
Language and territory
After registration with Access Manager, OSSO 10g Agents can communicate directly with Access Manager 11g services through the OSSO proxy. The OSSO proxy supports existing OSSO agents when upgrading to Access Manager. The proxy handles requests from OSSO Agents and translates the OSSO protocol into a protocol for Access Manager 11g authentication services.
The OSSO Proxy supports inter-operability between Access Manager and OSSO agents (using an OSSO agent to access a valid SSO session created for a Webgate or Access Client and vice versa).
OSSO Proxy Supports | Description |
---|---|
SSO login | From an OSSO Agent to the OAM Server (and OSSO-specific tokens) |
SSO logout | From the OSSO Agent to the OAM Server |
OSSO Agent requests and protocols | OSSO Proxy translates the OSSO protocol into a protocol for Access Manager. |
After registering 10g mod_osso as an agent, Access Manager gives mod_osso the redirect URL for the user based on the authentication scheme associated with the OAM policy defined for the resource (Table 24-1).
This topic introduces key components for implementing and enforcing Access Manager 11g single sign-on policies as compared to OSSO 10g. Access Manager 11g default behavior is to deny access when a resource is not protected by a policy that explicitly allows access. OracleAS SSO 10g provides only authentication. Table 24-2 summarizes the differences.
Table 24-2 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description | 11g Access Manager | OSSO 10g |
---|---|---|
Oracle Identity Management Infrastructure |
Enables secure, central management of enterprise identities. |
Enables secure, central management of enterprise identities. |
Agents Resides with the relying parties and delegate authentication and authorization tasks to OAM Servers. |
Note: Nine Administrator languages are supported. |
|
Servers Notes: Administrative users access the console home page by typing the URL: https://host:port/oamconsole. Non-administrative users first gain access to the single sign-on server by entering the URL of an application, which returns the SSO login page. |
See Also: "Using the New Oracle Access Management Console". "Introducing Access Manager Credential Collection and Login". |
See Also: Oracle Application Server Single Sign-On Administrator's Guide. |
Proxy Provides support for legacy systems: |
|
|
Console |
Oracle Access Management Console |
No console equivalent before Access Manager 11g. |
Protocols that secure information exchange on the Internet |
Front channel protocols exchanged between Agent and Server: HTTP/HTTPS. 11g Webgate secures information exchange using the Agent key. -See Also: Cryptographic keys. |
N/A |
Policy Store |
Database |
mod_osso and partner application |
Applications |
An application that delegates authentication and authorization to Access Manager and accepts headers from a registered Agent. Note: External applications do not delegate authentication. Instead, these display HTML login forms that ask for application user names and passwords. For example, Yahoo! Mail is an external application that uses HTML login forms. |
An application that delegates authentication to mod_osso and the OracleAS Single Sign-On server. Note: After registering mod_osso with Access Manager 11g, mod_osso delegates authentication to OAM. The mod_osso module enables the applications to accept authenticated user information once the user is logged in. Re authenticating is avoided by accepting headers from the registered OSSO Agent. The application is responsible for determining whether the authenticated user is authorized to use the application. |
SSO Engine |
Manages the session lifecycle, facilitates global logout across all relying parties in the valid session, and provides consistent service across multiple protocols. Uses Agents registered with Access Manager 11g:
|
|
Cryptographic keys |
Note: One key is generated and used per registered mod_osso Agent. However, one single key is generated for all 10g Webgates. |
|
Keys storage |
|
|
Cookies See Also: Table 18-8 and |
Host-based authentication cookie:
|
|
Policies |
Registered agents rely on Access Manager authentication, authorization, and token issuance policies to determine who gets access to protected applications (defined resources). |
mod_osso uses only Access Manager 11g authentication policies to determine who gets access to defined resources. mod_osso provides authentication only. |
Client IP |
|
|
Encryption / Decryption (converting encrypted data back into original form) |
Introduces client-side cryptography and ensures that cryptography is performed at both the agent and server ends:
|
Cryptography is performed at both mod_osso and OSSO server:
|
Session Management |
|
|
Response token replay prevention |
|
|
Multiple network domain support |
Access Manager 11g supports cross-network-domain single sign-on out of the box. Oracle recommends you use Oracle Federation for this situation. |
N/A |
Centralized log-out |
See Chapter 22. |
There is no change required for Access Manager 11g with mod_osso (OSSO Agents). Applications that use dynamic directives require no entry in mod_osso.conf. Instead, protection is written into the application as one or more dynamic directives. See Chapter 22. |
This section describes how to manage OSSO Agent registrations (mod_osso) using the Oracle Access Management Console. For details, see:
This topic describes OSSO Agent registration using the Oracle Access Management Console.
Note:
Before you register an OSSO Agent, ensure that the Oracle HTTP Server is installed on the client computer and that the Web server is configured for mod_osso.Figure 24-1 shows a Create OSSO Agent page, under the System Configuration tab in the Oracle Access Management Console.
On the Create OSSO Agent page, required information is identified by the asterisk (*). Table 24-3 describes the required and optional details that you can specify when you register a new agent.
Table 24-3 Create OSSO Agent Page Elements
Element | Description |
---|---|
Name |
The identifying name for this mod_osso Agent. |
Token Version |
The default version of the token is 3.0; the following options are available:
|
Base URL Required for OSSO agents. |
The required protocol, host, and port of the computer on which the Web server for the agent is installed. For example, http://host.example.domain.com:port or https://example.domain.com:port. Note: The host and port are used as defaults for the expanded registration. See Table 24-5. |
Admin ID |
Optional Administrator log in ID for this mod_osso instance. For example, SiteAdmin. |
Admin Info |
Optional Administrator details for this mod_osso instance. For example, Application Administrator. |
Host Identifier |
The host identifier is filled in automatically based on the Agent name |
Auto Create Policies |
During agent registration, you can have authentication and authorization policies created automatically. This option is checked (enabled) by default. The OSSO Proxy requires an Application Domain that includes a resource with the generic URL (/**) protected by a policy based on the LDAP scheme (default). This is why a generic URL is used at the server side. Default: Enabled Notes: If you already have a domain and policies registered, you can simply add new resources to it. If you clear (uncheck) this option, no Application Domain or policies are generated automatically. In an upgraded deployment, you must change the Authentication Scheme in your Authentication Policy to use SSOCoExistMigrateScheme. |
To help streamline Agent registration, several elements are concealed and default values are used during registration with the console. When you view an agent's registration page in the Oracle Access Management Console, all elements and values are revealed as described in "Understanding the Expanded OSSO Agent Page in the Console".
The OSSO Agent configuration file, osso.conf, is updated during agent registration and configuration changes. It is stored on the console host (AdminServer). Following registration or configuration updates, you must relocate the artifacts to the mod_osso directory path on the Agent host as shown in Table 24-4.
Users with Oracle Access Management Administrator credentials can perform the following procedure to register an OSSO Agent using the Oracle Access Management Console.
Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.
From the Oracle Access Management Console, click the New OpenSSO Agent link:
Alternatively: Open the System Configuration tab, Access Manager section, SSO Agents node, OSSO Agent node, then click the Create ... OSSO Agent button in the upper-right corner.
On the Create: OSSO Agent page, enter required details, as shown in Table 24-3:
Name
Base URL
Select the desired Token Version, and enter optional details as desired (Table 24-3).
Click Apply to submit the registration (or close the page without applying changes).
In the Confirmation window, check the path to generated artifacts and then close the window. For example:
Artifacts are generated in following location : /.../base_domain/output/$Agent_Name
Copy osso.conf file from the console host (AdminServer) to the Agent host Web server. For example:
osso.conf From ... | Path ... | |
---|---|---|
From the AdminServer (Console) host | $DOMAIN_HOME/output/$Agent_Name/ | |
To the mod_osso directory path on the Agent host Web server: $OHS_dir/osso.conf. | $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/osso.conf |
In an upgraded deployment, change the Authentication Scheme in the Protected Resources Policy to use SSOCoExistMigrateScheme.
Restart the OAM Server hosting the Agent.
Proceed as needed:
This section describes how to manage OSSO Agent registrations (mod_osso) using the Oracle Access Management Console. For details, see:
During registration, only a subset of available parameters is displayed to streamline the registration 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 after registration. Default values populate previously concealed elements, which are visible when you open the Agent's page, as shown in Figure 24-2. The Confirmation window is still visible.
Figure 24-2 OSSO Agent Page and Confirmation Window
Table 24-5 summarizes the expanded elements and defaults that are used by the OSSO Agent.
Table 24-5 Expanded OSSO Agent Elements
Element | Description |
---|---|
Site Token |
The Application Token used by the partner when requesting authentication. This cannot be edited. |
Success URL |
The redirect URL to be used upon successful authentication. By default, osso_login_success on the fully qualified host and port specified with the Base URL are used. For example: Default: https://example.domain.com:7001/osso_login_success |
Failure URL |
The redirect URL to be used if authentication fails.By default, osso_login_failure on the fully qualified host and port specified with the Agent Base URL are used: Default: https://example.domain.com:7001/osso_login_failure |
Start Date |
First month, day, and year for which log in to the application is allowed by the server. Default: The date the Agent was registered. |
Home URL |
The redirect URL to be used for the Home page after authentication. By default, the fully qualified host and port specified with the Agent Base URL are used: Default: https://example.domain.com:7001 |
Logout URL |
The redirect URL to be used when logging out. This redirects the user to the global logout page on the server: osso_logout_success. By default, the fully qualified host and port specified with the Agent Base URL are used: Default: https://example.domain.com:7001/osso_logout_success See Also: "Introduction to Centralized Logout for Access Manager 11g". |
When you first open the OSSO Agents node, the Search form appears. The Results table lists all OSSO Agents. If there are too many to quickly locate the one you want, you can use the controls to refine your search.
There are only two element on which you can refine an OSSO Agent search: The Agent Name that assigned during registration or the Agent ID assigned by the system.
The OSSO Agent must be registered to be available in the Oracle Access Management Console.
To search for an OSSO Agent registration
Activate the System Configuration tab, Access Manager section.
Expand the SSO Agents node, and open the OSSO Agents node.
In the Name field, enter criteria for your search (with or without including the wild card (*)). For example:
my*
Click the Search button.
In the Search Results table:
Crreate: Click the Create OSSO Agent button at the top of the Search page.
Edt or View: Click the Edit command button in the tool bar to display the configuration page.
Delete: Proceed to "Deleting an OSSO Agent (mod_osso) Registration".
Detach: Click Detach in the tool bar to expand the table to a full page.
Reconfigure Table: Select a View menu item to alter the appearance of the results table.
Apply any changes (or dismiss the page) when finished.
Users with valid Administrator credentials can change any setting for a registered OSSO Agent using the Oracle Access Management Console, as described in the following procedure. For example, you might want to revise the end date or add Administrator information.
Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.
To view or modify an OSSO Agent registration
From the System Configuration tab, Access Manager section, expand the SSO Agents node.
Double-click the OSSO Agents node.
Find the Agent: See "Searching for an OSSO Agent (mod_osso) Registration".
View or Modify: On the registration page, view or modify details as needed (Table 24-3 and Table 24-5).
Click Apply to submit the changes (or close the page without applying changes), and close the Confirmation window.
Copy osso.conf file from the console host (AdminServer) to the Agent host Web server. For example:
osso.conf From ... | Path ... | |
---|---|---|
From the AdminServer (Console) host | $DOMAIN_HOME/output/$Agent_Name/ | |
To the mod_osso directory path on the Agent host Web server: $OHS_dir/osso.conf. | $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/osso.conf |
Restart the OAM Server hosting the Agent.
Proceed to Part VI, "Managing Access Manager SSO, Policies, and Testing".
Users with valid Administrator credentials can perform the following procedure to delete a registered OSSO Agent from the Oracle Access Management Console.
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 Contents".Evaluate the Application Domain, resources, and policies associated with this agent and ensure that these are configured to use another agent or that they can be removed.
To delete an OSSO Agent registration
From the System Configuration tab, Access Manager section, expand the SSO Agents node, and open the OSSO Agents node.
Click Search and choose the desired name (or refine your search as needed).
Optional: Double-click the desired name to display the registration page; confirm this is the agent to remove, and close the page.
Click the Agent name, click the Delete button in the tool bar, and confirm removal in the Confirmation window.
This section provides a brief review of remote registration using the Oracle-provided tool (oamreg) with OSSO Agents.
This section provides the following topics:
This topic provides the OSSO Registration Request for use with the remote registration tool oamreg.sh (Linux) or oamreg.bat (Windows). The information highlighted in bold must be modified for a mod_osso agent. However, all other fields can use the default values.
Both inband
and outofband
remote registration modes require a request file with the input argument, as listed in Table 24-6.
Table 24-6 OpenSSO Request Files for Remote Registration
Templates for . . . | Description |
---|---|
Register OSSO Agents (mod_osso) |
$OAM_REG_HOME/input/OSSORequest.xml |
Other Templates |
|
Update Agent: |
$OAM_REG_HOME/input/OSSOUpdateAgentRequest.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" |
Table 24-7 describes elements in the OSSO request file: OSSORequest.xml.
Table 24-7 OSSO-Specific Elements in a Remote Registration Request
Elements | Description | Example |
---|---|---|
<serverAddress> <agentName> <hostIdentifier> <agentBaseUrl> <autoCreatePolicy> <applicationDomain> <virtualhost> |
Elements common to all remote registration request templates. |
See Table 16-8, "Common Elements in Remote Registration Requests" |
<ssoServerVersion> |
SSO Token version values:
|
<ssoServerVersion> >...</ssoServerVersion> > |
<OracleHomePath> |
The absolute file system directory path to the mod_osso agent. |
<oracleHomePath> $ORACLE_HOME </oracleHomePath> |
<updateMode> |
Default: None specified |
<updateMode></updateMode> |
<adminInfo> |
Optional. Administrator details for this mod_osso instance. For example, Application Administrator. Default: None specified |
<adminInfo></adminInfo> |
<adminId> |
Optional. Administrator log in ID for this mod_osso instance. For example, SiteAdmin. Default: None specified |
<adminId></adminId> |
<logoutUrl> |
Include the Logout URLs for consumption during remote registration. Default: None specified |
<logoutUrl>logout1.html</logoutUrl> |
<failureUrl> |
Include the Failure URLs for consumption during remote registration. Default: None specified |
<failureUrl>failure1.html</failureUrl> |
Remote OSSO Agent registration automatically:
Creates the agent page for the Oracle Access Management Console
Creates an Application Domain and basic policies to protect applications
Updates the OSSO configuration file on the client to be consumed by the agent at run time
This is a brief summary of tasks required to perform in-band remote registration for your OSSO agent. Full details are provided in Chapter 16.
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 AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/osso.conf
To: mod_osso directory path on the Agent host: $OHS_dir/osso.conf. 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".
The term out-of-band registration refers to manual registration that involves coordination and actions by both the in-band Administrator and the out-of-band Administrator.
In outofband
mode, the in-band Administrator uses the starting request file submitted by the out-of-band Administrator, and returns a generated response file to the out-of-band Administrator for additional processing. The out-of-band Administrator runs the remote registration tool with the response file as input to update the agent configuration file.
This is a brief summary of tasks required to perform out-of-band remote registration for your OSSO 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/OSSORequest.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":
osso_Response.xml is generated for the out of band Administrator to use in Step 3.
osso.conf is 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.
osso_Response.xml.
osso.conf
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 24-8 Delta: OSSO Remote Registration versus Remote Updates
Delta | Element |
---|---|
Adds |
<startDate>yyyy_mm_dd</startDate> element to track changes |
<homeUrl> element that specifies the agent_base_url_port |
|
Omits |
<hostidentifier> |
Omits |
<agentbaseURL> |
To remotely update OSSO 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 OSSOUpdateAgentRequest.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/*OSSOUpdateAgentRequest.xml
Provide the registration Administrator user name and password when asked.
Confirm success with on-screen messages.
Relocate to the agent host osso.conf:
From the AdminServer (Console) host: /rreg/output/Agent_Name/
To the mod_osso directory path (Agent host Web server $OHS_dir/osso.conf):
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
!
This section provides the following topics:
With OSSO Agents (mod_osso 10g), partner applications also cede logout control to the OAM Server (single sign-on server). When the user logs out of one application, she is automatically logged out of all other applications.
Note:
No change is needed in the logout URL configuration of existing applications that use the OSSO Agent.Process overview: Centralized logout with mod_osso
Clicking Logout in an application takes the user to the page where logout occurs
When a user has signed off successfully, each of the applications listed on the centralized logout page has a check mark beside the application name.
A broken image beside an application name identifies an unsuccessful logout.
Once all of the application names activated in a session have a check mark, you can click Return to go to the application from which you initiated logout.
Delete the custom mod_osso agent cookies on logout.
The OSSO server cookie includes a list of partner IDs.
Process overview: When a user logs off from one partner application
OSSO server pulls a list of the logout URLs.
OSSO server clears its own cookie.
OSSO server redirects to a customized JSP page (hosted on the OSSO server), and passes the list of logout URLs in the request.
The JSP page loads those logout URLs that contains some image tags of check marks, and as a result of the loading, the cookies for those mod_osso instances are cleared
However, on user logout, some custom cookies set by OAM Server through authentication response settings might not get deleted. However, you can edit oam-config.xml to configure the OAM Server to delete custom cookies set during authentication when a user logs out of OAM. For instance, when integrating with Oracle E-Business Suite, the ORASSO_AUTH_HINT cookie is set by the application and should be included in the CookieNames
list (or the UCM cookie, for example).
Syntax (beneath PluginClass" Type=
...):
<Setting Name="CookieDelMap" Type="htf:map"> <Setting Name="CookieNames" Type="xsd:string">COOKIE_NAME</Setting> </Setting>
The following procedure guides as you edit the CookieDelMap
element and add CookieNames as a single value or a comma-separated list of custom cookies to delete when a user logs out. This procedure also explains how to increment the oam-config.xml file version to propagate your change to all managed servers without restarting.
Caution:
Work carefully. In general, Oracle recommends that you do not edit the oam-config.xml file. This, however, is a rare exception.To delete custom mod_osso cookies on logout
Back up $DOMAIN_HOME/config/fmwconfig/oam-config.xml.
In oam-config.xml, add (or edit) the CookieDelMap
element and CookieNames
. For example:
<Setting Name="ResponsePluginSetting" Type="htf:map">
<Setting Name="PluginClass" Type=... </Settings>
<Setting Name="CookieDelMap" Type="htf:map">
<Setting Name="CookieNames" Type="xsd:string">ORASSO_AUTH_HINT
</Setting>
</Setting>
</Setting>
Configuration Version: Increment the Version xsd:integer
as shown in the next to last line of this example (existing value (25, here) + 1):
Example:
<Setting Name="Version" Type="xsd:integer">
<Setting xmlns="http://www.w3.org/2001/XMLSchema"
Name="NGAMConfiguration" Type="htf:map:>
<Setting Name="ProductRelease" Type="xsd:string">11.1.1.3</Setting>
<Setting Name="Version" Type="xsd:integer">25</Setting>
</Setting>
Save the file.
See Table 24-9 for additional information on legacy OSSO agents with Access Manager.
Table 24-9 Other OSSO Information in this Guide
Topic | Location |
---|---|
Component Loggers |
Table 8-3, "Oracle Access Management Server-Side Component Loggers" |
OSSO Metrics in the DMS Console |
|
Sessions and Session Management |