Identity and access management

Identity and access management overview

HeartAI provides consolidated identity and access management by implementing the Keycloak platform. Keycloak integrates an authorisation service with OAuth 2.0, an identity service 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 the OpenID Connect and SAML, and identity federation through Kerberos and LDAP.

Users typically interact with HeartAI applications and services through well-defined endpoints that manage authentication and authorisation in an integrative way. For HeartAI web-based applications, this involves single-sign on functionality with information about the authentication state securely stored within a web browser session. For HeartAI service endpoints, the user is often required to manually interact with a HeartAI Keycloak server instance to retrieve an access token to then include this token in the request to a service endpoint. Throughout either approach, the application or service will further confirm the validity of the user identity and access token, such as the token having the correct role or group assignments, the token expiry time, the correct digital signatures, and will accept or reject each token on a per-request basis.

The ability to broker and federate identity provides additional capabilities with HeartAI deployments within host organisations. These approaches allow the user of a host organisation to authenticate with a HeartAI Keycloak instance by deferring authority to the identity provider of the organisation. For example, with the HeartAI deployment to the SA Health digital environment, SA Health users may authenticate with the corresponding HeartAI Keycloak instance by providing their SA Health Health Active Directory (HAD) identity credentials. Further, if the user is logged into a current Active Directory session, this login process is automated. These approaches are particularly important for maintaining process management and governance within a host organisation, where HeartAI can defer to the authority of these processes through identity brokering or identity federation. In this way users may have their scope of permissions defined by the host organisation and these permissions will be mapped through a HeartAI Keycloak instance to within the corresponding HeartAI environment.

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.

Software: Keycloak implementation

Further information about the HeartAI implementation of Keycloak may be found with the following documentation section:

Red Hat Single Sign-On

The HeartAI identity and access management implementation is currently migrating to the downstream supported version of Keycloak: Red Hat Single Sign-On.

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 browser-based access control

Browser-based access control is the typical approach for interacting with HeartAI service and client endpoints. General end-users will most often interact with client applications such as dashboards or mobile applications.

Keycloak browser-based access control patterns

Further information about browser-based access control patterns may be found with the following sections:

On first login to the these components, end-users will typically proceed with an authorisation flow similar to the following example login process for the Azure Red Hat OpenShift web console:

An end-user reaches the Azure Red Hat OpenShift web console and is greeted with the login landing page:

openshift-login.png

On selecting keycloak, the end-user is directed to Keycloak to submit authentication details:

openshift-login-2.png

On first login, the end-user will be asked to update their password:

openshift-login-3.png

Following, multi-factor authentication is registered:

openshift-login-4.png

The end-user account details may be modified:

openshift-login-5.png

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-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.

Service architecture and service interfaces

Please refer to the documentation sections Service architecture and Service interfaces for an overview of approaches for interfacing with system services.

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.png

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.png

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.png

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.png

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.png

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.png

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.png

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-authentication.png

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.png

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.png

OpenShift identity provision and access control

HeartAI instances of OpenShift integrate natively with the HeartAI implementation of Keycloak. This allows users to authenticate with OpenShift through the OpenShift OAuth 2.0 and OpenID Connect framework. With support for federated identity, users will also be able to authenticate with their Microsoft Azure Active Directory identity.

The OpenShift identity provider allows role-based access control (RBAC) at the following levels:

RBAC level Description
Cluster RBAC Roles and bindings that are applicable across all projects. Cluster roles exist cluster-wide, and cluster role bindings can reference only cluster roles.
Local RBAC Roles and bindings that are scoped to a given project. While local roles exist only in a single project, local role bindings can reference both cluster and local roles.

Access control is managed with the following authorisation types:

Authorisation type Description
Rules Sets of permitted verbs on a set of objects. For example, whether a user or service account can create pods.
Roles Collections of rules. You can associate, or bind, users and groups to multiple roles.
Bindings Associations between users and/or groups with a role.

The following general roles exist within an OpenShift instance:

Role Description
admin A project manager. If used in a local binding, an admin has rights to view any resource in the project and modify any resource in the project except for quota.
basic-user A user that can get basic information about projects and users.
cluster-admin A super-user that can perform any action in any project. When bound to a user with a local binding, they have full control over quota and every action on every resource in the project.
cluster-status A user that can get basic cluster status information.
edit A user that can modify most objects in a project but does not have the power to view or modify roles or bindings.
self-provisioner A user that can create their own projects.
view A user who cannot make any modifications, but can see most objects in a project. They cannot view or modify roles or bindings.

Corresponding roles are applied to HeartAI administrators and developers in relation to their access to the OpenShift environment.

References

Further information about these approaches may be found with the following external references:

Identity and access management policy

HeartAI provides a variety of platform environments and functionalities with the ability to interact with these being dependent on the user’s identity. These identities are managed by an identity management framework that assigns users to varying groups and roles with a corresponding allocation of permissions. This framework is used to constrain user access in alignment with their assigned permissions and is generally intended to operate with a minimum-necessary permissions allocation. HeartAI administrators and developers typically have a greater level of access to internal HeartAI platform environments, such as operational environments, elevated data server access, and logging, monitoring, and observability systems. HeartAI end-user access is often designated for application interaction corresponding to the user’s role and use-case.

HeartAI implements integrated functionality for identity and access management. This includes support for authentication, authorisation, token exchange, identity brokering, identity federation, and multi-factor authentication. Through these approaches HeartAI users are categorised through a role-based access control (RBAC) mechanism. In addition, identity and access management frameworks are further extended by integration with HeartAI logging, monitoring, and observability systems, such that important identity and access event information is recorded and analyses. This includes the recording and auditing of login events, token requests, token rotations, token revocations, failed authentications and authorisations, unusual pattern detection, and behavioural profiling.

Within South Australian health system digital environments, HeartAI supports identity brokering and identity federation with existing identity and access providers. This allows HeartAI to authenticate and authorise users through these existing providers, such as with SA Health Health Active Directory (HAD) identity and service principal accounts. Identity information and corresponding permissions may be issued through brokering or federation from these providers such that existing identity management and credentialing processes are maintained.

Policy: Identity and access management

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

HeartAI access control environments

The following is a list of HeartAI environments and their corresponding access control patterns:

HeartAI access control environment Access control pattern(s)
Hello world service Direct service endpoint access control
HIB interface service Direct service endpoint access control
HIB FHIR translation service Direct service endpoint access control
RAPIDx AI service Direct service endpoint access control
RAPIDx AI analytics Direct service endpoint access control
Proxied direct service endpoint access control
SAVCS service Direct service endpoint access control
SAVCS application Proxied client endpoint access control
Proxied indirect service endpoint access control
SAVCS analytics Direct service endpoint access control
Proxied direct service endpoint access control
Red Hat OpenShift console Proxied client endpoint access control
Proxied indirect service endpoint access control
Keycloak console Proxied client endpoint access control
Proxied indirect service endpoint access control
Grafana console Proxied client endpoint access control
Proxied indirect service endpoint access control
Kiali console Proxied client endpoint access control
Proxied indirect service endpoint access control
Kibana console Proxied client endpoint access control
Proxied indirect service endpoint access control
Argo CD console Proxied client endpoint access control
Proxied indirect service endpoint access control
Red Hat Advanced Cluster Security console Proxied client endpoint access control
Proxied indirect service endpoint access control

Specification references

HeartAI identity and access management refers to the following specifications:

The OAuth 2.0 Authorization Framework

JSON Web Security