How do I remove admin UI access in AM (All versions)?

Background information

The old JATO console has been removed in AM 7.

In AM 6.x, AM uses a mix of the old JATO console (Classic UI) and the new XUI JavaScript®-based administration pages, although the end user pages are all XUI-based.

The changes described in this article apply to both the XUI administrative pages and the JATO console (Classic UI).

Removing admin UI access

There are three approaches to removing admin UI access and securing AM:

• Allowlist approach - configure your load balancer or proxy with only the URLs that are allowed. An allowlist is more secure as it ensures only specific endpoints are exposed; however, you risk affecting existing behavior unless you test carefully.
• Denylist approach - create a list of URLs that should be blocked. A denylist is easier to apply to existing setups and ensure that current behavior is unaffected.
• Remove the /console directory (AM 6.x)

An allowlist on a load balancer or proxy could be used in combination with a denylist elsewhere in the infrastructure. For example, a denylist rule could be created to deny access to /json/users/amadmin, which would effectively prevent the amAdmin user from being able to login.

Allowlist approach

The recommended way of creating an allowlist is as follows:

1. Establish all use cases involving AM.
2. Test these use cases against AM servers in a load balanced pool. During testing, you can use browser developer tools such as those in Chrome™, tools such as Wireshark or the logs on a load balancer to analyze the endpoints used in each use case. This will give you a list of all endpoints used.
3. Update this list of endpoints to include any sub-realms in use.
4. Add the following endpoints to this list if you use SAML 2 functionality; these should suffice in most cases, but you should test them in your environment to be sure: saml2/jsp/<all paths> SSORedirect/<all paths> IDPSloRedirect/<all paths> Consumer/<all paths> ArtifactResolver/<all paths> IDPSloPOST/<all paths> IDPSloSoap/<all paths> idpsaehandler/<all paths>
5. Configure your load balancer or proxy to only allow this list of endpoints.

Example using HAProxy

This example demonstrates creating an allowlist in HAProxy where the following endpoints are used for the purposes of authentication and showing user components in the XUI:

This example has one sub-realm called customers, resulting in these additional endpoints:

The following shows the configuration required in HAProxy (haproxy.cfg) to block these example endpoints plus the ones identified above for SAML 2 functionality in AM 7.1 and later:

Denylist approach

The URLs listed below still provide all user functionality, such as profile changes and self-service, namely against the /users endpoint. You should be particularly careful with this endpoint (and the realm specific version) because it has specific uses. Some examples of these uses are as follows:

• GET json/realms/root/users?_queryId=* - this is used to enumerate users. It would only ever be used by an administrator.
• GET json/realms/root/users?_action=idFromSession - this is used in all login scenarios (user and admin) with the XUI.
• GET/POST/PUT json/realms/root/users/{username} - this could be used by both a user (on their username only) and an administrator, depending on the context.

The following URLs can be blocked in a proxy, web application firewall (WAF) or load balancer to prevent access to the administrative REST endpoints in AM:

• Rest Endpoints (with json/realms/root part removed):

• XUI admin UI endpoints:
  • AM 7 and later: ui-admin/*
  • AM 6.x: XUI/templates/admin/* XUI/org/forgerock/am/ui/admin/*
• JATO admin console endpoints: console/* realm/* idm/* agentconfig/* sts/* task/* service/* federation/* config/* session/*

Example method of filtering URLs using web.xml

If you are using Apache Tomcat™, you can block these endpoints by setting a <security-constraint> element in the web.xml file (located in the /path/to/tomcat/webapps/am/WEB-INF directory where AM is deployed).

The following example shows the <security-constraint> element set in the web.xml file with all the applicable AM 7 endpoints blocked, where there is one sub-realm called realm-one:

If you use this example as the basis of your changes, you must replace the realm-one realm name with a realm that you are using and add other endpoints for other realms you may have configured. If you are not using sub-realms, then you can remove these endpoints. Additionally, you should add the required XUI admin UI endpoints and the JATO admin console endpoints in AM 6.x.

Testing

The example bash script provides a means of testing these blocked URLs using repeated curl commands. This script authenticates against AM and then runs various GET calls against the list of URLs defined in endpoints.txt. It then outputs HTTP response codes (200, 400, 401, 403 etc) which indicate the type of response.

The following is an example output from the script:

With the URL filters in place, the script should return 403 for all the URLs tested, except for:

• The /json/realms/root/users endpoint
• The /console endpoint, which does a redirect (302) to /console/* that is blocked (AM 6.x).

Without any filters in place, the script would return 200 codes, except on queries where no existing object is in place to query. In that case, a 404 (not found) would be returned.

For example, a GET on the endpoint json/realms/root/realms/realm-one/policies/example-policy would return:

• 403 if it is blocked by a rule in web.xml or on a load balancer, WAF etc.
• 404 if the URL is not blocked and the policy called “example-policy” does not exist in the realm called “realm-one”.
• 200 if the URL is not blocked and the policy called “example-policy” does exist in the realm called “realm-one”.

The attached endpoints.sh script and endpoints.txt file can be used as the basis for your own testing. They have been created based on the default endpoints that need blocking in AM 7 with one sub-realm (realm-one) defined. The cli tool jq needs to be installed in order to execute this script. This can be installed using operating system package tools, such as apt-get, yum and brew.

The endpoints.sh file contains the following script, which can be used as the basis for your testing:

The endpoints.txt file contains the following URLs, which can be used as a basis for your testing:

Remove the /console directory (AM 6.x)

In AM 6.x, the /console directory contains:

• The legacy JATO admin console, responsible for configuration, federation and some parts of the realm configuration.
• The user profile and self-service pages when the XUI is disabled.

If you want the above features to be removed from your deployment, you can remove the /console directory from the /path/to/tomcat/webapps/am directory where AM is deployed.

See Also

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

AM 7 REST API endpoints

AM 6.5 REST API Endpoints

AM 6 REST API Endpoints​

Related Training

N/A

Related Issue Tracker IDs

N/A