Obtaining Tokens by Direct Grant

Describes how to obtain access and refresh tokens with a user's credentials and the Keycloak service address.

An external client program can obtain tokens for a user through a POST request to a token-granting URL path under the Keycloak service address. Keycloak has an endpoint on the ua-grant OIDC client in the HPE Ezmeral Unified Analytics Software realm for the resource owner's password credentials. The OIDC client is the API endpoint that the external client program interacts with for token operations. For additional information, see Identity and Access Management.
IMPORTANT
This endpoint is only functional when the authentication source for the cluster is external AD/LDAP or internal LDAP. For other authentication configurations, such as the OIDC authentication used in HPE Ezmeral Unified Analytics Software, this endpoint cannot be used. Instead, use the browser method to obtain a refresh token, which can then be used to obtain access tokens. See Obtaining Refresh Tokens with Browser.

Use the Keycloak service address (keycloak.<cluster-DNS-domain-name>.com) and user credentials (username and password) in a POST request to obtain an access token (in JWT format) from the response body. You can then use the access token in requests to application API endpoints by specifying the token as a bearer token in the Authorization header.

cURL POST Request

You can use the following cURL POST request to obtain access and refresh tokens:
UA_DOMAIN=<cluster-DNS-domain-name>.com
KC_ADDR=keycloak.$UA_DOMAIN
USERNAME=<username>
PASSWORD=<user-password>

response_json=$(curl --data "username=$USERNAME&password=$PASSWORD&grant_type=password&client_id=ua-grant" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token")
TIP
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.
Offline Access
If you do not want the token to expire, include the offline_accessscope in the request, as shown:
response_json=$(curl --data "username=$USERNAME&password=$PASSWORD&grant_type=password&client_id=ua-grant&scope=offline_access" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token")
An offline_access token can be used repeatedly; however, if an offline_access refresh token is not used for thirty days, the token becomes invalid.

Reconfigured ua-grant OIDC Client as a Confidential Client
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 "username=$USERNAME&password=$PASSWORD&grant_type=password&client_id=ua-grant&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.

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.

Example

The DNS domain name for a Unified Analytics cluster is my-ua.com, which makes the Keycloak address keycloak.my-ua.com. An external client program can obtain tokens for a user (bob) through a cURL POST request to the token-granting URL path under the keycloak.my-ua.com service address, as shown:
KC_ADDR=keycloak.my-ua.com
USERNAME=bob
PASSWORD=bobspassword
response_json=$(curl --data "username=$USERNAME&password=$PASSWORD&grant_type=password&client_id=ua-grant" "https://$KC_ADDR/realms/UA/protocol/openid-connect/token")
From the response body, extract the access_token and refresh_token attributes from the JSON object, as shown:
ACCESS_TOKEN=$(echo "$response_json" | jq -r '.access_token')
REFRESH_TOKEN=$(echo "$response_json" | jq -r '.refresh_token')
To use the access token in requests to the application API endpoints, specify the token as a bearer token in the Authorization header.