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 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.
-
Introduction to Policy Enforcement Agents
-
Introduction to Agent Registration
-
OAM Remote Registration
14.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, the application delegates the authentication function to the single sign-on (SSO) provider: Access Manager.
During agent registration, the application can be automatically registered and basic policies automatically generated. Alternatively, you can turn off automatic policy generation during Agent registration and manually create policies.
After registration, the Agent acts as a filter for HTTP/HTTPS requests, communicating between the OAM Server and its services. The Agent intercepts requests for resources protected by Access Manager and works with Access Manager to fulfill access requirements. The following sections introduce the types of agents.
-
Agent Types and Runtime Processing for OAM Agents
-
About OAM WebGate Configured as a Detached Credential Collector
14.1.1 Agent Types and Runtime Processing for OAM Agents
With Access Manager, each Agent acts as a filter for requests.
Your deployment can include the agent types described in Table 14-1, in any combination.
Table 14-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:
|
Table 14-2 introduces Access Manager features that support agent registration, configuration, management, and single-sign on. Links to topics providing more information are included.
Table 14-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: Access Manager Single Sign-On Components |
Protocols that secure information exchange on the Internet | This depends on the credential collector you choose. See Also: Table 22-4 |
Login and Logout Forms | The location of the login and logout forms depends on the credential collector. See Also: Table 22-4 and Configuring Centralized Logout for Sessions Involving OAM WebGates |
Cryptographic keys | One key is generated and used per registered Webgate. See Also: Table -1 |
Keys storage |
|
Table 14-3 provides run time processing information for OAM Agents.
See Also:
Understanding Credential Collection and Login
Table 14-3 Run Time Processing Overview for Access Manager
Agent Type | Description |
---|---|
WebGates Access Clients | After installation and registration, 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)
Process overview, Basic Authentication: When a request for a resource protected by Basic authentication scheme comes without an authorization header (credentials)
See Also: "About OAM WebGate Configured as a Detached Credential Collector" |
14.1.2 About OAM WebGate Configured as a Detached Credential Collector
With Oracle Access Manager, the Embedded Credential Collector (ECC) is the default. The ECC was and is integrated with the OAM Server.
Access Manager also supports the ECC by default. However, Access Manager also enables you to configure a WebGate to use a detached credential collector (DCC). The DCC is considered more secure when compared to the default ECC.
A WebGate configured to act as a DCC is known as an Authenticating WebGate. WebGates that protect resources are known as Resource WebGates.
See Also:
"Configuring OAM WebGate and Authentication Policy for DCC"
14.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 of these tools.
This section provides the following details.
-
Keys and Policies Generated during Agent Registration
-
File System Changes and Artifacts for Registered Agents
14.2.1 Keys and Policies Generated during Agent Registration
Administrators must register each Agent to operate with Access Manager. Only registered agents can communicate with an OAM Server, and process information for a user attempting to access a protected resource.
The agent is presumed to reside on the computer hosting the application to be protected. However, it can reside on a proxy Web server and the application on a different host.
An agent key and partner key are created during registration. You can also create policies to protect the application during agent 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:
-
When you register a WebGate, allow the process to create a host identifier (a name of your choice), and enable "Auto Create Policies".
-
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 (using either the console or remote registration tool), the full agent registration appears in the Oracle Access Management Console and is propagated to all Managed Servers in the cluster. Table 14-4 identifies the keys and policies generated during agent registration.
Table 14-4 Keys and Policies Generated During Agent Registration
Keys and Policies | Accessible to | Accessible through |
---|---|---|
One key per WebGate Agent See Also: "Key Use, Generation, Provisioning, and Storage" |
|
|
Partner key for the application |
| Client-side |
Application Domain and default Policies are generated during Agent registration on demand:
|
|
|
14.2.2 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 14-5.
Table 14-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. See Also: Properties files generated on the client in this table. |
cwallet.sso WebGate only | WebGates, regardless of the transport security mode. |
Certificate and password files for secure communication | All WebGates/Access Clients. For example:
Cert Mode:
Note: When editing a 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: Configuring Access Manager Settings for details about Simple and Cert mode transport security) |
Generated or updated artifacts must be copied from the console host (AdminServer) into the agent's installation directory, as shown in Table 14-6.
Table 14-6 Copying Generated Artifacts
Agent Type & Artifacts | Copy Generated Artifacts to Agent Installation Directory ... |
---|---|
ObAccessClient.xml (and WebGate cwallet.sso) 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: Registering and Managing OAM Agents |
14.3 OAM 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 (Managing Data Sources).
Secure registration and creation of an Application Domain (as well as Symmetric key generation) is supported using either remote registration mode described in Table 14-7.
Table 14-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 WebGate.
The functionality that are not supported with remote registration are as follows:
-
Persistence of the Key and Agent Information
-
Generation of Keys used by internal components
-
API support for reading Agent information
For more information on the registration modes, see the following sections:
-
Performing In-Band Remote Registration
-
Performing Out-of-Band Remote Registration
-
Updating Agent Configuration Files
Registering and Managing OAM Agents has additional details.
14.3.1 Performing In-Band Remote Registration
Using the remote registration tool, an in-band Web server Administrator can perform tasks for provisioning an application. 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.
- Acquire the registration tool as described in "Acquiring and Setting Up the Remote Registration Tool".
- Update the 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 and create a default Application Domain for the resources, as described in "Performing In-Band Remote Registration".
- 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 "Verifying Authentication and Access After Remote Registration".
14.3.2 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.
Following is a brief overview of out-of-band remote registration (when the 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 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).
-
- 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 WebGate cwallet.sso file), which the out-of-band Administrator can use to bootstrap the WebGate.
WebGates: SSO wallet creation.
-
-
- 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. - 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 "Verifying Authentication and Access After Remote Registration".
See Also:
-
"Updating Agent Configuration Files"
-
"Remote Registration Tool, Modes, and Process"
14.3.3 Updating 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.
The artifacts for Agent’s registration or update are described in Table 14-8.
Table 14-8 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: Securing Communication |
OAM Agents (WebGate/Access Client) | See Also: Registering and Managing OAM Agents |