12 Introduction to Agents and Registration

An agent (also known as a single sign-on agent or policy-enforcement agent) is any front-ending entity that acts as an access client to enable single sign-on across enterprise applications. Individual agents must be registered with Access Manager 11g to set up the required trust mechanism between the agent and OAM Server. Registered agents delegate authentication tasks to the OAM Server.

This chapter includes the following topics to give you an overview of agents, their registration and management, processing, and tools. It includes the following topics:

• Introduction to Policy Enforcement Agents

• Introduction to Agent Registration

• Introduction to Remote Registration

12.1 Introduction to Policy Enforcement Agents

An agent is a software plug-in that can be installed on a Web server (such as Oracle HTTP Server) where the application resides. To secure access to protected resources, a Web server, Application Server, or third-party application must be associated with an agent that is registered with Access Manager. To spare users from re-authenticating when accessing multiple resources, an application must delegate the authentication function to the single sign-on (SSO) provider: Access Manager.

During agent registration, the application can be automatically registered and basic policies generated automatically. Alternatively, you can turn off automatic policy generation during Agent registration and manually create policies.

After registration, the Agent collaborates communication between the OAM Server and its services and acts as a filter for HTTP/HTTPS requests. The Agent intercepts requests for resources protected by Access Manager and works with Access Manager to fulfill access requirements.

This section introduces the types of agents for Access Manager:

• About Agent Types and Runtime Processing

• About 11g Webgate Configured as a Detached Credential Collector

• About 11g Webgate Functionality for Mobile and Social

• About the Pre-Registered 10g Webgate IAMSuiteAgent

12.1.1 About Agent Types and Runtime Processing

With Access Manager 11.1.2, each Agent acts as a filter for requests. Your deployment can include the agent types described in Table 12-1, in any combination.

Table 12-1 Agent Types

Agent Type	Description
OAM Agents Note: Unless explicitly stated, the terms Webgate and Access Client are used interchangeably.	OAM Agents must be installed independently, following Oracle Access Management installation. After registering the agent with Access Manager, the agent communicates directly with registered OAM Servers and Access Manager services. OAM Agents communicate with Access Manager using the OAM Proxy to "sanitize" the request and respond identically for all agents. The following OAM Agents types are available: Webgate: An out of an box Web server access client that intercepts HTTP requests for Web resources and forwards these to the OAM Server. Webgates for various Web servers are shipped with Access Manager. 11g Webgates (Chapter 22) provide: Oracle Universal Installer for platform Host-based cookie Individual Webgate OAMAuthnCookie_<host:port> Resource to Authorization Policy Authorization Result Webgate Authorization Caching Diagnostic page to tune parameters Capability to act as a detached credential collector See Also: "About 11g Webgate Functionality for Mobile and Social" "About 11g Webgate Configured as a Detached Credential Collector" Oracle Fusion Middleware Performance and Tuning Guide 10g Webgates provide InstallShield and One installer per platform Domain-based cookie ObSSOCookie (one for all 10g Webgates) Web server configuration See Also: 10g Pre-registered IAMSuiteAgent in this table and Chapter 22 Custom Access Clients: Access Manager provides a pure Java software developer kit (SDK). Use this SDK to create custom Access Clients and extensions for Access Manager authentication and authorization functionality (and custom tokens). An Access Client processes requests for Web and non-Web resources (non-HTTP) from users or applications. See details in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
IAMSuiteAgent a Pre-registered OAM 10g Agent	This pre-registered 10g agent provides single sign-on functionality for the IAM suite of consoles. The IAM Suite Agent includes a companion Application Domain (IAMSuite) and basic policies that should not be modified. See Also: About the Pre-Registered 10g Webgate IAMSuiteAgent
Legacy OSSO Agents	mod_osso is part of the OracleAS 10g single sign-on (OSSO) solution that authenticates users at a central OSSO Server. The mod_osso module is an Oracle HTTP Server module that provides authentication to OracleAS applications. After registration with Access Manager, OSSO 10g Agents communicate directly with Access Manager 11g services through an OSSO proxy. The OSSO proxy supports existing OSSO agents when upgrading to Access Manager. The OSSO proxy handles requests from OSSO Agents and translates the OSSO protocol into a protocol for Access Manager 11g authentication services. 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 See Also: Chapter 21, "Registering and Managing Legacy OSSO Agents" as well as the following topics:
Legacy OpenSSO Agents	Java Agents are deployed J2EE containers to work with the OpenSSO server. Web Agents can be deployed on any Web or Servlet container. Each OpenSSO Agent is a filter that is plugged into the container (Oracle WebLogic Server, JBoss, Apache, and so on) that hosts applications. Access Manager provides an OpenSSO Proxy to handle requests for resources protected by OpenSSO Agents: Scope can be Host- or Domain-based OpenSSO Agent key stored locally (Agent bootstrap file, Agent host) See Also: Chapter 20, "Registering and Managing Legacy OpenSSO Agents".

