Resource: proxmox_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¶

Path	Attribute
/access/domains	Realm.Allocate

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)

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_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_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
}