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.
It is possible to confuse the terms access token and session token. Unlike access tokens, session tokens are short-lived and require a password to refresh, for example, to authenticate by using the
qq login
command. Access tokens are the focus of this section.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.
- 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. Treat access tokens, and the bearer tokens they generate, like passwords. Store your tokens securely, rotate your tokens often, and create a token revocation policy for your organization. - Because a token allows indefinite authentication to the associated user's account, we strongly recommend against creating tokens for individual Qumulo Core REST API users. For more information, see Best Practices for Using Access Tokens.
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.
Creating and Using Access Tokens
PRIVILEGE_ACCESS_TOKEN_WRITE
is required for creating, disabling, and deleting access tokens for all users in the system. This section explains how to create access tokens without or with an expiration time by using the qq
CLI.
To Create an Access Token without an Expiration Time
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
- Although you can create groups for users, you can't create access tokens for groups.
- 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 theqq
CLI can use—when you create the access token.
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": "12345678901234567890123"
}
- As soon as you receive your bearer token, record it in a safe place. If you misplace the bearer token, you can't retrieve it at a later time. You must create a new access token.
- Any user can have a maximum of two access tokens. If a user already has two access tokens, creating new tokens fails until you remove at least one token from the user. We strongly recommend creating a single access token for each user and using the second access token to perform secret rotation.
- Treat access tokens, and the bearer tokens they generate, like passwords. Store your tokens securely, rotate your tokens often, and create a token revocation policy for your organization.
- To decrease the risk of giving an attacker full administrative access—including access to cluster data—avoid generating tokens for accounts with administrative privileges.
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.
The
--expiration-time
flag interprets arguments as timestamps in the UTC time zone.
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
Getting Metadata for Access Tokens
PRIVILEGE_ACCESS_TOKEN_READ
is required for listing access tokens. This section explains how to get metadata for a specific access token or all access tokens by using the qq
CLI.
To Get 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": "12345678901234567890123",
"user": {
"auth_id": "1002",
"domain": "LOCAL",
"gid": null,
"name": "svc",
"sid": "S-1-1-12-12345678-2345678901-1234567890-1002",
"uid": null
}
}
To Get Metadata for All Access Tokens
Run the qq auth_list_access_tokens
command.
Listing access tokens doesn't return the bearer token required for authentication. If you misplace the bearer token, you can't retrieve it at a later time. You must create a new access token.
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
PRIVILEGE_ACCESS_TOKEN_WRITE
is required for creating, disabling, and deleting access tokens for all users in the system. This section explains how to modify access tokens by using the qq
CLI.
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.
The
--expiration-time
flag interprets arguments as timestamps in the UTC time zone.
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.
PRIVILEGE_ACCESS_TOKEN_WRITE
is required for creating, disabling, and deleting access tokens for all users in the system. This section explains how to disable an access token by using the qq
CLI.
After you disable an access token, you can no longer use any bearer tokens associated with the access token to authenticate to Qumulo Core.
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
PRIVILEGE_ACCESS_TOKEN_WRITE
is required for creating, disabling, and deleting access tokens for all users in the system. This section explains how to delete an access token by using the qq
CLI.
After you delete an access token, you can no longer use any bearer tokens associated with the access token to authenticate to Qumulo Core.
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
-
Log in to the Qumulo Core Web UI.
-
Create a service account.
-
Click Cluster > Local Users & Groups.
-
In the Users section, click Create.
-
In the Create user dialog box, enter a User name and Password, re-enter the password, and then click Create.
-
-
Create a role with privileges.
-
Click Cluster > Role Management.
-
In the Role Management section, click Create Role.
-
On the Create Role page, enter a Name and Description, click the Privileges for the user, and then click Save.
-
-
Assign the service user to the role.
-
On the Role Management page, find the name of the role you created and then click Add Member.
-
In the Add Member to <MyRoleName> dialog box, for Trustee, enter the name of the user you created and then click Yes, Add Member.
-
-
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
-
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.
-
To create a new access token for the service account, run the
qq auth_create_access_token
command. -
In the credential store of your service, replace the old access token with the new one.
-
Test that your service account can access the Qumulo Core REST API.
-
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.
-
To delete the old access token, run the
qq auth_delete_access_token
command.