Table 12-2 introduces Access Manager features that support agent registration, configuration, management, and single-sign on. Links to topics providing more information are included.

Table 12-2 Agent Registration and SSO Support

	Oracle Provides	Description
	Oracle Access Management Console	Agent Registration, Configuration, Management. See Also: "Registering an OAM Agent Using the Console"
	oamreg tool	Remote Agent Registration and Management See Also: "Acquiring and Setting Up the Remote Registration Tool".
	SSO Implementations	Access Manager supports numerous SSO scenarios. See Also: "Introduction to Access Manager Single Sign-On"
	Protocols that secure information exchange on the Internet	This depends on the credential collector you choose. See Also: Table 16-5, "Comparing the DCC and ECC"
	Login and Logout Forms	The location of the login and logout forms depends on the credential collector. See Also: Table 16-5, "Comparing the DCC and ECC" and Chapter 19
	Cryptographic keys	One key is generated and used per registered mod_osso or 11g Webgate. However, one single key is generated for all 10g Webgates. See Also: Table 1-3, "Introduction: Access Manager 11.1.2"
	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.

OAM Agent Run Time Processing

Table 12-3 provides run time processing information for OAM Agents.

See Also:

"Introduction to Access Manager Credential Collection and Login"

Table 12-3 Run Time Processing Overview for Access Manager

