Overview

UDS Core leverages Keycloak and Authservice to implify authentication and authorization for applications. These tools enable seamless user authentication experiences while supporting various OAuth 2.0 and OpenID Connect (OIDC) flows.

UDS Core automates Keycloak Client configuration, secret management, and advanced templating, offering scalable support for a wide range of applications and authentication scenarios. The chart below illustrates the basic logical connection between these concepts:

Single Sign-On Flow Chart

When a new UDS Package CR with the sso configuration gets deployed, the UDS Operator creates a new Keycloak Client. This process happens using the Keycloak Admin endpoint for managing Clients. The latter mode reads the Client Secrets from the keycloak-client-secrets Kubernetes Secret deployed in keycloak namespace. This Secret is managed automatically by the UDS Operator. Once the Keycloak Client is ready, and the enableAuthserviceSelector is defined in the spec, the UDS Operator deploys Istio Request Authentication and AuthorizationPolicy for both JWT and Request Headers. Both actions combined, enables seamless and transparent application authentication and authorization capabilities.

Rotating the UDS Operator Client Secret

The UDS Operator uses a dedicated Client in Keycloak. In some cases, the Client Secret needs to be rotated. In order to do so, you need to manually modify the keycloak-client-secrets Kubernetes Secret in the keycloak namespace and delete the uds-operator key. The UDS Operator will automatically re-create it.

Secret Pod Reload for SSO Clients

When SSO client secrets are updated or rotated, applications using these secrets may need to be restarted to pick up the new values. UDS Core provides a Secret Pod Reload mechanism that detects changes to secrets and restarts the relevant pods or deployments.

To enable this functionality for SSO client secrets, you can add the uds.dev/pod-reload: "true" label to the secret via the secretLabels field in your Package CR. When a secret with this label is updated, UDS Core will either:

Restart pods matching the selector specified in the uds.dev/pod-reload-selector annotation (which can be added via the secretAnnotations field), or
Automatically discover and restart pods that are consuming the secret through volume mounts, environment variables, or projected volumes

For more details on configuring Secret Pod Reload, see the Secret Pod Reload documentation or the Secret Templating documentation.

User Groups

UDS Core deploys Keycloak which has some preconfigured groups that applications inherit from SSO and IDP configurations. More details might be found in the Package CR spec.

Applications

Grafana

Grafana maps the groups from Keycloak to its internal Admin and Viewer groups.

Keycloak Group	Mapped Grafana Group
`Admin`	`Admin`
`Auditor`	`Viewer`

If a user doesn’t belong to either of these Keycloak groups the user will be unauthorized when accessing Grafana.

Overriding Grafana Groups

To override the Keycloak -> Grafana group mapping you can provide the following bundle overrides:

grafana:
  uds-grafana-config:
    values:
      # Allows access to Keycloak Client
      - path: sso.groups
        value:
          - KEYCLOAK_ADMIN_GROUP # name of an existing Keycloak group
          - KEYCLOAK_AUDITOR_GROUP # name of an existing Keycloak group
  grafana:
    values:
      # Sets the role mappings in grafana
      - path: grafana\.ini.role_attribute_path
        value: "contains(groups[], 'KEYCLOAK_ADMIN_GROUP') && 'Admin' || contains(groups[], 'KEYCLOAK_AUDITOR_GROUP') && 'Viewer' || 'Unauthorized'"

Neuvector

Neuvector maps the groups from Keycloak to its internal admin and reader groups.

Keycloak Group	Mapped Neuvector Group
`Admin`	`admin`
`Auditor`	`reader`

Overriding Neuvector Groups

To override the Keycloak -> Neuvector group mapping you can provide the following bundle overrides:

neuvector:
  uds-neuvector-config:
    values:
        # Sets this as an allowed group for the Keycloak Client and maps to Neuvector admin group
        - path: sso.adminGroups
          value:
            - KEYCLOAK_ADMIN_GROUP # name of an existing Keycloak group
        # Sets this as an allowed group for the Keycloak Client and maps to Neuvector reader group
        - path: sso.readerGroups
          value:
            - KEYCLOAK_AUDITOR_GROUP # name of an existing Keycloak group

Keycloak

All groups are under the UDS Core parent group. Frequently a group will be referred to as UDS Core/Admin or UDS Core/Auditor. In the Keycloak UI this requires an additional click to get down to the sub groups.

Single Sign-On Contents

Cookie Settings Privacy Policy