Skip to content
Guides
/
Redfish concepts
/
Authentication and sessions

Redfish authentication and sessions

If you perform an HTTP operation on any other resource than the root /redfish/v1/ resource, you will receive an HTTP 401 Unauthorized error indicating that you don’t have the authentication needed to access the resource.

The following example shows the error displayed on a GET /redfish/v1/Systems/ request when no authentication is attempted:

curl --include --insecure     \
     --location https://{IP}/redfish/v1/Systems/
TIP

HPE implements a Two Factor Authentication OEM extension in iLO firmware.

Basic authentication

The Redfish API allows you to use HTTP Basic Authentication with a valid Management Controller user name and password. The following example retrieves the /redfish/v1/Systems/ URI using cURL (with response headers), the HPE Redfish Python library and the DMTF Redfish Python library.

Warning

The DMTF Redfish Python library and the HPE Redfish Python library cannot co-exist in the same Python environment. You should uninstall one before installing the other one.

curl --include --insecure     \
     --user username:password \
     --location https://{IP}/redfish/v1/Systems/
NOTE

cURL does not need a specific logout operation to delete the session opened in the Redfish service. However, you should always make sure Python or PowerShell scripts disconnect completely from the remote Management Controller. Management Controllers have a low limit of simultaneous connections. Reaching this limit prevents other connections.

Session authentication

For complex multi-resource operations, you should log in and establish a session in the Redfish service session manager object at the documented URI /redfish/v1/SessionService/Sessions. To create such a session, POST a JSON object to the session manager.

If the session is created successfully, you receive an HTTP 201 (Created) response from the Management Controller. There will be also two important HTTP response headers.

  • X-Auth-Token Your session key (token). This is a unique string for your login session. It must be included as a header in all subsequent HTTP operations during the session lifetime.

  • Location The URI of the newly created session resource. The Management Controller allocates a new session resource describing your session. This is the URI that has to be DELETEd in order to log out.

Tips

It is a good practice to save the Location URI of the newly created session as well as the X-Auth-Token. This is your unique session information and will be needed later to issue other requests and to log out. High level Redfish libraries (i.e. HPE and DMTF Python Redfish libraries) save these two properties automatically in the Redfish object respectively at REDFISH_OBJ.session_location and REDFISH_OBJ.session_key.

The following example creates a Redfish session using cURL, the DMTF Redfish Python Library and the HPE Python Library.

Warning

The DMTF and the HPE Python Redfish libraries cannot co-exist in the same Python environment. They contain identical classes names with different methods.

# The following Bash command creates a Redfish session and populates
# the $TokenAndUrl array with the Session Token and the Location URL.
TokenAndUrl=$(curl --silent --location --insecure --include \
              --request POST  --header 'Content-Type: application/json' \
              --data '@/tmp/data.json' \
              "https://${bmc_ip}/redfish/v1/SessionService/Sessions/" | \
              awk  '/^Location/ || /^X-Auth-Token/ {print $NF}' | \
              sort | tr '\r' ' ')

# content of the data.json data file:
cat data.json
    {
      "UserName": "<your username>", 
      "Password": "<your password>"
    }

Examples of headers and body responses of a successful session creation using the Python scripts of the above example:

Cache-Control: no-cache
Connection: keep-alive
Content-length: 163
Content-type: application/json; charset=utf-8
Date: Tue, 14 Jun 2016 22:23:39 GMT
ETag: W/"C84E3EA9"
Link: </redfish/v1/SessionService/Sessions/{item}/>; rel=self
Location: https://{IP-BMC}/redfish/v1/SessionService/Sessions/{item}/
OData-Version: 4.0
Server: HPE-iLO-Server/1.30
X-Auth-Token: 1b6cd3e49f2ffbe54347112d7315d8fd
X-Frame-Options: sameorigin
X_HP-CHRP-Service-Version: 1.0.3

Session management