Agent Type	Description
11g Webgates 11g Access Clients	After installation and registration, 11g Webgates communicate with Access Manager using the OAM Proxy to "sanitize" the request and respond identically for all agents. Process overview, Authentication Request without OAMAuthnCookie: When a request for a resource protected by Basic authentication scheme comes without an authorization header (credentials) Webgate redirects through the front channel to either Embedded or Detached Credential Collector (depending on scheme configuration) to collect credentials. Credential Collector collects user credentials based on the challenge method defined for the authentication scheme. User is authenticated; OAM Proxy (Embedded Collector) or Detached Collector itself (DCC) communicates with the OAM Server through the back channel protocol for the token and returns a response through the front channel with a token issued by the OAM Server. Webgate validates the response, extracts the authentication token issued by the OAM Server, and sets a token in OAMAuthnCookie. Webgate is redirected to the requested resource, with the newly set OAMAuthnCookie attached. Webgate validates the OAMAuthnCookie, performs authorization through the back channel, and serves the page when authorization is successful. Process overview, Basic Authentication: When a request for a resource protected by Basic authentication scheme comes without an authorization header (credentials) Webgate responds with WWW-Authenticate header containing the realm mentioned in the authentication scheme with status code 401(authorization required). Browser client interprets the WWW-Authenticate header and collects credentials from user. Browser client performs request again with authorization header containing credentials. See Also: "About 11g Webgate Configured as a Detached Credential Collector" "About 11g Webgate Functionality for Mobile and Social"
10g Webgates 10g Access Clients	After installation and registration, 10g Webgates communicate directly with Access Manager using the OAM proxy, which acts as a bridge. See Also: IAMSuiteAgent for details about this agent and Application Domain. Chapter 22 for details about registering legacy 10g Webgates with Access Manager. Appendix A for details about legacy 10g Webgates currently operating with Web Applications coded for Oracle ADF Security and the OPSS SSO Framework. Oracle Fusion Middleware Application Security Guide for details about legacy 10g Webgates configured as the Identity Assertion Provider (IAP) for SSO (for applications using WebLogic container-based security with Access Manager 11g (or Oracle Access Manager 10g).
OpenSSO Agents	See Also: "Runtime Processing Between OpenSSO Agents and Access Manager".
OSSO Agent (mod_osso 10g)	See: "Understanding OSSO Agents with Access Manager".

12.1.2 About 11g Webgate Configured as a Detached Credential Collector

With Oracle Access Manager 11.1.1, the Embedded Credential Collector (IECC) is the default. The ECC was and is integrated with the OAM Server.

Access Manager 11.1.2 also supports the ECC by default. However, Access Manager 11.1.2 also enables you to configure an 11g Webgate to use as a detached credential collector (DCC).

An 11g Webgate configured to act as a detached credential collector (DCC) is known as anAuthenticating Webgate. Webgates that protect resources are known as Resource Webgates.

The DCC is considered more secure compared to the default embedded credential collector (ECC).

See Also:

"Configuring 11g Webgate and Authentication Policy for DCC"

12.1.3 About 11g Webgate Functionality for Mobile and Social

Webgate interacts with the client to perform authentication and authorization, which involves redirection to collect credentials, set the cookie to hold the session, error reporting, and so on. Webgate works with browser clients, which usually have all the support required for this interaction end to end. However, there are cases where a non-browser/REST client needs to access resources and perform authentication and authorization.

Mobile and Social support is enabled using two user-defined parameters within the Webgate agent registration page. Mobile and Social services use a programmatic non-browser client with Access Manager.

See Also:

• Part IX, "Managing Oracle Access Management Mobile and Social"

• Oracle Fusion Middleware Developer's Guide for Oracle Access Management

12.1.4 About the Pre-Registered 10g Webgate IAMSuiteAgent

This 10g Webgate and the companion Application Domain provides single sign-on functionality for the IDM Administration Console. IAMSuiteAgent is installed and pre-configured as part of the OAM Server installation and configuration.

Oracle strongly recommends that you do not alter IAMSuiteAgent and the companion Application Domain. However, you can replace the IAMSuiteAgent with a fresh 10g Webgate.

See Also:

• "Configuring Centralized Logout for IAMSuiteAgent"

• "Replacing the IAMSuiteAgent with an 10g Webgate"

• "Bundled 10g IAMSuiteAgent Artifacts"

12.2 Introduction to Agent Registration

You can use either the Oracle Access Management Console or the remote registration tool for Agent registration and updates. Unless explicitly stated, information in this section applies to agent registration using either the Oracle Access Management Console or the remote registration tool.

This section provides the following information:

• About Agent Registration, Keys, and Policies

• About File System Changes and Artifacts for Registered Agents

12.2.1 About Agent Registration, Keys, and Policies

Only registered agents can communicate with an OAM Server, and process information when a user attempts to access a protected resource. During agent registration, you can create policies to protect the application during agent registration.

Administrators must register each Agent to operate with Access Manager. The agent is presumed to reside on the computer hosting the application to be protected. However, the Agent can reside on a proxy Web server and the application on a different host.

An agent key and partner key are created during registration. If you choose to automatically create policies during agent registration, a host identifier and Application Domain are created with basic policies and resource definitions. Later on, you can view and manage the Application Domain and policies.

Note:

You can register multiple Webgates or Access Clients under a single host identifier, with the same Application Domain and policies, as follows:

1. When you register a Webgate, allow the process to create a host identifier (a name of your choice), and enable "Auto Create Policies".

2. Register a second Webgate with the same host identifier as Step 1, and clear the "Auto Create Policies" box to eliminate policy creation.

Following a successful registration, whether using the console or using remote registration, the full agent registration appears in the Oracle Access Management Console and is propagated to all Managed Servers in the cluster. Table 12-4 identifies the keys and policies generated during agent registration.

Table 12-4 Keys and Policies Generated During Agent Registration

Keys and Policies	Accessible to	Accessible through
One key per 11g Webgate Agent One key for all 10g Agents One key per OpenSSO Agent stored in local Agent bootstrap file One key per OSSO Agent See Also: "About Key Use, Generation, Provisioning, and Storage"	OAM Server	Client-side: Secure local storage on the client host (a local wallet file) Server side: The Java Keystore
Partner key for the application (None for OpenSSO Agents)	11g Webgate	Client-side
Application Domain and default Policies are generated during Agent registration on demand: Named for the Agent Populated with default authentication and authorization policies (but not Token Issuance Policies) Identified by the same host identifier that was specified for the Agent during registration	Administrators can view, modify, or remove a registered agent using either the Oracle Access Management Console or custom WLST commands for Access Manager All agent types at run time monitor attempts to access a Web site and use OAM Servers to provide authentication and authorization services before completing the request	Oracle Access Management Console Policy Configuration Application Domains DomainName

12.2.2 About File System Changes and Artifacts for Registered Agents

When you register an agent using the Oracle Access Management Console, a new file system directory is created for the Agent on the Oracle Access Management Console host (AdminServer).

This new directory includes generated files for the registered agent, as described in Table 12-5.

Table 12-5 Artifacts Associated with Agent Registration

Registration Artifact	Generated for ...
All Webgates or Access Client ObAccessClient.xml	All Webgates/Access Clients on the console host (AdminServer). During run time, periodic update checks are made. ObAccessClient is updated automatically when a change is discovered. Note: The pre-registered 10g IAMSuiteAgent does not use ObAccessClient.xml for bootstrap or configuration. See Also: Properties files generated on the client in this table.
cwallet.sso 11g Webgate only	11g Webgates, regardless of the transport security mode.
Certificate and password files for secure communication	All Webgates/Access Clients. For example: password.xml (nominally encrypted file for Simple Mode Global passphrase) aaa_cert.pem (reserved name for Webgate certificate file, which cannot be changed) aaa_key.pem (reserved name for Webgate key file, which cannot be changed) Cert Mode: PEM keystore Alias PEM keystore Alias Password Note: When editing an 11g Webgate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In Cert mode, once generated, password.xml cannot be updated. Editing the agent Key Password does not result in creation of a new password.xml. See: Chapter 11 for details about Simple and Cert mode transport security)
OpenSSO Properties files	See: Chapter 20, "Registering and Managing Legacy OpenSSO Agents"
osso.conf file	See: Chapter 21, "Registering and Managing Legacy OSSO Agents"

