Skip to content

Identity

This guide declares OpenBao identities in Kubernetes: entities and groups, the aliases that link logins to them, group membership, and OpenBao as an OIDC provider for other applications.

Before you begin

A Ready connection whose OpenBao policy allows the identity/ paths of the kinds you use (OpenBao policy: platform operator lists them). Aliases also need the auth mounts they refer to.

1. Create entities and groups

An Entity is a person or a service; a Group gives policies to its members. An internal group gets members through GroupMembership; an external group gets them from an identity provider through a GroupAlias:

# Identity entities for two people, with policies and metadata; logins are linked to them by EntityAlias resources.
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Entity
metadata:
  name: obco-alice
  namespace: openbao-config
  labels:
    obco.example.com/team: platform
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Orphan
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  name: obco-alice
  policies:
    - obco-reader
    - obco-writer
  metadata:
    team: platform
    email: alice@example.com
  disabled: false
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Entity
metadata:
  name: obco-bob
  namespace: openbao-config
  labels:
    obco.example.com/team: platform
spec:
  connectionRef:
    name: openbao
  policies:
    - obco-reader
# Internal identity groups that grant policies to their members (added with GroupMembership), plus an external
# group for an identity provider group.
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Group
metadata:
  name: obco-developers
  namespace: openbao-config
  labels:
    obco.example.com/role: developers
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Orphan
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  name: obco-developers
  type: internal
  policies:
    - obco-reader
    - obco-writer
  metadata:
    owner: platform
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Group
metadata:
  name: obco-operators
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  type: internal
  policies:
    - obco-reader
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Group
metadata:
  name: obco-keycloak-admins
  namespace: openbao-config
  labels:
    obco.example.com/idp: keycloak
spec:
  connectionRef:
    name: openbao
  type: external
  policies:
    - obco-admin
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-platform
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Delete
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  groupRef:
    name: obco-developers
  entitySelector:
    matchLabels:
      obco.example.com/oncall: "true"
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-alice
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupName: obco-developers
  entityRef:
    name: obco-alice
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-bob
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupSelector:
    matchLabels:
      obco.example.com/role: developers
  entityName: obco-bob
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-legacy
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupID: 6f1e3c2a-0000-4000-8000-000000000002
  entityID: 6f1e3c2a-0000-4000-8000-000000000001
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-operators
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupRef:
    name: obco-developers
  memberGroupRef:
    name: obco-operators
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-nested
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupRef:
    name: obco-developers
  memberGroupName: obco-reviewers
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-selected-groups
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupRef:
    name: obco-developers
  memberGroupSelector:
    matchLabels:
      obco.example.com/nested-in: developers
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
  name: obco-developers-legacy-group
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  groupRef:
    name: obco-developers
  memberGroupID: 6f1e3c2a-0000-4000-8000-000000000004

Entities and groups default to deletionPolicy: Orphan, so deleting the resource keeps the identity, its ID and everything that refers to it.

An alias ties a login on one auth mount to an entity or a group. Each alias names its mount and its target in one of four ways: a resource in the same namespace (mountRef, entityRef, groupRef), a name or path, a label selector, or an OpenBao ID:

apiVersion: identity.openbaoconfig.io/v1alpha1
kind: EntityAlias
metadata:
  name: obco-alice-approle
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Delete
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  aliasName: obco-alice-ci
  mountRef:
    name: obco-approle
  entityRef:
    name: obco-alice
  customMetadata:
    source: gitops
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: EntityAlias
metadata:
  name: obco-bob-approle
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: obco-bob-ci
  mountPath: approle-ci
  entityName: obco-bob
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: EntityAlias
metadata:
  name: obco-platform-approle
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: obco-platform-ci
  mountSelector:
    matchLabels:
      obco.example.com/auth: approle
  entitySelector:
    matchLabels:
      obco.example.com/service: platform-ci
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: EntityAlias
metadata:
  name: obco-legacy-approle
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: obco-legacy-ci
  mountAccessor: auth_approle_0a1b2c3d
  entityID: 6f1e3c2a-0000-4000-8000-000000000001
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupAlias
metadata:
  name: obco-keycloak-admins
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Delete
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  aliasName: /obco/admins
  mountPath: oidc
  groupRef:
    name: obco-keycloak-admins
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupAlias
metadata:
  name: obco-keycloak-auditors
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: /obco/auditors
  mountRef:
    name: obco-oidc
  groupName: obco-keycloak-auditors
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupAlias
metadata:
  name: obco-keycloak-viewers
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: /obco/viewers
  mountSelector:
    matchLabels:
      obco.example.com/auth: oidc
  groupSelector:
    matchLabels:
      obco.example.com/idp: keycloak-viewers
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupAlias
metadata:
  name: obco-keycloak-legacy
  namespace: openbao-config