This section explains how to manually use the session location and the session key (token) with low level Redfish clients (ex: Postman, cURL). Higher level Redfish clients (iLOrest, PowerShell Cmdlets, Python scripts using Redfish libraries) should not require such manual session management.

Using a session

To use a newly created session, simply include the X-Auth-Token header with its all Redfish requests. The left part of the following example creates a session and saves the token and the session location URL in an array. The middle part of the example includes the X-Auth-Token header and its value and retrieves the properties of the just created session location (${TokenAndUrl[1]}). The right part shows the response body of an iLO 6 Redfish service.

# The following Bash command creates a Redfish session and populates
# the $TokenAndUrl array with the Session Token and the Location URL.
TokenAndUrl=( $(curl --silent --location --insecure --include \
              --request POST  --header 'Content-Type: application/json' \
              --data '@/tmp/data.json' \
              "https://${bmc_ip}/redfish/v1/SessionService/Sessions/" | \
              awk  '/^Location/ || /^X-Auth-Token/ {print $NF}' | \
              sort | tr  '\r' ' '))

# content of the data.json data file:
cat data.json
    {
      "UserName": "admin", 
      "Password": "<admin password>"
    }

Disconnect a session

Redfish services supports a limited number of simultaneous user sessions. If you do not properly log out from a session and open other sessions, you may reach this limit and will locked out until an unused session expires. To limit that risk, it is good practice to delete the current session when finished working with it.

To disconnect a session, send a DELETE request to the session location (/redfish/v1/SessionService/Sessions/{item}). In the following example user Administrator retrieves the session collection of an iLO 6 Redfish service and disconnect the session of user student.

GET /redfish/v1/SessionService/Sessions/
TIP

If you failed to save your session location and need to delete your own session, the HPE iLO Redfish service implements the MySession link in the Oem/Hpe extension of the Session Collection URI (/redfish/v1/SessionService/Sessions). It provides as well the MySession Boolean property in the Oem extension of the session members.

You can use this information to identify your own session location and disconnect it safely using a DELETE operation.

Certificate authentication

Some Redfish services like the HPE iLO Redfish service offer the possibility to authenticate users with an X509 certificate instead of username/password credentials. The following steps are required to benefit from this HPE added value feature on iLO based servers. Hints and pointers are provided for performing them via the iLO GUI or Redfish.

  • An "iLO Advanced" license is required for this feature (iLO GUI: Administration --> Licensing)

    The following example shows the generic GET request to retrieve the detail of an HPE iLO license. It shows as well an iLOrest sequence to retrieve the iLO license type using two methods and the corresponding responses.

    TIP

    Refer to the Odata query options section to learn more about the ?only option mentioned in the following generic GET request.

    GET /redfish/v1/Managers/1/LicenseService/?only

    The following example shows how to upload an HPE iLO license with a generic POST request (and associated body), an iLOrest sequence and then a cURL request.

    POST /redfish/v1/Managers/1/LicenseService/
BODY:
{
"LicenseKey": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
}

  • Configure NTP Server(s) (iLO GUI: iLO [Dedicated|Shared] Network Port --> SNTP)

  • Verify the date and time is accurate (iLO GUI: Information --> iLO Overview - Main pane: iLO - iLO Date/Time)

  • If not already done, generate an SSL iLO Certificate Signing Request (CSR), have a trusted root Certificate Authority (CA) sign it and import the signed SSL certificate in iLO (iLO GUI: Security --> SSL Certificate --> Customize Certificate --> Import Certificate)

  • Enable "CAC/Smartcard Authentication" (iLO GUI: Security --> CAC/SmartCard)

    The following example shows a generic PATCH request and the corresponding iLOrest sequence to enable the "CAC/Smartcard Authentication" of an HPE iLO 6.

    PATCH /redfish/v1/Managers/1/SecurityService/CertificateAuthentication/
