Using Refresh Tokens

Describes how to use refresh tokens that were obtained by direct grant or download from a web browser.

You can use a POST request to refresh an access token. When an access token is refreshed, it reflects the user's current roles and attributes. Each refresh token is typically valid for a week; however, you can include the offline_access scope in the POST to obtain a refresh token that does not expire unless the token is not used for thirty days.

Consider the following information when using refresh tokens:
  • If you obtained a refresh token from the browser, the token is already an offline token and the it will not expire unless it is not used for thirty days.
  • A refresh will fail if a user has been offboarded (denied access to the cluster) or if the cluster login has been generally disabled, for example, due to license expiration.
  • Variables used in the example POST requests have the following definitions:
    • UA_DOMAIN=<cluster-DNS-domain-name>.com
    • KC_ADDR=keycloak.$UA_DOMAIN

Using a Refresh Token Obtained by Direct Grant

If the refresh token was obtained by presenting credentials (username/password) to the ua-grant client, the refresh token must be presented to the ua-grant client. A client secret is not required.

The following cURL example demonstrates how to use the refresh token:
response_json=$(curl --data "grant_type=refresh_token&client_id=ua-grant&refresh_token=$REFRESH_TOKEN" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token") 
ACCESS_TOKEN=$(echo "$response_json" | jq -r '.access_token') 
REFRESH_TOKEN=$(echo "$response_json" | jq -r '.refresh_token')
Usage Notes
  • For testing purposes, you can use curl -k to skip peer certificate validation if the local CA certificate store cannot validate the Unified Analytics gateway certificate.
  • If you do not want the token to expire, include the offline_access scope in the request, as shown:
    response_json=$(curl --data "grant_type=refresh_token&client_id=ua-grant&refresh_token=$REFRESH_TOKEN&scope=offline_access" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token")
    An offline_access token can be used repeatedly. If an offline_access refresh token is not used for thirty days, the token becomes invalid.
  • If the ua-grant OIDC client is reconfigured to be a confidential client, you must specify the client_secret as one of the data parameters in the cURL request. For example, if ua-grant is a confidential client with the a secret value of 3EMVFnKnOU3B5Yh9B8MchwcFHvOVTcdh, then the cURL request must include that value for the client_secret parameter, as shown:
    response_json=$(curl --data "grant_type=refresh_token&client_id=ua-grant&refresh_token=$REFRESH_TOKEN&client_secret=3EMVFnKnOU3B5Yh9B8MchwcFHvOVTcdh" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token")
    For additional information, see Making the ua-grant OIDC Client a Confidential Client.

Using a Refresh Token Downloaded from a Web Browser

If the refresh token was obtained from a web browser download, the refresh token must be presented to the ua client, and a client secret is required. The client secret is different for every HPE Ezmeral Unified Analytics Software instance.

The following cURL example, with $CLIENT_SECRET representing the actual client secret value, demonstrates how to use the refresh token: 
response_json=$(curl --data "grant_type=refresh_token&client_id=ua&client_secret=$CLIENT_SECRET&refresh_token=$REFRESH_TOKEN" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token") 
ACCESS_TOKEN=$(echo "$response_json" | jq -r '.access_token') 
REFRESH_TOKEN=$(echo "$response_json" | jq -r '.refresh_token')

Usage Note

The client secret for the ua client can currently only be fetched from the Kubernetes API with administrative credentials. An admin user with administrative credentials can obtain the client secret and give it to users for external use of refresh tokens. The following invocation fetches the client secret value:
CLIENT_SECRET=$(kubectl -n ezaddon-system get secret hpecp-bootstrap-authconfig -o jsonpath='{.data.OIDC_CLIENT_SECRET}' | base64 -d)

Getting the Access and Refresh Tokens from the Response Body

To get the access and refresh tokens, extract the access_token and refresh_token attributes from the JSON object in the response body. For example, you can use the jq command-line JSON processor, as shown:
ACCESS_TOKEN=$(echo "$response_json" | jq -r '.access_token')
REFRESH_TOKEN=$(echo "$response_json" | jq -r '.refresh_token')
The tokens are in JWT format.

To use the access token in requests to the application API endpoints, specify the token as a bearer token in the Authorization header.

Refreshing Tokens in a Notebook

If you encounter a JWT token expiration error while running cells in a notebook, you can resolve the error by running the %update_token magic function. For details, see %update_token