Best Practice

Best practice for blocking the top level realm in a proxy for AM/OpenAM (All versions)

Last updated Sep 14, 2020

The purpose of this article is to provide best practice advice on preventing access to the top level realm in AM/OpenAM. It is often a security requirement to prevent access to this realm since it is where the most privileged AM/OpenAM accounts are located. This article discusses common approaches to doing this in a proxy, web application firewall (WAF) or load balancer.

2 readers recommend this article


The recommendations made in this article are not an exhaustive list of approaches for preventing access to the top level realm or for securing your deployment. These recommendations are provided without any warranty or liability to ForgeRock.

You should read How do I remove console access in AM/OpenAM (All versions)? before following any guidance in this article.

Background Information

There is often a security requirement to prevent access to the top level realm as this realm is where the most privileged AM/OpenAM accounts are located. This article discusses common approaches to doing this in a proxy, web application firewall (WAF) or load balancer, and includes the following sections:

Common mistakes

  • Using realm DNS aliases for security. When a client reaches a realm by, they can navigate to other realms using
  • Not blocking access to the application authentication module (built in module for use by agents and ssoadm), which can always be reached even if module based authentication is disabled. The amAdmin account can authenticate on this module in the top level realm.
  • Creating rules just for endpoints, rather than the query strings on those endpoints.
  • Not creating the equivalent rules for authIndexType= and authIndexValue= when creating rules for the service= and module= query strings.
  • Not blocking access to legacy endpoints such as /sessionservice, /profileservice, /policyservice, /namingservice, /loggingservice, /authservice and /notificationservice.
  • Configuring in memory time based account lockout for administrative accounts to prevent brute force attacks. This feature has no affect on the amAdmin account.
  • Creating whitelist (allow) rules for URL query parameters. These can be specified multiple times; different implementations handle this situation in different ways. AM/OpenAM takes the first instance of a URL query parameter that is found. If you create a whitelist for parameters, specifying multiples of the parameter can be used to circumvent the rule.
  • Not considering URL encoding when creating rules. For example, realm=/ may be blocked, but is realm=2F blocked?

AM/OpenAM configuration best practice

You should ensure you comply with the following best practice advice when configuring AM/OpenAM:

  • Follow all the security guidance in Installation Guide › Securing Installations.
  • Disable module based authentication. When enabled, this can be used to circumvent multi-factor authentication if multiple modules are configured in a chain with the same authLevel.
  • Create realms for your organization(s) and separate administrative users from end users as recommended in Installation Guide › Securing Administration. It is recommended to use the top level realm for administrative users. Access to that realm should be tightly controlled.
  • Ensure the top level realm does not contain federation entities, agent profiles, authorizations, OAuth2/OIDC or STS services to reduce the attack surface on this realm.
  • Create separate administrative instances of AM/OpenAM that are outside of the load balanced pool. Endpoints that are not used in the user facing instances can have unused endpoints removed from the web.xml file and the console folder can be deleted.
  • Use realm DNS aliases only for convenience, to “prettyfy” URLs and to mask the configuration of the AM/OpenAM deployment. Do not use them as a means of securing the deployment.

See How do I mitigate brute force attacks in AM/OpenAM (All versions)? for additional considerations for mitigating brute force attacks.

Proxy/WAF rules best practice

You should ensure you comply with the following best practice advice for proxy/WAF rules:

  • Use a combination of whitelist (allow) and blacklist (deny) rules, making sure to create rules for endpoints AND the query strings used on those endpoints.
  • Create whitelist (allow) rules to only allow access on the endpoints that are used in your use cases. This will have the added benefit of blocking legacy endpoints, which could be used for authentication. Create additional blacklist (deny) rules that prevent navigation by query string to the top level realm. For example, deny the query string realm=/ on the authenticate endpoint in each realm. Make sure that these rules are also effective when URL encoding is used, for example, realm=2F
  • Create blacklist (deny) rules that prevent the Application authentication module from being called externally. You should be aware that this endpoint is also used as follows and can be accessed even when module based authentication is disabled:
    • Web/JEE policy agents use this endpoint in versions 4.x and lower.
    • ssoadm uses this endpoint.
    • json/authenticate uses this endpoint if used with the following parameters:
      The XUI will understand the syntax module=Application and convert it to the above format on the authenticate endpoint.
    • Legacy endpoints such as /UI/Login use the format module=Application.
  • Deny the query string realm=/ on the /oauth2/authorize and /oauth2/access_token endpoints if an OAuth2 provider is required in the top level realm for administrative use internally (not recommended).
  • Ensure that only hostnames that are supposed to be used externally are permitted; this prevents AM/OpenAM from redirecting to the default site URL, which may not be suitable. This situation can occur if an attacker tries to access AM/OpenAM via the IP address of a front end load balancer, instead of the hostname.

