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
Readyconnection whose OpenBao policy allowsauth/<mount>/role/*on the approle mount (OpenBao policy for the operator), plussys/auth/<mount>andsys/auth/<mount>/tunewithsudoif 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¶
# 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.
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 |
Related¶
- API reference: AppRole, AppRoleSecretID, AuthMount.
- Connect to OpenBao: AppRole for the operator's own login.