spec:
  connectionRef:
    name: openbao
  aliasName: /obco/legacy
  mountAccessor: auth_oidc_0a1b2c3d
  groupID: 6f1e3c2a-0000-4000-8000-000000000003

Apply an EntityAlias before the first login of that identity. Otherwise the first login creates its own alias with the same name, and the EntityAlias reports Conflict. For an OIDC group alias, aliasName is the group name exactly as the identity provider sends it in the groups claim.

3. Run OpenBao as an OIDC provider

Six kinds make OpenBao an OIDC provider for other applications: a signing key, scopes, clients, assignments that say who may use a client, the provider, and the issuer configuration.

apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCKey
metadata:
  name: obco-signing-key
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Delete
  name: obco-signing-key
  rotationPeriod: 24h
  verificationTTL: 48h
  algorithm: ES256
  allowedClientIDs:
    - "*"
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCScope
metadata:
  name: obco-groups
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Delete
  name: obco-groups
  template: '{"groups": {{identity.entity.groups.names}}}'
  description: Group names of the authenticated entity
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCAssignment
metadata:
  name: obco-portal-users
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Delete
  name: obco-portal-users
  entities:
    - entityID: 6f1e3c2a-0000-4000-8000-000000000001
    - entityName: obco-alice
    - entityRef:
        name: obco-bob
    - entitySelector:
        matchLabels:
          obco.example.com/portal: "true"
  groups:
    - groupID: 6f1e3c2a-0000-4000-8000-000000000002
    - groupName: obco-developers
    - groupRef:
        name: obco-operators
    - groupSelector:
        matchLabels:
          obco.example.com/portal: "true"
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCClient
metadata:
  name: obco-portal
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Delete
  name: obco-portal
  key: obco-signing-key
  clientType: confidential
  redirectURIs:
    - https://portal.obco.example.com/oidc/callback
    - http://localhost:8250/oidc/callback
  assignments:
    - obco-portal-users
  idTokenTTL: 30m
  accessTokenTTL: 1h
  authorizationCode: true
  clientCredentials: true
  writeSecretRef:
    name: obco-portal-oidc-credentials
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCProvider
metadata:
  name: obco-provider
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Delete
  name: obco-provider
  issuer: https://openbao.obco.example.com:8200
  allowedClients:
    - clientRef:
        name: obco-portal
    - clientName: obco-cli
    - clientID: obcoStaticClientId0000000000000
    - clientSelector:
        matchLabels:
          obco.example.com/provider: obco-provider
  scopesSupported:
    - obco-groups
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: OIDCConfig
metadata:
  name: obco-oidc-config
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  driftDetection: Enabled
  driftInterval: 30m
  managementPolicy: Manage
  deletionPolicy: Orphan
  issuer: https://openbao.obco.example.com:8200

OIDCClient writes the generated client ID and secret to the Secret in writeSecretRef. Give it to the application that logs its users in through OpenBao. OIDCRole (examples/identity/oidcrole.yaml) is for the other direction: OpenBao issues signed identity tokens to its own logged-in identities at identity/oidc/token/<name>, for example so that workloads can authenticate to other systems.

4. Check that it worked

kubectl -n openbao-config get entities,entityaliases,groups,groupaliases,groupmemberships
bao read identity/entity/name/obco-alice

Every resource shows Ready True. The entity lists its aliases and the groups it belongs to.

Troubleshooting

symptom check
an alias or membership reports ReferenceNotReady for up to about 30 seconds it waits for the mount, entity or group it names and retries with a backoff from 2 seconds up to 30 seconds; each level of references can add up to 30 seconds when you apply everything at once
EntityAlias reports Conflict a login created the alias first: delete that alias in OpenBao, or adopt it with creationPolicy: CreateOrAdopt
an OIDC user is not in the external group the GroupAlias aliasName against the groups claim, and the role's groupsClaim
OIDCClient reports SecretNotOwned a Secret named in writeSecretRef exists and was not created by this resource