How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM 6, 5.x and OpenAM 13.x?
The purpose of this article is to provide information on configuring Web and JEE policy agents to authenticate users against a specific realm in AM/OpenAM. This information does not apply to Agents 5 since they use conditional redirection rules to achieve this.
1 reader recommends this article
Archived
This article has been archived and is no longer maintained by ForgeRock.
Overview
You can specify a realm in the agent login URL to authenticate users against a realm. For example, you may choose to configure your agent in one realm, yet have your users authenticate through another realm. In this scenario, you would want your agents to redirect users to authenticate to the user's realm, rather than the agent's realm.
Note
Policy agents can only protect one realm; this means a policy agent cannot send some users to realmA for authentication while sending other users to realmB.
Authentication to a specific realm is not enforced when you configure your policy 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 access. If you want the policy 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 Authorization Guide › Configuring Policies and Setup and Maintenance Guide › Working With Realms and Policy Agents for further details.
See the following sections for further information on setting the login and logout URLs:
Note
Agents 5 uses conditional redirection rules to achieve this. See How do I configure Agents (All versions) to authenticate users against a specific realm, tree or authentication module in AM? for further information.
Configuring the login URL
You can configure the login URL for the policy agent using either the console or ssoadm:
- AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the login URL (including the realm).
- OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the login URL (including the realm).
- ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.login.url[0]=[loginURL] replacing [realmname], [agentname], [adminID], [passwordfile] and [loginURL] with appropriate values.
Note
If you specify a realm in the login URL, you should also specify the realm in the logout URL.
Accepted URL formats
The way of specifying a realm parameter in the login URL depends on your AM/OpenAM version as follows, where the realm is employees:
- AM / OpenAM 13.5: the query must be defined before the hash (#login), and the realm must be specified using the absolute path (/employees) or the realm DNS alias. Therefore a valid login URL is: http://host1.example.com:8080/openam/XUI?realm=/employees#login/
- OpenAM 13: in OpenAM 13, you should use the Classic UI form of the URL even if you use XUI to avoid a known issue: http://host1.example.com:8080/openam/UI/Login?realm=employees See XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 13.x login page loading for further information on this known issue.
Configuring the logout URL
You can configure the logout URL for the policy agent using either the console or ssoadm:
- AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the logout URL (including the realm).
- OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the logout URL (including the realm).
- ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.logout.url[0]=[logoutURL] replacing [realmname], [agentname], [adminID], [passwordfile] and [logoutURL] with appropriate values.
Accepted URL formats
The way of specifying a realm parameter in the logout URL depends on your AM/OpenAM version as follows, where the realm is employees:
- AM / OpenAM 13.5: the query must be defined before the hash (#logout), and the realm must be specified using the absolute path (/employees) or the realm DNS alias. Therefore a valid logout URL in the XUI is: http://host1.example.com:8080/openam/XUI?realm=/employees#logout/
- OpenAM 13: in OpenAM 13, you should use the Classic UI form of the URL even if you use XUI: http://host1.example.com:8080/openam/UI/Logout?realm=employees
See Also
FAQ: Configuring Agents in Identity Cloud and AM
XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 13.x login page loading
Web Policy Agent Guide › Configuring Access Management Services Properties
OpenAM JEE Policy Agents User's Guide › Configuring Java EE Policy Agent OpenAM Services Properties
Related Training
ForgeRock Access Management Core Concepts (AM-400)
Related Issue Tracker IDs
OPENAM-8173 (OpenAM Login URL in the agent profile should support XUI login URL)
OPENAM-8157 (Upgrade from OpenAM 12 to OpenAM 13 XUI login is redirecting to http://undefined/)
OPENAM-6340 (XUI needs to support DNS/Alias behaviour for subrealms as per OPENAM-5508)
OPENAM-5547 (Agent behaviour when appending goto= to LoginURLs is not compatible with XUI login URL)