4. Authentication

4.1 Authentication Overview

To authenticate access to Redfish resources, user credentials are provided to the Redfish service through either HTTP Basic authentication or sessions. When attempting to access a resource without valid credentials or with insufficient privileges, the service returns the HTTP 401 Unauthorized or 403 Forbidden status code.

4.2 HTTP Basic Authentication

With HTTP Basic authentication, credentials are provided as a Base64-encoded string of the username and password as <USERNAME>:<PASSWORD>.This string is provided in the Authorization request header with the Basic scheme:

Authorization: Basic <Base64-encoded credentials>

For example, if the username is admin and the password is password, the following header would be used:

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

When using HTTP Basic authentication, users will need to provide this header in each request to the service. This means that the service will need to verify the username and password on every request. This can have a negative impact on timing and latency, so this method is not optimal for most circumstances when multiple requests will be issued to the service.

4.3 Sessions

Redfish sessions allow a user to exchange a username and password for a session token, and the session token is used in susbsequent requests. This is a more optimal approach when performing a multiple operations so that the username and password only need to be verified by the service on the initial session creation request.

To create a session, perform a POST operation on the /redfish/v1/SessionService/Sessions URI:

curl -k -D - -X POST 'https://<REDFISH-HOST>/redfish/v1/SessionService/Sessions' \
    -H "Content-Type: application/json" -d '{ "UserName": "<USERNAME>", "Password": "<PASSWORD>" }'

The response from the service, if successful, will contain the session ID and session token in the Location and X-Auth-Token response headers respectively. These values need to be saved for future operations with the session.

The following is an example response where a session was successfully created:

HTTP/1.1 201 Created
Location: /redfish/v1/SessionService/Sessions/<SESSION-ID>
X-Auth-Token: <SESSION-TOKEN>
Content-Type: application/json
{
  "@odata.type": "#Session.v0_0_1.Session",
  "@odata.id": "/redfish/v1/SessionService/Sessions/<SESSION-ID>",
  "Id": "1",
  "Name": "User Session",
  "UserName": "<USERNAME>",
  "Password": null,
  "RoleId": "Administrator"
}

In subsequent requests to the service, provide the X-Auth-Token request header with the session token received in the response from the session creation. The following example shows a request to the URI /redfish/v1/Chassis/1U with the X-Auth-Token header provided:

curl -k 'https://<REDFISH-HOST>/redfish/v1/Chassis/1U' -H 'X-Auth-Token: <SESSION-TOKEN>'

When the session is no longer needed, perform a DELETE operation on the session URI that represents the session:

curl -k -X DELETE 'https://<REDFISH-HOST>/redfish/v1/SessionService/Sessions/<SESSION-ID>' \
    -H 'X-Auth-Token: <SESSION-TOKEN>'

If successful, the session token is invalidated. The service will reject future requests that contain the invalidated token.

Next section