ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 18, 2023

The purpose of this article is to provide assistance if you receive a 400 Bad Request response when adding or updating resources via REST or Amster when the resource name contains URL encoded forward slashes. This issue only occurs if AM is deployed in the Apache Tomcat™ web application container and affects resources such as SAML2 entities, policy names and application names.

1 reader recommends this article


You see a 400 Bad Request response when you make a PUT call (REST) or a create call (Amster) with a resource name that contains URL encoded forward slashes:

{"code":400,"reason":"Bad Request"}

For example:

  • REST - you will see this response when adding a SAML2 entity via REST: $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ "metadata": "<?xml ...", "entityConfig": "<?xml ...", }' '' < HTTP/1.1 400 Bad Request < Server: Apache-Coyote/1.1 < Content-Length: 0 < Connection: close
  • Amster - you will see this response when adding a SAML2 entity via Amster: $ create Saml2Entity --realm / --id --body '{"metadata": "<?xml ...","entityConfig": "<?xml ..."}' [main] ERROR - Unhandled client error: [Status: 400 Bad Request] Failed to execute the 'create' command. 400 Bad Request

Recent Changes



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.

See Prepare Apache Tomcat and Tomcat Documentation for further information.


This issue can be resolved by setting the property using the CATALINA_OPTS variable either in Tomcat's startup scripts (for example, or or as system parameter.


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 resource names 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.

Startup scripts

  1. Add the following line to the startup script, for example the file: export CATALINA_OPTS="‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
  2. Restart the web container.

System parameter

  • On Linux® and Unix® systems: $ export CATALINA_OPTS= \ "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true" $
  • On Microsoft® Windows® systems: C:\> set CATALINA_OPTS= ^ "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true" C:\> startup.bat

You will now be able to add resources via REST or Amster providing you URL encode (%2F) any forward slashes in the resource name, for example:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -v -d '{ "metadata": "<?xml ...", "entityConfig": "<?xml ...", }' '' * Trying * Connected to ( port 8080 (#0) > PUT /am/json/realms/root/realm-config/federation/entityproviders/saml2/ HTTP/1.1 ... < HTTP/1.1 200 OK ... < {"_id":"","_rev":"1553138821","metadata":"<?xml version=….”,”entityConfig":"<?xml version=“…, ”* Connection #0 to host left intact _type":{"_id":"saml2","name":"Entity Descriptor ","collection":true}}

See Also

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


Using the REST API in AM

Using Amster in AM

Related Training


Related Issue Tracker IDs


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