BODY: {"CertificateLoginEnabled": true}

  • Create an iLO user (iLO GUI: Administration --> User Administration ; Click on the New button)

  • Generate a signed certificate for the user created in the previous step (generate private key and CSR. Get CSR signed by trusted root CA).

    The following example provides hints to generate a user CSR (and associated private key) and sign it with a local self-signed Certificate Authority.

    Warning

    For obvious security reasons it is not recommended to sign CSRs and produce certificates with a self-signed Certificate Authority.

    # This is a light example to generate a private key and
# Certificate Signing Request (CSR) for user student.
u=student
openssl req -new -newkey rsa:2048 -nodes -keyout ${u}.key -out ${u}.csr

  • Map the just signed user certificate with user in iLO (GUI: Security --> Certificate Mappings --> Authorized Certificates ; select new user --> Authorize New Certificate --> Import Certificate)

    TIP

    X509 certificate files contain lines of ASCII characters separated by the LineFeed (LF) or CarriageReturn-LineFeed (CR-LF) invisible characters. Those characters are not valid in Redfish POST actions and must be translated into respectively: \n and \r\n. You can use the following commands to convert X509 files with multiple lines into a suitable JSON body.

    sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' certfile.crt > certfile.txt

# Explanation:
# :a Creates a label
# N Joins current line and next one
# $!ba If we are not at last line, perform the following search/replace pattern
# \r{0,1} if \r is present or not

    The following example presents the generic POST request to map an iLO user with a signed certificate.

    POST: /redfish/v1/AccountService/UserCertificateMapping
BODY: 
{
    "UserName": "student",
    "Fingerprint": "-----BEGIN CERTIFICATE-----\nMIIDoTCCAokCAQcwDQYJKoZIhvcNAQELBQAwgZYxCzAJBgNVBAYTAkZSMSMwIQYD\nVQQIDBpQcm92ZW5jZS1BbHBlcy1Db3RlIGQnQXp1cjEZMBcGA1UEBwwQU29waGlh\nLUFudGlwb2xpczEMMAoGA1UECgwDSFBFMRAwDgYDVQQLDAdDb21wdXRlMScwJQYD\nVQQDDB50b3lib3guZXRjLmZyLmNvbW0uaHBlY29ycC5uZXQwHhcNMjEwOTE1MTI0\nMDAwWhcNMzEwOTEzMTI0MDAwWjCBlTELMAkGA1UEBhMCRlIxEjAQBgNVBAgMCVJl\nZ2lvblN1ZDEZMBcGA1UEB.....55Ja8g\n-----END CERTIFICATE-----\n\n"
}

  • Import the trusted CA certificate used to sign the just created iLO user certificate (iLO GUI: Security --> CAC-SmartCard --> Import Trusted CA Certificates)

    The following example provides the generic POST request and the corresponding iLOrest sequence to upload a trused CA certificate used to sign the certificed iLO user created earlier.

    POST /redfish/v1/Managers/1/SecurityService/CertificateAuthentication/Actions/HpeCertAuth.ImportCACertificate/
BODY (truncated): {"Action": "HpeCertAuth.ImportCACertificate", "Certificate": "-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIQMYguQIQAZI5POAgAEjlMDzANBgkqhkiG9w0BAQsFADA8\nMRMwEQYKCZImiZPyLGQBGRYDbGFiMRI wEAYKCZImiZPyLGQBGRYCbGoxET  .....l4u5\n4WuYIn7HHDxiCCQExkLV\n-----END CERTIFICATE-----\n"}

Once the above steps have been performed, it is possible to log into the remote iLO as certified user student using iLOrest or a Python script as shown in the following example.

# You can omit the --userpassphrase parameter if the --userkey file is not protected.
ilorest login ilo-hst345g11-9 --usercert student.crt --userkey student.key
--userpassphrase "passphrase"
# The following command returns MySession URI to proof that user
"student" is logged in.
ilorest get --json   | jq -r '.Oem.Hpe.Links.MySession'
ilorest logout
NOTE

The DMTF Python Redfish library only provides basic and session authentication methods.

Previous page
Next page