ForgeRock Identity Platform
ForgeRock Identity Cloud

URLDecoder: Illegal hex characters in escape (%) pattern or Client authentication failed error when requesting an OAuth2 access token in AM (All versions)

Last updated Feb 25, 2021

The purpose of this article is to provide assistance if you receive a "URLDecoder: Illegal hex characters in escape (%) pattern" or "Client authentication failed" response when making a call to the OAuth2 access_token endpoint in AM using a basic authorization header. You may see this in AM 6.5 and later when the client ID and secret are not URL encoded, or in earlier versions when one or both of them are URL encoded.


One of the following responses is received when requesting a token from the access_token endpoint using a basic authorization header:

  • invalid_request: {    "error_description": "URLDecoder: Illegal hex characters in escape (%) pattern - For input string: \"+\"",     "error": "invalid_request" }
  • invalid_client: {   "error_description": "Client authentication failed",    "error": "invalid_client" }

You may see an error similar to the following in the Authentication debug log when this happens:

Invalid Password : failedUserId clientID amAuth:10/09/2019 04:09:56:646 PM BST: Thread[http-bio-8080-exec-2,5,main]: TransactionId[af1f9187-1d99-4240-8208-7db8bd3cb128-86180] Invalid Password : Exception com.sun.identity.authentication.spi.InvalidPasswordException: invalid password   at com.sun.identity.idm.plugins.internal.AgentsRepo.authenticate( ...

Recent Changes

Upgraded to AM 6.5 or later.

URL encoded special characters in the client ID and/or secret in the basic authorization header in pre-AM 6.5.


Changes were made in AM 6.5 to allow the client ID and secret to be URL encoded when using the basic authorization header per the standard (RFC 6749).

You will see this error in different versions as follows:

  • AM 6.5 and later: this error signifies that one or both of the client ID and secret are not URL encoded. Any special characters in both the client ID and secret must be URL encoded as of AM 6.5.
  • Pre-AM 6.5: this error indicates that the client ID and/or secret are URL encoded (which is not supported in earlier versions).


This issue can be resolved as follows depending on your AM version:

AM 6.5 and later

You should URL encode (UTF-8) any special characters in the client ID and secret before base64 encoding the string for the basic authorization header. Refer to the example process in Getting Started with REST › Authenticating to AM Using REST for further information.

Alternatively, you should remove any special characters from the client ID and secret.

See FAQ: OAuth 2.0 in AM (Q. Why don't all special characters in client IDs and secrets need URL encoding?) for further information on which special characters do need URL encoding.

Pre-AM 6.5

You should upgrade to AM 6.5 or later, which supports URL encoded client IDs and secrets; you can download this from BackStage. Alternatively, you can remove any URL encoding from the client ID and secret.

See Also

OAuth 2.0 in AM/OpenAM

OAuth 2.0 Guide › Authenticating Clients Using Authorization Headers

Related Training


Related Issue Tracker IDs

OPENAM-15454 (Section on Basic Auth on OAuth2 guide should mention URL encoding)

OPENAM-14306 (OAuth2 client secret - not all special characters require encoding)

OPENAM-13609 (Allow for URL encoded client id and secret in basic auth secured oauth endpoints)

OPENAM-11360 (OAuth2 ClientID and password URL decoded as per RFC-6749 )

Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.