Authentication fails in OpenAM 13 if username or password has non-English characters in a REST call

Last updated Jan 5, 2021

The purpose of this article is to provide assistance if you receive a 401 Unauthorized response when trying to authenticate to OpenAM using the /json/authenticate REST endpoint, and have non-English or UTF-8 characters in your username or password.

Archived

This article has been archived and is no longer maintained by ForgeRock.

Symptoms

Authenticating to OpenAM using the /json/authenticate REST endpoint fails if you have non-English or UTF-8 characters in your username or password. For example:

$ curl -X POST -H "X-OpenAM-Username: ɗëɱø" -H "X-OpenAM-Password: changeitÖ" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate

Example responses:

{"code":401,"reason":"Unauthorized","message":"Authentication Failed!!"} {"code":401,"reason":"Unauthorized","message":"Access Denied"}

The same user can authenticate to OpenAM in a browser, which proves their credentials are correct.

Recent Changes

N/A

Causes

The HTTP headers used to submit usernames and passwords in a REST call do not support any encoding, which prevents the use of non-English characters. Therefore, when non-English characters are used, the authentication call fails.

Solution

This issue can be resolved by upgrading to OpenAM 13.5 and later; you can download this version from BackStage.

You can then include UTF-8 usernames or passwords in your REST calls as base-64 encoded values as described in Authentication and Single Sign-On Guide › Authentication and Logout.

Workaround

You can authenticate using callbacks in your REST call, which are passed in the POST body rather than using headers to authenticate. This method is the same as the one used when logging in via the XUI in a browser. For example, you could use a REST call such as:

$ curl -X POST -H "Content-Type: application/json" -d '{"callbacks":[{"type":"NameCallback","input":[{"name":"IDToken1","value":"ɗëɱø"}]},{"type":"PasswordCallback","input":[{"name":"IDToken2","value":"changeitÖ"}]}]}' http://host1.example.com:8080/openam/json/authenticate

Note

This workaround is only supported for a single stage authentication process as explained in OPENAM-3335 (REST authentication inconsistency with ZPL). For example, if you have a chain where the Persistent Cookie module is SUFFICIENT followed by the DataStore module set to REQUIRED, this method will not work as the authentication process will not know which module the username and password applies to.

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3750 (REST authentication failed if unicode/utf8 login/password)