Authentication Tokens

The CipherTrust Data Security Platform Service supports two types of authentication tokens:

• API Tokens (JWT)

• Refresh Tokens

Both authentication tokens can be issued (created) using username and password or client credentials, but the API Token (JWT) can alternatively be issued using a refresh token. API Tokens (JWT) are short lived tokens and are used for accessing the REST API as a "Bearer" token. API Tokens (JWT) are valid for 5 minutes.

Refresh tokens are long lived tokens and can be used as an alternative way to issue API Tokens (JWT). One typical use case for refresh tokens is for a long lived browser session where a user enters credentials to get a refresh token. This allows the browser to automatically issue new API Tokens (JWT) using the refresh token during the session.

Refresh Token Duration

Refresh token duration depends on the CipherTrust Data Security Platform Service user interface. Refresh tokens have both a timeout due to inactivity, and an absolute lifetime beyond which the token expires.

The following timeouts due to inactivity apply to the CipherTrust Data Security Platform Service interfaces:

• Web console UI: An idle browser session logs out the user after 10 minutes of inactivity, due to an additional timeout unrelated to the refresh token. The refresh token timeout is 30 minutes, and applies in the case that the user has closed the browser window without logging out. In that situation, the user can navigate back to the CipherTrust Data Security Platform Service URL and access the GUI without logging in again, if the refresh token is still active.

• API playground: The Authenticate button in the top right corner issues refresh tokens which timeout after 60 minutes of inactivity. This means that if you do not make any API requests for more than 60 minutes, you must authenticate with the username and password again to make new API requests. As well, the API playground does not issue API tokens automatically, so you must click the Re Authenticate button to issue API tokens with the refresh token every 5 minutes.

• ksctl CLI: By default, refresh tokens do not timeout due to inactivity. If you manually issue a refresh token with the ksctl tokens create command, there is an optional parameter --rt-unused-life to set the timeout in minutes for inactivity.

By default, there is no absolute lifetime for refresh token issued through the web console UI, the API playground Authenticate button, or the ksctl tokens create command. The ksctl login command sets the lifetime at 30 days by default. Both ksctl commands have options to specify the refresh token lifetime.

API Tokens (JWT)

Tokens are string values used to authenticate calls to the REST API. You use an endpoint to trade a user credential for an API token:

GET /api/v1/auth/tokens/

Example: Token

    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUy
    Nzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJre
    WxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQyODAsImV4cC
    I6MTQ4MTEyNDU4MH0.xTWlkVnYTiCAzJ_ZL746F2HB5HAqxOdnHJ-Qyjq_K84

Refresh Tokens

API Tokens expire, but the same endpoint can be used to "refresh" a token. You can use a refresh token to acquire a fresh access token.

Refresh tokens are longer lived tokens that can be used instead of user or client credentials for requesting a new API access token when the current API access token becomes invalid or expires. The refresh token might expire as well and should be renewed periodically depending on the nature of the client application.

Refresh tokens can be created by passing an additional flag "issueRefreshToken" when requesting an API token.

Example: Refresh token

ujeViKSNKXUbiL8fEjliukE8AgSzH8DxojwnYuDL4hoX4OqpZX1OEPPDgRPtkdQY

Example use cases for refresh tokens:

• Provide an application with a refresh token to allow access to the service.

• Provide a browser with a refresh token to allow a more long lived session.

To issue an API token (JWT) using ksctl:

You can issue an API token (JWT) in one of three ways.

• Issue using username and password:

  $ ksctl tokens create --user admin --password admin --issue-rt | jq -r .refresh_token
  

  Refresh token reply (example):

  e7UySu7fj8ZAwPKVIjEGwOTmt8AidxFHK8Wc4tL0RiaHVf7sd3oBQ74y2M8pPhNI
  

