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

Last updated Nov 2, 2020

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/OpenAM is deployed in the Apache Tomcat™ web application container and affects resources such as SAML2 entities, policy names and application names.


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 Installation Guide › Preparing 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/OpenAM 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/OpenAM (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 /openam/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/OpenAM (All versions) if username contains forward slash


Using the REST API in AM/OpenAM

Using Amster in AM

Related Training


Related Issue Tracker IDs

OPENAM-11798 (REST interface for SAML2 config does not accept entity IDs that are URLs)

Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.