OpenTofu and Terraform provider

The keenauth/keenauth provider manages the configuration of one KeenAuth environment as code. It calls the management API, speaks plugin protocol 6 and works with OpenTofu and Terraform. It is not published to a provider registry yet.

Authentication and target

The provider manages the environment that its credential belongs to. To manage several environments, configure one provider alias per environment. It authenticates in exactly one of two ways: with a management API key, or keylessly as a management application with private_key_jwt. Setting both is an error.

terraform {
  required_providers {
    keenauth = { source = "keenauth/keenauth" }
  }
}

provider "keenauth" {
  region = "eu"
}

Keyless authentication with private_key_jwt

1. Create an application with app_type = "management" and a keenauth_management_client record with the permissions the configuration needs.
2. Register the public key of a key pair on the application (POST /v1/applications/{application_id}/credentials with type: public_key, the CLI or the dashboard).
3. Give the provider the application ID, the private key and the issuer:

export KEENAUTH_CLIENT_ID="app_..."
export KEENAUTH_PRIVATE_KEY="$(cat ops-automation.pk8.pem)"
export KEENAUTH_ISSUER="https://acme.eu.keenauth.app"
tofu plan

For each management token the provider signs a client assertion (RFC 7523) that is valid for 60 seconds: iss and sub are the client ID, aud is the issuer, jti is random and kid is the RFC 7638 thumbprint of the key. It exchanges the assertion with the client_credentials grant for a 10-minute token and gets a new one a minute before the old one expires. The token can never have more permissions than the application's keenauth_management_client record. Endpoints that accept only an API key, such as management clients, need a provider alias configured with api_key.

Resources

resource "keenauth_connection" "google" {
  key      = "google"
  type     = "social"
  strategy = "google"
  name     = "google"
  status   = "active"
  settings = jsonencode({ scopes = ["openid", "email", "profile"] })
}

resource "keenauth_application" "storefront" {
  key            = "storefront"
  name           = "Storefront"
  app_type       = "web"
  party          = "first_party"
  redirect_uris  = ["https://shop.example.com/callback"]
  connection_ids = [keenauth_connection.google.id]
}

Import

Applications and connections can be imported by their key or their ID, a custom domain by its hostname or its ID, and an API key by its ID:

tofu import keenauth_application.storefront storefront
tofu import keenauth_connection.google conn_01j9zq3v8c5m2x7k4t6r1n0b3d
tofu import keenauth_custom_domain.login login.example.com

The environment settings, the attack protection and the branding draft exist once per environment; import them with the fixed IDs environment-settings, attack-protection and branding. Destroying one of them only removes it from state.

Safe changes

• A create sends an Idempotency-Key, so a retried create never makes a second object.
• An update or delete sends If-Match with the last read ETag. If someone changed the object after the plan was made, the API answers 412 and nothing changes. Run plan again.
• A change made in the dashboard shows up in the next plan as drift, and apply reverts it. An object deleted outside the provider is removed from state and created again.
• An update sends only the changed fields as a JSON merge patch (RFC 7396).

Secrets

No resource stores a secret in plain text in state. Secrets that you give to KeenAuth are write-only arguments (*_wo): the provider sends them but never writes them to state or plan files, and sends them again only when their *_wo_version changes. They need OpenTofu or Terraform 1.11 or later. Today this is the client secret of an enterprise OIDC connection (keenauth_connection_oidc_config). Application client secrets and signing keys are not managed by this version of the provider; create and rotate them in the dashboard or with the CLI. Secrets that KeenAuth generates cannot be write-only, because a write-only argument only carries a value from the configuration to the provider. The provider never creates API keys, because the raw key would end up in state: create a key with the CLI, store it in your secret manager and import it into keenauth_api_key by its ID. A directory's SCIM token is shown once by the API, so the provider revokes the token that creating a directory returns and never keeps it; keenauth_directory_token creates the token for your identity provider and keeps it in state only encrypted to your RSA public key. keenauth_webhook_endpoint keeps the webhook signing secret the same way, only encrypted to its public_key, and discards it when no key is given. Connection settings must not contain secrets; the API rejects secret-like settings.

Limits of this version

• Applications, connections and their OIDC configuration, environment settings, attack protection, the environment theme of the branding draft, custom domains, API keys (import only), organizations, roles and permissions, organization domains, organization session and MFA policies, email templates, management clients, SCIM directories, their group-to-role mappings, SCIM tokens (encrypted to your public key) and webhook endpoints are managed. Hooks, log streams and SMS templates come in later versions.
• The provider does not publish branding; publish the draft in the dashboard or with keenauth branding publish.
• Optional fields with a server default (for example grant_types) keep their last value when you remove them from the configuration.
• Schema descriptions and error messages are in English.