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: Refresh tokens timeout after 30 minutes of inactivity. This means that if a browser session with the GUI is idle for more than 30 minutes, the user is logged out of CipherTrust Manager.
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
Note
Replace <kylo-system>
with the name or the IP address of the host with the CipherTrust Manager instance.
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
.
Note
The config.yaml
file stores an additional information, KSCTL_CLIENTID. This is used by the login
command and should not be deleted or modified.
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