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.
2. Link logins with aliases¶
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 |
Related¶
- API reference: identity.openbaoconfig.io, with Entity, EntityAlias, Group, GroupAlias, GroupMembership and the OIDC kinds.
- Templated policies: paths built from entity and group names.
- Access model:
AccessLayoutwrites external groups and aliases for you.