Signing Proxmox VE users in with authentik over OpenID Connect
A team running one or more Proxmox VE clusters usually wants one identity source for the people who administer and operate them, so that joiners, leavers and role changes happen in one place. The supported approach is to add an OpenID Connect realm in Proxmox VE and point it at an OAuth2/OIDC provider that authentik creates. Proxmox VE's user management documentation describes how realms, users and groups relate, and it is the page to read alongside this section. Proxmox VE 9.x is the current major line, and Proxmox VE 8 reached end of life in August 2026, so any cluster still on 8 should be planned as an upgrade before identity work begins.
Confirm the realm fields, client settings and CLI options against the user management page for the exact Proxmox VE version you run, because realm options can differ between releases. Before you touch the cluster, decide three things: the issuer URL and client ID you will register in authentik, which authentik groups should map to Proxmox VE groups, and whether a local administrator account stays available for recovery if the identity provider is unreachable. Keep that break-glass account documented and tested, and check that it does not depend on the same authentik instance it is meant to back up.
Once the realm exists, verify it with a test login from a non-administrator account before you assign broad permissions. Make sure the group names your authentik provider emits match the realm suffix convention Proxmox VE expects, since a mismatch is the most common reason a user signs in successfully but receives no access. Because the cluster configuration is replicated across nodes, plan the realm change as a cluster-wide task and confirm that the setting appears on every node. Ask your authentik operators which signing keys, token lifetimes and redirect URIs they will manage, so that certificate or secret rotation does not silently lock out your operators.
What must be in place before the realm is created
The realm itself is a short configuration task, but most failed Proxmox VE sign-ins trace back to decisions made earlier: which authentik and Proxmox VE lines you run, how the endpoints resolve and trust each other, and who can still log in if the identity provider is down. Settle these items first so the realm setup is a verification exercise rather than a debugging session.
Supported authentik release line
Run an authentik release that receives security fixes. The authentik security policy lists 2026.5.x and 2026.8.x as the supported lines, and the project announces security releases at least 24 hours in advance. Record the exact version you deploy, because the OIDC settings you copy from authentik depend on the provider configuration of that release. Plan a window to apply security releases on short notice, since the realm depends on authentik being reachable.
Proxmox VE version and repository access
Confirm the Proxmox VE release and the Debian release beneath it, since Proxmox VE versions are supported as long as the matching Debian release has security support. For production, the enterprise repository requires a valid subscription key and is the recommended choice. The no-subscription repository suits testing and non-production use. Decide which repository each node uses before you change anything, and confirm the subscription tier and support entitlements on the pricing page.
Three-node cluster if HA is in scope
If guests must restart on another node after a failure, plan at least three cluster nodes for reliable quorum, shared storage for guests, redundant hardware and watchdog-based fencing. Realm login does not depend on HA, but the identity dependency still matters: when the authentik endpoint is unavailable, administrators need another way in. Confirm the cluster design with your platform team before treating the realm as the only administrative path.
DNS and TLS for both endpoints
The browser must reach authentik and each Proxmox VE node by name, and both certificates must be trusted by the client. Decide which hostname the Proxmox VE web interface uses, because it forms the callback base for the redirect. Confirm that the authentik certificate chain is valid from the browsers and from the Proxmox VE nodes, since token exchange happens server to server. Mismatched hostnames and private certificate authorities are the most common causes of realm errors.
Redirect URI plan
Write down the exact redirect URI that the Proxmox VE realm will send users back to, including scheme, hostname, port and path. Enter the same value in the authentik OAuth2/OIDC provider, because the identity provider rejects callbacks that do not match exactly. If you run several Proxmox VE clusters or a load balancer in front of the nodes, decide which address is canonical and document it. Changing the hostname later means updating both sides together.
Break-glass administrator and edition check
Name an owner for a local Proxmox VE administrator account that remains available when the OpenID realm or authentik fails. Store its credentials under your normal break-glass controls and test that the login works before you disable any other path. Also confirm edition requirements before purchase: the authentik pricing page's enterprise-only list names Google Workspace, Microsoft Entra ID, mTLS, privileged access management and other features, but it does not name OAuth2/OIDC providers. Verify this on the pricing page before you commit.
How the realm name and group suffix connect authentik groups to Proxmox permissions
Proxmox VE identifies every account as a user and realm pair, so a login through authentik always lands in a named realm that you create for it. Permissions are then granted to users and groups in that realm, which means the realm name is part of the identity itself. Group-based access depends on the realm suffix used when groups are created or referenced in Proxmox VE, so the group names that come from authentik must be written with the same suffix that the realm uses. Before you build the mapping, confirm the exact suffix format and the name of the group claim in the Proxmox VE user management documentation, because a mismatch will not fail loudly and simply leaves users without the rights you expected.
The main design decision is whether one realm serves all administrators or whether each authentik application or team gets its own realm. A single realm keeps the permission model short, with one set of groups to audit and one place to remove access. Separate realms let you scope who can sign in to which cluster or pool, and they keep a compromise or misconfiguration in one client from affecting others, but they multiply the groups, role assignments and suffixes you must maintain. For an illustrative cluster with a small platform team, a single realm with a few groups is often easier to review, while a larger organization with separate operations and tenant owners may need the separation.
Whichever layout you choose, write it down before you touch the authentik side. List each authentik group that should receive Proxmox access, the realm it will sign in through, the Proxmox group name with its suffix, and the role or path it will hold. Then test with one account from each group and confirm the resulting permissions in the Proxmox VE interface. Changing a realm name later changes the identity of every user in it, so treat the realm name and suffix as long-lived decisions.
Configuring the authentik provider and the Proxmox VE realm in sequence
This sequence connects authentik to Proxmox VE as an OpenID Connect realm so that users sign in with company credentials and receive permissions through group membership. It finishes with a non-admin and an administrator login verified on the cluster, with the realm configuration identical on every node.
Create the OAuth2/OIDC provider in authentik
An authentik administrator creates an OAuth2/OIDC provider and pairs it with an application that users will see in the authentik library. Set the client type to confidential, record the client ID and client secret in your secret store, and enter the redirect URI for the Proxmox VE realm exactly as the Proxmox VE user management guide describes for your version. Done when the application lists the provider, and the provider's OpenID configuration URL opens in a browser and shows the issuer and endpoint details.
Define scopes and the groups claim
On the same provider, bind the standard OpenID scopes and add a scope mapping that places the user's authentik group names into a groups claim. Confirm the claim name and the username claim that Proxmox VE expects before you save, because a mismatch produces logins with no permissions. Done when a test user's token preview in authentik shows the expected subject, email and groups values.
Create the realm in the Proxmox VE web interface
On the first node, open the datacenter permissions area, add an OpenID Connect realm, and enter the authentik issuer URL, client ID, client secret, username claim and scopes. Keep the realm name short and final, because it becomes the suffix on every user name. Done when the realm appears in the login realm selector and a sign-in attempt redirects to the authentik login page.
Replicate the realm across the cluster from the CLI
Confirm the realm definition from the command line so that every node carries the same configuration, and check the realm file in the cluster file system that Proxmox VE replicates to all nodes. Use the same settings you entered in the web interface, and make sure the client secret is not written into documentation or tickets. Done when the realm listing is identical on each node and the login selector on a second node shows the same realm.
Map authentik groups to Proxmox VE permissions
Create the Proxmox VE groups that will hold permissions, and name them so the realm suffix is clear to administrators. Assign roles and paths to those groups in the permissions view, then confirm in the user management guide how group claims from the OpenID realm are matched to Proxmox VE groups in your version. Done when the permissions view shows each group with the expected path and role, and no group is granted more access than its authentik counterpart requires.
Test a non-admin login
Sign in with a test user who belongs only to a limited authentik group, using the new realm on the login page. Check that the account appears in the users list with the realm suffix and that it can see only the resources its Proxmox VE group grants. Done when the login succeeds, the expected group appears against the account, and the denied actions fail as designed.
Test an administrator login
Sign in with a test administrator from the administrator group, and log in through a node other than the one where the realm was created. Confirm that the account carries the datacenter-level role you assigned and that administrative actions work on every node. Keep your local root account available for recovery, and confirm the recovery procedure before you enforce SSO for everyone. Done when both administrator access and recovery access are verified.
Which authentik attributes and groups map to Proxmox VE users and permissions
This table lists each identity element that crosses from authentik into Proxmox VE, the source attribute, the Proxmox target, whether it is required, and what to confirm on your installed versions. Read it as a checklist to run before the first live login, because the claim names and group handling depend on how the authentik provider and property mappings are configured. The main takeaway is that the user name, realm suffix and group-to-ACL link must agree, and one group should stay outside SSO for break-glass access.
| Identity element | Source in authentik | Target in Proxmox VE | Required or optional | What to confirm |
|---|---|---|---|---|
| Username | Preferred username claim from the OpenID Connect token (commonly preferred_username) | Proxmox user name with the realm suffix | Required | Exact claim name and whether it is unique and stable across renames |
| Email claim, mapped from the user's email attribute | User email field in Proxmox VE | Optional | Claim name, scope that releases it, and whether Proxmox VE stores it for notifications | |
| Group membership | Groups claim built from authentik group membership through a scope mapping | Proxmox VE group and the ACL that grants permissions on pools, nodes or VMs | Required for group-based access | Claim name, group naming format, and that each group has an ACL in Proxmox VE |
| Realm suffix | Not sent by authentik; set by the realm name you create in Proxmox VE | Realm part of the user ID, for example name@realm | Required | Realm name is identical in the UI, the CLI and every ACL entry |
| Break-glass group | A dedicated authentik group kept outside SSO role mapping | Local Proxmox VE accounts with a realm of pam or pve, not the authentik realm | Required | Local root or admin password is stored offline and tested before realm changes |
| Service accounts | Non-human accounts kept out of the authentik group used for Proxmox access | API tokens or local service users managed in Proxmox VE | Optional | Whether automation depends on a user that SSO sign-in would change or lock |
| Default role for new users | Group membership that grants no elevated rights by default | Proxmox VE role assigned through ACL, which can be empty at first login | Optional | Whether first-login users receive any permissions and who approves elevation |
| Cluster-wide realm definition | Authentik issuer URL and client settings, identical across nodes | Realm configuration replicated through the Proxmox Cluster File System | Required | Realm appears on every node after the change and the client secret is handled securely |
Hardening the SSO path for Proxmox VE administrators
Signing administrators in through authentik moves the most sensitive login on the cluster to a second system. The cards below cover the decisions that keep that path recoverable, tightly scoped and patched, and they show what to check before the realm goes live.
Keep a break-glass root credential
Keep a local Proxmox VE administrator account that does not depend on authentik, with a long, unique credential stored in your sealed secrets process. If the authentik server, its database or its certificate fails, this account is the only way into the cluster until the realm is restored. Write down who may use it, when it is tested, and the exact steps to recover. Confirm that the account still works from each node before you disable any other login path.
Restrict which groups reach the realm
Authentik decides who can authenticate, but Proxmox VE decides what a signed-in user may do. Create a dedicated authentik group for cluster administrators and bind the OIDC application to it through an access policy, so that users outside that group are refused before a Proxmox VE session starts. Review group membership on a fixed schedule, because removing someone from the authentik group is the fastest way to cut off realm access.
Enforce MFA for administrative groups
Attach an authenticator stage to the flow used by the administrative group so that a password alone never completes a Proxmox VE login. Choose a second factor your administrators can use on every node and every console, and test the recovery path for lost devices before go-live. Remember that the Proxmox VE login is only as strong as the flow that issues the token, so confirm the enforcement with a test account in the admin group.
Use certificates both ends trust
The browser must trust the certificate on the Proxmox VE web interface, the authentik endpoint must present a certificate the cluster nodes trust for the discovery and token exchange, and API clients must trust the same chain. Use an internal certificate authority or a public certificate you control, distribute the root to every node and workstation, and confirm the chain on each node before you enable the realm. Plan renewal so that an expired certificate does not lock out every administrator at once.
Limit the redirect URI to one endpoint
Register the redirect URI with the exact address of the cluster endpoint users reach, including scheme, host name and port, and avoid wildcards or several hosts unless each one is a real, managed entry point. A loose redirect URI lets an attacker who controls another host receive authorization codes meant for the cluster. When you add a second node name or a load balancer, add that exact value and remove any old entries.
Track releases and plan patch windows
Keep both authentik and Proxmox VE on lines that still receive security fixes, and subscribe to their security notices. The authentik security policy names the supported version lines, and the project announces security releases at least 24 hours in advance, so schedule a standing window that can absorb a same-week patch. Record the running versions of authentik and Proxmox VE in your change log so you can answer quickly whether a published fix applies to your deployment.
Log realm logins for review
Forward authentik authentication events and Proxmox VE authentication log entries to the log platform you already operate, so that a realm login can be matched to the authentik user, the source address and the cluster node that accepted it. Define alerts for logins from unexpected networks, repeated failures and realm logins for accounts outside the administrative group. Confirm the retention period with your compliance owner before you rely on these logs as evidence.
Single node or cluster: where the realm should be configured
On a single Proxmox VE node, the realm is created and tested on one host, and there is no replication to check. This setup suits testing, a small lab or a proof of concept, where the goal is to confirm that the identity provider, redirect URI and group mapping work before anything depends on them. Keep the lab realm separate from production client registrations so that a test secret or redirect URI never ends up in a live configuration.
- Test the full login path: Sign in with a test user, confirm the group claim arrives, and check that the user lands in the expected Proxmox VE group.
- Use a non-production client: Register a separate OIDC client in authentik for the lab so the production client secret is never copied into test notes.
- Record the realm settings: Keep the issuer URL, client ID, scopes and username claim in a change record so the cluster build can repeat them exactly.
- Expect a repository choice: The no-subscription repository is described as suited to testing and non-production use, so confirm which repository the lab node uses before you treat it as a model for production.
Before you reuse the lab configuration, confirm that the realm name, claim names and group naming match what the production cluster will use.
Proxmox VE clusters are multi-master: every node can perform all management tasks, and the Proxmox Cluster File System replicates configuration to all nodes in real time. In practice, you create the OpenID Connect realm once, from any node, and it becomes visible across the cluster. You still verify it on every node after the change, because a login attempt routed to a node that did not receive the update will fail in a way that looks like an identity problem.
- Create the realm once: Make the change from one node, then confirm the realm appears on each cluster member.
- Verify on every node: Check each node's realm list and attempt a login through each node's web interface or API endpoint.
- Plan the client secret: Decide where the OIDC client secret is stored, who can read it, and how it is rotated, and document the procedure before go-live.
- Limit who edits realms: Restrict realm and permission changes to a small administrator group so that configuration does not drift between nodes.
- Rotate on a schedule: Rotate the authentik client secret and update the Proxmox VE realm in one planned window, then re-verify on every node.
After any realm change, confirm that each node accepts a login and that the group mapping produces the expected Proxmox VE permissions.
High availability is a separate design decision from the realm configuration. The Proxmox VE HA documentation calls for at least three cluster nodes for reliable quorum, shared storage for guests, redundant hardware, and watchdog-based fencing so that a failed node is reset before its guests are recovered elsewhere. None of these requirements changes the realm settings, but they do affect how you plan the authentik side and the maintenance windows around it.
- Quorum and realm changes: Confirm that the cluster has quorum before you edit the realm, so the change replicates cleanly.
- Fencing is not a login control: Watchdog fencing protects guests after a node failure, and it does not replace the need to verify login on surviving nodes.
- Plan for identity dependency: If authentik is unavailable, administrators may need a local account or another recovery path, so decide that before go-live.
- Document the recovery path: Record who can disable the OIDC realm or sign in with a local administrator during an identity outage.
- Test failover separately: Run node failure tests on their own schedule, then repeat the login check after a node rejoins.
Before you go live, confirm the quorum, fencing and local recovery arrangements with your Proxmox VE documentation and your own infrastructure team.
Common failures when Proxmox VE SSO with authentik does not work
This table pairs each common failure in an authentik OpenID Connect realm for Proxmox VE with its likely cause and the fix, plus the check that proves the fix worked. Work through the rows in order when a login fails, because the redirect, certificate and clock problems block sign-in before permissions are ever evaluated. The main takeaway is that a login that succeeds but shows no permissions is almost always a group name or realm suffix problem, not an authentication problem.
| Symptom | Likely cause | Fix and proving check |
|---|---|---|
| Redirect fails with an invalid redirect URI error at authentik | The redirect URI registered in the authentik OAuth2/OIDC provider does not match the Proxmox VE node URL used to start login, including port, path or hostname | Register the exact callback URL for each hostname users use, then confirm login starts and returns to the Proxmox VE login page from a clean browser session |
| Browser shows a certificate trust error on the Proxmox VE or authentik endpoint | The authentik endpoint or the Proxmox VE node uses a certificate from an internal CA that the client or the Proxmox VE host does not trust | Install the internal CA on the Proxmox VE nodes and client browsers, then confirm the issuer endpoint validates with a standard TLS client from a Proxmox VE node |
| User signs in but sees no VMs, containers or pools | Group names in authentik do not match the Proxmox VE group names, or the realm suffix is missing from the group identifier | Compare the group names returned in the claim with the Proxmox VE groups and realm suffix, then confirm the user sees the expected resources after a fresh login |
| User signs in but sees no permissions at all | The groups claim is empty because the groups scope was not requested by the Proxmox VE realm configuration | Add the groups scope to the realm, log in again, and confirm the claim appears in the token or userinfo response for that user |
| Login fails with token validation or 'token not yet valid' style errors | Clock skew between authentik, the Proxmox VE nodes and the client, which shifts token issue and expiry times | Enable time synchronization on every node and authentik host, then confirm the offset is small on each host before retesting login |
| Realm appears on one cluster node but not on others | The realm was created on one node through the GUI or CLI without replication to the cluster configuration, or a node was not updated | Check the realm list on every node after a change, then confirm each node returns the same realm and login succeeds through a second node |
| All administrators are locked out after a mapping change | A mapping change removed or renamed the group that granted the Administrator role, and the local root account was disabled or unavailable | Keep a local administrator account for recovery, test mapping changes on a second realm first, and confirm an administrator can log in before closing the change |
Questions teams ask before connecting Proxmox VE to authentik
Do we need a paid authentik edition or a Proxmox VE subscription to connect them?
No paid edition is needed to add authentik as an OpenID Connect realm in Proxmox VE if the OIDC provider is available in the edition you run, so confirm that on the authentik side before you start. The authentik pricing page lists an Open Source tier at no cost, an Enterprise tier and an Enterprise Plus tier, and the features you need should be checked against that list. On the Proxmox side, the software is the same across all subscription tiers. The tiers differ in support tickets, response times and access to the enterprise repository, and the software can be used without a subscription. The enterprise repository is the recommended choice for production, so a subscription is a support and repository decision rather than a feature decision. Confirm both choices with your own licensing owner before the build.
How long does a Proxmox VE and authentik SSO setup take?
The duration depends on a few drivers, and no fixed figure applies to every environment. The number of realms and the group design usually matter most, because each entitlement you map to a Proxmox group needs a decision, a test account and a review. Cluster size affects the work, since the realm configuration is shared across nodes and the CLI steps must be verified on each. MFA policy adds time when you must agree which factors apply to which users and how recovery works. Testing with real administrator accounts, a rollback plan and a change window often takes longer than the configuration itself. A written, fixed-scope plan should show these phases with dates, and you should ask for that breakdown in any quote.
What does our internal team need to provide for this integration?
Four roles usually need named people. An authentik administrator owns the OIDC provider, the application definition, the scopes and the group claims. A Proxmox VE administrator owns the realm, the group structure, the permissions and the cluster-wide CLI work. A network and certificate owner confirms that the Proxmox nodes can reach the authentik issuer URL, that TLS certificates are trusted by each node, and that DNS names resolve as expected. A test window is the fourth requirement, with time to sign in with test accounts from each entitlement group, confirm that permissions match, and agree on a fallback path. Confirm these owners and the test window before the work starts, because gaps there cause most of the delay.
Can one administrator set up Proxmox VE with authentik alone?
One experienced administrator can complete the configuration if they hold both authentik administration rights and Proxmox VE root or equivalent rights, can reach the certificate and DNS owners, and have a test window. The risk is the concentration of knowledge and access in one person, especially for the rollback path and for changes that could lock administrators out. Many teams keep a local Proxmox administrator account as a break-glass route and agree on who approves the change. A separate reviewer for the group mapping and the test results is a sensible control even when one person does the build. If your team cannot cover one of the four roles, a fixed-scope engagement can fill the gap and document the result.
What drives the cost of an authentik and Proxmox VE integration?
Cost comes from the people doing the work and the time they need, plus any licenses or infrastructure you add. Main drivers include the number of realms and applications, the complexity of the group and role design, the number of cluster nodes to validate, the MFA rules and the amount of testing and documentation required. One-time costs cover design, configuration, testing and handover. Recurring costs cover the authentik and Proxmox VE subscriptions you choose, the time to review upgrades, and ongoing support if you need it. In a quote, ask for the scope list, the deliverables, the assumptions about your environment, the test plan, the rollback plan, the support entitlements after go-live and which items are fixed and which depend on your decisions. DeployOpen does not publish a price list, and each quote follows from the written scope.
What happens to existing local Proxmox VE accounts after the OIDC realm is added?
Existing local accounts in the Proxmox VE pam and pve realms keep working, because adding an OpenID Connect realm does not remove them. Users who sign in through the new realm are identified by their username with the realm suffix, so a single person can appear as two separate Proxmox identities if both realms are used. Permissions do not move automatically, so each group and user needs an explicit ACL on the objects they manage. Plan how you will retire or keep local accounts, which administrators keep a local login for recovery, and how you will check that no permissions were granted by accident. Confirm the exact realm and user behavior in the Proxmox VE user management documentation for your version before you change production.
What should we check before relying on authentik for Proxmox VE sign-in?
Check that the authentik issuer and the Proxmox realm settings match exactly, including the client ID, secret and redirect URL. Confirm that group claims arrive in the token and map to the expected Proxmox group names, since a missing or misspelled group leaves users with no permissions. Test sign-in on every node, not only the one you configured first, and test with an account that belongs to each entitlement group. Confirm that a local break-glass account still works and that its password is stored in your secrets process. Review the authentik release you run against the supported versions listed in the authentik security policy, and confirm how you will receive security release notices, since the project announces security releases at least 24 hours in advance.
Which Proxmox VE version should we target for this integration?
Target a Proxmox VE release that still receives security support for your planned operating window. Proxmox VE versions are supported at least as long as the matching Debian release has Debian security support, which the Proxmox VE FAQ describes as roughly three years. Proxmox VE 8 on Debian 12 reached end of life in August 2026, so a new deployment should not start on that line. Proxmox VE 9.0 was released on August 5, 2025 on Debian 13, Proxmox VE 9.1 on November 19, 2025 and Proxmox VE 9.2 on May 21, 2026. Confirm the current release and your upgrade path with the Proxmox VE documentation before you choose the version for your cluster.
How DeployOpen scopes and delivers Proxmox VE SSO with authentik
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes connecting authentik as an OpenID Connect realm for Proxmox VE. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- The written scope lists which Proxmox VE clusters, nodes and authentik instances are in or out of the integration.
- We confirm the authentik version in use and the provider settings needed for the OpenID Connect realm.
- Group-to-role mapping, realm suffix naming and the cluster-wide CLI rollout are agreed in writing before build starts.
How we build
- We configure the authentik OAuth2/OIDC provider, application and entitlements that Proxmox VE will read.
- We create the Proxmox VE realm from the CLI on one node and verify that the configuration replicates across the cluster.
- We test login, group membership and permission mapping with pilot accounts before users are moved to the new realm.
How we hand over
- You receive documentation of the authentik provider settings, redirect URIs, realm configuration and group mappings.
- The handover covers the verification steps, rollback approach and the local administrator account kept for recovery.
- Runbooks describe how to add groups, rotate client secrets and check realm status after a Proxmox VE upgrade.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the initial build.
- Support can cover checks after authentik and Proxmox VE upgrades, including Proxmox VE release changes you schedule.
- Ask your quote to name who maintains the realm configuration after go-live and how changes are requested.
