Skip to main content

almaforge_oidc_connector Resource

Manage an AlmaForge OIDCConnector resource.

Before you start​

Use the Terraform setup guide to install the provider and sign in. Your identity needs permission to manage this resource. Keep one owner for each resource name, following the ownership rules.

Register an OAuth client with your identity provider and configure its callback URL before applying. The OIDC guide explains where to find the issuer URL, client ID, and client secret, and how to map claims to roles.

The example creates a role and assigns it to members of the IdP's engineering group. Change the claim name and value to match the claims your IdP actually returns. Keep a working admin login while testing the new connector. The cluster's first admin must already be bootstrapped through OIDC setup.

Example Usage​

Download main.tf into its own directory. Replace example values with your cluster and integration settings. Use the plan and apply workflow after preparing the prerequisites above.

Supply sensitive inputs from your secret manager or protected TF_VAR_ environment variables. Sensitive values are hidden in normal plan output but remain in saved plans and state. See connector secrets.

HCL
# Manage a separate OIDC connector after signing in with an existing admin.
terraform {
  required_providers {
    almaforge = {
      source = "get.almaforge.com/almaforge/almaforge"
    }
  }
}

provider "almaforge" {}

variable "client_secret" {
  type        = string
  sensitive   = true
  description = "OAuth client secret. Supply through TF_VAR_client_secret."
}

resource "almaforge_role" "developers" {
  metadata = {
    name = "developers"
  }
  spec = {
    allow = {
      server_logins = ["ubuntu"]
      server_labels = {
        env = ["dev"]
      }
    }
  }
}

resource "almaforge_oidc_connector" "engineering" {
  metadata = {
    name = "engineering"
  }
  spec = {
    issuer_url    = "https://idp.example.com"
    client_id     = "YOUR_CLIENT_ID"
    client_secret = var.client_secret
    scope         = ["openid", "email", "profile", "groups"]
    claims_to_roles = [
      {
        claim = "groups"
        value = "engineering"
        roles = [almaforge_role.developers.metadata.name]
      }
    ]
  }
}

See the configuration reference for the resource manifest and field context.

Changes and deletion​

Configuration is authoritative. Removing an optional attribute resets its API default or clears it when no default exists. Changing metadata.name replaces the resource. Review the plan before applying. See lifecycle behavior.

Destroy deletes the connector. Check the linked integration guide's operations and removal sections before removing a connector that users or approval workflows depend on.

To read an existing object without managing it, use the named data source.

Schema​

Required​

Optional​

Nested Schema for metadata​

Required:

  • name (String) Resource name. Changing this name replaces the resource.

Optional:

  • labels (Map of String) Labels attached to the resource.

Read-Only:

  • resource_version (String) Server revision used to detect concurrent changes.

Nested Schema for spec​

Optional:

  • acr_values (String) ACR is the Authentication Context Class Reference value.
  • allow_unverified_email (Boolean) AllowUnverifiedEmail tells the connector to accept OIDC users with unverified emails.
  • claims_to_roles (Attributes List) ClaimsToRoles specifies dynamic mapping from OIDC claims to AlmaForge roles. (see below for nested schema)
  • client_id (String) ClientID is the OIDC app client ID.
  • client_secret (String, Sensitive) ClientSecret is the OIDC app client secret. Accepts a literal value or a value-expansion reference such as "${file:/etc/oidc.secret}" or "${env:OIDC_CLIENT_SECRET}".
  • display (String) Display is the connector display name shown in the login UI.
  • google_admin_email (String) GoogleAdminEmail is the email of a Google admin to impersonate for group lookups.
  • google_service_account (String, Sensitive) GoogleServiceAccount is the Google service account JSON (for Google Workspace). Accepts a literal JSON value or a ${env:NAME} / ${file:PATH} reference.
  • issuer_url (String) IssuerURL is the endpoint of the provider, e.g. https://accounts.google.com.
  • max_age (String) MaxAge is how recently the identity provider must have authenticated a user for a login to be accepted. The login request carries it to the provider, which is expected to re-authenticate anyone whose session is older, and the response is refused unless it reports an authentication time inside the window. It does not bound the lifetime of the session that the login produces. Written as a duration, for example "12h" or "30m". Zero means no requirement.
  • pkce_mode (String) PKCEMode controls PKCE (Proof Key for Code Exchange) usage. Valid values: "auto" (default), "enabled", "disabled".
  • prompt (String) Prompt is the OIDC "prompt" parameter sent on the authorization request. Valid values per OIDC Core 1.0 §3.1.2.1: "none", "login", "consent", "select_account". Space-separated combinations are allowed (e.g. "login consent"). When left empty it defaults to "select_account", which makes the identity provider show its account picker instead of silently reusing an existing session.
  • provider (String) Provider is the external identity provider name.
  • scope (List of String) Scope specifies additional OAuth2 scopes to request from the provider.
  • username_claim (String) UsernameClaim specifies the name of the claim to use as the user's AlmaForge username.

Nested Schema for spec.claims_to_roles​

Optional:

  • claim (String) Claim is the claim name.
  • roles (List of String) Roles is the set of AlmaForge roles this mapping resolves to.
  • value (String) Value is the claim value to match.

Import​

Create the matching resource block first, then import the existing object's metadata.name. With the example above, the Terraform address and server name are:

Terminal
terraform import almaforge_oidc_connector.engineering engineeringterraform plan

Use the address from your configuration and the name of the existing object. Import records the object in Terraform state. Review the first plan carefully because omitted fields will reset or clear on apply. The import guide also covers generating configuration from an existing object.

Supply the connector's current secret values before applying. The API redacts credentials on reads, so import cannot recover them. Configured secrets are preserved during subsequent refreshes.