Provider OpenTofu e Terraform

Il provider keenauth/keenauth gestisce la configurazione di un ambiente KeenAuth come codice. Chiama l'API di gestione, usa il protocollo plugin 6 e funziona con OpenTofu e Terraform. Non è ancora pubblicato in un registro dei provider.

Autenticazione e destinazione

Il provider gestisce l'ambiente a cui appartiene la sua credenziale. Per gestire più ambienti, configura un alias del provider per ogni ambiente. L'autenticazione avviene in esattamente uno dei due modi: con una chiave API di gestione, oppure senza chiave come applicazione management con private_key_jwt. Impostarli entrambi è un errore.

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

provider "keenauth" {
  region = "eu"
}

Autenticazione senza chiave con private_key_jwt

1. Crea un'applicazione con app_type = "management" e un record keenauth_management_client con le autorizzazioni di cui la configurazione ha bisogno.
2. Registra la chiave pubblica di una coppia di chiavi sull'applicazione (POST /v1/applications/{application_id}/credentials con type: public_key, tramite la CLI o la dashboard).
3. Fornisci al provider l'ID dell'applicazione, la chiave privata e l'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

Per ogni token di gestione il provider firma un client assertion (RFC 7523) valido per 60 secondi: iss e sub sono l'ID client, aud è l'issuer, jti è casuale e kid è il thumbprint RFC 7638 della chiave. Scambia l'assertion con la concessione client_credentials per un token di 10 minuti e ne ottiene uno nuovo un minuto prima che quello vecchio scada. Il token non può mai avere più autorizzazioni del record keenauth_management_client dell'applicazione. Gli endpoint che accettano solo una chiave API, come i client di gestione, richiedono un alias del provider configurato con api_key.

Risorse

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

Importazione

Le applicazioni e le connessioni possono essere importate tramite la loro key o il loro ID, un dominio personalizzato tramite il suo hostname o il suo ID, e una chiave API tramite il suo ID:

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

Le impostazioni dell'ambiente, la protezione dagli attacchi e la bozza di branding esistono una sola volta per ambiente; importali con gli ID fissi environment-settings, attack-protection e branding. La distruzione di uno di essi lo rimuove solo dallo stato.

Modifiche sicure

• Una creazione invia un Idempotency-Key, quindi una creazione ripetuta non crea mai un secondo oggetto.
• Un aggiornamento o una eliminazione invia If-Match con l'ultimo ETag letto. Se qualcuno ha modificato l'oggetto dopo la creazione del piano, l'API risponde con 412 e nulla cambia. Esegui di nuovo plan.
• Una modifica fatta nella dashboard compare nel plan successivo come drift, e apply la riporta indietro. Un oggetto eliminato al di fuori del provider viene rimosso dallo stato e creato di nuovo.
• Un aggiornamento invia solo i campi modificati come JSON merge patch (RFC 7396).

Segreti

Nessuna risorsa memorizza un segreto in chiaro nello stato. I segreti che fornisci a KeenAuth sono argomenti write-only (*_wo): il provider li invia ma non li scrive mai nei file di stato o di piano, e li reinvia solo quando cambia il loro *_wo_version. Richiedono OpenTofu o Terraform 1.11 o successivo. Attualmente si tratta del client secret di una connessione OIDC enterprise (keenauth_connection_oidc_config). I client secret delle applicazioni e le chiavi di firma non sono gestiti da questa versione del provider; creali e ruotali nella dashboard o con la CLI. I segreti generati da KeenAuth non possono essere write-only, perché un argomento write-only trasporta un valore solo dalla configurazione al provider. Il provider non crea mai chiavi API, perché la chiave grezza finirebbe nello stato: crea una chiave con la CLI, conservala nel tuo gestore di segreti e importala in keenauth_api_key tramite il suo ID. Il token SCIM di una directory viene mostrato una sola volta dall'API, quindi il provider revoca il token restituito dalla creazione di una directory e non lo conserva mai; keenauth_directory_token crea il token per il tuo provider di identità e lo mantiene nello stato solo cifrato con la tua chiave pubblica RSA. keenauth_webhook_endpoint mantiene il segreto di firma del webhook allo stesso modo, solo cifrato con il suo public_key, e lo scarta quando non viene fornita alcuna chiave. Le settings di una connessione non devono contenere segreti; l'API rifiuta le impostazioni che sembrano segreti.

Limiti di questa versione

• Sono gestiti: applicazioni, connessioni e la relativa configurazione OIDC, impostazioni dell'ambiente, protezione dagli attacchi, il tema dell'ambiente della bozza di branding, domini personalizzati, chiavi API (solo importazione), organizzazioni, ruoli e autorizzazioni, domini delle organizzazioni, policy di sessione e MFA delle organizzazioni, modelli email, client di gestione, directory SCIM, le relative associazioni gruppo-ruolo, token SCIM (cifrati con la tua chiave pubblica) ed endpoint webhook. Hook, log stream e modelli SMS arriveranno nelle versioni successive.
• Il provider non pubblica il branding; pubblica la bozza nella dashboard o con keenauth branding publish.
• I campi opzionali con un valore predefinito lato server (ad esempio grant_types) mantengono l'ultimo valore quando li rimuovi dalla configurazione.
• Le descrizioni dello schema e i messaggi di errore sono in inglese.