How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure Agents (All versions) to authenticate users against a specific realm, tree or authentication module in AM?

Last updated Sep 27, 2021

The purpose of this article is to provide information on configuring Web and Java Agents to authenticate users against a specific realm, tree or authentication module in AM using conditional redirection rules.


2 readers recommend this article

Overview

Communication between the Agent and AM uses the OAuth 2.0 Authorization Framework. This means the agent and AM exchange OpenID Connect JSON web tokens (JWTs) containing the information required to authenticate clients and authorize access to protected resources. Agents authenticate to and log out users from the oauth2/authorize endpoint, which is not configurable. To specify the realm, tree or authentication module users should authenticate to, or log out from, you must add a conditional redirection rule. For example, the following value would authenticate users in a realm called 'customers' using an authentication tree called 'myTree':

example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers&service=myTree

See the following links for further information:

Additional considerations 

  • Java Agents 5 introduced changes to several configuration properties used to customize login and logout URLs for redirecting users (including conditional login rules). See Changes to Login, Logout, and Conditional Login Properties for further information.
  • Web Agents 5.6.3 introduced a new Accept SSO Token property (com.forgerock.agents.accept.sso.token) for use with SSO token exchange during custom redirect mode. This property replaces the Exchange SSO Token for JWT (com.forgerock.agents.accept.ipdp.cookie) property, which has been removed in Web Agents 5.9. See Changes to the Custom Login Redirection Mode for further information.

Configuring conditional redirection rules (Web Agent)

You can configure conditional redirection rules for the Web agent using the Conditional Login URL property (com.forgerock.agents.conditional.login.url). This is a custom property that you manually set in the agent's profile. You can either add it as an advanced property in the console or via the command line (Amster or ssoadm):

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property. For example: com.forgerock.agents.conditional.login.url[0] = example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: customProperties
    • Property value: com.forgerock.agents.conditional.login.url[0]

For example:  "customProperties": {            "inherited": false,             "value": [                 "com.forgerock.agents.conditional.login.url[0]=example.com|http://host1.example.com/openam/oauth2/authorize?realm=customers"             ]         }

  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "com.forgerock.agents.conditional.login.url[0]=[conditionalloginURL]" replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    • AM 7 and later: $ ./ssoadm update-agent -e / -b MyWebAgent -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a "com.forgerock.agents.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
    • Pre-AM 7: $ ./ssoadm update-agent -e / -b MyWebAgent -u amadmin -f pwd.txt -a "com.forgerock.agents.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
Note

If you have a custom Login URL set (which defines the URL of a custom login page) you must also set the Allow Custom Login Mode property (org.forgerock.openam.agents.config.allow.custom.login) to true. This specifies whether the agent should use the default or the custom login mode when redirecting unauthenticated users. See Login URL and Login Redirect for further information.

Configuring conditional redirection rules (Java Agent)

You can configure conditional redirection rules for the Java agent using the Conditional Login URL property (org.forgerock.openam.agents.config.conditional.login.url). You can set this property using either the console, Amster or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > AM Services > AM Conditional Login URL and enter the conditional redirect rule. For example: example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers
  • AM 5.5 console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > OpenAM Services > OpenAM Conditional Login URL and enter the conditional redirect rule.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: J2eeAgents
    • Property: conditionalLoginUrl
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "org.forgerock.openam.agents.config.conditional.login.url[0]=[conditionalloginURL]" replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    • AM 7 and later: $ ./ssoadm update-agent -e / -b MyJavaAgent -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a "org.forgerock.openam.agents.config.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
    • Pre-AM 7: $ ./ssoadm update-agent -e / -b MyJavaAgent -u amadmin -f pwd.txt -a "org.forgerock.openam.agents.config.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
Note

If you have a custom Login URL set (which defines the URL of a custom login page) you must also set the Allow Custom Login Mode property (org.forgerock.openam.agents.config.allow.custom.login) to true. This specifies whether the agent should use the default or the custom login mode when redirecting unauthenticated users. See Login URL and Login Redirect for further information.

See Also

Redirect loop between AM and Agents (All versions) after successful authentication

Login Redirect (Web)

Login Redirect (Java)

Agents and policies in AM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


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