Admin Tokens

Admin tokens provide tokenized account access for automated StrongDM use. They can be utilized for administrative tasks, such as the following:

• Auditing
• Managing users
• Managing roles
• Managing resources
• Managing gateways and relays
• Managing access
• Managing secret stores

This article describes how to create, manage, and use admin tokens.

Create Admin Tokens #

Admin tokens can be generated in the Admin UI or the CLI.

Admin UI #

To create an admin token using the Admin UI, follow these steps:

1. Make sure you have admin access to the Admin UI.
2. On Access > API & Admin Tokens, click Add token.
3. On the Create Admin Token page, give your token a name.
4. Specify when the token expires (1 week, 1 month, 1 year, or never).
5. Choose the permission(s) that this admin token grants and select the appropriate options for your admin token use case.
6. Click Create. The token appears in a modal.
7. Copy the token and keep it somewhere safe. The token only displays once.

CLI #

To create an admin token using the CLI, follow these steps.

1. Make sure your StrongDM permission level is Administrator.
2. In the CLI, run the sdm admin tokens add or sdm admin tokens create CLI command with the required options. In the example shown, an admin token is created with the name “Example Admin Token”, which has a duration of one week and is able to create roles.

   sdm admin tokens add
   --name="Example Admin Token"
   --type="admin-token"
   --duration="604800"
   --permissions="role:create"
   

Options #

Authentication #

There are two methods to authenticate the CLI with an admin token: with an environment variable or through the sdm login command.

Environment variable #

The CLI references the environment variable SDM_ADMIN_TOKEN if it is set. You can set this in your shell by using export:

export SDM_ADMIN_TOKEN='<TOKEN_VALUE>'

Login command #

The CLI can use the token directly if the --admin-token flag is used:

sdm login --admin-token='<TOKEN_VALUE>'

General Usage #

Once authenticated with an admin token, you can run any sdm admin command granted to the token. No other commands (for example, sdm status) work using an admin token, regardless of permission level.

You can run any of the following commands that you have granted to the token once you are authenticated with the token:

• User commands: sdm admin users list
• Role commands: sdm admin roles list
• Datasource commands: sdm admin datasources list
• Server commands: sdm admin servers list
• Relay commands: sdm admin nodes list. Note that the relays list command requires the token to have been granted datasources list; without it, relays list does not work because it provides some information on the connected datasources for each relay.

Rotate Admin Tokens #

Rotating an admin token generates a new secret while maintaining the name and permissions. We recommend doing so if you believe a token has been compromised, a user with access to the token has left your organization, or a user who owns the admin token is suspended.

To rotate a token, use these steps.

1. Find the token on the API & Admin Tokens page of the Admin UI.
2. Click to Rotate. A tooltip alerts you that the existing secret will be unable to authenticate, and existing authentications will expire after 24 hours.
3. Click Rotate to regenerate the token secret and expire the existing token after 24 hours.

Delete Admin Tokens #

Once a token is rotated or deleted, the token immediately loses its ability to authenticate commands.

Admin Tokens Created by Suspended Users #

What happens to admin tokens that are owned by a suspended user? Admin tokens are still usable even if the user who created them is suspended.

When suspending a user, the Admin UI lists the admin tokens created by that user and asks if they should be deleted. Select No to keep them.

After confirming suspension, you can see in section Principals > Tokens of the Admin UI that the admin tokens continue to be owned by the suspended user and remain usable. For the admin tokens that are still needed, rotate the credentials to deactivate the existing token secret and generate a new one.