Calabi Documentation

Calabi

Single-host disconnected OpenShift on nested KVM, with intent-first docs for architecture, orchestration, auth, and recovery.

AUTOMATION FLOWORCHESTRATION PLUMBINGMANUAL PROCESSORCHESTRATION GUIDEAD / IDM POLICY MODELDOCS MAP

Authentication Model

Purpose

This doc defines the supported authentication and authorization model.

It answers:

  • what authenticates users
  • what authorizes users
  • what AD, IdM, Keycloak, OpenShift, and RHEL each own
  • what the breakglass path is
  • how the current model aligns with public zero-trust guidance

The planned future evolution where AD becomes the user and source-group system of record while IdM local groups remain the authorization boundary is tracked separately in AD / IDM POLICY MODEL.

Current Supported Model

The supported default platform auth baseline is:

  • HTPasswd breakglass for recovery
  • Keycloak OIDC for human login
  • IdM as the identity and policy hub
  • OpenShift authorization through group claims
  • AAP authorization through Keycloak groups plus gateway authenticator maps
  • direct OpenShift LDAP auth disabled by default
  • direct AAP LDAP retired from the preferred clean-build path

The current live IdM group descriptions are intentionally terse so operators can distinguish access groups from AD source groups at a glance in the web UI and ipa output.

At a high level:

flowchart LR User[Human User] --> OCP[OpenShift OAuth] User --> AAP[AAP Gateway] OCP --> KC[Keycloak] AAP --> KC KC --> LDAP[IdM compat LDAP] LDAP --> IDM[IdM] IDM --> AD[AD trust] KC --> Token[OIDC token with groups] Token --> RBAC[OpenShift RBAC] Token --> AAPRBAC[AAP authenticator maps]

The current repo proves two supported login cases:

  • native IdM user -> Keycloak -> OpenShift
  • AD-trusted user -> IdM trust/compat -> Keycloak -> OpenShift
  • AD-trusted user -> Keycloak -> AAP

Authorization Boundary

The most important rule in the current model is:

  • authentication is brokered through Keycloak
  • authorization is granted by group membership
  • OpenShift and RHEL consume IdM-side policy groups

Today those IdM local groups are:

IdM group Current meaning Current access
openshift-admin OpenShift platform admin Bound to OpenShift cluster-admin
admins Linux/RHEL admin Granted passwordless sudo by admins-nopasswd-all
virt-admin reserved virtualization role group exists; no broad privilege binding documented as default
developer reserved non-admin role group exists; no broad privilege binding documented as default

That means:

  • OpenShift cluster-admin is granted to the group openshift-admin
  • RHEL sudo is granted to the group admins
  • privilege is not supposed to be inferred from broad ambient trust alone

Component Responsibilities

AD currently provides:

  • optional trusted external identities
  • source-side AD users and AD groups for the trust path

AD does not directly grant OpenShift RBAC or IPA sudo in the current supported model.

IdM

IdM currently provides:

  • identity hub for native lab users
  • trust relationship to AD
  • compat-tree visibility for trusted users and groups
  • local policy groups such as openshift-admin and admins
  • RHEL-side policy such as the admins-nopasswd-all sudo rule

Keycloak

Keycloak currently provides:

  • web login broker for OpenShift
  • LDAP federation to the IdM compat tree
  • OIDC token issuance with groups claims

Keycloak is not the long-term source of authorization policy. It emits what the IdM-side policy model gives it.

OpenShift

OpenShift currently provides:

  • OAuth/OIDC login integration
  • claim-to-group mapping from the OIDC groups claim
  • RBAC binding of openshift-admin to cluster-admin
  • a separate HTPasswd breakglass path

AAP

AAP currently provides:

  • management-plane access through Keycloak OIDC
  • gateway authenticator and authenticator-map enforcement
  • superuser elevation from the emitted admin access group

In the validated clean-build path:

  • AAP uses the Keycloak realm already deployed for cluster SSO
  • the AAP client ID is aap
  • the required admin group is access-openshift-admin
  • direct AAP LDAP is not the supported default path

RHEL Hosts

IdM-enrolled RHEL hosts currently provide:

  • SSSD-backed user resolution
  • IdM policy enforcement
  • sudo authorization through IdM local groups

Current Login Flows

Native IdM User To OpenShift

sequenceDiagram participant U as Native IdM User participant O as OpenShift OAuth participant K as Keycloak participant I as IdM compat LDAP U->>O: access console O->>K: OIDC redirect K->>U: login form U->>K: credentials K->>I: user and group lookup I-->>K: IdM identity and groups K-->>O: OIDC token with groups O->>O: map groups to RBAC O-->>U: session established

AD-Trusted User To OpenShift

sequenceDiagram participant U as AD-Trusted User participant O as OpenShift OAuth participant K as Keycloak participant I as IdM compat LDAP participant T as IdM trust to AD U->>O: access console O->>K: OIDC redirect K->>U: login form U->>K: credentials K->>I: resolve trusted user and groups I->>T: trusted identity path T-->>I: user and group visibility I-->>K: trusted identity and groups K-->>O: OIDC token with groups O->>O: map groups to RBAC O-->>U: session established

Breakglass

The breakglass path is intentionally separate from IdM, AD, and Keycloak.

It exists so cluster access remains available if:

  • Keycloak is down
  • IdM is down
  • AD is down
  • the trust path is degraded

That is why the repo keeps:

  • a local HTPasswd identity provider
  • a local breakglass admin binding

This is not a second preferred human-login path. It is a recovery control.

Zero-Trust Alignment

This model is better described as zero-trust aligned than zero-trust complete.

Why it aligns:

  • authentication and authorization are separated
  • broad network location is not the trust boundary
  • applications authenticate users directly rather than trusting network placement
  • authorization is group-driven and explicit
  • least privilege is expressible through narrowly scoped policy groups
  • breakglass is isolated from the primary identity path

Why it is not sufficient on its own:

  • zero trust also depends on session policy, logging, monitoring, MFA posture, device posture, and continuous validation
  • those controls are larger than this repo’s auth topology alone

Standards And Guidance Alignment

This architecture is not presented as formal certification or compliance by itself. It is, however, directionally aligned with the following public guidance:

The practical synergy is:

  • least-privilege group-based authorization
  • explicit application login rather than perimeter trust
  • unique identities
  • isolated emergency access
  • cleaner separation between identity proof and authorization policy

Planned Evolution

The future direction under consideration is:

  • AD as the user and source-group system of record
  • IdM external groups bridging trusted AD groups into local IdM policy groups
  • local IdM groups remaining the authorization boundary for both RHEL and OpenShift

The first implementation slice for that bridge now exists in the orchestration:

  • the mapping contract lives in vars/global/ad_group_policy.yml
  • the AD trust play can create the mapped IdM external groups and nest them into the target local groups

The remaining proof is consumer-side:

  • confirm trusted AD users inherit the intended local IdM groups
  • confirm RHEL sudo flows from those local groups
  • confirm Keycloak emits those local groups into the OpenShift OIDC groups claim

That future model is documented in AD / IDM POLICY MODEL.

It should be treated as planned work, not current live behavior.

Continue