Identity Cloud

Authentication over REST

To authenticate using REST, send an HTTP POST request to the json/authenticate endpoint. You must specify the realm hierarchy. Prefix each realm in the hierarchy with the realms/ keyword; for example, /realms/root/realms/alpha.

The /json/authenticate endpoint does not support the CRUDPAQ verbs and therefore does not technically satisfy REST architectural requirements. The term REST-like describes this endpoint better than REST.

By default, you authenticate using the default authentication service configured for the realm. To override the default, specify authentication services and other options in the REST request.

AM supports simple authentication methods, such as providing a username and password, and complex authentication journeys that might involve nested journey evaluations and multi-factor authentication.

For authentication journeys where providing a username and password is sufficient, you can log in to AM by providing these credentials in headers. The following command logs in user bjensen with password Secret12!:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…​TU3OQ*",
    "successUrl": "/enduser/?realm=/alpha",
    "realm":"/alpha"
}

This zero page login mechanism works only for username/password authentication.

Note that the POST body is empty. If you submit a POST body, AM interprets the body as a continuation of an existing authentication attempt that uses a supported callback mechanism. Callback mechanisms support complex authentication journeys, such as those where the user must be redirected to a third party or interact with a device as part of multi-factor authentication.

After successful authentication, AM returns a tokenId that applications can present as a cookie value for other operations that require authentication. The tokenId is known as the session token. For information about how applications can use session tokens, refer to Session tokens after authentication.

For more information about how to authenticate, log out, and use AM session tokens, see Authenticate using REST.

Copyright © 2010-2022 ForgeRock, all rights reserved.