Back to Documentation

OpenID Connect Configuration

ProxMan supports OpenID Connect (OIDC) authentication, allowing you to use modern OAuth2-based single sign-on with your Proxmox VE and Proxmox Backup Server infrastructure.

What is OpenID Connect?

OpenID Connect is an authentication layer built on top of OAuth 2.0 that provides:

  • Single Sign-On (SSO): Use one identity provider across multiple services
  • Enhanced Security: Token-based authentication without storing passwords
  • Modern Standards: Industry-standard authentication protocol
  • Centralized Management: Manage user access from a single identity provider

Prerequisites

Before configuring OpenID Connect in ProxMan, you need:

1. Proxmox Server: Version 7.0 or later (8.x recommended)

2. Identity Provider: A configured OIDC provider (Keycloak, Azure AD, Google, Okta, etc.)

3. Proxmox OIDC Realm: OpenID Connect realm configured on your Proxmox server

4. Network Access: ProxMan must be able to reach both Proxmox and your identity provider

Configuring OpenID Connect on Proxmox

Step 1: Create OpenID Realm in Proxmox

1. Log into your Proxmox web interface

2. Navigate to Datacenter → Permissions → Realms

3. Click Add → OpenID Connect Server

4. Configure the realm:

- Realm: Choose a name (e.g., myoidc)

- Issuer URL: Your identity provider's issuer URL

- Client ID: Application/client ID from your identity provider

- Client Key: Client secret from your identity provider

- Username Claim: Claim to use as username (usually sub or email)

- Scopes: Required scopes (typically openid profile email)

- Autocreate Users: Enable to automatically create users on first login

Step 2: Configure Your Identity Provider

Keycloak Example

1. Create a new client in Keycloak

2. Set Client Protocol: openid-connect

3. Set Access Type: confidential

4. Add Valid Redirect URIs: https://your-proxmox-server/* and proxman://auth/callback

5. Note the Client ID and Client Secret

6. Configure Scopes: Ensure openid, profile, and email are included

Azure AD Example

1. Register a new application in Azure AD

2. Add Redirect URI: https://your-proxmox-server/* and proxman://auth/callback

3. Create a Client Secret under Certificates & Secrets

4. Note the Application (client) ID and Directory (tenant) ID

5. Configure API Permissions: Add openid, profile, and email

6. Use Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0

Step 3: Assign Permissions

After the realm is configured, assign appropriate permissions:

1. Navigate to Datacenter → Permissions

2. Add permissions for users from your OIDC realm

3. Example: /vms → user@myoidc → PVEVMUser role

Using OpenID Connect in ProxMan

Adding a Server with OIDC

1. Open ProxMan

2. Tap "Add Server"

3. Choose Proxmox VE or Proxmox Backup Server

4. Enter server details:

- Display Name: Friendly name for your server

- Hostname/IP: Your Proxmox server address

- Port: 8006 (PVE) or 8007 (PBS)

- Realm: Select your OIDC realm (e.g., @myoidc)

- HTTPS: Enable for secure connection

5. Tap "Authenticate with OpenID"

6. You'll be redirected to your identity provider

7. Log in with your identity provider credentials

8. Authorize Proxmox to access your account

9. You'll be redirected back to ProxMan with authentication complete

Authentication Flow

The OpenID Connect authentication flow in ProxMan works as follows:

1. Initiate Login: ProxMan sends an authentication request to Proxmox

2. Redirect to IdP: Proxmox redirects to your identity provider

3. User Authentication: You log in at your identity provider

4. Authorization: You authorize Proxmox to access your account

5. Token Exchange: Identity provider returns tokens to Proxmox

6. Session Creation: Proxmox creates a session and returns credentials to ProxMan

7. Secure Storage: ProxMan stores tokens securely in iOS Keychain or Android Keystore

Common Identity Providers

Keycloak

Issuer URL Format 

https://keycloak.example.com/realms/{realm-name}

