Tokens

The CipherTrust Manager supports two types of tokens:

• API Tokens (JWT)

• Refresh Tokens

Both tokens can be issued (created) using username and password 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.

Another typical use case for refresh tokens is to give an application access to the CipherTrust Manager without the need to share the username and password to the application. Instead the application can be given a refresh token to allow it to issue short lived API Tokens (JWT). The same CipherTrust Manager account (username/password) can issue and revoke several independent refresh tokens, providing access control per application.

Refresh Token Duration

Refresh token duration depends on the CipherTrust Manager 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 Manager 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 Manager 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.

There is a system property,MAXIMUM_REFRESH_TOKEN_LIFETIME, accessible through the v1/configs/properties/ API endpoint or the ksctl properties commands. By default, MAXIMUM_REFRESH_TOKEN_LIFETIME is not set. When set, this system property applies to every CipherTrust Manager user interface, and overrides any other configuration related to refresh token lifetime, preventing users from creating refresh tokens which have a longer lifetime than the set maximum.

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, that is, exchange a token that is close to expiration for a fresh token. This is done using a "refresh token".

Refresh tokens are longer lived tokens that can be used instead of user 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 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.

Login Command

Use the login command to create and save a long lived refresh token that makes it easier to access your CipherTrust Manager 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 Manager instance

• Flag indicating that SSL verification should not take place

Example 1: When no config.yaml file exists

$ ksctl login –-user <username> --url https://<kylo-system> --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://kylo-system
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