Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Authentication

Authentication Tokens

search

Please Note:

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: 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

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.

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:

To delete refresh tokens:

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

    Do not specify a domain or an auth_domain.

  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.

    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

    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 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 are web-ui and nae-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 idclient name
      c5890024-a6d4-408d-a592-5d4d5807c722nae
      17771cf2-f80b-4eb5-a19b-a2d0032179c3web-ui
      5ffb6fac-2cb5-4b91-8183-e20ad3b62577ksctl
      837c840d-75dd-4b4f-a318-79cb16ca248dapi-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.

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

      2. Navigate to Access Management>Client Hub.

      3. View the ID column. This represents valid client identity values.

      4. Click on a client name to obtain more details about that client.

  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 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.yamlfile 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

On this page