Configuration

  • Client Protocol: openid-connect
  • Access Type: confidential
  • Standard Flow: Enabled
  • Direct Access Grants: (Optional) Enabled if you need password grant support
  • Valid Redirect URIs: 
https://your-proxmox:8006/*
proxman://auth/callback
  • Web Origins: 
https://your-proxmox:8006
proxman://auth/callback

---

Azure Active Directory (Microsoft Entra ID)

Issuer URL Format 

https://login.microsoftonline.com/{tenant-id}/v2.0

Configuration

  • Platform: Web
  • Redirect URIs: 
https://your-proxmox:8006/*
proxman://auth/callback
  • Supported account types: Choose based on your audience (Single tenant, Multi-tenant, etc.)
  • Client secret: Required
  • Implicit grant: Ensure ID tokens are enabled
  • Allow public client flows: Disabled (for confidential clients only)

---

Okta

Issuer URL Format 

https://{your-domain}.okta.com/oauth2/default

Configuration

  • Application type: Web
  • Grant type: Authorization Code
  • Sign-in redirect URIs: 
https://your-proxmox:8006/*
proxman://auth/callback
  • Sign-out redirect URIs: (Optional) 
https://your-proxmox:8006/
  • Trusted Origins:

Add both your Proxmox URL and your app’s scheme (proxman://auth/callback)

---

Auth0

Issuer URL Format 

https://{your-domain}.auth0.com/

Configuration

  • Application type: Regular Web Application
  • Allowed Callback URLs: 
https://your-proxmox:8006/*
proxman://auth/callback
  • Allowed Logout URLs: 
https://your-proxmox:8006/
  • Allowed Web Origins: 
https://your-proxmox:8006
proxman://auth/callback
  • Grant Types: Authorization Code (PKCE if possible)

Security Best Practices

Identity Provider Configuration

  • Use HTTPS: Always use HTTPS for both Proxmox and identity provider
  • Restrict Redirect URIs: Only allow specific redirect URIs
  • Enable MFA: Use multi-factor authentication at your identity provider
  • Audit Logs: Monitor authentication logs for suspicious activity

Proxmox Configuration

  • Minimal Scopes: Request only necessary scopes
  • User Permissions: Grant least-privilege access to OIDC users
  • Token Lifetime: Configure appropriate token expiration times
  • Autocreate Users: Consider security implications before enabling
  • Username Claims: Use stable claims like sub rather than email

ProxMan Security

  • Biometric Lock: Enable Face ID/Touch ID for app access
  • Network Security: Use VPN when accessing over public networks

Troubleshooting

Authentication Fails

Problem: Cannot authenticate with OpenID Connect

Solutions:

  • Verify realm name matches exactly (case-sensitive)
  • Check identity provider is accessible from your network
  • Confirm client ID and secret are correct in Proxmox
  • Verify redirect URIs are properly configured
  • Check Proxmox logs

Token Expired Errors

Problem: Frequent "token expired" messages

Solutions:

  • Check system time on mobile device is correct
  • Verify token lifetime settings in identity provider
  • Ensure refresh tokens are enabled
  • Check network connectivity for token refresh

User Not Found

Problem: "User does not exist" error after authentication

Solutions:

  • Enable "Autocreate Users" in Proxmox OIDC realm
  • Manually create user in Proxmox with correct realm
  • Verify username claim mapping is correct
  • Check user has appropriate permissions

Redirect Issues

Problem: Stuck on redirect or blank screen

Solutions:

  • Verify redirect URIs include wildcard: proxman://auth/callback
  • Check HTTPS is properly configured
  • Clear ProxMan app cache and retry
  • Verify identity provider allows the redirect

Advanced Configuration

You can get additional configuration details from Proxmox Documentation

Related Documentation

Support

Having problems with OpenID Connect configuratio with ProxMan?

  • Email: support@proxman.app
  • Documentation: Check our FAQ
  • Identity Provider Docs: Consult your IdP's documentation

Was this page helpful? Contact Support