Endpoints that allow authentication in the top level realm

The following endpoints can provide an SSO token for users in the top level realm or can provide tokens that can then be exchanged for SSO tokens of users in the top level realm; these endpoints use example realms /europe and /customers. Consider blocking these endpoints (substituting your realm names for the example ones) if you wish to deny access to the top level realm.

Endpoint AM 5 and later OpenAM 13.x
/json/realms/root/authenticate Yes --
/json/realms/root/realms/root/authenticate Yes --
/json/realms/root/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/realms/customers/authenticate?realm=/ Yes --
/json/realms/root/realms/europe/authenticate?realm=/&realm=/customers Yes --
/json/authenticate Yes Yes
/json/authenticate?realm=/ Yes Yes
/json/authenticate?realm=/&realm=/europe Yes Yes
/json/europe/authenticate?realm=/ Yes Yes
/json/europe/customers/authenticate?realm=/ Yes Yes
/UI/Login?realm=/ Yes Yes
/UI/Login Yes Yes

Additionally, the following legacy authentication endpoints can also allow authentication in the top level realm.

  • /UI/Login
  • /authservice
  • /identity/authenticate
  • /cdcservlet (removed in AM 7)
  • /SSORedirect

Sample proxy configuration

HaProxy Whitelist style (recommended)

This configuration permits (whitelists) only the endpoints that are required for the service that AM performs. In this example, AM is only required to expose endpoints required for authentication and there is one /customers realm. In addition, query strings that allow navigation to the top level realm are denied.

   acl xui path_beg /am/XUI
   acl legacy_ui_login path /am/UI/Login
   acl legacy_ui_logout path /am/UI/Logout

   acl authN path /am/json/realms/root/realms/customers/authenticate

   acl authZ path /am/oauth2/realms/root/realms/customers/authorize
   acl access_token path /am/oauth2/realms/root/realms/customers/access_token
   acl userinfo path /am/oauth2/realms/root/realms/customers/userinfo
   acl endSession path /am/oauth2/realms/root/realms/customers/connect/endSession

   acl jsonsessions path /am/json/realms/root/realms/customers/sessions
   acl jsonusers path_beg /am/json/realms/root/realms/customers/users
   acl jsonserverinfo path /am/json/realms/root/realms/customers/serverinfo/*
   acl jsonsessionstop path /am/json/sessions
   acl jsonuserstop path /am/json/users

   acl realmNav query -m sub "realm="
   acl rootRealmQueries query,url_dec -m reg -i (realm=\/($|&)|(authIndexValue|module)=Application)

   http-request allow if !acl_am
   http-request allow if authN !rootRealmQueries
   http-request allow if authZ
   http-request allow if access_token
   http-request allow if userinfo
   http-request allow if endSession
   http-request allow if jsonusers #METH_GET
   http-request allow if jsonuserstop
   http-request allow if jsonsessions
   http-request allow if jsonsessionstop
   http-request allow if jsonserverinfo
   http-request allow if xui
   http-request allow if legacy_ui_login realmNav !rootRealmQueries
   http-request allow if legacy_ui_logout

   http-request deny

HaProxy Blacklist style (not recommended)

This configuration denies endpoints and query strings that can be used to authenticate against the top level realm (blacklist approach). This approach does not follow the principal of least privilege; it therefore carries the risk of exposing endpoints that may allow an attacker to take advantage of the service.

   acl rootAuthNpaths path_reg -i \/UI\/Login$|(\/json|\/realms\/root)(\/authenticate$)
   acl subAuthNpaths path_reg -i \/json\/((.*)|\/)authenticate
   acl rootRealmQueries query,url_dec -m reg -i (realm=\/($|&)|(authIndexValue|module)=Application)
   acl realmNav query -m sub "realm="
   acl legacyEndpoints path_reg -i (\/am\/(sessionservice|profileservice|policyservice|namingservice|authservice|notificationservice))
   http-request allow if !acl_am
   http-request deny if rootAuthNpaths !realmNav
   http-request deny if rootAuthNpaths rootRealmQueries
   http-request deny if subAuthNpaths rootRealmQueries
   http-request deny if legacyEndpoints

See Also

How do I understand what privileges apply to amAdmin and delegated administrators in AM/OpenAM (All versions)?

Installing and configuring AM/OpenAM

Installation Guide

Deployment Planning Guide

Related Training


Related Issue Tracker IDs


Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.