--- title: Authenticate over REST description: AM provides the /json/authenticate endpoint for authentication, and the /json/sessions endpoint for managing sessions and logging out. component: pingam version: 8.1 page_id: pingam:am-authentication:authn-rest canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/authn-rest.html keywords: ["Authentication", "REST API"] section_ids: login-using-REST: Log in to AM over REST authenticate-UTF-8: UTF-8 usernames providing-auth-information: Authenticate to specific authentication trees login-callbacks: Return callback information to AM --- # Authenticate over REST AM provides the `/json/authenticate` endpoint for authentication, and the `/json/sessions` endpoint for managing sessions and logging out. The following table summarizes authentication operations you can perform using REST: | Task | Resources | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Authenticate to AM**Authenticating to AM means logging in to a specific realm and receiving a session token from AM. Add parameters to the authentication request to provide AM with more information about how you want to authenticate. | [Log in to AM over REST](#login-using-REST) | | **Use the session token**AM provides you with a session token after authenticating to a realm. Use this token in subsequent calls to AM. For example, when using REST calls to create, modify, or delete configuration objects. | [Session token after authentication](rest-using-ssotokens.html) | | **Log out of AM**Log out your users by sending a `logout` action to the `/json/sessions` endpoint. | [Log out of AM over REST](logout-using-rest.html) | | **Invalidate sessions**Obtain all the sessions for a given user and invalidate them to ensure they are logged out of AM. | [Invalidate sessions](../am-sessions/managing-sessions-REST.html#invalidate-sessions) | ## Log in to AM over REST To authenticate to AM using REST, make an HTTP POST request to the `json/authenticate` endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the `realms/` keyword. For example, `/realms/root/realms/customers/realms/europe`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `/json/authenticate` endpoint doesn't support the CRUDPAQ verbs and therefore doesn't technically satisfy REST architectural requirements. The term *REST-like* describes this endpoint better than *REST*. | AM uses the default authentication service configured for the realm. You can override the default by [specifying authentication services](#providing-auth-information) and other options in the REST request. AM provides both simple authentication methods, such as providing username and password, and complex authentication journeys that may involve a tree with inner tree evaluation and/or multi-factor authentication. For authentication journeys where providing a username and password is enough, you can log in to AM using a `curl` command similar to the following: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…​TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" } ``` The username and password are sent in headers. This zero page login mechanism works only for name/password authentication. Note that the POST body is empty; otherwise, AM interprets the body as a continuation of an existing authentication attempt, one that uses a supported [callback](#login-callbacks) mechanism. AM implements callback mechanisms to support complex authentication journeys, such as those where the user needs to be redirected to a third party or interact with a device as part of multi-factor authentication. After a successful authentication, AM returns a `tokenId` object that applications can present as a cookie value for other operations that require authentication. This object is known as the session token. Find information about how applications can use the session token in [Session token after authentication](rest-using-ssotokens.html). If `HttpOnly` cookies are enabled and a client calls the `/json/authenticate` endpoint with a valid SSO token, AM returns the `tokenId` field **empty**. For example: ```json { "tokenId":"", "successUrl":"/am/console", "realm":"/alpha" } ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can request AM to authenticate a user without providing them a session by using the `noSession` parameter. Learn more in [Authenticate endpoints](authenticate-endpoint-parameters.html). | ### UTF-8 usernames To use UTF-8 usernames and passwords in calls to the `/json/authenticate` endpoint, base64-encode the string, and wrap the string as described in [RFC 2047](https://www.rfc-editor.org/info/rfc2047): ``` encoded-word = "=?" charset "?" encoding "?" encoded-text "?=" ``` For example, to authenticate using a UTF-8 username, such as `ɗëɱø`, perform the following steps: 1. Encode the string in base64 format: `yZfDq8mxw7g=`. 2. Wrap the base64-encoded string as per RFC 2047: `=?UTF-8?B?yZfDq8mxw7g=?=`. 3. Use the result in the `X-OpenAM-Username` header passed to the authentication endpoint as follows: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: =?UTF-8?B?yZfDq8mxw7g=?=" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' { "tokenId": "AQIC5w…​NTcy*", "successUrl": "/am/console", "realm":"/alpha" } ``` ## Authenticate to specific authentication trees You can provide AM with additional information about how you are authenticating. For example, you can specify the authentication tree you want to use, or request from AM a list of the authentication services that would satisfy a particular authentication condition. The following example shows how to specify the `Example` tree by using the `authIndexType` and `authIndexValue` query string parameters: ```bash $ curl \ --request POST \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Example' ``` You can exchange `Example` with any other tree. Find information about using the `authIndexType` parameter to authenticate to specific services in [Authenticate endpoints](authenticate-endpoint-parameters.html). ## Return callback information to AM The `/json/authenticate` endpoint supports callback mechanisms to perform complex authentication journeys. Whenever AM needs to return or request information, it will return a JSON object with the authentication step, the authentication identifier, and the related callbacks. The following types of callbacks are available: * Read-only callbacks AM uses read-only callbacks to provide information to the user, such as text messages or the amount of time that the user needs to wait before continuing their authentication journey. * Interactive callbacks Interactive callbacks request information from the user. Use these, for example, to request a user's username and password or to request that the user select between options. * Backchannel callbacks AM uses backchannel callbacks when it needs to access additional information from the user's request. For example, when it requires a particular header or a certificate. Read-only and interactive callbacks have an array of `output` elements suitable for displaying to the end user. The JSON returned in interactive callbacks also contains an array of `input` elements that must be completed and returned to AM. For example: ```json "output": [ { "name": "prompt", "value": " User Name: " } ], "input": [ { "name": "IDToken1", "value": "" } ] ``` The value of some interactive callbacks can be returned as headers, such as the `X-OpenAM-Username` and `X-OpenAM-Password` headers, but most of them must be returned in JSON as a response to the request. Depending on how complex the authentication journey is, AM may return several callbacks sequentially. Each must be completed and returned to AM until authentication is successful. The following example shows a request for authentication, and AM's response of the `NameCallback` and `PasswordCallback` callbacks: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' { "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…​", (1) "template": "", "stage": "DataStore1", "callbacks": [ { "type": "NameCallback", (2) "output": [ (3) { "name": "prompt", "value": " User Name: " } ], "input": [ (4) { "name": "IDToken1", "value": "" } ] }, { "type": "PasswordCallback", "output": [ { "name": "prompt", "value": " Password: " } ], "input": [ { "name": "IDToken2", "value": "" } ] } ] } ``` | | | | ----- | ------------------------------------------------------------------------------------------------------------ | | **1** | The JWT that uniquely identifies the authentication context to AM. | | **2** | The type of callback. It must be listed under [Supported callbacks](callbacks-supported.html). | | **3** | The information AM offers about this callback. Usually, this information is displayed to the user in the UI. | | **4** | The information AM is requesting. The user must fill the `"value": ""` object with the required information. | To respond to a callback, send back the whole JSON object with the missing values filled. The following example shows how to respond to the `NameCallback` and `PasswordCallback` callbacks, with the `bjensen` and `Ch4ng31t` values filled: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ --data '{ "authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…​", "template":"", "stage":"DataStore1", "callbacks":[ { "type":"NameCallback", "output":[ { "name":"prompt", "value":" User Name: " } ], "input":[ { "name":"IDToken1", "value":"bjensen" } ] }, { "type":"PasswordCallback", "output":[ { "name":"prompt", "value":" Password: " } ], "input":[ { "name":"IDToken2", "value":"Ch4ng31t" } ] } ] }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…​TU3OQ*", "successUrl": "/am/console", "realm":"/alpha" } ``` On complex authentication journeys, AM may send several callbacks sequentially. Each must be completed and returned to AM until authentication is successful. Find information about the callbacks AM can return in [Supported callbacks](callbacks-supported.html).