Skip to content

AppRole

This guide gives a machine outside Kubernetes, such as a CI runner or a VM, an AppRole login: the role is declared in Kubernetes, and the operator issues its secret ID into a Kubernetes Secret and replaces it before it expires.

Before you begin

  • A Ready connection whose OpenBao policy allows auth/<mount>/role/* on the approle mount (OpenBao policy for the operator), plus sys/auth/<mount> and sys/auth/<mount>/tune with sudo if the operator also enables the mount.
  • A way to deliver the Secret's values to the machine, for example a CI variable that a pipeline updates from the Secret.

1. Enable the auth method

Create an AuthMount with type: approle. The first object in this file enables it at approle-ci:

examples/sys/authmount.yaml
# Enables the auth methods that the auth kinds then configure: AppRole for CI pipelines at approle-ci, with user
# lockout after five failed logins, plus LDAP and Kubernetes mounts.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
  name: obco-approle
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Orphan
  driftDetection: Enabled
  driftInterval: 15m
  managementPolicy: Manage
  path: approle-ci
  type: approle
  description: AppRole logins for CI pipelines
  local: false
  sealWrap: false
  externalEntropyAccess: false
  forceNoCache: false
  pluginVersion: ""
  options: {}
  defaultLeaseTTL: 1h
  maxLeaseTTL: 24h
  listingVisibility: hidden
  auditNonHMACRequestKeys:
    - role_id
  auditNonHMACResponseKeys:
    - role_id
  passthroughRequestHeaders:
    - X-Request-Id
  allowedResponseHeaders:
    - X-Request-Id
  tokenType: default-service
  userLockout:
    threshold: 5
    duration: 15m
    counterResetDuration: 10m
    disable: false
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
  name: obco-ldap
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Orphan
  driftDetection: Enabled
  driftInterval: 15m
  managementPolicy: Manage
  path: ldap
  type: ldap
  pluginRef:
    name: obco-ldap-auth-plugin
  description: LDAP logins through the external plugin registered by the Plugin obco-ldap-auth-plugin
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
  name: obco-kubernetes
  namespace: openbao-config
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Orphan
  driftDetection: Enabled
  driftInterval: 15m
  managementPolicy: Manage
  path: kubernetes
  type: kubernetes
  description: Kubernetes ServiceAccount logins from the workload cluster

2. Create the role

examples/auth/approle.yaml
# An AppRole role for a CI deployer outside Kubernetes: a fixed role ID, secret IDs bound to a CIDR and valid for a
# day, and short-lived tokens with the ci-deployer policy.
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: AppRole
metadata:
  name: ci-deployer
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Delete
  driftDetection: Enabled
  mountPath: approle
  name: ci-deployer
  roleID: ci-deployer-role-id
  bindSecretID: true
  secretIDBoundCIDRs:
    - 10.42.0.0/16
  secretIDNumUses: 0
  secretIDTTL: 24h
  localSecretIDs: false
  tokenTTL: 20m
  tokenMaxTTL: 1h
  tokenExplicitMaxTTL: 2h
  tokenPeriod: 0s
  tokenPolicies:
    - ci-deployer
  policyRefs:
    - name: obco-team-a-reader
  tokenBoundCIDRs:
    - 10.42.0.0/16
  tokenNumUses: 0
  tokenType: service
  tokenNoDefaultPolicy: false
  tokenStrictlyBindIP: false

roleID fixes the role ID; leave it out and OpenBao generates one. secretIDBoundCIDRs and tokenBoundCIDRs limit where the secret ID and the tokens may be used. mountPath is the path of the auth method: approle here, so change it to approle-ci to use the mount of step 1.

3. Issue a secret ID

An AppRoleSecretID creates a secret ID for the role and writes it to the Secret named in writeSecretRef, with the keys role_id, secret_id and secret_id_accessor. Status holds only the accessor, never the secret ID.

examples/auth/approlesecretid.yaml
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: AppRoleSecretID
metadata:
  name: ci-deployer-login
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: CreateOrAdopt
  deletionPolicy: Delete
  driftDetection: Enabled
  roleRef:
    name: ci-deployer
  metadata:
    team: platform
    pipeline: deploy
  cidrList:
    - 10.42.0.0/16
  tokenBoundCIDRs:
    - 10.42.0.0/16
  ttl: 12h
  numUses: 0
  writeSecretRef:
    name: ci-deployer-approle
  rotation:
    enabled: true
    renewBefore: 33%
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: AppRoleSecretID
metadata:
  name: ci-deployer-login-by-name
spec:
  connectionRef:
    kind: OpenBaoConnection
    name: openbao
  creationPolicy: Create
  deletionPolicy: Delete
  driftDetection: Enabled
  mountPath: approle
  roleName: ci-deployer
  ttl: 6h
  numUses: 10
  writeSecretRef:
    name: ci-deployer-approle-by-name
  rotation:
    enabled: true
    renewBefore: 2h

With rotation enabled (the default for a secret ID with a TTL), the operator creates a new secret ID renewBefore the expiry, a duration or a percentage of the TTL, writes it to the Secret and then destroys the old one. Expiry is checked at every drift interval, so keep renewBefore longer than that interval. A secret ID cannot be adopted: use creationPolicy: Create or CreateOrAdopt.

4. Check that it worked

kubectl -n openbao-config wait approle/ci-deployer approlesecretid/ci-deployer-login \
  --for=condition=Ready --timeout=2m
kubectl -n openbao-config get secret ci-deployer-approle -o jsonpath='{.data}'

The Secret holds the three keys. The examples bind the secret ID and its tokens to 10.42.0.0/16, so the login works only from an address inside that range. Set secretIDBoundCIDRs, tokenBoundCIDRs and the secret ID's cidrList and tokenBoundCIDRs to the machine's range, or leave them out to allow any address. The secret ID's lists are immutable, so set them before you apply it. Test the login from a host inside the bound range. The command uses the mount approle of the example; with the mount of step 1, the path is auth/approle-ci/login:

bao write auth/approle/login \
  role_id="$(kubectl -n openbao-config get secret ci-deployer-approle -o jsonpath='{.data.role_id}' | base64 -d)" \
  secret_id="$(kubectl -n openbao-config get secret ci-deployer-approle -o jsonpath='{.data.secret_id}' | base64 -d)"

Troubleshooting

symptom check
AppRoleSecretID reports ReferenceNotReady the AppRole in roleRef exists and is Ready
AppRoleSecretID reports SecretNotOwned a Secret of that name exists and was not created by this resource: rename writeSecretRef or delete the Secret
AppRoleSecretID reports OutputNotDelivered OpenBao returned the secret ID but the Secret write failed; the message says how to rotate
login fails with invalid secret id the secret ID expired or was rotated: read the Secret again
login fails with a CIDR error secretIDBoundCIDRs and tokenBoundCIDRs against the machine's address