Solutions
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 Identity Cloud or AM (All versions)

Last updated Sep 22, 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 Identity Cloud or AM using a basic authorization header. You may see this in Identity Cloud; 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.


Symptoms

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 AM 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(AgentsRepo.java:1100) ...

Recent Changes

Deployed Identity Cloud.

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.

Causes

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). This also applies to Identity Cloud.

You will see this error in different versions as follows:

  • Identity Cloud; 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.
  • Pre-AM 6.5: this error indicates that the client ID and/or secret are URL encoded (which is not supported in earlier versions).

Solution

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

Identity Cloud; 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 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 Identity Cloud and 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

Authenticating Clients Using Authorization Headers

Related Training

N/A

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 Trademarks Copyright © 2021 ForgeRock, all rights reserved.