• Issue using a refresh token:

  $ ksctl tokens create --refresh-token e7UySu7fj8ZAwPKVIjEGwOTmt8AidxFHK8Wc4tL0RiaHVf7sd3oBQ74y2M8pPhN
  

  Response:

  {
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkOWNhZTVlOC0xNDJmLTQ2NmQtOTlhZS1iODI5YmQ4ZTc0YWQiLCJzdWIiOiJsb2NhbHw5MTdiNTNmYy1kMjA5LTQ4OTUtYmFiZS03NmM3MTFlNDI5ZGMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJncm91cHMiOlsiYWRtaW4iXX0sImp3dGlkIjoiNTg0MDI0N2YtZTQ5ZS00YmNkLTk0NjctNzE5YTU4OGQ0NjViIiwiaWF0IjoxNTMwODk1Nzg4LCJleHAiOjE1MzA4OTYwODh9.JMRtLevUUv5YOsxg4BJhHMt5pyzlvwxOTWLD49EzTU4",
    "duration": 300,
    "token_type": "Bearer"
  }
  

• Assign the API Token (JWT) to the environment variable using a refresh token:

  export KSCTL_JWT=$(ksctl tokens create --refresh-token e7UySu7fj8ZAwPKVIjEGwOTmt8AidxFHK8Wc4tL0RiaHVf7sd3oBQ74y2M8pPhNI | jq -r ".jwt")
  

To refresh the refresh token using ksctl:

Use this command to refresh the refresh token without the username and password.

$ ./ksctl tokens create --issue-rt --refresh-token cIb6w1PzazBnJM35v9QyP6LWN70lGnGfNVUMGQfzjrcY8Hfv9cJjuMIXFHqNIo9g

Response:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI2NzI3ZWQ1Ni0yNjkxLTRkMzctOGNhMC1iYmJhMzNhMjBkNzMiLCJzdWIiOiJsb2NhbHxmZDBiNTcwYi04NDlhLTRlNDAtOGExYS0xYTEyZTJjZDA4MjQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJncm91cHMiOlsiYWRtaW4iXX0sImp3dGlkIjoiOTAxODg4ZjYtODIzNy00ZWQxLTlkNWItOWJmNjBmNGQzM2E3IiwiaWF0IjoxNTMxMTQ3OTMxLCJleHAiOjE1MzExNDgyMzF9.5IKirMRFYfLeDXnN1LOQvxfnjZLL4lwCmbhZazHOhIU",
  "duration": 300,
  "token_type": "Bearer",
  "refresh_token": "1xy4tVzBzjrzsVho4xWQAtN5Whil3a71eH6nYMTi4VNSIEWXHv7NpKGAItdQRUip"
}

Revoke Refresh Token

A refresh token can be revoked by passing the refresh token and client id or user credentials to the following endpoints:

POST /api/v1/auth/revoke

A revoked refresh token can no longer be used to renew API tokens.

Deleting Refresh Token for Users with Multiple Logins

Users with active multiple logins can encounter a banner in the web console UI, "Multiple Logins Detected".

If you do not suspect an account compromise, you can selectively delete tokens for unnecessary user sessions.

A user might have active refresh tokens for the following login types:

• Web UI login with the user credentials

• ksctl CLI login with the user credentials

• API playground log with the user credentials

To delete refresh tokens:

1. Login to the API playground as an Application Administrator, such as admin.

2. Obtain the user ID, which is different than the username. The user ID is the user's authentication type, such as local|, followed by a 32 character alphanumeric randomly generated value.

   REST API

   List all users, using the query parameter username to filter to the user's name. Copy the value of "user_id" in the response.

   Syntax

   GET /v1/usermgmt/users?username=<username_value>

   Example command

   GET /v1/usermgmt/users?username=user1

   Web Console UI

   1. Login to the web console UI as a User Admin, such as admin.

   2. Navigate to Access Management>Users.

   3. Search for the user name in the list.

   4. View the ID column.

   5. Click Copy next to the value to copy.

3. List the authentication tokens for the user, using the user ID value as a query parameter to filter.

   Syntax

   GET /v1/auth/tokens?user_id=<user_id_value>

   Example Command

   GET /v1/auth/tokens?user_id="local|21bf2cb1-b535-46b9-aaa0-593def1ed385"

4. Examine the response to see which tokens are no longer needed.

5. For tokens you wish to delete, look in the list all tokens response for id values, and retain those.

6. Delete each token individually, using the id value for the token.

   Syntax

   DELETE /v1/auth/tokens/<token_id>

   Example Command

   DELETE /v1/auth/tokens/a52bf108-d214-40b8-8889-2a32dbc5e42c

