Authentication of REST API sessions

When you start a REST API session, you use the POST method to access the login resource of the switch and pass the username and password information as data. Ensure that HTTPS is configured to use port 443. HTTPS requests to port 80 are redirected to port 443.

If the credentials are accepted, your authenticated session is started for that username, and the switch returns a cookie containing encoded session information.

In subsequent calls to the API—including to the logout resource—you must pass the session cookie back to the switch.

The same session cookie is shared across browser tabs and, depending on the browser, multiple browser windows. However, the same session cookie is not shared across devices and scripts. For example, if a user logs into the Web UI from a laptop, again with a tablet, and then uses the same user name in a curl command, that user has three concurrent client sessions.

NOTE:

The number of concurrent HTTPS sessions per client and per switch are limited. Ensure that you log out of HTTP sessions when you are finished using them.

Authentication through methods other than the session cookie, such as OAuth or certificates, is not supported. The server uses self-signed certificates.

The procedure to pass the session cookie back and forth from the switch depends on how you access the REST API.

For example:

  • If you log in to the REST API using the ArubaOS-CX REST API Reference or using the Web UI and open the API Reference in another browser tab, the browser handles the session cookie for you. You do not have to save or otherwise manage the session cookie.

  • If you access the REST API using another method, such as the curl tool, you must do the following:

    • Save the session cookie returned from the login request.

    • Pass that saved cookie to the switch with every subsequent request you make to the REST API.

    IMPORTANT:

    Although it is possible to pass the user name and password information as a query string in the login URL, browser logs or tools outside the switch might save the accessed URL in cleartext in log entries. Instead, Hewlett Packard Enterprise recommends that you pass the credential information as data when using programs such as curl to log in to the switch.

    In the following examples, the workstation is running a Linux-based operating system and curl version 7.35 is installed.

    • Example of logging in and obtaining the session cookie, and storing that cookie in the file /tmp/auth_cookie on your local workstation:

      $ curl --noproxy 192.0.2.5 -k -X POST \
      -c /tmp/auth_cookie \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      "https://192.0.2.5:443/rest/v1/login" \
      --data 'username=admin&password=admin'
    • Example of passing using the -b curl command option to pass the cookie back to the switch:

      $ curl -k -X GET -b /tmp/auth_cookie \
      --header 'Content-Type:application/json' \
      --header 'Accept: application/json' \
      "https://192.0.2.5/rest/v1/system"
    • Example of logging out at the end of the session:

      $ curl -k -X POST -b /tmp/auth_cookie \
      --header 'Content-Type:application/json' \
      --header 'Accept: application/json' \
      "https://192.0.2.5/rest/v1/logout"