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

Symptoms

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 ...", }' 'https://am.example.com:8443/am/json/realms/root/realm-config/federation/entityproviders/saml2/https%3A%2F%2Fidp.example.com%3A8443%2Fam' < 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 https%3A%2F%2Fidp.example.com%3A8443%2Fam --body '{"metadata": "<?xml ...","entityConfig": "<?xml ..."}' [main] ERROR org.forgerock.amster.org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled client error: [Status: 400 Bad Request] Failed to execute the 'create' command. 400 Bad Request

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.

See Prepare Apache Tomcat and Tomcat Documentation for further information.

Solution

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

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 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

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

System parameter

On Linux® and Unix® systems: $ export CATALINA_OPTS= \ "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true" $ startup.sh
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 ...", }' 'https://am.example.com:8443/am/json/realms/root/realm-config/federation/entityproviders/saml2/https%3A%2F%2Fidp.example.com%3A8443%2Fam' * Trying 127.0.0.1... * Connected to am.example.com (127.0.0.1) port 8080 (#0) > PUT /am/json/realms/root/realm-config/federation/entityproviders/saml2/https%3A%2F%2Fidp.example.com%3A8443%2Fam HTTP/1.1 ... < HTTP/1.1 200 OK ... < {"_id":"https://idp.example.com:8443/am","_rev":"1553138821","metadata":"<?xml version=….”,”entityConfig":"<?xml version=“…, ”* Connection #0 to host am.example.com left intact _type":{"_id":"saml2","name":"Entity Descriptor ","collection":true}}

Related Training

N/A

Related Issue Tracker IDs

N/A