Token-Based Authentication

Language:

Oracle ILOM supports Token-Based Authentication as an alternative REST API client authentication method. This method might offer some performance improvement when a rapid succession of multiple requests are targeting a single Oracle ILOM instance. When using this method, the HTTP request includes a unique token in the X-REST-Token header to validate the user's identity for each request. For example:

X-Rest-Token:<unique_token>

Where "unique_token" represents a signed token generated by the API, which is then used by the server to validate the user's identity. After a user's identity is successfully validated, the user remains logged in until the token is no longer needed or it expires.

Note - Tokens are signed with a secret algorithm to protect against manipulation. To further protect the token from manipulation, an SSL certificate must be properly configured in Oracle ILOM. For configuration details, see Improve Security by Using a Trusted SSL Certificate and Private Key in Oracle ILOM Security Guide For Firmware Releases 3.x and 4.x

To better understand the process for generating a token and including the token in subsequent requests, see the following:

A user requests a token from the REST API by issuing a POST request to the /rest/v<version>/login resource

Syntax:
```
POST /rest/v1/login HTTP/1.1
Authorization: BASIC <Base64 encoding of username:password>
Accept: application/json
```
The server validates the user's credentials and returns the X-Rest-Token in the response to the POST request.

Example response:
```
{
 X-Rest-Token: LBiDHbTnrGeDJrLSDGaisLXIQMfVjo
}
```
The user passes the token in all subsequent requests within the Oracle ILOM REST API specific "X-Rest-Token" header.

Syntax:
```
<GET|POST|PATCH|DELETE> <Resource_Path> HTTP/1.1
X-Rest-Token: <token string>
```
Subsequent request example:
```
GET /System HTTP/1.1
X-Rest-Token: LBiDHbTnrGeDJrLSDGaisLXIQMfVjo
Accept: application/json
```
The server validates and matches the token in each subsequent request, authenticating the user for the given request.

Note - The requested operation only proceeds if the server is able to validate and match the algorithm of the token. If the server is unable to verify the token, the server would respond with a 401 unauthorized message indicating that the request could not be processed as authorization could not be verified.
The token is destroyed when one of the following occurs:
- Token expires after 15 minutes of inactivity.
  
  -or-
- The user logs out.
  
  Syntax:
```
POST /rest/v1/logout HTTP/1.1
X-Rest-Token: <token string>
```