FAQ
ForgeRock Identity Platform
ForgeRock Identity Cloud

FAQ: Configuring Agents in Identity Cloud and AM

Last updated Mar 30, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding configuring Agents in ForgeRock Identity Cloud and AM.

1 reader recommends this article

Frequently asked questions

Q. Can an Agent protect multiple realms?

A. No, an agent can only protect one realm; this means an agent cannot send some users to realmA for authentication whilst sending other users to realmB.

However, in AM, you can configure agents to authenticate users in a different realm to one in which the agent is configured. See How do I configure Agents (All versions) to authenticate users against a specific realm, tree or authentication module in AM? for further information.

Authentication to a specific realm is not enforced when you configure your agent for SSO only. SSO only mode verifies that a user has authenticated and that the authentication is valid, but it does not take into account the realm from which the authentication originated. It's one of the few components that doesn't automatically enforce realm authentication; therefore, any user with a valid SSO token is allowed in SSO only mode.

If you want the agent to enforce that a user must be authenticated to a specific realm, you must also configure a policy with an Environment Condition of type Authentication to a Realm and specify the required realm. See  Policies for further details.

Q. Is it possible to protect virtual hosts with Agents?

A. Yes, it is possible to protect virtual hosts with the Web agent. See Install Apache Web Agent on a virtual host for further information.

Q. Can I protect REST endpoints with an Agent?

A. No you cannot. It is suggested you use IG to protect REST endpoints. To achieve this, Identity Cloud or AM acts as an OAuth2 authorization server and IG acts as a resource server. IG can then verify that requests to the REST API contain a valid Access token that has been issued by Identity Cloud or AM. See IG as an OAuth 2.0 resource server for further information.

Q. Why is the hostname, port and/or protocol being replaced in the goto URL for my Agent protected application?

A. Override request URL properties exist, which can be set when configuring a Web agent for SSL offloading. When the Agent Deployment URI Prefix (com.sun.identity.agents.config.agenturi.prefix) property is set along with one or more of the following properties, the respective element in the URL is overridden with the value set in the Agent Deployment URI Prefix:

  • Override Request URL Protocol (com.sun.identity.agents.config.override.protocol) - when enabled, the protocol is overridden with the value from the Agent Deployment URI Prefix.
  • Override Request URL Host (com.sun.identity.agents.config.override.host) - when enabled, the host is overridden with the value from the Agent Deployment URI Prefix.
  • Override Request URL Port (com.sun.identity.agents.config.override.port) - when enabled, the port is overridden with the value from the Agent Deployment URI Prefix.

See Overriding protocol, host, and port for further information.

Q. Why does the fragment identifier disappear from the URL after the Web Agent redirects (Pre-Agents 5.7)?

A. Pre-Agents 5.7, the Web Agent doesn't have access to the fragment identifier (also called hash or anchor) part of the originally requested URL as it never leaves the browser in the HTTP request. This means the part of the URL after # is dropped upon redirect.

Resolved RFE: OPENAM-2164 (RFE: Web agents should include the fragment identifier of the original URL on redirect).

Q. What format should I use for adding a single IP address to the Not Enforced IP Processing list?

A. You must use CIDR notation when adding a single IP address, for example:

10.10.0.102/32

See Not Enforced IP List for further information.

Q. Can I disable the INCLUDE and FORWARD dispatchers?

A. The following dispatchers are included by default in the web.xml file when the Java Agent is installed:

<dispatcher>REQUEST</dispatcher> <dispatcher>INCLUDE</dispatcher>  <dispatcher>FORWARD</dispatcher>  <dispatcher>ERROR</dispatcher>

Either the INCLUDE or FORWARD dispatcher must be present with the REQUEST dispatcher:

  • REQUEST dispatchers are used to intercept requests, for example, a JSP.
  • INCLUDE dispatchers are used when another resource is included from another file such as a header or a footer.
  • FORWARD dispatchers are used in a similar way to client-side redirects, but are wholly server-side with the original request, and possibly additional new parameters, being forwarded on to the new URL. The FORWARD dispatcher can be disabled but it is not always appropriate as there is a risk that other forwarded requests may be missed. If your application uses FORWARD then potentially the agent has two chances to evaluate the policy; at the beginning of the request and when the forward is acted upon.

See Install Java Agent for further details.

Q. How do I add http_header attributes?

A. You must set the Profile Attribute Fetch Mode property to HTTP_HEADER and set the Profile Attribute Map properties for each attribute required as described in Profile Attribute Fetch Mode.

Example

