Keycloak implementation

Keycloak integrates an authorisation service implemented with OAuth 2.0, an identity service implemented with OpenID Connect, and provides advanced identity and access features such as single sign-on (SSO), multi-factor authentication (MFA), identity brokering, and federated identity. Authentication with OpenID Connect allows identity brokering through OpenID Connect and SAML, and identity federation through Kerberos and LDAP.

Identity and access management

Further information about HeartAI identity and access management may be found with the following documentation:

Keycloak authentication approaches

Authentication with Keycloak integrated OpenID Connect instances allow identity brokering through the OpenID Connect protocol and SAML, with additional support for identity federation and/or identity brokering through Kerberos and LDAP. This allows HeartAI instances of Keycloak to support authentication via identity brokering and/or identity federation to Active Directory services, such that system users may authenticate with for example their SA Health HAD identity. System users are also defined internal to the HeartAI domain and are managed by Keycloak directly.

The following HeartAI endpoints have access control flows that are managed by Keycloak:

Access control endpoint Access control flow
Red Hat OpenShift console OAuth 2.0 Authorization Code Grant
Keycloak console OAuth 2.0 Authorization Code Grant
Grafana console OAuth 2.0 Authorization Code Grant
Kiali console OAuth 2.0 Authorization Code Grant
Kibana console OAuth 2.0 Authorization Code Grant
Argo CD console OAuth 2.0 Authorization Code Grant
Red Hat Advanced Cluster Security console OAuth 2.0 Authorization Code Grant
Direct service endpoints OAuth 2.0 Client Credentials Grant
Indirect service endpoints OAuth 2.0 Authorization Code Grant
Proxied indirect service endpoints OAuth 2.0 Authorization Code Grant
Client endpoints OAuth 2.0 Authorization Code Grant
Proxied client endpoints OAuth 2.0 Authorization Code Grant

Keycloak access control patterns

The following Keycloak access control patterns represent some general approaches to managing access control:

HeartAI service-level and client-level deployments

HeartAI provides both service-level and client-level deployments to meet varying platform implementation requirements. Further information about these may be found with the following documentation:

Access control pattern Description
Direct service endpoint access control Direct interaction with a service endpoint. A user first authenticates with Keycloak to retrieve an access token and then the user provides the access token with a service request.
Proxied direct service endpoint access control Proxied direct interaction with a service endpoint. A user first authenticates with Keycloak to retrieve an access token and then the user provides the access token with a service request to a service proxy endpoint. The service proxy processes the request and forwards to the upstream service endpoint.
Indirect service endpoint access control Indirect interaction with a service endpoint. A user authenticates with Keycloak to access a client and to authorise the client to interact with the service on behalf of the user.
Proxied indirect service endpoint access control Proxied indirect interaction with a service endpoint. A user authenticates with Keycloak to access a client proxy and to authorise the client proxy, with the client proxy transferring access to the client and the client interacting with the service on behalf of the user.
Client endpoint access control Interaction with a client. A user authenticates with Keycloak to access the client.
Proxied client endpoint access control Proxied interaction with a client. A user authenticates with Keycloak to access a client proxy, with the client proxy transferring access to the client.

Keycloak direct service endpoint access control

The following example shows the access control flow for a client to interface with a service endpoint directly, with a direct client such as curl or wget. In this context the client is acting directly by end-user action, rather than on behalf of the end-user. Through these approaches a client may request an access token by providing client credentials, such as a client identity and client secret pair, to the token endpoint of OpenID Connect. This authorisation flow uses the OAuth 2.0 Client Credentials Grant. Following a successful authorisation flow, the client may pass the access token to corresponding protected system service endpoints via an Authorization: Bearer $ACCESS_TOKEN HTTP header.

The following figure shows the access control flow the direct service endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-direct-service-request.svg

Keycloak proxied direct service endpoint access control

The following example shows a similar access control flow to the above direct service endpoint interaction, with the access control component occurring at a service reverse-proxy and the access token transferred to the protected service following successful authentication. This approach is often used to provide access control to functionality-specific services, such as HeartAI analytics services, where the access control responsibility is delegated to the service reverse-proxy middleware.

The following figure shows the access control flow the proxied direct service endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-proxied-direct-service-request.svg

Keycloak indirect service endpoint access control

The following example shows the access control flow for a client to interface with a service endpoint indirectly, with an indirect client such as a web interface application or a desktop application. In this context the client is acting indirectly on behalf of the end-user, and the end-user should delegate authorisation to such a client. With this approach the corresponding client will perform the OAuth 2.0 Authorization Code Grant and attempt to authenticate the end-user by redirection to the Keycloak-integrated OpenID Connect service. The authenticated end-user will be prompted to delegate authority to the client for the scope of client permissions specified. The client may then request an access token from the OAuth 2.0 server by acting through the authorisation of the end-user. Following a successful authorisation flow, the client may pass the access token to corresponding protected system service endpoints via an Authorization: Bearer $ACCESS_TOKEN HTTP header.

The following figure shows the access control flow the indirect service endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-indirect-service-request.svg

