About Access and Refresh Tokens

Describes how to use the downloadable tokens provided for client access.

How Clients Use Tokens

In Data Fabric deployments where SSO is configured, you must provide an SSO user name and password for access to a fabric. Clients that aren’t aware of SSO user names and passwords can gain access to RPC communications by using JSON web tokens (JWTs). A JSON Web Token (JWT) is a method for securely transmitting information between services in a computing system.

In a Data Fabric deployment, the Keycloak SSO provider can generate tokens when a user supplies an SSO user name and password. The tokens enable the creation of short-lived Data Fabric tickets that facilitate communication with the file system.

Issuing commands from any of the following command line interfaces (CLIs) or clients requires the user or client to have a valid ticket.
  • maprcli
  • hadoop
  • mc
  • fuse (service start)
  • loopback nfs (service start)

The ticket allows the command line to connect to the CLDB service. To facilitate the process, you must obtain a token from the SSO provider and place it in a secure location that can be specified in an environment variable. Exporting the environment variable creates a temporary ticket, enabling the CLI to talk to the CLDB server. This method permits the use of any command without a password for the duration of the ticket.

For more information about Data Fabric tickets, see Managing Tickets.

Downloading the Tokens

In the Data Fabric UI, you use the Client library command to download the tokens. The tokens are contained in the jwt_tokens.tar.gz file, which are extracted to the client. The jwt_tokens.tar.gz file contains the following token files:
Token Type File Function
Access jwt_access Encapsulates the user's authentication information within the fabric.
Refresh jwt_refresh Enables the creation of a new access token when the current access token expires.

For more information about downloading the tokens, see Installing Client Libraries.

Exporting the Tokens

To enable a client to use the tokens, you must export the path to each token. This must be done each time you establish a host session. To export the paths:
Client To export the tokens . . .
Hadoop Use these commands:
export MAPR_JWT_TOKEN_LOCATION="/root/jwt_access"
export MAPR_REFRESH_TOKEN_LOCATION="/root/jwt_refresh"
Fuse POSIX Add the export paths shown for the Hadoop client in the first row of this table to the top of the following file: 
/opt/mapr/initscripts/mapr-posix-client-basic
Loopback NFS Add the export paths shown for the Hadoop client in the first row of this table to the top of the following file: 
/usr/local/mapr-loopbacknfs/initscripts/mapr-loopbacknfs
Alternatively, you can add the tokens to the core-site.xml file. Adding them to core-site.xml file causes the fabric to use the designated tokens every time you log on. To add the tokens, specify the following property in the core-site.xml:
<property>
    <name>fs.mapr.sso.tokenpath</name>
    <value>/root/jwt_access</value>
</property>

Token and Ticket Expiration and Renewal

Tokens and tickets expire after a short time. By default, Keycloak-generated tokens expire after two (2) hours. Short-lived tickets expire after 20 minutes.

If an access token expires or becomes invalid, the client application can use a refresh token to obtain a new access token without requiring the user to re-authenticate. The client application sends Keycloak a token-refresh request along with the current refresh token. Keycloak validates the refresh token and issues a new access token. This automatic-refresh mechanism repeats itself to allow client jobs to run for days or weeks as long as the tokens remain valid.

Changing Token and Ticket Durations

You can change the valid duration of tokens and tickets. Note that a ticket is valid for no more than 20 minutes or the expiry time of its associated access token, whichever is lower. Thus, if a ticket expiry time is set for 20 minutes and the associated access token is valid only for 10 minutes, the ticket will be valid for only 10 minutes.
CAUTION
Setting long lifetimes for tokens or tickets can introduce a considerable security risk. Hewlett Packard Enterprise recommends finding a balance between security and usability and, whenever possible, erring on the side of security in your use of tokens and tickets.

To check or change the expiry setting for short-lived tickets, see Checking and Changing the Temporary Ticket Duration.

To change the expiration setting for a token, you must be the fabric manager and have access to the Keycloak UI.

Access Token Expiry

You can configure the access token expiry time at the realm level or at the client level.
  1. Log in to the Keycloak admin console. See Accessing the Keycloak Administration Console.
  2. Select the realm for which you want to configure the access token expiry time.
  3. Go to the Realm Settings > Tokens tab.
  4. In the Access Token Lifespan field, specify the desired expiration time for the access tokens in hours, minutes, or days.
  5. Save your changes.

Refresh Token Expiry

You typically configure the refresh token expiry time at the realm level:
  1. Log in to the Keycloak admin console. See Accessing the Keycloak Administration Console.
  2. Select the realm for which you want to configure the access token expiry time.
  3. Go to the Realm Settings > Sessions tab.
  4. In the SSO Session Max field, specify the desired maximum lifespan for refresh tokens in minutes, hours, or days.
  5. Save your changes.