Solutions
ForgeRock Identity Platform
Does not apply to Identity Cloud

400 response with json/users endpoint in AM (All versions) if username contains forward slash

Last updated Apr 13, 2021

The purpose of this article is to provide assistance if you receive a 400 Bad Request response when the username contains a URL encoded forward slash (%2F) and you make a REST call to the json/users endpoint. You will see a 404 Not Found response instead if the forward slash is not encoded. This issue only occurs if AM is deployed in the Apache Tomcat™ web application container.


Symptoms

URL Encoded forward slash

You see a 400 Bad Request message when you make a call to the json/users endpoint if the username contains a URL encoded forward slash (%2F). The exact message will vary depending on what you are trying to do, but typically you will see:

{"code" : 400,"reason" : "Bad Request","message" : "Resource name '/users/user/1' contains empty path elements"}

If you are trying to change the user's password, for example using a URL such as: http://host1.example.com:8080/openam/json/users/user%2F1?_action=changePassword, you will see the following message instead:

{"code":400,"reason":"Bad Request","message":"Invalid Password"}

Non-encoded forward slash

If you attempt to make a call to the json/users endpoint with a username that contains a forward slash (not encoded), you will see the following response:

{"code":404,"reason":"Not Found"}

Recent Changes

N/A

Causes

Tomcat only accepts path delimiters (/ and \) if they are URL encoded and the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH property is set to true. This property is set to false by default, which means these path delimiters are not permitted.

Solution

This issue can be resolved as follows:

  1. Add the following line to the setenv.sh file: export CATALINA_OPTS="‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
  2. Restart the web container.

You will now be able to make calls to the json/users endpoint with a username that contains a forward slash providing it is URL encoded (%2F).

Caution

It is strongly recommended that you do not set this option when running AM in production as it introduces a security risk. When Tomcat is deployed behind a reverse proxy, this setting can expose you to a directory traversal security vulnerability (CVE-2007-0450); see Apache Tomcat 6.x Vulnerabilities for further information. Therefore, it is preferable to avoid usernames that contain slashes. If this is not possible, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM (All versions)? for further information.

See Also

400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM (All versions)

How do I change what characters are permitted in user names in AM (All versions) for authentication purposes?

FAQ: REST API in AM

Using the REST API in AM

Related Training

N/A

Related Issue Tracker IDs

N/A


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