22 Registering and Managing Legacy OSSO Agents

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

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

• Understanding OSSO Agents with Access Manager

• Registering OSSO Agents Using Oracle Access Management Console

• Configuring and Managing Registered OSSO Agents Using the Console

• Performing Remote Registration for OSSO Agents

• Updating Registered OSSO Agents Remotely

• Configuring Logout for OSSO Agents with Access Manager 11.1.2

• Locating Other OSSO Agent Information

22.1 Understanding OSSO Agents with Access Manager

This section provides the following topics:

• About OSSO Agents with Access Manager

• Comparing Access Manager 11g SSO versus OSSO 10g

22.1.1 About OSSO Agents with Access Manager

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 22-1).

Table 22-1 OSSO Agents with Access Manager

Checks for an existing valid Oracle HTTP Server cookie	Redirects to the OAM Server if needed to contact the directory during authentication
Decrypts the encrypted user identity populated by the OSSO server	Sets the headers with user attributes

22.1.2 Comparing Access Manager 11g SSO versus OSSO 10g

This topic introduces key components to implementing and enforcing Access Manager 11g policies for single sign-on as compared with 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 22-2 summarizes the differences.

Table 22-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.	11g OAM Agents 10g OAM Agents 10g OSSO Agents (mod_osso) OpenSSO Agents Note: Eight Administrator languages are supported.	mod_osso (partner) Note: The mod_osso module is an Oracle HTTP Server module that provides authentication to OracleAS applications.
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.	OAM Server Oracle Access Management Console (installed on the WebLogic Administration Server) See Also: "Logging In to and Signing Out of Oracle Access Management Console". "Introduction to Access Manager Credential Collection and Login".	OracleAS SSO server (OSSO server) See Also: Oracle Application Server Single Sign-On Administrator's Guide.
Proxy Provides support for legacy systems:	OAM Proxy supports legacy Access Manager implementations by acting as a legacy Access Server. OSSO Proxy supports OSSO Agents by acting as the legacy OSSO Server. Oracle-provided OpenSSO Proxy handles requests for resources protected by OpenSSO Agents	OSSO Proxy supports legacy SSO implementations by acting as the legacy OSSO Server.
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: Authentication (credential collection) occurs across the HTTP (HTTPS) channel Authorization occurs across the Oracle Access Protocol (OAP) channel	mod_osso delegates authentication only and communicates exclusively through the HTTP channel.
Cryptographic keys	During 11g agent registration, a key is generated for the agent and also shared with the OAM Server The key is used for encrypting and decrypting SSO cookies During 10g agent registration, a global shared secret key is generated across all of Access Manager 11g (all Agents and OAM Servers). During OSSO agent registration, One key per partner shared between mod_osso and OSSO server. OpenSSO Agent: Host- or Domain-based key stored locally in bootstrap file on Agent host. During OAM Server installation, one OAM Server key is generated Note: One key is generated and used per registered mod_osso Agent. However, one single key is generated for all 10g Webgates.	One key per partner shared between mod_osso and OSSO server OSSO server's own key One global key per OSSO setup for the GITO domain cookie
Keys storage	Agent side: A per-agent key is stored locally in the Oracle Secret Store in a wallet file OAM Server side: A per- agent key, and server key, are stored in the credential store on the server side Security Token Service	mod_osso side: partner keys and GITO global key stored locally in obfuscated configuration file OSSO server side: partner keys, GITO global key, and server key are all stored in the directory server
Cookies See Also: Table 16-8 and "About Single Sign-On Cookies During User Login"	Host-based authentication cookie: 11g Webgate, One per agent: OAMAuthnCookie_<host:port>_<random number> 10g Webgate, One ObSSOCookie for all 10g Webgates. One for the OAM Server: OAM_ID (Table 16-8)	Host-based authentication cookie: one per partner: OHS-host-port one for OSSO server: (not with Access Manager 11g) Domain-level session cookie for global inactivity timeout (GITO) if enabled
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	Maintain this Client IP, and include it in the host- based OAMAuthnCookie.	Include the original client IP inside the host cookie. In later authentication requests, when the cookie is presented, the original client IP is compared with the presenter's IP. Rejection occurs if there is no match
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: Webgate encrypts obrareq.cgi using the agent key. Note: obrareq.cgi is the authentication request in the form of a query string redirected from Webgate to OAM Server. OAM Server decrypts the request, authenticates, creates the session, and sets the server cookie. OAM Server also generates the authentication token for the agent (encrypted using the agent key), packs it in obrar.cgi with a session token (if using cookie-based session management), authentication token and other parameters, then encrypts obrar.cgi using the agent key. Note: obrar.cgi is the authentication response string redirected from the OAM Server to Webgate. Webgate decrypts obrar.cgi, extracts the authentication token, and sets a host-based cookie.	Cryptography is performed at both mod_osso and OSSO server: site2pstore token (request from mod_osso to server) is encrypted using the partner key locally at mod_osso. OSSO server decrypts site2pstore token, authenticates, and generates its own cookie. urlc token (the response from OSSO server to mod_osso) is encrypted using the partner key at the server. mod_osso decrypts the urlc token locally and re-encrypts using its own format to set in a host-based cookie.
Session Management	Session idle timeout behavior is supported through the 11g Session Management Engine (SME).	Single domain supported through a domain-level cookie for global inactivity timeout (GITO). Multi-domain SSO: After a user logs in to one domain, and then goes to a different domain, he is considered idle from the first domain. When the idle times out on the original domain, the user must re-authenticate on the original domain.
Response token replay prevention	Include RequestTime (the timestamp just before redirect) in obrareq.cgi and copy it to obrar.cgi to prevent response token replay.	Include RequestTime (timestamp just before redirect) in the site2pstore token and copy it to the urlc token to prevent token replay.
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	The logOutUrls (10g Webgate configuration parameter) is preserved. 10g logout.html requires specific details for Access Manager 11g. 11g Webgate parameters are new: Logout Redirect URL Logout Callback URL Logout Target URL See Chapter 20.	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 20.

