How authentik signs operators into Vault with OIDC
Platform teams that run HashiCorp Vault or OpenBao usually need two things at once: operators should sign in with the corporate identity provider, and there must be a separate, tested path in when that provider is unavailable. authentik's Vault guide, marked with authentik support level, configures an OAuth2/OpenID provider for Vault's OIDC auth method, so the starting point is an authentik provider and application that Vault trusts as its OIDC issuer. The same pattern applies to OpenBao, which documents a JWT/OIDC auth method, although the exact settings and paths should be checked against the OpenBao auth documentation for the version you deploy.
The work divides cleanly. authentik owns identity: it authenticates the user, enforces the MFA and flow policies you configure, and emits the claims Vault reads, most importantly the group membership that identifies the operator's team. Vault owns authorization: a Vault role defines which claims are accepted, which redirect URIs are allowed for the UI and CLI, and which token policies are attached to a login. Group names in authentik should therefore be treated as an interface contract with Vault policies. Decide the group naming scheme and the claim you will map before building either side, and confirm with your own Vault version which claim fields the role configuration accepts.
Two decisions carry most of the risk. The first is who may hold the most privileged policies, because a group claim that grants administrative access is only as safe as the authentik group membership behind it, so restrict who can edit those groups in authentik. The second is the emergency path. Keep a local or non-SSO method, such as a root or recovery mechanism that Vault documents for your edition, sealed and tested, and verify it in a drill before the first production cutover. Confirm the exact break-glass procedure in the Vault documentation for your version rather than relying on memory of an older release.
What you need before configuring Vault OIDC with authentik
Four things must be settled before anyone edits an auth method: which authentik release you run, which Vault or OpenBao build sits behind the UI, how traffic and certificates flow between them, and who holds the rights to change the configuration. Each card below is a check to close with your own environment and your vendor.
Confirm the authentik release
Check that your authentik server and worker run a version that still receives security fixes. The security policy lists 2026.5.x and 2026.8.x as supported lines, and the project announces security releases at least 24 hours in advance. Record the exact version, because the Vault guide's provider settings depend on the release you deploy. Plan a window to upgrade if you run an unsupported line.
Verify the Vault or OpenBao version
Confirm the exact build of every Vault or OpenBao node, not just the version your team remembers. Note whether the cluster runs Community Edition or Vault Enterprise, because Enterprise features need a license applied to the cluster and the license terms differ from Community Edition. Ask your vendor or platform owner to confirm the edition in writing before you plan the OIDC method.
Map the network path
List every route the login flow uses: operator browsers to the Vault UI, Vault nodes to the authentik issuer and token endpoints, and CLI workstations to authentik for the device or browser callback. Vault nodes must reach the OIDC discovery URL themselves, because Vault fetches provider metadata from the server side. Confirm firewall rules and proxies for each hop before you change anything.
Trust certificates on both sides
Make sure every Vault node trusts the certificate chain presented by your authentik endpoint, and that operator browsers trust the Vault UI certificate. Private CA chains are a common cause of failed discovery. Install the CA bundle on Vault hosts and confirm it with a request from each node before you configure the auth method.
Plan an admin account that can change auth methods
Identify the Vault administrator who will enable and configure the OIDC auth method, and a second person who can approve changes. The account needs a policy that allows writing to the auth path and to the policies it maps to. Keep a root or break-glass token procedure documented and tested in advance, because a misconfigured OIDC method can lock out every SSO user.
Decide the Vault storage and HA setup
Record the storage backend and high availability design of the cluster, since they shape how you roll out a change. HashiCorp recommends integrated storage (Raft) for most use cases, and integrated storage and Consul are its officially supported backends. Confirm this with your team, then schedule the auth change so that each active and standby node receives the same configuration.
Configuring the authentik provider and Vault OIDC method in sequence
This sequence connects authentik to Vault's OIDC auth method so that users sign in with their directory identity, receive policies from their group membership, and can use both the UI and the CLI. Each step ends with a check you can run before moving on.
Create the authentik OAuth2/OpenID provider and application
An authentik administrator creates an OAuth2/OpenID provider and an application that points to it, choosing a confidential client type and recording the client ID and client secret. Set the signing key and scopes so that the group claim is included in the ID token or the userinfo response, since Vault's role mapping depends on it. Confirm the group claim name with a test login before Vault is configured. The step is done when the provider's OpenID configuration URL opens in a browser and lists the expected issuer and endpoints.
Register UI and CLI redirect URIs
Add the Vault UI callback for your Vault address to the provider's redirect URIs, using the path that Vault's OIDC method expects for the UI. Also add the localhost callback that Vault's CLI login uses, so that
vault login -method=oidccan complete the browser flow on the workstation. Keep the list of URIs to the addresses you actually use, and record which ones belong to the UI and which to the CLI. The check is that authentik accepts the saved provider and that both URIs appear in its redirect list without validation warnings.Enable and configure the Vault OIDC auth method
A Vault administrator enables the OIDC auth method at its default path or a path you name, then sets the OIDC discovery URL from the authentik provider, the client ID, the client secret and the default role. Store the client secret in Vault's own configuration handling or your secret delivery process, not in shared notes. If you run OpenBao, confirm that its JWT/OIDC method accepts the same settings in its auth methods documentation before you apply them. The check is that
vault auth listshows the OIDC path and that the configuration read back matches the discovery URL you supplied.Create the default role and group-scoped roles
Create a default role that allows a minimal login and grants a low-privilege policy, then create one role per group that needs more access. Each group role sets the bound claims to the group name from authentik, sets the user claim, and lists the redirect URIs that match step two. Keep the role names aligned with the authentik group names so that audits are simple to read. The check is that
vault read auth/oidc/role/<name>returns the bound claims and policies you intended for each role.Bind authentik groups to Vault policies
Write Vault policies for each access level, then attach them to the group roles so that membership in an authentik group produces the matching policy set. Use the group claim to choose the role at login, and avoid granting administrative policies to the default role. Ask your security team to review which policies each group receives before go-live, because the mapping lives in both systems. The check is that a user in one test group signs in and the policies shown match that group, while a user outside the group does not receive the same access.
Verify a UI login and a CLI login
Sign in to the Vault UI as a test user through authentik, then run
vault login -method=oidcfrom a workstation with the localhost callback reachable. Each login should open the browser, complete authentik's flow, and return to Vault. Confirm that the UI and CLI both succeed for the same user and role. The check is a successful login in both paths, with no redirect or callback errors in the Vault server log.Confirm the token carries the expected policies
Inspect the token issued to the test user with
vault token lookup, and compare the listed policies and the identity alias with the group the user belongs to in authentik. Repeat the check for a user in a different group and for a user with no group, and record the results. Any extra policy or missing policy means the group claim, the bound claims or the policy attachment needs correction before real users are onboarded. The step is done when each test user's token shows exactly the policies in your access design.Document a break-glass path before go-live
Before users rely on SSO, record how an administrator reaches Vault if authentik is unavailable. Options your team should confirm include a separate root or recovery procedure held under dual control, a non-OIDC auth method reserved for emergencies, and the storage of unseal or recovery material. Test the break-glass method in a non-production instance if one is available. The check is a written runbook that names the person who can invoke it and a tested login through that path.
Mapping authentik groups and claims to Vault roles and policies
This table lists each identity value authentik sends to Vault and the Vault object it feeds, with the rule for whether the two sides must match exactly or are chosen by your team. Read it before creating the authentik provider so the names, claims and redirect URIs line up on the first attempt. The main takeaway is that the subject, the groups claim and the redirect URIs are fixed contracts, while group names and policy names are design choices you record once and reuse.
| Element | Where it is set | Must match exactly? |
|---|---|---|
| Subject (sub) claim | authentik OIDC provider subject mode; read by Vault as the entity alias name | Yes, the alias name in Vault is derived from this claim, so changing the subject mode later creates new entities |
| Groups claim | authentik property mapping that adds group names to the token; referenced by Vault's groups_claim and bound claims | Yes, the claim name and value format must be identical in both systems |
| Group names | Chosen in authentik, then referenced in Vault bound_claims and group aliases | No, your team chooses the names, but each name must be spelled identically in both systems |
| Vault role name | Chosen in Vault under the JWT/OIDC auth method; used in the UI login form and CLI login command | No, choose one role per access tier and document it |
| Allowed redirect URIs | Set on the authentik provider and in the Vault role; one for the UI and one for the CLI callback | Yes, each URI must match character for character, including scheme, host and path |
| Token policies | Vault policy names attached to each role; defined in Vault as HCL policy documents | No, the names are yours, but the role must reference the exact policy name that exists |
| Entity and group aliases | Created in Vault so identity groups inherit policies from the authentik group claim | Yes, the alias must equal the claim value from authentik for group membership to apply |
| Client ID and secret | Generated on the authentik provider; entered into the Vault OIDC configuration | Yes, copy exactly and store the secret in a managed location, not in plain configuration files |
Browser UI and CLI logins need different redirect setup
The Vault web UI runs in the operator's browser. After authentik authenticates the user, it sends the browser back to a UI callback address on your Vault or OpenBao endpoint. That address must match exactly what is registered on the authentik OAuth2/OIDC provider and what is allowed in the OIDC role on the Vault side.
- Public address: Use the host name operators type into their browser, such as the name behind your load balancer or reverse proxy, and keep internal node names out of the allowed list.
- Scheme and path: Use https in production and include the UI callback path that the Vault OIDC method expects. Confirm the exact path in Vault's OIDC documentation and the authentik integration guide.
- Authentik registration: Add the UI callback as an allowed redirect URI on the provider created from the guide.
- Exact matching: Redirect comparison is strict, so a trailing slash, a missing port or a changed host name fails the login.
After any change to the endpoint address, test the UI in a private browser window and confirm the login lands on the Vault dashboard with the expected policies applied.
When an operator runs an OIDC login from the Vault CLI, the CLI opens a browser and starts a temporary listener on the operator's own machine. authentik redirects the browser to that loopback address with the authorization code, and the CLI exchanges the code for a token. The redirect therefore points at localhost, which authentik must also accept.
- Loopback listener: The CLI listens on a local port for the duration of the login, so the callback never leaves the workstation.
- Registered loopback entry: Add the exact local callback URI to the allowed redirect list. The port and path must match what the CLI uses, so confirm both in Vault's OIDC documentation.
- Role binding: Vault's OIDC role holds the allowed redirect URIs for each flow, so the CLI entry belongs in the role that CLI users sign in through.
- Same machine requirement: The browser that completes the login must run on the same machine as the CLI listener.
Test the CLI login on a clean workstation after each change to the provider, because a successful UI login does not prove the loopback entry is correct.
Operators who work through a bastion host, a remote shell or a machine without a graphical browser cannot complete the loopback flow directly. The browser that receives the authentik redirect cannot reach a listener on the remote host, so the login stalls or fails. Plan an access path for these operators before the rollout reaches them.
- Local forwarding: SSH local port forwarding can carry the CLI callback port from a laptop to the remote host, provided the port is known in advance. Confirm the port and CLI options in Vault's documentation.
- Login on a workstation: Some teams log in on a workstation with a browser and use the resulting token on the remote host, within the limits set by the token policy.
- Machine identities: Servers, pipelines and automation should authenticate with a machine auth method instead of a person's OIDC session. Check which methods your Vault or OpenBao edition supports.
- Documented choice: Record which path each team uses so support staff can diagnose failures without guessing.
Before you approve a headless procedure, have an operator who has no browser on the target host complete the full login and read a secret.
Most login failures in this setup come from registering one path and assuming the other works. Each path has its own redirect, so the authentik provider and the Vault OIDC role must cover both, and each mistake shows up at a different point in the flow.
- UI only: The browser login works, but the CLI fails at the redirect step with a mismatch error that points at authentik.
- CLI only: The CLI opens the browser, the operator authenticates, and then the UI callback fails with an error page.
- Broad wildcards: Wide loopback or host wildcards let authentik redirect to more addresses than you intend. Prefer exact entries.
- Endpoint changes: A new reverse proxy, a changed host name or a switch from http to https breaks both paths at once, so update every entry together.
- Separate roles: Keep a UI role and a CLI role, each with its own redirect set, and map the same authentik groups to the same Vault policies in both.
After any change, test both paths from a clean browser session and a clean workstation, and keep the CLI path working before you retire any local fallback.
Hardening the OIDC path into Vault
Signing in to Vault through authentik puts an identity provider in the path to your secrets, so the controls around that path matter as much as the auth method itself. The cards below cover where the client secret lives, how long tokens last, which groups can reach admin policies, how MFA applies to Vault-bound logins, and where audit logging depends on your license.
Store the client secret outside Vault config
The OIDC client secret that authentik issues lets Vault exchange authorization codes for identity tokens, so anyone holding it can mount a login attempt against your Vault role. Keep it in your configuration management or a secret store that the Vault operators control, not in a plain Helm value or a shared wiki page. Rotate it on a schedule you can document, and confirm how the rotation step updates the Vault auth configuration without a window where logins fail.
Bound audiences and token lifetime
Set the Vault OIDC role's bound audiences to the client ID authentik issues for this Vault application, so tokens minted for other applications are rejected. Then review the token TTL and maximum TTL on the Vault role and on the authentik provider, and keep Vault tokens short enough that a stolen token has limited use. Test both settings by logging in with a second authentik application and confirming Vault refuses it.
Least-privilege policies per group
Map each authentik group to one Vault policy that grants only the paths that group needs, such as a KV path per team. Avoid a catch-all group claim that maps to a broad default policy, because every new member of that group inherits its access. Write the mapping down as a table, review it when groups change, and test each policy with a token from a representative user of that group.
Restrict who reaches admin policies
Vault admin policies cover sys paths, auth configuration and policy writes, so the groups allowed to produce those tokens should be a short, named list. Filter the group claim or use an authentik policy binding so only the admin group can sign in through the admin role. Keep a separate Vault role for administrators and record who holds it, because a mistake in the group filter is the most direct route to a Vault-wide compromise.
Enforce MFA in authentik for Vault flows
Attach an authentication flow with MFA to the authentik application that Vault uses, so the second factor is required before authentik issues the token Vault consumes. Confirm which second-factor types your users have enrolled and whether hardware keys are required for the admin group. Vault itself does not see the factor, so the enforcement lives entirely in authentik and should be verified there.
Audit logs and the license boundary
Vault writes its own audit device logs, and those should be enabled and forwarded to storage your security team controls. authentik's enhanced audit logging is listed on its pricing page as an Enterprise feature, so confirm with authentik whether your subscription covers it before you design around it. The open-source edition should be treated as providing the sign-in trail you can verify in your own logs, not as an enhanced audit feature.
Keeping a break-glass path when authentik is down
Relying on the OIDC auth method alone makes authentik a single point of failure for every human login to Vault or OpenBao. If the authentik server, its worker, PostgreSQL or the network path to the identity provider is down, no operator can authenticate through SSO, and the people who most need access during an incident are often the ones locked out. Plan a documented emergency path before go-live, and treat it as part of the OIDC design rather than an afterthought. Confirm with your own team, and with the Vault or OpenBao documentation for the exact version you run, how the root or recovery credential is generated, who holds it, and which steps it requires, since those steps differ between releases and should not be copied from memory.
Keep the emergency path deliberately separate from authentik. Store the root or recovery material offline under dual control, so that no single administrator can use it alone and every use is recorded in a ticket or incident log. Alongside it, enable a non-SSO method that does not depend on authentik and test it. Vault and OpenBao both document username and password and token methods, and OpenBao recommends Userpass for developer machines and AppRole for servers. Use AppRole for automation that must keep working during an identity outage, and restrict Userpass to a small named set of administrators with login MFA where your version supports it. Scope the policies bound to these identities to recovery tasks, not to everyday secret access.
Break-glass paths decay unless they are exercised. Schedule drills that log in through the fallback method, confirm that the policies attached to it still allow the recovery tasks your runbook lists, and check that the stored credentials open the cluster as expected. Run a drill after each authentik upgrade, each Vault or OpenBao upgrade and each change to group-to-policy mappings, because any of these can break the path silently. Record the date, the people involved and the outcome, and rotate the emergency credentials after each use or drill. Ask your DeployOpen team or your internal platform owners to confirm the drill cadence against your change-control and audit requirements.
Common Vault OIDC login failures and their causes
This table pairs each common failure when signing in to Vault through authentik with its most likely cause and the first check to run. Read it from the symptom the user reports, then work down the matching row before changing any settings. Most failures trace back to a redirect URI, a discovery URL or a claim name that does not match exactly between authentik and Vault.
| Failure | Likely cause | First check |
|---|---|---|
| Redirect URI mismatch after clicking sign in | The redirect URI registered in the authentik provider does not exactly match the callback Vault sends, including scheme, host, port and path | Compare the redirect URIs in the authentik provider with the role's allowed_redirect_uris in Vault, character for character |
| CLI login opens browser but never returns | The localhost callback URI used by the Vault CLI is missing from the provider's redirect URIs, or a local firewall blocks the callback port | Confirm the CLI callback address is listed in the provider and that the port is reachable from the workstation |
| Discovery URL unreachable | The oidc_discovery_url is wrong, uses a path without the trailing application slug, or Vault cannot reach authentik over the network | Fetch the discovery URL from the Vault server itself with curl and check the returned issuer value |
| Certificate trust error on login | authentik is served by a certificate issued by an internal CA that Vault does not trust | Set oidc_discovery_ca_pem on the Vault auth method to the CA chain and retest from the Vault host |
| Issuer mismatch | The issuer in the token does not match the oidc_discovery_url, often because of a trailing slash or an http versus https difference | Compare the iss value in a decoded test token with the issuer shown by the discovery document |
| Login succeeds but group claims are missing | The scope that carries groups is not requested, the claim is named differently in authentik, or the property mapping was not attached to the provider | Decode the ID token or userinfo response and confirm the groups claim exists with the expected name |
| Role bound claims not matching | The bound_claims or bound_subject values in the Vault role do not equal the values in the token, such as a group name with different case | Compare each bound claim in the Vault role with the decoded token value and correct the mismatch |
| User logs in but has no expected policies | Group names are not mapped to Vault identity groups or the group alias uses a different name from the authentik group | Check the Vault identity group aliases against the group claim values and confirm each maps to the intended policies |
| Denied after authentik group change | Existing Vault tokens keep their old policies until they expire, or the user is outside the groups allowed by the role | Review token TTLs and revoke affected tokens, then have the user sign in again |
Questions buyers ask before wiring Vault to authentik
What drives the cost and effort of an authentik and Vault OIDC integration?
The main drivers are the number of groups and policies that must map to Vault policies, the number of Vault clusters and namespaces, the HA topology, the number of CLI and automation users, and how much testing the change needs. Each additional group-to-policy mapping adds design, review and test work, and each extra cluster repeats the redirect URI, role and claim configuration. Ask for a quote that lists these items separately, and confirm whether it covers one-time build work, documentation and handover, or ongoing support, since the last of these recurs. No figure is given here because effort depends on the written scope.
Can our team set up Vault OIDC with authentik using only the vendor guide?
Often yes, if you have engineers who already run both products and a clear group design. The authentik HashiCorp Vault guide, which carries authentik's support level, walks through configuring an OAuth2/OpenID provider for Vault's OIDC auth method. What the guide does not decide for you is how your groups map to Vault policies, which redirect URIs your UI and CLI paths need, how break-glass access is kept, and how the change is tested before production. Those decisions are where most rework happens, so review the guide against your own access model before you commit internal time.
How long does an authentik and Vault OIDC integration take?
Duration depends on scope: the number of groups, clusters, automation paths and the size of the test window your change board requires. A single cluster with a small group set is a much smaller job than several HA clusters with CI pipelines and documented break-glass procedures. No duration is published for this work, so ask any provider for a timeline written against a defined scope, with milestones for design, build, test and cutover. Confirm who schedules the change window on both the authentik and Vault sides.
What do we need to provide for the integration work?
You need administrative access to authentik to create providers, applications, groups and property mappings, and administrative access to Vault to enable the OIDC auth method, create roles and write policies. You also need a decision-maker who approves the group-to-policy design, a named owner for break-glass credentials, and a test window in a non-production Vault where SSO logins, CLI logins and policy checks can be exercised safely. Agree these inputs in the written scope so that delays do not surface during the build.
Does Vault Enterprise licensing change the authentik setup?
The OIDC configuration pattern is the same on Vault Community Edition and Vault Enterprise, but the licensing and feature set differ. Vault Enterprise features such as namespaces, control groups, Sentinel policy as code and MFA require a license applied to the cluster, and some of them may shape how you structure policies and namespaces. HashiCorp prices Enterprise through sales rather than a published list, and Vault's license terms changed from MPL-2.0 to the Business Source License 1.1 for releases from 1.15.0 onward. Have legal review the license terms that apply to your deployment and confirm which Enterprise features your design needs before fixing the policy model.
Do the same steps work for OpenBao?
The overall approach is similar because OpenBao is a community fork of Vault under the MPL-2.0 license and supports JWT/OIDC as an auth method. However, do not assume the Vault guide applies unchanged. Confirm the OpenBao auth method settings, role and claim syntax, and API behavior against the OpenBao version you run, since its migration guide was tested only against Vault 1.14.1 community edition. Its feature set also differs from Vault Enterprise, so any policy or namespace design that relies on Enterprise features needs its own verification.
What should we test before cutting over to SSO for Vault?
Test each login path separately: the UI redirect flow, CLI login with the OIDC method, and any automation that authenticates through a non-interactive path. For each group, confirm that the expected Vault policy is attached and that users outside the group receive no extra access. Also test the break-glass route with authentik unavailable, including token or root credential storage, and confirm that the procedure is documented and that someone other than the operator can follow it. Record the results so that auditors and your own change board can review them.
Vault licensing and OpenBao: what changes the choice
HashiCorp announced on August 10, 2023 that future Vault releases would move from MPL-2.0 to the Business Source License 1.1. The Vault LICENSE file names IBM as licensor, covers Vault 1.15.0 or later, bars competitive hosted or embedded offerings, and converts each version to MPL-2.0 four years after publication. IBM completed its acquisition of HashiCorp on February 27, 2025, so the licensor and commercial owner of Vault is now IBM. Before you standardize on either product, read the HashiCorp announcement on the license change alongside the LICENSE file for the exact versions you plan to run, and have your counsel confirm whether your planned use, including any internal platform offered to other business units, falls within the restrictions.
OpenBao is a community fork of Vault under MPL-2.0, managed by the Linux Foundation's OpenSSF as a Sandbox project. Its documentation describes it as an open source, community-driven secrets manager. Its migration guide was tested only against Vault 1.14.1 community edition, not Vault Enterprise, so if you run Enterprise features such as namespaces, Sentinel policy as code or performance replication, treat OpenBao compatibility as something to verify in your own environment rather than assume. Ask the Vault vendor or your reseller for written license terms for Enterprise and HCP Vault Dedicated, since HashiCorp's pricing pages direct self-managed Enterprise buyers to sales rather than publishing prices.
The OIDC pattern in this guide applies to both products: the same authentik provider, redirect URIs, client settings and group claims are used, and the oidc auth method path is configured in the same way. The licensing choice therefore affects your support model, upgrade cadence and feature set more than the SSO design. Record the license version you intend to run, the edition and any Enterprise features you depend on, and the owner of the decision, then retest the login path after any change of product or major version.
How DeployOpen delivers authentik and Vault OIDC integrations
DeployOpen plans, builds and documents the authentik and Vault OIDC integration inside your own infrastructure, so your team keeps control of identity, secrets and the break-glass path. Each engagement starts from a written scope that names the authentik provider, the Vault or OpenBao auth mount, the group-to-policy mapping and the recovery procedure.
How we scope
- Confirm whether the target is HashiCorp Vault, Vault Enterprise or OpenBao, and the version your cluster runs.
- Agree which authentik groups map to which Vault policies, and who approves changes to that mapping.
- Record redirect URIs for the UI and CLI callback paths, along with the environments each one covers.
How we build
- Configure the authentik OAuth2/OpenID provider and the Vault OIDC auth method against the authentik integration guide.
- Test UI and CLI logins with a non-production user set before any group-based policy goes live.
- Verify that a user outside every mapped group receives no access, and that a removed group loses access on the next login.
How we hand over
- Deliver the written configuration, mapping tables, redirect URI inventory and test results as documentation.
- Document the break-glass procedure, including where emergency credentials are stored and who may use them.
- Walk your platform and security engineers through the runbook for adding groups, rotating client secrets and reviewing mappings.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, version upgrades of authentik and Vault or OpenBao, and continuous testing are available as a retainer.
- Ask for a written quote based on your scope. DeployOpen does not publish a price list.