The following example demonstrates adding two http_headers (one for the uid LDAP attribute and one for the cn LDAP attribute) using the UI, Amster and ssoadm:

  • Identity Cloud admin UI: go to Native Consoles > Access Management > Applications > Agents > Web > [Agent Name] > Application, set Profile Attribute Fetch Mode to HTTP_HEADER, and then specify the Key and Value pairs in the Profile Attribute Map: Key Value --- ----- uid header_uid cn header_cn
  • AM admin UI: go to: Realms > Top Level Realm / > Applications > Agents > Web > [Agent Name] > Application, set Profile Attribute Fetch Mode to HTTP_HEADER, and then specify the Key and Value pairs in the Profile Attribute Map: Key Value --- ----- uid header_uid cn header_cn
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with the following JSON for the profileAttributeFetchMode and profileAttributeMap properties: "profileAttributeFetchMode": {            "inherited": false,             "value": "HTTP_HEADER"         },         "profileAttributeMap": {             "inherited": false,             "value": {                 "uid": "header_uid",                 "cn": "header_cn"             }         }
  • ssoadm: enter the following command:
    • AM 7 and later: $ ./ssoadm update-agent -e / -b webAgent -u uid=amAdmin,ou=People,dc=am,dc=forgerock,dc=org -f pwd.txt -a com.sun.identity.agents.config.profile.attribute.fetch.mode=HTTP_HEADER com.sun.identity.agents.config.profile.attribute.mapping[uid]=header_uid com.sun.identity.agents.config.profile.attribute.mapping[cn]=header_cn
    • AM 6.x: $ ./ssoadm update-agent -e / -b webAgent -u amadmin -f pwd.txt -a com.sun.identity.agents.config.profile.attribute.fetch.mode=HTTP_HEADER com.sun.identity.agents.config.profile.attribute.mapping[uid]=header_uid com.sun.identity.agents.config.profile.attribute.mapping[cn]=header_cn

Q. Why can't I see the http_header attributes in the browser?

A. When the Profile Attribute Fetch Mode property (com.sun.identity.agents.config.profile.attribute.fetch.mode) is set to HTTP_HEADER, the agent retrieves the profile attributes through direct communication with Identity Cloud or AM. The agent will then inject the attribute(s) as a Request header before sending the request to the application, then removes them before displaying the page, meaning you will not see them in your browser but they will be accessible to your application.

You can observe this in your agent debug log (amAgent or debug.out log), which shows the headers being cleared:

2015-06-03 11:32:54.788 Warning 9819:1d65310 all: clear_headers(): Clearing header name cn. 2015-06-03 11:32:54.788 Warning 9819:1d65310 all: clear_headers(): Clearing header name email. 2015-06-03 11:32:54.788 Warning 9819:1d65310 all: clear_headers(): Clearing header name userId.

You can observe the header is properly set in the agent debug log (amAgent or debug.out log), where user.0 is the uid of a test user:

2015-07-01 11:26:03.928 Debug 23204:7fd7d830cae0 all: set_user_attributes(): set request header key uid, value user.0, returned AM_SUCCESS
Note

How do I capture HTTP headers set by Web Agents (All versions) in Apache HTTP server using a Perl script? provides information on using a Perl® script to capture user profile attributes set in HTTP headers.

Alternatively, you could write a short script at the application level that will print out the headers received. For example, you could write a PHP script as follows:

echo "header : \n"; foreach (getallheaders() as $name => $value) {    echo "$name: $value\n"; }

You will then be able to check that the values have been received by the application via the HTTP header, for example:

header : Host: am.example.com Connection: keep-alive Cache-Control: max-age=0 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.122 Safari/537.36 Referer: https://am.example.com:8443/am/UI/Login?goto=https%3A%2F%2Fam.example.com%2Ftest.php Accept-Encoding: gzip,deflate,sdch Accept-Language: en-US,en;q=0.8 Cookie: amlbcookie=01; iPlanetDirectoryPro=AQIC5wM2LY4SfcyvzT... cn: user.0 email address: user.0@forgerock.com uid: user.0

Q. What do I need to change if I add a load balancer to an existing setup that does not already have a load balancer?

A. If you subsequently add a load balancer in front of a Web or Java Agent that was initially configured without a load balancer, you must set the FQDN Default (com.sun.identity.agents.config.fqdn.default) to the agent's load balancer URL. In addition, you should check the Agent Deployment URI Prefix (com.sun.identity.agents.config.agenturi.prefix) for Web agents and update the URL as necessary.

Note

It is easier to create a new agent profile and set the Agent URL to the load balancer URL.

See Configure load balancers and reverse proxies (Web) and Configure load balancers and reverse proxies (Java) for further information on configuring agents behind load balancers.

Q. How do I configure the Agent to pass the client IP address when it is behind a load balancer?

A. You can set the advanced com.sun.identity.agents.config.client.ip.header property in the UI as follows:

  • Identity Cloud admin UI: go to Native Consoles > Access Management > Applications > Agents > [Web or Java] > [Agent ID] > Advanced > Client IP Address Header.
  • AM admin UI: go to: Realms > [Realm Name] > Applications > Agents > [Web or Java] > [Agent ID] > Advanced > Client IP Address Header.

For IIS agents this should be set to:

com.sun.identity.agents.config.client.ip.header = HTTP_X_FORWARDED_FOR

For all other agents, it should be set to:

com.sun.identity.agents.config.client.ip.header = X_FORWARDED_FOR

See Handle HTTP request headers for further information on using the X-Forwarded-For HTTP request header.

Q. Which Apache httpd Multi-Processing Module (MPM) should I use with the Web Agent?

A. It is recommended that you always use Worker MPM rather than Prefork MPM. You should ensure there are enough processes and threads available to service the expected number of client requests. You can then tune the Worker mode performance in the conf/extra/http-mpm.conf file as detailed in Tune Apache multi-processing modules.

You can check which MPM Apache is using with the following command:

$ apachectl -V

The MPM in use is shown against Server MPM.

Note

Turning off the Apache™ KeepAlive feature can potentially improve performance as well since the KeepAlive feature increases memory usage. You should test your performance with KeepAlive enabled and then again with it off to check what impact it has on your setup.

See Also

FAQ: Configuring policies in Identity Cloud and AM

Agents and policies in AM

Web Agents User guide

Java Agents User guide

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.