Auth Tokens

Describes auth tokens and how auth tokens work in HPE Ezmeral Unified Analytics Software.

An auth token encapsulates a user's authentication and authorized roles within the Unified Analytics cluster. Unified Analytics uses auth tokens to determine a user's identity and authorization. Some applications also use the auth tokens to communicate with other services in the Unified Analytics cluster.

All auth tokens in Unified Analytics are short-lived for security and functionality purposes. Short-lived tokens:
  • Work well for long-running jobs
  • Promptly reflect changes in user enablement and roles
  • Have a short lifespan, which limits the time a malicious person or program can use them if accessed
In Unified Analytics, auth tokens are in the:
  • Request header (of incoming web requests)
  • Token secret (Unified Analytics-specific access token in a user's namespace)

Request Header Token

Applications can look at the request header and use the token in request processing. When a user signs in to HPE Ezmeral Unified Analytics Software, the token in the request header is valid for one hour. This one hour lifetime limits the amount of time that an external client can store and reuse the access token.

When the token expires, it becomes invalid and the external client program that was using the token must obtain a new access token. HPE does not recommend storing this token in applications or reusing the token.

Token Secret

When a Unified Analytics administrator creates a new user or adds a user to the Unified Analytics platform, the system automatically creates a unique namespace for that user. All jobs that the user launches, such as a Spark job, run in the user's unique namespace, isolated from other users. Included in the user's namespace is a secret, created by the Unified Analytics token service. The secret in the user's namespace contains an access token, aptly named access-token, in the value of AUTH_TOKEN.

The access token in the secret has the following attributes:

  • Valid for up to 30 minutes, but always has a minimum of 10 minutes left to live. When the token is read from the secret, the token always has 10 minutes left to live.
  • The token is started when a user signs in to Unified Analytics.
  • The Unified Analytics token service regularly refreshes the token unless the user login is blocked for some reason.
  • Token claims:
    • Contains the namespace claim. You can locate the user's namespace using the namespace claim.
    • When the sign in via the email address is not allowed, the email claim remains empty incase the email address is not provided.
Notebook Access to the Token Secret
A web request to the user's notebook contains a token in the request header; however, if the notebook needs to make requests to another service that requires a token for authentication, the notebook can get the access token out of the secret.

The secret mounts the notebook's filesystem in the local pod at /etc/secrets/ezua/.auth_token. The notebook reads the token from the file and puts the token in an outgoing request. The notebook can do this repeatedly because the token service in Unified Analytics regularly refreshes the access token.

The following diagram shows the basic access flow between the notebook and the secret:

You can mount the access token to any pod running jobs in your namespace. To mount the access token to a pod, add the hpe-ezua/add-auth-token annotation to the Pod configuration, as shown in the following example:
apiVersion: v1
kind: Pod
metadata:
   name: nginx
   namespace: hpedemo-usr
   annotations:
     hpe-ezua/add-auth-token: "true"
spec:
  containers:
  - name: nginx
    image: nginx: 1.14.2
    ports:
    - containerPort: 80
Application Access to the Token Secret
A web request to an application in Unified Analytics contains a token in the request header. When a user runs an application in Unified Analytics, the application runs in the user's namespace. If the application needs to access data or another service, the application can get the access token from the secret in the user's namespace and then use the token to make multiple requests for data access.

The following diagram shows the basic access flow between an application, secret, and data source:

Auth Tokens for External Client Application Access to External APIs

Some application APIs are exposed for use outside of the Unified Analytics cluster. These APIs are also authenticated by tokens. External client applications can obtain a token to talk to these external APIs.

If the external client application understands OIDC OAuth2 protocols, you can point the application to a particular OIDC client that Keycloak exposes. However, if you need to get a token and put the token in a particular header request that you are sending to an API, you can do this through the API endpoint in Unified Analytics that is exposed for Keycloak, by providing the user credentials (username and password) in a cURL POST request to obtain a token and then use the token to authenticate, as described in Obtaining Access Tokens with User Credentials.

The token is a short-lived token in JWT format. If the external client application will be running multiple API requests where authentication is required, the external client should get a refresh token from the API and then repeatedly request new access tokens. See Obtaining Refresh Tokens.

Auth Tokens for External Clients that Require Kubernetes API Credentials

If an external client can read secrets, the external client can obtain the access token from the secret in a user's namespace; however, this is not recommended as the default method. See Obtaining Access Tokens with a Kubernetes Secret.