Generated or updated artifacts must be copied from the console host (AdminServer) into the agent's installation directory, as shown in Table 12-6.

Table 12-6 Copying Generated Artifacts

Agent Type & Artifacts	Copy Generated Artifacts to Agent Installation Directory ...
ObAccessClient.xml (and 11g Webgate cwallet.sso) 11g Webgate or Access Client	Before agent startup, copy the ObAccessClient file (and cwallet.sso) from the generated location (AdminServer (Console) host) to the agent installation directory. See: Chapter 13, "Registering and Managing OAM 11g Agents"
ObAccessClient.xml 10g Webgate or Access Client	Before agent startup, copy ObAccessClient.xml from the generated location to the agent installation directory. For example, from the AdminServer (Console) host: Note: The pre-registered IAMSuiteAgent does not use ObAccessClient.xml and should not be modified. See: Chapter 22, "Registering and Managing 10g Webgates with Access Manager 11g"
OpenSSO Agent Properties Files	See: Chapter 20, "Registering and Managing Legacy OpenSSO Agents"
10g OSSO Agent osso.conf	See: Chapter 21, "Registering and Managing Legacy OSSO Agents"

12.3 Introduction to Remote Registration

As an alternative to using the console for agent registration, you can use the remote registration utility, oamreg, with Oracle-provided templates. The user of the remote registration script can be a part of any group that is mapped against the Administrator's Role in the primary user-identity store for Access Manager (Chapter 4).

