LDAP & OIDC Authentication
ProxCenter supports external authentication via LDAP/Active Directory and OIDC (OpenID Connect) providers. This lets your team log in with their existing corporate credentials instead of managing separate ProxCenter accounts.
Overview
By default, ProxCenter uses local authentication (email and password). When you configure an external identity provider, users can authenticate through that provider and are automatically provisioned in ProxCenter on first login.
You can use LDAP, OIDC, or both simultaneously. Local authentication remains available as a fallback.
LDAP / Active Directory
Configuration
Navigate to Settings > Authentication and select the LDAP tab.
| Field | Description |
|---|---|
| Server URL | LDAP server address (e.g., ldap://dc.example.com or ldaps://dc.example.com) |
| Bind DN | Distinguished name for the service account used to search (e.g., cn=proxcenter,ou=services,dc=example,dc=com) |
| Bind Password | Password for the bind DN |
| Base DN | The search base for users (e.g., ou=users,dc=example,dc=com) |
| User Filter | LDAP filter to match user accounts (e.g., (sAMAccountName={{username}})) |
| Email Attribute | Attribute containing the user's email (default: mail) |
| Display Name Attribute | Attribute for the user's display name (default: displayName) |
| Group Base DN | Optional base DN for group lookups |
| Use TLS | Enable STARTTLS or LDAPS |
Group Mapping
You can map LDAP groups to ProxCenter roles. For example, map CN=Proxmox-Admins,OU=Groups,DC=example,DC=com to the admin role in ProxCenter. Users who belong to that LDAP group are automatically assigned the corresponding role on login.
Test your LDAP configuration using the Test Connection button before saving. It verifies the bind credentials and attempts a user search with the configured filter.
OIDC / SSO
ProxCenter always sends ${NEXTAUTH_URL}/api/auth/callback/oidc as the redirect URI, built from the NEXTAUTH_URL environment variable set at install time. If ProxCenter is behind a reverse proxy, make sure NEXTAUTH_URL matches your public FQDN before registering the application with your identity provider, otherwise the provider will receive ProxCenter's internal IP as the callback and the login flow will fail. See Reverse Proxy and Public URL for the procedure.
Configuration
Navigate to Settings > Authentication and select the OIDC tab.
| Field | Description |
|---|---|
| Provider Name | Display name shown on the login button (e.g., "Sign in with Okta") |
| Issuer URL | The OIDC provider's issuer URL (e.g., https://accounts.google.com) |
| Client ID | The OAuth 2.0 client ID registered with your provider |
| Client Secret | The OAuth 2.0 client secret |
| Scopes | Requested scopes (default: openid profile email) |
| Advanced Endpoints (Authorization / Token / Userinfo URL) | Optional manual overrides, found under the collapsed Advanced Endpoints section. Leave blank for any provider that publishes .well-known/openid-configuration, which is the case for every major identity provider (Entra ID, Google, Okta, Duo, Keycloak, Authentik). Fill these in only if your provider does not expose discovery, in which case all three must be set explicitly. |
URLs to Register with Your Identity Provider
Two URLs have to be registered, and the Provider Configuration card prints both with the exact values ProxCenter will send:
| What to register | Value |
|---|---|
| Redirect / callback URL | https://your-public-fqdn/api/auth/callback/oidc |
| Post-logout redirect URL | https://your-public-fqdn/login |
Neither is a setting: both are built from the NEXTAUTH_URL environment variable, and the card computes them server-side from that variable, so what it prints is what the provider will receive even when you are browsing ProxCenter through a different host name.
The /api/auth/callback/oidc path is fixed. The trailing oidc segment is ProxCenter's internal provider id, not the name you gave the application in your identity provider, so it stays oidc whatever you called the client.
Register both exactly: scheme, host, port and path, with no trailing slash difference. To change them, edit NEXTAUTH_URL in /opt/proxcenter/.env and restart the stack, as described in Reverse Proxy and Public URL.
Signing out of ProxCenter also ends the session at the identity provider, and a provider refuses a logout whose return URL it does not know, exactly as it refuses an unregistered callback. A missing registration answers invalid_redirect_uri and leaves the user stranded at the provider instead of back on the login page. See Signing Out below.
Supported Providers
Any OIDC-compliant provider works. Commonly used with:
- Microsoft Entra ID (Azure AD) -- For Microsoft 365 organizations
- Google Workspace -- For Google-based organizations
- Okta -- Enterprise identity management
- Duo Single Sign-On -- See the dedicated SSO with Duo walkthrough
- Keycloak -- Self-hosted identity provider
- Authentik -- Open-source identity provider popular with homelab users
User Provisioning
When a user logs in via OIDC for the first time, ProxCenter automatically creates a local account linked to their OIDC identity. The user's email and display name are populated from the OIDC claims.
Subsequent logins match on the email address claim. If the user already has a local account with the same email, the accounts are linked.
Group-to-Role Mapping
The User Provisioning card carries a Group-to-role mapping table: "Map IdP group names to a ProxCenter role, in a tenant and optionally inside a single vDC. A group can appear on several rows to grant access in several tenants. First match wins per tenant and vDC."
Each row is four fields, added with Add mapping:
| Field | What it holds |
|---|---|
| IdP Group | The group name as the identity provider sends it |
| Tenant | The tenant the role is granted in |
| vDC | A single vDC of that tenant, or Whole tenant |
| Role | The ProxCenter role to grant |
The Tenant and vDC columns appear on an installation that has more than one tenant or at least one vDC. On a single-tenant installation the table stays the two-column list it has always been, and a mapping written before this release is read as one unscoped row in the provider tenant: there is nothing to migrate.
How a login resolves. Groups are walked in the order the provider sends them, and every row matching a group is taken; the first row per tenant and vDC pair wins, which is the multi-tenant reading of the old "first match wins". One login can therefore end up with a role in the provider tenant and a vDC-scoped role in a customer tenant at the same time. When nothing matches, the Default role is granted in the provider tenant, as before.
A row naming a vDC grants the role scoped to that vDC's Proxmox pool; a row naming the whole tenant leaves the role's own default scope in place. A row pointing at a vDC that has since been deleted, or whose tenant no longer matches, is dropped rather than widened to the whole tenant. Tenant membership follows the mapping too: a user mapped into a new tenant joins it, and one who loses their last grant in a tenant leaves it.
An administrator who has taken a user's role over in one tenant no longer freezes the identity provider out of the other tenants. See When an administrator sets the role by hand.
When an Administrator Sets the Role by Hand
Setting a user's role from Security > Users takes that user over: the role an administrator writes is the one that stands, and a later SSO login leaves it alone instead of adding its own beside it.
Before v1.4.10 it did add its own. The Users dialog replaces every role row of a user, the provider-owned one included; the login re-sync found no provider row, concluded the user was new, and created one. The visible symptoms were a user carrying two roles, a role picker that opened empty in the Users dialog, and a demotion below the configured default that came back at the next login.
To hand a user back to the identity provider, clear their role in the Users dialog. That leaves no row at all, and the next login re-seeds one from the group mapping.
Two rows deliberately do not count as an administrator takeover:
- A row owned by the other directory, an LDAP-owned role when the user signs in through OIDC and the reverse. An account moved from one to the other has to pick up the new mapping rather than keep the old role.
- An expired grant. It already grants nothing, so it must not read as a role the user holds.
Signing Out
Signing out of ProxCenter also ends the session at the identity provider, so a user who signs out and clicks the SSO button again is asked to authenticate rather than being silently signed straight back in.
There is nothing to configure. ProxCenter reads the provider's end_session_endpoint from its discovery document, and a provider that publishes none, Google for instance, keeps the plain local sign-out. A discovery that fails never blocks the sign-out either.
What ProxCenter sends is the provider's end-session endpoint with a post_logout_redirect_uri pointing at /login, plus an id_token_hint when the session carries one, or the client_id when it does not. The hint is the interoperable form and the one Okta requires; the client_id fallback is what lets Keycloak and Entra ID skip their "really sign out?" confirmation screen.
This is why the post-logout redirect URL has to be registered at the provider like the callback URL: without it the provider answers invalid_redirect_uri and the browser never comes back.
Only an OIDC session carries the identity token this uses. A local or LDAP sign-out is the same local sign-out it always was.
Ensure that email addresses returned by your OIDC provider are verified. An attacker who can control their OIDC email claim could potentially link to an existing ProxCenter account.
ProxCenter does not add a second factor on top of OIDC sign-ins. MFA is the responsibility of the identity provider (Entra ID Conditional Access, Okta MFA, Authentik flows, Duo, Keycloak, etc.). For local and LDAP accounts ProxCenter offers a built-in TOTP flow, see Two-Factor Authentication.
LDAP/Active Directory and OIDC authentication are available in the Enterprise edition.
Permissions
| Permission | Description |
|---|---|
settings.manage | Required to configure LDAP and OIDC settings |