See Also:

"Introduction to Access Manager Credential Collection and Login"

22.2 Registering OSSO Agents Using Oracle Access Management Console

This section describes how to manage OSSO Agent registrations (mod_osso) using the Oracle Access Management Console. For details, see:

• Understanding the Create OSSO Agent Registration Page and Parameters

• Registering an OSSO Agent (mod_osso) Using the Console

22.2.1 Understanding the Create OSSO Agent Registration Page and Parameters

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 22-1 shows a Create OSSO Agent page, under the System Configuration tab in the Oracle Access Management Console.

Figure 22-1 Create OSSO Agent Page

Description of "Figure 22-1 Create OSSO Agent Page"

On the Create OSSO Agent page, required information is identified by the asterisk (*). Table 22-3 describes the required and optional details that you can specify when you register a new agent.

Table 22-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: 1.2 1.4 3.0
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 22-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".

OSSO Agent Configuration File

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 22-4.

Table 22-4 Relocating OSSO Artifacts

From AdminServer . . .	To OHS_dir/osso.conf
$DOMAIN_HOME/output/$Agent_Name/	$WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/osso

22.2.2 Registering an OSSO Agent (mod_osso) Using the Console

Users with Oracle Access Management Administrator credentials can perform the following procedure to register an OSSO Agent using the Oracle Access Management Console.

Prerequisites

Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.

See Also:

Understanding the Create OSSO Agent Registration Page and Parameters

To register an OSSO Agent

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

   
   Welcome page
   SSO Agent panel
   New OSSO 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.

2. On the Create: OSSO Agent page, enter required details, as shown in Table 22-3:

   • Name

   • Base URL

3. Select the desired Token Version, and enter optional details as desired (Table 22-3).

4. Click Apply to submit the registration (or close the page without applying changes).

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

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

   
   

7. In an upgraded deployment, change the Authentication Scheme in the Protected Resources Policy to use SSOCoExistMigrateScheme.

8. Restart the OAM Server hosting the Agent.

9. Proceed as needed:

   • "Configuring and Managing Registered OSSO Agents Using the Console"

   • Part V, "Managing Access Manager SSO, Policies, and Testing"

22.3 Configuring and Managing Registered OSSO Agents Using the Console

This section describes how to manage OSSO Agent registrations (mod_osso) using the Oracle Access Management Console. For details, see:

• Understanding the Expanded OSSO Agent Page in the Console

• Searching for an OSSO Agent (mod_osso) Registration

• Viewing or Editing OSSO Agent (mod_osso) Registration

• Deleting an OSSO Agent (mod_osso) Registration

22.3.1 Understanding the Expanded OSSO Agent Page in the Console

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 22-2. The Confirmation window is still visible.

Figure 22-2 OSSO Agent Page and Confirmation Window

Description of "Figure 22-2 OSSO Agent Page and Confirmation Window"

Table 22-5 summarizes the expanded elements and defaults that are used by the OSSO Agent.

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

22.3.2 Searching for an OSSO Agent (mod_osso) Registration

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.

Prerequisites

The OSSO Agent must be registered to be available in the Oracle Access Management Console.

