Identity & Authorization
UDS Core uses Keycloak as its central identity provider. Applications can own their OIDC or SAML authentication flow and use OAuth2 for delegated authorization, or UDS Core can provide operator-managed Authservice protection at the Istio mesh boundary. Choose the pattern based on the application requirements and the desired ownership boundary.
Authservice is a first-class security option, not only a compatibility mechanism for applications without native SSO. It keeps the browser OIDC implementation and enforcement in the platform, which can reduce application-specific mistakes and maintenance. This separation can provide a stronger security posture when a native integration is difficult to assess or maintain. Native SSO remains appropriate when the application must own public and protected routes, session behavior, or domain-specific authorization.
Why centralized identity?
Section titled “Why centralized identity?”Applications deployed on regulated platforms should not each maintain independent identity systems or repeat the same authentication implementation. Centralizing identity provides:
- A single audit trail: all authentication events flow through one system
- Consistent access control: group membership and role assignments apply uniformly across services
- Reduced implementation burden: application teams declare SSO requirements in a
PackageCR; the operator handles client registration and, when Authservice is enabled, the browser OIDC flow and token enforcement
These benefits apply to both native SSO and Authservice. Authservice adds platform-owned browser authentication and mesh-level enforcement without requiring each application to implement that flow.
The SSO model
Section titled “The SSO model”Keycloak is the identity provider. It manages users, groups, and OAuth2/OIDC clients, and federates to external identity providers (Azure AD, Google, LDAP) when teams need to connect an existing directory service.
The UDS Operator automates Keycloak client registration. When a Package CR declares an sso block, the operator:
- Creates a Keycloak OIDC client with the correct redirect URIs
- Stores the client credentials in a Kubernetes secret in the application namespace
The UDS Operator supports two SSO integration patterns.
Applications that implement OIDC natively use the credentials from the operator-managed secret to speak directly to Keycloak. The application handles login redirects, token validation, and session management itself. Native SSO can be the right choice for a mature application with a robust integration and application-specific identity requirements.
Use native SSO when:
- The application needs to combine public and authenticated routes
- The application needs to control login, logout, or session behavior
- The application requires an application-specific machine-authentication flow that cannot use platform-issued tokens
- The application owns fine-grained authorization or user-management behavior
Authservice handles the browser OIDC flow at the mesh boundary before requests reach the application. The UDS Operator creates the Authservice chain and the required Istio RequestAuthentication and AuthorizationPolicy resources from the Package CR. In ambient mode, the operator also creates and manages the waypoint proxy required for L7 enforcement.
Use Authservice when:
- The platform should own the OIDC flow and authentication enforcement
- The application is legacy, off-the-shelf, or its native OIDC implementation is difficult to assess or maintain
- The application should receive complete protection without adding authentication code
- Consistent platform-level policy and group-based access should apply across applications
Authservice does not remove application visibility into identity. Authservice forwards the authenticated OIDC ID token to the application, while Istio preserves an inbound bearer token when one is already present. For Authservice-protected workloads, groups.anyOf provides a platform-level coarse-grained gate that determines whether a user can reach the workload at all. After access is granted, application code can use the forwarded identity and, when configured, groups claims to enforce fine-grained authorization based on application data, resource ownership, business roles, or features. See Register and customize SSO clients for the group membership mapper. Istio and Authservice remain part of the platform observability path.
Authservice-protected workloads can also use Keycloak-issued service-account tokens for machine-to-machine access. groups.anyOf restrictions apply during the browser-based authentication flow and do not restrict client-credentials callers. If machine identities need separate authorization, enforce it with an application or mesh policy. See Configure service account clients for the required audience mapping.
For COTS applications, evaluate native OIDC or SAML based on the application’s actual session, group, and authorization behavior. Protocol support alone does not establish that native integration is the best fit.
Authentication and authorization boundaries
Section titled “Authentication and authorization boundaries”Authservice provides authentication enforcement at the platform boundary. The Package CR can declare group-based access requirements for an SSO client, which UDS Core enforces as a coarse-grained gate during browser-based authentication. Authservice does not replace application user management or fine-grained, domain-specific authorization. After the platform grants access, application teams still own decisions that depend on application data, business roles, resource ownership, or workflow state.
Authservice protection is intended for complete protection of the selected workload. In the current UDS Core implementation, application traffic to a protected workload requires a valid UDS JWT. The operator adds exceptions for configured Prometheus endpoints and the sidecar metrics endpoint. If an application requires unauthenticated routes or a machine-authentication flow that cannot use a Keycloak-issued service-account token, evaluate native SSO or another supported application design before enabling Authservice.
Platform groups
Section titled “Platform groups”UDS Core pre-configures two Keycloak groups that drive access to platform admin interfaces:
| Group | Purpose | What it protects |
|---|---|---|
/UDS Core/Admin | Platform administrators | Grafana admin, Keycloak admin console, Alertmanager |
/UDS Core/Auditor | Read-only platform access | Grafana viewer, log browsing |
Application teams can define their own group-based restrictions in their Package CR using the groups.anyOf field. During the browser-based authentication flow, an SSO client configured with groups.anyOf: ["/UDS Core/Admin"] will reject users who are not members of that group, even if they are otherwise authenticated. Client-credentials callers are not subject to this restriction; authorize machine identities separately.
Keycloak configuration layers
Section titled “Keycloak configuration layers”UDS Core supports three layers of Keycloak customization, each suited to different use cases:
| Approach | Use for | Requires image rebuild? |
|---|---|---|
| Helm chart values | Session policies, account settings, auth flow toggles | No |
| UDS Identity Config image | Custom themes, plugins, CA truststore | Yes (themes and plugins apply when the Keycloak pod restarts; no realm re-import needed) |
| OpenTofu / IaC | Managing groups, clients, IdPs post-deploy | No |
Most operational configuration (session timeouts, lockout policies, authentication flows) is handled via Helm chart values without rebuilding anything. Custom themes, plugins, and truststore changes require building and deploying a custom UDS Identity Config image. Post-deploy management of Keycloak resources (groups, clients, IdPs) can be automated with OpenTofu.