28.5 Performing Remote Registration for OpenSSO Agents

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

• Request Templates for OpenSSO Agent Remote Registration

• OpenSSO Bootstrap Configuration Mappings

• Performing In-Band Remote Registration with OpenSSO Agents

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

28.5.1 Request Templates for OpenSSO Agent Remote Registration

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

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

Table 28-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 28-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 28-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 15-8
<agentType>	Choose between J2EE or Web type OpenSSO agents.	<agentType>WEB</agentType>
Password Re-enter Password	A required, unique password for this OpenSSO agent, which can be assigned during this registration process. The entry will appear in obfuscated format in the console, in oam-config.xml, and in OpenSSOAgentBootstrap.properties. When a registered agent connects to an OAM SServer, the user is prompted for the password. The password is used for authentication to prevent unauthorized agents from connecting and obtaining policy information.	You are asked to supply a password during remote registration. This does not appear in the template.
Extended OpenSSO Template Only
<agentDebugDir>	With <debug> set to true, you can configure the directory path for logged agent messages. Default: None See Also: Logging Component Event Messages	<agentDebugDir>/scratch/debug</agentDebugDir>
<agentAuditDir>	Defines the directory path for audit logs from the OAM Server: Audit Login events Audit Logout success events See Also: Auditing Administrative and Run-time Events	<agentAuditDir>/scratch/audit</agentAuditDir>
<agentAuditFileName>	Defines the audit log file name.	<agentAuditFileName>audit.log</agentAuditFileName>
<debug>	When set to true, the OAM Server logs messages for: Login success and login failure events Logout success and logout failure events Log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE), each of which indicates severity in descending order. Default: false See Also: Logging Component Event Messages	<debug>false</debug>
<cookieName>	The name of the cookie, which the agent finds this cookie after the OpenSSO Proxy triggers session validation The end user has the following valid cookies: OAM_ID cookie (represents the end user session after agent authentication) OpenSSO cookie	<cookieName>iPlanetDirectoryPro</cookieName>
<accessDeniedUrl>	If access is denied, the user is redirected to this URL.	<accessDeniedUrl></accessDeniedUrl>
<protectedAuthnScheme>	Specifies the Authentication Scheme to use in the Authentication Policy. In an upgraded environment, use SSOCoExistMigrateScheme for the Protected Resource Policy for any new OSSO Agents you register.	<protectedAuthnScheme></protectedAuthnScheme>

28.5.2 OpenSSO Bootstrap Configuration Mappings

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

• Table 28-10

• Table 28-11

Table 28-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 28-11 shows the mappings between a Web Agent request file and properties file.

Table 28-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>

28.5.3 Performing In-Band Remote Registration with OpenSSO Agents

Here is a brief summary of tasks required to perform in-band remote registration for your OpenSSO agent.

Prerequisites

"OAM Remote Registration"

Task overview: In-band Administrators performing remote registration

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

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

2. Create your input file with unique values for the agent and Application Domain as described in "Creating Your Remote Registration Request".
   • From: OpenSSORequest.xml
   • To: myopenssoagent_request.xml
3. Run the registration tool to configure the Agent, create a default Application Domain for the resources, and copy the updated agent configuration file as described in "Performing In-Band Remote Registration".

   From the console host (AdminServer):

   /rreg/output/Agent_Name/

   • OpenSSOAgentBootstrap.properties

   • OpenSSOAgentConfiguration.properties

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

   • $WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/
4. Validate the configuration as described in "Validating Remote Registration and Resource Protection".
5. Perform access checks to validate that the configuration is working, as described in "Verifying Authentication and Access After Remote Registration".

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

Here is a brief summary of tasks required to perform out-of-band remote registration for your OpenSSO agent.

Prerequisites

"OAM 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/OpenSSORequest.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":

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

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

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

   • opensso_Response.xml.

   • opensso....properties files

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