To search for an OSSO Agent registration

1. Activate the System Configuration tab, Access Manager section.

2. Expand the SSO Agents node, and open the OSSO Agents node.

3. In the Name field, enter criteria for your search (with or without including the wild card (*)). For example:

   my*
   

4. Click the Search button.

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

6. Apply any changes (or dismiss the page) when finished.

22.3.3 Viewing or Editing OSSO Agent (mod_osso) Registration

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.

Prerequisites

Ensure that the Oracle HTTP Server is installed and running on the client computer, and is configured for mod_osso.

See Also:

• Understanding the Expanded OSSO Agent Page in the Console

To view or modify an OSSO Agent registration

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

2. Double-click the OSSO Agents node.

3. Find the Agent: See "Searching for an OSSO Agent (mod_osso) Registration".

4. View or Modify: On the registration page, view or modify details as needed (Table 22-3 and Table 22-5).

5. Click Apply to submit the changes (or close the page without applying changes), and close the Confirmation window.

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

   
   

7. Restart the OAM Server hosting the Agent.

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

22.3.4 Deleting an OSSO Agent (mod_osso) Registration

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

Prerequisites

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.

See Also:

Searching for an OSSO Agent (mod_osso) Registration

To delete an OSSO Agent registration

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

2. Click Search and choose the desired name (or refine your search as needed).

3. Optional: Double-click the desired name to display the registration page; confirm this is the agent to remove, and close the page.

4. Click the Agent name, click the Delete button in the tool bar, and confirm removal in the Confirmation window.

22.4 Performing Remote Registration for OSSO Agents

This section provides a brief review of remote registration using the Oracle-provided tool (oamreg) with OSSO Agents.

This section provides the following topics:

• Understanding Request Templates for OSSO Remote Registration

• Performing In-Band Remote Registration of OSSO Agents

• Performing Out-of-Band Remote Registration for OSSO Agents

22.4.1 Understanding Request Templates for OSSO Remote Registration

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 22-6.

Table 22-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 22-7 describes elements in the OSSO request file: OSSORequest.xml.

Table 22-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 14-8, "Common Elements in Remote Registration Requests"
<ssoServerVersion>	SSO Token version values: v3.0: Most secure token using AES encryption standard for encrypting tokens exchanged between OAM Server and mod_osso. This is the default value. This was supported by OSSO 10.1.4.3 patch set. v1.4: This is supported by OSSO 10g prior to OSSO 10.1.4.3 patch set. Uses DES encryption standard. v1.2: This used to be version of tokens exchanged between OSSO partners prior to OSSO 10.1.4.0.1. Uses DES.	<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

22.4.2 Performing In-Band Remote Registration of OSSO Agents

This is a brief summary of tasks required to perform in-band remote registration for your OSSO agent. Full details are provided in Chapter 14.

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: OSSORequest.xml
   To: myossoagent_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 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:

   
   $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/ osso.conf
   

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

22.4.3 Performing Out-of-Band Remote Registration for OSSO Agents

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.

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.

   • 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).

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

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

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

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

22.5 Updating Registered OSSO 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 22-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

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 OSSOUpdateAgentRequest.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/*OSSOUpdateAgentRequest.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 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):

      
      $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/osso.conf
      

   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!

22.6 Configuring Logout for OSSO Agents with Access Manager 11.1.2

This section provides the following topics:

• About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager

• Removing Custom mod_osso Cookies on Logout

22.6.1 About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager

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

1. Clicking Logout in an application takes the user to the page where logout occurs

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

3. A broken image beside an application name identifies an unsuccessful logout.

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

5. Delete the custom mod_osso agent cookies on logout.

22.6.2 Removing Custom mod_osso Cookies on Logout

The OSSO server cookie includes a list of partner IDs.

Process overview: When a user logs off from one partner application

1. OSSO server pulls a list of the logout URLs.

2. OSSO server clears its own cookie.

3. OSSO server redirects to a customized JSP page (hosted on the OSSO server), and passes the list of logout URLs in the request.

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

1. Back up $DOMAIN_HOME/config/fmwconfig/oam-config.xml.

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

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

4. Save the file.

22.7 Locating Other OSSO Agent Information

See Table 22-9 for additional information on legacy OSSO agents with Access Manager.

Table 22-9 Other OSSO Information in this Guide

Topic	Location
Component Loggers	Table 6-3, "Oracle Access Management Server-Side Component Loggers"
OSSO Metrics in the DMS Console	"Reviewing OSSO Agent Metrics"
Sessions and Session Management	"About Timeout with Multiple-Agent Types: OSSO and OAM Agents"