Secure registration and creation of an Application Domain (as well as Symmetric key generation) is supported using either remote registration mode described in Table 12-7.

Table 12-7 Remote Registration Methods

Method	Description
In-band mode	For Administrators within the network who manage the Web server that hosts the agent can use this mode or the Oracle Access Management Console.
Out-of-band mode	Administrators outside the network must submit registration requests to an Administrator within the network. After processing the request, the in-band Administrator returns the files required by the out-of-band Administrator who uses the files to configure his environment.

Symmetric key generation per Application: One key is generated and used per registered mod_osso or 11g Webgate. However, one single key only is generated for all 10g Webgates.

Note:

Registration of legacy Agents (10g Webgate, OpenSSO, and OSSO 10g), is also supported.

Table 12-8 describes functionality that is not supported:

Table 12-8 Remote Registration Does Not Support

Not Supported with Remote Registration
Persistence of the Key and Agent Information
Generation of Keys used by internal components
API support for reading Agent information

For more information, see the following topics in Chapter 13:

• About Performing In-Band Remote Registration

• About Performing Out-of-Band Remote Registration

• About Updated Agent Configuration Files

12.3.1 About Performing In-Band Remote Registration

Following is a brief overview of in-band Web server Administrator tasks for provisioning an application using the remote registration tool. Unless explicitly stated, tasks are the same regardless of the type of agent you have protecting resources.

In this overview, the term "Administrator" refers to any user within the network who is part of the LDAP group that is designated for Administrators in the Default System User Identity Store registered with Oracle Access Management.

Task overview: In-band Administrators performing remote registration

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

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

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

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

12.3.2 About Performing Out-of-Band 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.

Task overview: Out-of-band remote registration (Agent 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 as described in "Acquiring and Setting Up the Remote Registration Tool".

   • Copy and edit a template to input unique values for the agent and Application Domain as described in "Creating Your Remote Registration Request".

   • 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 as described in "Acquiring and Setting Up the Remote Registration Tool".

   • Use the out-of-band starting request with the registration tool to provision the agent and create the following files to return to the out-of-band Administrator. See "Performing Out-of-Band Remote Registration" for details:

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

     • OAM Agents: A modified ObAccessClient.xml file is created (and the 11g Webgate cwallet.sso file), which the out-of-band Administrator can use to bootstrap the Webgate.

       11g Webgates: SSO wallet creation.

     • OSSO Agents: A modified osso.conf file is created for the out-of-band Administrator to bootstrap the OSSO module.

     • OpenSSO Agents: A modified version of the OpenSSO properties files are generated.

3. Out-of-band Administrator: Uses the registration tool with the agentName_Response.xml file and copies the Agent configuration and any other generated artifacts to the appropriate file system directory.

   Note:

   In outofband mode, the in-band Administrator uses the starting request file submitted by the out-of-band Administrator, and returns a generated agentName_Response.xml file to the out-of-band Administrator for additional processing. The out-of-band Administrator runs the remote registration tool with agentName_Response.xml as input to generate agent configuration files.

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

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

See Also:

• "About Updated Agent Configuration Files"

• "Understanding the Remote Registration Tool, Modes, and Process"

12.3.3 About Updated Agent Configuration Files

After a successful registration (or update), you must locate the Agent configuration files on the AdminServer (console) host and copy these to the Agent host, as described in Table 12-9.

Table 12-9 Agent Registration and Configuration Update Artifacts

Artifacts For ...	Description
Simple or Cert mode	If Simple or Cert mode is used, certificate artifacts must also be copied to the Agent host following registration. See Also: Appendix C, "Securing Communication"
11g OAM Agents (Webgate/Access Client)	See Also: Chapter 13, "Registering and Managing OAM 11g Agents"
10g OAM Agents (Webgate/Access Client)	See Also: Chapter 22, "Registering and Managing 10g Webgates with Access Manager 11g"
OSSO Agent	See Also: Chapter 21, "Registering and Managing Legacy OSSO Agents"
OpenSSO Agent	See Also: Chapter 20, "Registering and Managing Legacy OpenSSO Agents"