Keycloak proxied indirect service endpoint access control

The following example shows the access control flow for a proxied client to interface with a service endpoint indirectly, with an indirect client such as a web interface application or a desktop application. In addition to the indirect client, a client reverse-proxy allows the indirect client to defer away responsibility for performing the authorisation flow itself. This approach is particularly useful for legacy clients that have a limited ability to independently perform the OAuth 2.0 Authorization Code Grant. The primary implementation with this approach is through the OAuth 2 Proxy. In this context the client proxy is acting indirectly on behalf of the end-user, and the end-user should delegate authorisation to such a client proxy. With this approach the corresponding client proxy will perform the OAuth 2.0 Authorization Code Grant and attempt to authenticate the end-user by redirection to the Keycloak-integrated OpenID Connect service. The authenticated end-user will be prompted to delegate authority to the client proxy for the scope of client proxy permissions specified. The client proxy may then request an access token from the OAuth 2.0 server by acting through the authorisation of the end-user. Following a successful authorisation flow, the client proxy may pass the access token to corresponding client, which itself may forward to access token onto protected system service endpoints.

The following figure shows the access control flow the proxied indirect service endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-proxied-indirect-service-request.svg

Keycloak client endpoint access control

The following example shows the access control flow for access to a client through the client endpoint. In this example, there is no authorisation for the client to access protected services on behalf of the user. The client may rather interact with public or non-protected service endpoints, or provide domain functionality directory within the client.

The following figure shows the access control flow the client endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-client-endpoint-request.svg

Keycloak proxied client endpoint access control

The following example shows a similar access control flow to the above client endpoint interaction, with the access control component occurring at a client reverse-proxy and the access token transferred to the protected client following successful authentication. This approach is often used to provide access control to functionality-specific services, such as HeartAI analytics services, where the access control responsibility is delegated to the client reverse-proxy. This approach is particularly useful for legacy clients that have a limited ability to independently perform the OAuth 2.0 Authorization Code Grant. The primary implementation with this approach is through the OAuth 2 Proxy.

The following figure shows the access control flow the proxied client endpoint interaction. The components to the right of Keycloak are protected by the access control:

heartai-proxied-client-request.svg

Keycloak client registration

Keycloak requires clients of HeartAI system services to register before they may authenticate end-users or request authorisation tokens. For increased security, clients may only register as confidential clients, and the corresponding client must secure its client ID and client key. The client ID and client key enables the client to authenticate against the Keycloak server as part of its communication to Keycloak.

Keycloak token specification

The HeartAI system supports identity tokens and access tokens as encryptable Base64-encoded JSON Web Tokens (JWTs). JWTs are a component of the JavaScript Object Signing and Encryption (JOSE) specifications, with related specifications as follows:

JOSE specification Description Standard Reference
JSON Web Signature (JWS) Digital signature standard for JSON objects. RFC 7515 https://datatracker.ietf.org/doc/html/rfc7515
JSON Web Encryption (JWE) Encryption standard for JSON objects. RFC 7516 https://datatracker.ietf.org/doc/html/rfc7516
JSON Web Key (JWK) Format standards for JWS and JWE keys. RFC 7517 https://datatracker.ietf.org/doc/html/rfc7517
JSON Web Algorithms (JWA) Cryptographic standards for JWS and JWE keys. RFC 7518 https://datatracker.ietf.org/doc/html/rfc7518
JSON Web Token (JWT) Consists of two Base64-encoded JSON objects, comprised of a header and a body, and any extensions such as JWS. RFC 7519 https://datatracker.ietf.org/doc/html/rfc7519

An example decoded JWT access token is shown following (with the signing key omitted):

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "vBCGRzQBhYrQ1a6SQPR80YLbMINNhPrRwtaArDRNlYs"
}

Body

