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 Principals > 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"

To view a list of all available permissions for admin tokens, run sdm admin tokens create --permissions-help.

Options

Option	Requirement	Description	Example
--duration	Required	Duration before token expires, in seconds (default: 0)	sdm admin tokens add --duration 3153600000
--file or -f	Optional	Load tokens from JSON file	sdm admin tokens add --file
--name	Required	Name of token	sdm admin tokens add --name "Example Admin Token"
--permissions	Required	Permissions attached to the token, in a comma-separated list	sdm admin tokens add --permissions role:create,role:list
--permissions-help	Optional	Displays all available permission values for tokens	sdm admin tokens add --permissions-help
--stdin or -i	Optional	Load from stdin	sdm admin tokens add --stdin
--tags	Optional	Tags in 'key=value,...' format	sdm admin tokens add --tags 'env=dev'
--template or -t	Optional	Display a JSON template	sdm admin tokens add --template
--timeout	Optional	Set time limit for command	sdm admin tokens add --timeout 60
--type	Required	Type of token, either admin token (admin-token) or API token (api)	sdm admin tokens add --type admin-token

Authentication

There are two methods to authenticate the CLI Reference 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>'

If the admin token is used at login in this manner, or if SDM_ADMIN_TOKEN is set as an environment variable, there is no need to log in via the CLI or GUI. Any active client sessions break when you try to log in with the --admin-token flag. Instead, you can just begin executing commands without needing to log in with credentials.

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.