Managing Tokens

Workbench

Workbench uses a bearer token to authenticate requests to the Workbench SCIM API endpoint.

Important

This token is required in order for the IdP to communicate with Workbench. Failure to configure this token results in user provisioning not working correctly.

Workbench provides two methods for managing tokens:

Managing tokens with the CLI tool

Workbench provides a CLI tool for managing tokens. This tool can be used to generate, list, and revoke tokens. This tool is installed with Workbench and can be accessed via the rstudio-server command.

Generating tokens

To generate a token, run the following command on the Workbench server:

terminal
$ sudo rstudio-server user-service generate-token "My Token"

This generates a token with the name My Token and prints the token to the terminal. This token can be used to authenticate requests to the Workbench SCIM API. By default, tokens are valid for 365 days.

The following options are available for this command:

  • --duration: The duration of the token to generate (in days). By default, tokens are valid for 365 days.
  • --no-expiry: Generate a token that does not expire.

Listing tokens

To list all tokens, run the following command on the Workbench server:

terminal
$ sudo rstudio-server user-service list-tokens

This prints a table of all tokens to the terminal, including the token name, scrubbed token key, creation date, expiration date, and last used date.

Revoking tokens

To revoke a token created with the generate-token command, run the following command on the Workbench server:

terminal
$ sudo rstudio-server user-service revoke-token "My Token"

The following options are available for this command:

  • --all: Revoke all tokens.

Managing tokens through the environment

It is also possible to configure tokens through the environment, which is particularly useful for Kubernetes-based Workbench deployments. This method requires the token to be provided by the admin, and it must be placed in a file in a location accessible by Workbench. File security on the token file should be such that permissions allow for read/write access by the admin and read access by Workbench.

Note

Tokens configured through the environment cannot be revoked with the revoke-token command. To revoke a token, admins should delete or change the token file directly and then restart Workbench.

Configuring the Workbench SCIM API authentication token

This method can be used as an alternative to the generate-token command.

To configure the token used to authenticate requests to the Workbench SCIM API, set the WORKBENCH_USER_SERVICE_AUTH_TOKEN_PATH environment variable to the token path.

For example, if you have installed the token to /mnt/shared/scim_api, set WORKBENCH_USER_SERVICE_AUTH_TOKEN_PATH to this token path:

WORKBENCH_USER_SERVICE_AUTH_TOKEN_PATH=mnt/shared/scim_api

When Workbench starts, it looks for the WORKBENCH_USER_SERVICE_AUTH_TOKEN_PATH environment variable. If it is set, Workbench attempts to read and configure the token at startup.

Token scopes

Tokens for Workbench’s SCIM API are associated with a scope. A token’s scope determines the type of operations and data that can be accessed by the token, described by the token’s permission and access level:

  • Permission: The permission level of the token. This can be either READ or WRITE.
  • Access Level: The access level of the token. This can be either USER or ADMIN.
Note

All tokens generated via the rstudio-server user-service generate-token command and tokens configured through the WORKBENCH_USER_SERVICE_AUTH_TOKEN_PATH environment variable have the WRITE permission and USER access level. This is not configurable.

Permission

  • READ: Tokens with the READ permission can only read data from the SCIM API.
  • WRITE: Tokens with the WRITE permission can read and write data to the SCIM API.

Access level

  • USER: Tokens with the USER access level can access all data for users except for the shadowPassword attribute.
  • ADMIN: Tokens with the ADMIN access level can access all data for users.

NSS tokens

The NSS tokens, user-token and admin-token that are generated by Workbench are used by the Workbench NSS module to authenticate requests to the Workbench SCIM API. Both NSS tokens have the READ permission. The user-token has the USER access level, while the admin-token has the ADMIN access level.

Back to top