{
  "exp": 1600235151,
  "iat": 1600234551,
  "jti": "3b7583d8-0ee2-41fa-9886-0b4dea70b92b",
  "iss": "http://127.0.0.1:9990/auth/realms/heartai",
  "aud": "account",
  "sub": "c28bd3a0-2617-400a-a5e3-3eef0af12eb8",
  "typ": "Bearer",
  "azp": "heartai",
  "session_state": "a0343af7-7784-45b8-913e-956879b67e8c",
  "acr": "1",
  "allowed-origins": [
    "http://localhost:14000"
  ],
  "realm_access": {
    "roles": [
      "offline_access",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "email profile",
  "email_verified": true,
  "name": "heartai",
  "groups": [
    "admin",
    "heartai",
    "shiny-adjudication-portal-developer",
    "shiny-adjudication-portal-user",
    "shiny-records-developer",
    "shiny-records-user",
    "shiny-reports-developer",
    "shiny-reports-user"
  ],
  "preferred_username": "heartai",
"email": "[email protected]"
}

Keycloak token signing

HeartAI identity tokens and access tokens currently support digital signing (with encryption methods also in development). The implemented signing algorithm is SHA-256.

Keycloak token validation

Protected resources can validate these tokens through for example token introspection.

For HeartAI service-level deployments resources this approach is coordinated with the PAC4J security packages, through which access tokens may be validated to provide access to the corresponding resource.

Keycloak console for administrator login

The following image shows the Keycloak web interface login screen for the administrator console. The web interface login supports:

  • Authentication through a login mechanism that is centrally managed by Keycloak, managing risk away from client applications to a well-defined and consistent security process.
  • Strong default HTTP security controls.
  • Support for multi-factor authentication (MFA).

Keycloak_login

Keycloak console for realm settings: General

The following image shows the Keycloak web interface for realm settings. Keycloak realms are namespaced environments that allow an individual Keycloak instance to provide multi-tenancy identity and access management solutions. The web interface for realm settings provides:

  • An ability to review and edit information about the realm.
  • Configuration options for:
    • The realm login process.
    • Certificates and keys.
    • Realm email provider integration.
    • Realm theming.
    • Data caches and temporary storage.
    • Identity, authorisation, access, and refresh tokens.
    • Client registration.
    • Security defence mechanisms.

Keycloak_realm

Keycloak console for realm settings: Token

The following image shows the Keycloak realm settings web interface for tokens. Keycloak tokens Base64-encoded JSON Web Tokens (JWTs), as a component of the JavaScript Object Signing and Encryption (JOSE) specifications . The realm settings web interface for tokens provides:

  • Realm-level token configuration options, including:
    • Default signature algorithm.
    • Refresh token revocation.
    • SSO session idle time.
    • SSO session maximum time.
    • SSO session idle remember me time.
    • SSO session maximum remember me time.
    • Offline session idle time.
    • Limitations for offline session maximum time.
    • Client session idle time.
    • Client session maximum time.
    • Access token lifespan.
    • Access token lifespan for implicit flow.
    • Client login timeout.
    • Login timeout.
    • Login action timeout.

Keycloak_realm_tokens

Keycloak console for realm clients

The following image shows the Keycloak realm clients web interface. Keycloak clients may request end-user authentication for the participation in single sign-on, and may further request end-user delegation of authority to function on behalf on the end-user, typically with a limited scope of delegated permissions. The realm clients web interface provides:

  • An overview of realm clients, including:
    • The client ID.
    • Whether the client is enabled.
    • The base URL of the client.
    • Actions to manage the client.

Keycloak_clients

Keycloak console for realm client settings

The following image shows the Keycloak realm clients web interface for client settings. Keycloak realm clients are configurable with a range of settings. The realm clients web interface for client settings provides:

  • Client-level configuration options, including:
    • The client ID.
    • The client name.
    • The client description.
    • Whether the client is enabled.
    • Whether the client requires end-user authorisation consent.
    • The client login theme.
    • The client authentication protocol.
    • The client access type.
    • Whether the OAuth 2.0 Authorization Code Grant is enabled.
    • Whether the OAuth 2.0 Implicit Grant is enabled.
    • Whether the OAuth 2.0 Password Grant is enabled.
    • The root URL.
    • The valid redirect URIs.
    • The base URL.
    • The admin URL.

Keycloak_client_settings

Keycloak console for realm client scopes

The following image shows the Keycloak realm client scopes web interface. Keycloak client scopes are a mechanism to limit the authority that an end-user delegates to the client, such that the client is provided with the minimum necessary permissions to perform its functionality. The realm client scopes web interface provides:

  • An overview of realm client scopes, including:
    • The client scope name.
    • The client scope protocol.
    • The client scope GUI display order.
    • Actions to modify or delete the client scope.

Keycloak_client_scopes

Keycloak console for realm roles

The following image shows the Keycloak realm roles web interface. Keycloak roles are associated to realm users for the purposes of permissions assignment. The realm roles web interface provides:

  • An overview of realm rolmes, including:
  • The role name.
  • Whether the role is a composite role.
  • A description of the role.
  • Actions to modify or delete the role.

Keycloak_realm_roles

Keycloak console for realm authentication flows

The following image shows the Keycloak authentication flows web interface. Keycloak authentication flows declare the authentication process for all authentications and actions that occur during end-user registration, authentication, and authorisation. The authentication flows web interface provides:

  • An overview of configured authentication flows.
  • The process requirement of the authentication flow, including:
    • Required
    • Alternative
    • Disabled
    • Conditional

Keycloak_authetication

Keycloak console for user groups

The following image shows the Keycloak user groups web interface. Keycloak user groups manage collections of user attributes and role mappings. Users may belong to zero or more groups, and inherit the user attributes and role mappings assigned to each group. The user groups web interface provides:

  • An overview of configured user groups.

Keycloak_user_groups

Keycloak console for users

The following image shows the Keycloak users web interface. Keycloak users represent the identity principals within Keycloak, and are the primary entity corresponding to OpenID Connect authentication. The users web interface provides:

  • An overview of current users, including:
    • The user ID.
    • The user username.
    • The user email.
    • The user last name.
    • The user first name.
    • Actions to edit, impersonate, or delete the user.

Keycloak_users