Solutions

Authentication fails in OpenAM 12.0.0, 12.0.1, 12.0.2, 12.0.3 and 13.0 if username or password has non-English characters in a REST call

Last updated Jul 9, 2018

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.


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 12.0.4, or 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. 

See Also

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

Authentication and Single Sign-On Guide › About the REST API › Authentication and Logout

Related Training

N/A

Related Issue Tracker IDs

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



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...