Login Command

In the ksctl CLI, use the login command to create and save a long lived refresh token that makes it easier to access your CipherTrust Data Security Platform Service server. This method is safer than storing a password in the config.yaml file because a refresh token can easily be revoked and renewed if ever exposed. For more information on refresh tokens, refer to Refresh Tokens.

Configuration file with a saved refresh token

The login command can be used as an alternative to creating a config.yaml file as defined in the CLI Installation. When using the login command, if no config.yaml file exists, one is created in the .ksctl subdirectory of the user’s home directory, or the configuration file that is specified in the login command is used. See examples below.

The login command requires:

• User name

• URL of the CipherTrust Data Security Platform Service instance

• Flag indicating that SSL verification should not take place

Example 1: When no config.yaml file exists

$ ksctl login –-user <username> --url https://<ip_address_or_hostname> --nosslverify

You are then prompted for the password. If the password is successful, you will see the following message:

this login will expire in 30 days

This command also creates a config.yaml file similar to the following:

KSCTL_VERBOSITY: false
KSCTL_RESP: json
KSCTL_URL: https://ip_address_or_hostname
KSCTL_USERNAME: admin
KSCTL_REFRESHTOKEN: icmtiodYvNfCAr5XXXODlgJjATkYPpYs3oHRXXXCdGWhGpSXXX70x3AQF1tkcpGO
KSCTL_CLIENTID: ffbbd794-68a3-4da9-83bc-9b0dd7a3ee48
KSCTL_NOSSLVERIFY: true

Example 2: When specifying the config.yaml file to use

The following login command can be run to create a custom configuration file by adding the configfile variable:

$ ksctl login –-user <username> --url https://<kylo-system> --nosslverify –-configfile localconfig.yaml

As in Example 1, you are prompted for the password. On successful creation of the refresh token, a custom configuration file is created with the name localconfig.yaml.

Example 3: When config.yaml file already exists

When the URL and the username or refresh token are already stored in a config.yaml file, the following command can be run:

$ ksctl login

Example 4: Initial login command using password

$ ksctl login –-user <username>

You are prompted for a password. If successful, a refresh token with a default lifetime of 30 days is created. You will see the following message:

$ this login will expire in 30 days

The refresh token is written to the config.yaml file to be used by subsequent invocations of ksctl.

Refresh token lifetime

If you do not specify the lifetime for a refresh token, a default of 30 days is used.

Example 1: Specifying a refresh token lifetime in days

Use the --days option to specify the number of days the token should be valid.

$ ksctl login –-user admin –-days 10

Returned information:

this login will expire in 10 days

Example 2: Specifying a refresh token lifetime in hours

Use the --hours option to specify the number of hours the token should be valid.

$ ksctl login –-user admin –-hours 10

Returned information:

this login will expire in 10 hours

Example 3: Specifying a refresh token lifetime in days and hours

Use both the --days and --hours options to specify the number of days and hours the token should be valid.

$ ksctl login –-user admin –-days 10 --hours 10

Returned information:

this login will expire in 10 days, 10 hours

Summary of login command options

The following options can be provided in the login command. Each option used overrides the corresponding value in the configuration file.

• --user : required only when there is no configuration file. If provided, the value is saved to the configuration file.

• --password : never required, never saved to the configuration file.

• --url: required only when there is no configuration file. If provided, the value is saved to the configuration file.

• --nosslverify : required when there is no configuration file. If provided, the value is saved to the configuration file.

• --verbose: never required, used during invocation, and never saved to the configuration file.

If you get the following error, it indicates that your ssl verification is being done and that you did not specify –nosslverify in the login command.

Post https://localhost/api/v1/auth/tokens: x509: certificate is not valid for any names, but wanted to match localhost

Revoke/refresh an existing token

If a token already exists in the configuration file when a login command is invoked, the existing token will be revoked/refreshed automatically.

Logout Command

The logout command reads the configuration file and revokes the login token found in it. This command does not require any options.

$ ksctl logout

If the login token is successfully revoked, the following message is returned:

login revoked

If there is no login refresh token or client id present in the file, the following message is returned:

login token and client id must exist in ksctl configuration file