This section explains how to create and use access tokens—by using the Qumulo Core REST API, Python SDK, and qq CLI—to authenticate external services to Qumulo Core.

In Qumulo Core 5.3.0 (and higher), you can use access tokens to let a user authenticate to the Qumulo Core REST API without having to complete repetitive login procedures.

Access tokens are long-lived. They provide an alternative to session-based authentication that the qq login command and the Qumulo Core Web UI use. They also support support authentication for services, long-lived automation processes, and programmatic REST API access that doesn’t require user input.

Prerequisites

  • PRIVILEGE_ACCESS_TOKEN_WRITE is required for creating, disabling, and deleting access tokens for all users in the system.
  • PRIVILEGE_ACCESS_TOKEN_READ is required for listing access tokens for all users in the system.

Creating and Using Access Tokens

This section explains how to create access tokens without or with an expiration time by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_WRITE is required for creating, disabling, and deleting access tokens for all users in the system.

To create an Access Token for Yourself

Run the qq auth_create_access_token command with the --self flag. For example:

$ qq auth_create_access_token --self

The qq auth_create_access_token command returns a JSON response that contains the bearer token body and the access token ID, which you can use to manage the access token.

{
  "bearer_token": "access-v1:abAcde...==",
  "id": "1234567890123456789012"
}

To Create an Access Token For a Specific User

Run the qq auth_create_access_token command and specify the user. For example:

$ qq auth_create_access_token jane

You can:

  • Specify the user as a name
  • Qualify the user by using a domain prefix, for example:
    • ad:jane
    • AD\jane
    • local:jane
  • Specify ID types, for example:
    • auth_id:1234
    • SID:S-1-1-0

To Create an Access Token with an Expiration Time

In Qumulo Core 5.3.2 (and higher), you can run the qq auth_create_access_token command and specify the expiration time. You can specify the expiration time in different formats. For example:

$ qq auth_create_access_token jane --expiration-time 'Jan 01 2023'

$ qq auth_create_access_token jane --expiration-time '01/01/2023 00:00'

When an access token’s expiration time elapses, it isn’t possible to use the token for authentication. Any attempt to use the token results in an authentication error. To continue the authentication process, you must either create a new access token or update the expiration time for your existing token.

Using Bearer Tokens for Authentication

A Qumulo Core access token returns a bearer token, an item in the Authorization HTTP header which acts as the authentication mechanism for the Qumulo Core REST API.

REST API

When you use the Qumulo Core REST API, add the bearer token to the Authorization HTTP header. For example:

Authorization: Bearer access-v1:abAcde...==

You can also add the bearer token to a curl command. For example:

$ curl https://203.0.113.0:8000/v1/session/who-am-i -H 'Authorization: Bearer access-v1:abAcde...=='

Python SDK

When you use the Qumulo Python SDK, add the bearer token to a RestClient object. For example:

from qumulo.rest_client import RestClient
from qumulo.lib.auth import Credentials
client = RestClient('203.0.113.0', 8000, Credentials('access-v1:abAcde...=='))

For more information, see the Qumulo Core Python SDK.

qq CLI

To use an access token in the qq CLI, you must use the --file flag—to specify a path for saving your credentials file in a format that the qq CLI can use—when you create the access token. For example:

$ qq auth_create_access_token jane --file ./qumulo_credentials

To use the credentials file, specify its location by using the --credentials-store flag. For example:

$ qq --credentials-store ./qumulo_credentials who_am_i

Listing Access Tokens

This section explains how to list access tokens for yourself, a specific user, or all users by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_READ is required for listing access tokens for all users in the system.

  • To list access tokens for yourself, run the qq auth_list_access_tokens command with --self flag. For example:

    $ qq auth_list_access_tokens --self

  • To list access tokens for a specific user, run the qq auth_list_access_tokens command and use the --user flag to specify a user. For example:

    $ qq auth_list_access_tokens --user jane

  • To list access tokens for all users, run the qq auth_list_access_tokens command without any additional parameters. For example:

    $ qq auth_list_access_tokens

Retrieving Metadata for Access Tokens

This section explains how to get metadata for a specific access token or all access tokens by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_READ is required for listing access tokens for all users in the system.

To Retrieve Metadata for a Specific Access Token

Run the auth_get_access_token command and specify the access token ID. For example:

$ qq auth_get_access_token 1234567890123456789012

This command returns a JSON object that lists:

  • The access token ID
  • The user that the access token represents
  • The access token's creator
  • The access token's creation time
  • The access token's expiration time
  • Whether the access token is enabled

For example:

