Authentication Tokens
The CipherTrust Manager 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 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
JWT Signing Key
The CipherTrust Manager 2.15 onward, the default JWT signing key is ECDSA(ES256). Previously it was HMAC(HS256).
To rotate a authentication key:
Example - for ECDCA
ksctl tokens rotate-auth-key --type ecdsa --curve p256
Example - for HMAC
ksctl tokens rotate-auth-key --type hmac
Note
When you deploy a new instance of CipherTrust Manager 2.15 or above, it generates a new ECDSA authentication key. In case of upgrading to CipherTrust Manager 2.15 or above, the authentication key type remains the same as before.
When you rotate the JWT signing key without passing authentication key type, the default rotation key type will be ECDSA(ES256).
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".
Warning
If your organization suspects the account is compromised, take actions to change the user credentials immediately.
Change the password. Users can change their own passwords, or an administrator in the User Admins or Admins group can do so for the user account. This action revokes all active tokens.
For certificate-authenticated users, an administrator in the CA Admins or Admins group can use a local certificate authority to revoke the certificate for the user.
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
NAE-XML clients using the user's credentials for user delegation or impersonation
KMIP clients using the user's credentials for user delegation or impersonation
To delete refresh tokens:
Login to the API playground as an Application Administrator, such as
admin
.Do not specify a domain or an auth_domain.
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.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
Login to the web console UI as a User Admin, such as
admin
.Navigate to Access Management>Users.
Search for the user name in the list.
View the ID column.
Click Copy next to the value to copy.
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"
Examine the list tokens response to view what interfaces the tokens are associated with. This can help you identify which tokens are no longer needed.
The
labels
field indicates tokens issued for web console UI access and for NAE-XML and KMIP clients using the user's credentials. Potential values areweb-ui
andnae-auth
.client_id
indicates the client identity associated with the token. The following public client identities are valid for web console UI tokens, ksctl CLI tokens, API playground tokens, and tokens for unregistered NAE-XML clients acting as public clients:client id client name c5890024-a6d4-408d-a592-5d4d5807c722 nae 17771cf2-f80b-4eb5-a19b-a2d0032179c3 web-ui 5ffb6fac-2cb5-4b91-8183-e20ad3b62577 ksctl 837c840d-75dd-4b4f-a318-79cb16ca248d api-playground Registered NAE-XML clients, and all KMIP clients, have individual client identities which were set up on client registration. To confirm the client identity and look up other details about these clients:
List all clients.
Syntax
GET /v1/client-management/clients
The
id
value for each client confirms the client identity.Login to the web console UI as a Client Admin, such as
admin
.Navigate to Access Management>Client Hub.
View the ID column. This represents valid client identity values.
Click on a client name to obtain more details about that client.
For tokens you wish to delete, look in the list all tokens response for
id
values, and retain those.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 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://<ip_address_or_hostname> --nosslverify
Note
Provide the name or the IP address of the host for 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://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
.
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