Resource: proxmox_virtual_environment_realm_openid¶

Manages an OpenID Connect authentication realm in Proxmox VE.

OpenID Connect realms allow Proxmox to authenticate users against an external OpenID Connect provider.

Privileges Required¶

Example Usage¶

resource "proxmox_virtual_environment_realm_openid" "example" {
  realm      = "example-oidc"
  issuer_url = "https://auth.example.com"
  client_id  = "your-client-id"
  client_key = var.oidc_client_secret

  # Username mapping
  username_claim = "email"

  # User provisioning
  autocreate = true

  # Group mapping (optional)
  groups_claim      = "groups"
  groups_autocreate = true
  groups_overwrite  = false

  # Scopes and prompt
  scopes         = "openid email profile"
  query_userinfo = true

  comment = "Example OpenID Connect realm managed by Terraform"
}

Schema¶

Required¶

• client_id (String) OpenID Connect Client ID.
• issuer_url (String) OpenID Connect issuer URL. Proxmox uses OpenID Connect Discovery to configure the provider.
• realm (String) Realm identifier (e.g., 'my-oidc').

Optional¶

• acr_values (String) Authentication Context Class Reference values for the OpenID provider.
• autocreate (Boolean) Automatically create users on the Proxmox cluster if they do not exist.
• client_key (String, Sensitive) OpenID Connect Client Key (secret). Note: stored in Proxmox but not returned by API.
• comment (String) Description of the realm.
• default (Boolean) Use this realm as the default for login.
• groups_autocreate (Boolean) Automatically create groups from claims rather than using existing Proxmox VE groups.
• groups_claim (String) OpenID claim used to retrieve user group memberships.
• groups_overwrite (Boolean) Replace assigned groups on login instead of appending to existing ones.
• prompt (String) Specifies whether the authorization server prompts for reauthentication and/or consent (e.g., 'none', 'login', 'consent', 'select_account').
• query_userinfo (Boolean) Query the OpenID userinfo endpoint for claims. Required when the identity provider does not include claims in the ID token.
• scopes (String) Space-separated list of OpenID scopes to request.
• username_claim (String) OpenID claim used to generate the unique username. Common values are subject, username, email, and upn.

Read-Only¶

• id (String) Realm identifier (same as realm)

Import¶

Import is supported using the following syntax:

#!/usr/bin/env sh
# OpenID realms can be imported using the realm identifier, e.g.:
terraform import proxmox_virtual_environment_realm_openid.example example-oidc

Notes¶

Client Key Security¶

The client_key is sent to Proxmox and stored securely, but it's never returned by the API. This means:

• Terraform cannot detect if the client key was changed outside of Terraform
• You must maintain the client key in your Terraform configuration or use a variable
• The client key will be marked as sensitive in Terraform state

Username Claim¶

The username_claim attribute is fixed after creation — it cannot be changed once the realm is created. Changing it requires destroying and recreating the realm. Common values:

• subject (default) — Uses the OpenID sub claim
• username — Uses the preferred_username claim
• email — Uses the email claim
• upn — Uses the User Principal Name claim (common with ADFS/Azure AD)

Any valid OpenID claim name can be used. Ensure the chosen claim provides unique, stable identifiers for your users.

Common Configuration Scenarios¶

Minimal Configuration¶

resource "proxmox_virtual_environment_realm_openid" "minimal" {
  realm      = "my-oidc"
  issuer_url = "https://auth.example.com"
  client_id  = var.oidc_client_id
  client_key = var.oidc_client_secret
}

With User and Group Provisioning¶

resource "proxmox_virtual_environment_realm_openid" "full" {
  realm          = "corporate-oidc"
  issuer_url     = "https://auth.example.com/realms/my-realm"
  client_id      = var.oidc_client_id
  client_key     = var.oidc_client_secret
  username_claim = "email"
  autocreate     = true

  # Group synchronization
  groups_claim      = "groups"
  groups_autocreate = true

  scopes         = "openid email profile"
  query_userinfo = true
}

See Also¶

• Proxmox VE User Management
• Proxmox VE OpenID Connect Authentication
• Proxmox API: /access/domains