Identity and Access Management

Describes identity and access management in HPE Ezmeral Unified Analytics Software.

HPE Ezmeral Unified Analytics Software uses Keycloak as its OIDC provider for identity and access management. Keycloak secures access to HPE Ezmeral Unified Analytics Software and applications through authorization, authentication, and SSO protocols. Users authenticate to Keycloak instead of authenticating to multiple application services.

The following steps describe the basic access flow for a user signing in to HPE Ezmeral Unified Analytics Software application services:
  1. A user goes to the application URL with their web browser.
  2. If the user has not yet signed in to an application in this cluster, the user's browser is redirected to a sign-in page that is managed by the cluster's Keycloak instance.
  3. The user enters their credentials (username and password) at the sign-in page.
  4. Keycloak verifies the user's credentials against those in the organization's AD/LDAP server.
  5. If the provided credentials are valid, the user's browser is redirected to the originally requested application URL. The browser receives one or more cookies. The cookies represent active sessions with Keycloak and the application.
  6. The application is (through a secure back channel) provided with an access token that encapsulates the user's authentication and their authorized roles within the cluster.
  7. The application internally uses the access token to determine the user's identity and authorization. Some applications may also use this token to communicate with other services within the cluster.
Once a user signs in to HPE Ezmeral Unified Analytics Software, SSO enables the user to seamlessly switch between different authentication-requiring application services while the session is valid. For example, the user can open the Feast application without reentering their credentials. However, if the user signs out of HPE Ezmeral Unified Analytics Software and then tries to access the Feast endpoint URL, the OIDC provider (Keycloak) prompts the user to reenter their credentials.

If the browser is left idle in the main interface for more than one hour, the user is automatically signed out. If more than one week has passed since the user has authenticated, the user must re-enter credentials.

Architecture

The following diagram shows two access flows - one for application A and one for application B. Application A is an OIDC-native application that understands how to integrate with a provider such as Keycloak for user authentication and authorization. Application B is not an OIDC-native application.

The auth proxy interacts with Keycloak to ensure that access to application B is only available to authenticated users. The proxy also provides information about user identity and roles to application B through HTTP headers.

Note that although application A is OIDC-native, it also sits behind the auth proxy. This ensures that, regardless of how the application itself manages sessions and access tokens, a user will be immediately blocked from accessing the application if an admin has revoked the user's cluster access.



The following sections describe the components in the access flow diagram:
Ingress

Istio provides the service mesh, request routing, policy enforcement, and the proxies used to intervene in service requests.

The Istio Ingress gateway performs TLS termination for all incoming traffic and validates JSON Web Tokens (JWTs) issued by Keycloak. External client access to application services is TLS-terminated at the Istio Ingress gateway, then routed to internal service endpoints with mutual TLS encryption. Internal service communications also use TLS.

Communication to internal services (from the gateway or from applications) is policy-restricted to a set of allowed clients. The clients are identified by SPIFFE credentials. Istio and SPIRE manage the SPIFFE credentials.

Routing

Istio routes traffic from the Ingress gateway to the appropriate application service based on the DNS name destination of the traffic. During HPE Ezmeral Unified Analytics Software installation, the administrator can set up a DNS domain that includes the entire sub-domain DNS (sub-domain wild card A record) to route all domain traffic to the Ingress of the application environment.

Auth Proxy (Oauth2 Proxy)
Oauth2 Proxy gates access to applications that are not OIDC aware. It gives those applications information about the user's token and claims in the token by inserting header values (individual claim values as well as the entire token). The primary header values populated by the proxy are:
  • Authorization, from "Bearer" prefixed to the entire token in JSON Web Token (JWT) format
  • X-Auth-Request-Preferred-Username, from the preferred_username claim
  • X-Auth-Request-Email, from the email claim
  • X-Auth-Request-Groups, from the groups claim
(Some additional headers are populated with the same username and groups values for backwards compatibility reasons.)

Oauth2 Proxy is also used with OIDC-native apps in order to promptly and universally enforce administrative revocation of user access.

Oauth2 Proxy hooks into application traffic through Istio authorization policies. The Istio authorization policy forces traffic to go through the proxy before accessing services in HPE Ezmeral Unified Analytics Software.

OIDC Client

An OIDC client provides a set of API endpoints used for interactions with the OIDC provider, such as authenticating users.

The OIDC client instance used by browser-accessed applications in an HPE Ezmeral Unified Analytics Software cluster is represented by the ID ua and a unique generated secret. This secret is passed to application installation scripts during initial setup, then stored in a Kubernetes secret for later use in deploying applications that you import into HPE Ezmeral Unified Analytics Software.

For any OIDC-native application that integrates with this OIDC client, Keycloak must be configured to be aware of an application-specific "callback URL" that will be used as part of the OIDC flow. For applications imported after initial setup, you must modify Keycloak's list of allowed callback URLs using the Keycloak web interface or REST API.

A separate OIDC client with the ID ua-grant (no client secret) is available, which can be used from a CLI or program to directly exchange user credentials for tokens. This client implements the resource owner password credentials grant flow, or what Keycloak documentation calls Direct Access Grant.

The ua-grant OIDC client is used for two main purposes, both of which apply to REST APIs (or other non-browser service endpoints) exposed to out-of-cluster users:
  • If the service requires token-based authentication, the out-of-cluster caller can use the ua-grant client to obtain a token which is then provided to the service. Note that it is the caller's responsibility to securely store and otherwise manage the token.
  • If the service requires username/password authentication, perhaps because of constraints from existing service clients, the service can use the ua-grant client internally to validate the user and also obtain a token that can be used to communicate with other cluster services.

OIDC Provider (Keycloak)

Keycloak sources user information from the internal or external AD/LDAP directory. Keycloak imports user data from the AD/LDAP server on an hourly basis. The following user attributes are mapped from the AD/LDAP server to Keycloak:

  • username
  • email
  • full name
NOTE
The specific attribute names representing these three items are provided in the AD/LDAP configuration details when the HPE Ezmeral Unified Analytics Software is installed.

Users authenticate with Keycloak instead of authenticating with individual applications. Keycloak assigns a special Keycloak ID to each user and supplies applications with tokens in JWT format. Each token contains claims that describe the user's authenticated identity and other attributes.

The claims mapped from the AD/LDAP user attributes, respectively, are:
  • preferred_username
  • email
  • name, given_name, and family_name (The latter two formed by splitting "name" at the first space.)

The token also contains a groups claim. This claim contains a list of the user's group memberships that are important to Keycloak or to applications. Currently, the only application-significant group is admin, which is present in the groups list if the user has been designated as an Administrator of the cluster.

For additional information about Keycloak, including how to access the Keycloak Admin Web Console, refer to the Keycloak Admin Web Console section in Security.

Internal/External AD/LDAP

See AD/LDAP Servers and Working with Certs and the Truststore.

User Management (Management Operator)
An administrator manages users through the HPE Ezmeral Unified Analytics Software UI; for example, creating users and assigning roles. These operations result in the creation of custom Kubernetes resources (representing queries and user configuration) that are processed by the backend user management service. This service has credentials for the Keycloak administrative REST API, the Kubernetes API, and (if applicable) the internal LDAP server. Tasks performed by this service include:
  • Accessing the internal LDAP server to create and delete users.
  • Marking a user in Keycloak to enable or disable their ability to authenticate into the cluster.
  • Assigning roles to users in Keycloak.