{
  "creation_time": "2022-12-06T01:14:39.56621474Z",
  "creator": {
    "auth_id": "500",
    "domain": "LOCAL",
    "gid": null,
    "name": "admin",
    "sid": "S-1-1-12-12345678-2345678901-1234567890-500",
    "uid": null
  },
  "enabled": true,
  "expiration_time": "2023-01-01T00:00:00Z",
  "id": "1234567890123456789012",
  "user": {
    "auth_id": "1002",
    "domain": "LOCAL",
    "gid": null,
    "name": "svc",
    "sid": "S-1-1-12-12345678-2345678901-1234567890-1002",
    "uid": null
  }
}

To Retrieve Metadata for All Access Tokens

Run the qq auth_list_access_tokens command.

The auth_list_access_tokens command returns:

  • The access token ID
  • The user that the access token represents
  • The access token's creator
  • The access token's creation time
  • The access token's expiration time
  • Whether the access token is enabled

For example:

id                      user   creator  creation time
======================  =====  =======  ==============================
1234567890123456789012  svc    admin    2022-10-27T15:18:09.725513764Z
0987654321098765432109  svc    admin    2022-10-27T15:18:24.997572918Z

expiration time       enabled
====================  =======
                      True
2023-01-01T00:00:00Z  False

To filter the command’s output by user, use the --user flag and use the same format for the name as for the qq auth_create_access_token command.

Modifying the Expiration Time for an Access Token

This section explains how to modify access tokens by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_WRITE is required for creating, disabling, and deleting access tokens for all users in the system.

Run the auth_modify_access_token command and specify the access token ID and the expiration time. For example:

$ qq auth_modify_access_token 1234567890123456789012 --expiration-time 'Jan 01 2023'

When an access token’s expiration time elapses, it isn’t possible to use the token for authentication. Any attempt to use the token results in an authentication error. To continue the authentication process, you must either create a new access token or update the expiration time for your existing token.

Disabling an Access Token

To help you check your system’s security posture, Qumulo Core lets you disable an access token without deleting it. This is a good way to check for dependencies on the access token before you delete the token permanently. This section explains how to disable an access token by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_WRITE is required for creating, disabling, and deleting access tokens for all users in the system.

To disable an access token, run the qq auth_modify_access_token command, specify the access token ID, and use the -d flag. For example:

$ qq auth_modify_access_token 1234567890123456789012 -d

To enable an access token, run the qq auth_modify_access_token command, specify the access token ID, and use the -e flag. For example:

$ qq auth_modify_access_token 1234567890123456789012 -e

Deleting Access Tokens

This section explains how to delete an access token by using the qq CLI.

PRIVILEGE_ACCESS_TOKEN_WRITE is required for creating, disabling, and deleting access tokens for all users in the system.

To delete an access token, run the qq auth_delete_access_token command and specify the access token ID. For example:

$ qq auth_delete_access_token 1234567890123456789012

Best Practices for Using Qumulo Core Access Tokens

This section lists the best practices for limiting the exposure to lost credentials and working with Qumulo Core access tokens securely.

Avoiding Creation of Tokens for Administrative Accounts

An attacker can use an access token to authenticate as the token’s user to Qumulo Core REST API (through HTTP, the Python SDK, or the qq CLI) and gain all of the user’s privileges. To decrease the risk of giving an attacker full administrative access—including access to cluster data—avoid generating tokens for accounts with administrative privileges.

Generating Tokens for Service Accounts

When you connect external services to the Qumulo Core REST API, we recommend creating a service account with limited privileges for each individual service and generating an access token for each service account.

To Create a New Service Account

  1. Log in to the Qumulo Core Web UI.

  2. Create a service account.

    1. Click Cluster > Local Users & Groups.

    2. In the Users section, click Create.

    3. In the Create user dialog box, enter a User name and Password, re-enter the password, and then click Create.

  3. Create a role with privileges.

    1. Click Cluster > Role Management.

    2. In the Role Management section, click Create Role.

    3. On the Create Role page, enter a Name and Description, click the Privileges for the user, and then click Save.

  4. Assign the service user to the role.

    1. On the Role Management page, find the name of the role you created and then click Add Member.

    2. In the Add Member to <MyRoleName> dialog box, for Trustee, enter the name of the user you created and then click Yes, Add Member.

  5. Create access tokens for your service account.

Rotating Access Tokens

We strongly recommend rotating access tokens for a service account at a regular interval.

To Rotate an Access Token for a Service Account

  1. To ensure that there is only one access token for each service account, run the qq auth_list_access_tokens command.

    If multiple access tokens exist, delete any unused access tokens.

  2. To create a new access token for the service account, run the qq auth_create_access_token command.

  3. In the credential store of your service, replace the old access token with the new one.

  4. Test that your service account can access the Qumulo Core REST API.

  5. Confirm that there is nothing else relying on the old access token by disabling it first. If this causes any disruptions then you can re-enable it while you resolve the issue.

  6. To delete the old access token, run the qq auth_delete_access_token command.