# keenauth_directory

La risorsa `keenauth_directory` crea una directory SCIM 2.0 per un'organizzazione. Una directory è l'endpoint a cui il provider di identità dell'organizzazione (Okta, Entra ID e altri) invia utenti e gruppi tramite provisioning.

```terraform
resource "keenauth_directory" "acme_okta" {
  organization_id = keenauth_organization.acme.id
  name            = "Okta"
  scim_host       = "acme.eu.keenauth.app"
}

output "scim_base_url" {
  value = keenauth_directory.acme_okta.base_url
}
```

`base_url` è `https://<scim_host>/scim/v2/<id>`. Forniscilo al provider di identità insieme a un token SCIM.

## Modifiche sul posto e sostituzioni

`name` e le impostazioni della directory cambiano sul posto. Il provider invia una JSON merge patch con solo i campi modificati e l'ETag dell'ultima lettura come `If-Match`; se la directory è cambiata al di fuori di questa configurazione dopo quella lettura, l'API risponde `412`, non viene modificato nulla e devi eseguire di nuovo plan. L'API non accetta impostazioni alla creazione di una directory, quindi le impostazioni configurate vengono applicate subito dopo la creazione, nello stesso apply.

Modificare `organization_id`, `scim_host` o `type` sostituisce la directory.

- Una sostituzione elimina prima la vecchia directory. L'eliminazione di una directory è immediata e definitiva: i suoi token, gli utenti e i gruppi provisionati, le appartenenze ai gruppi e le sospensioni di deprovisioning in attesa vengono eliminati con essa, e le richieste SCIM del provider di identità ricevono `401`. Una nuova directory ha un nuovo ID e un nuovo base URL, e il provider di identità deve essere indirizzato a essa con un nuovo token.
- Proteggi una directory che non puoi permetterti di perdere con `lifecycle { prevent_destroy = true }`.
- Una nuova directory è `inactive`. Il provider non la attiva né la disattiva (lo fanno `keenauth directories activate` e `deactivate`); `state` viene solo letto.
- L'eliminazione dell'organizzazione elimina le sue directory. Una directory eliminata al di fuori del provider viene rimossa dallo state e pianificata di nuovo.

## Impostazioni

```terraform
resource "keenauth_directory" "acme_okta" {
  organization_id = keenauth_organization.acme.id
  name            = "Okta"
  scim_host       = "acme.eu.keenauth.app"

  provisioning_mode   = "user_store"
  attribute_allowlist = ["title", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:department"]
  delete_action       = "remove_membership"

  mass_deprovision_guard = {
    percent      = 20
    absolute_min = 50
  }
}
```

| Impostazione | Valori | Predefinito |
|---|---|---|
| `provisioning_mode` | `user_store` (vengono scritti gli utenti dell'ambiente, le appartenenze all'organizzazione e i ruoli di gruppo) oppure `mirror` (vengono conservati solo i record della directory) | `user_store` |
| `attribute_allowlist` | Fino a 40 attributi SCIM opzionali da conservare sugli utenti della directory: `title`, `usertype`, `phonenumbers` e le chiavi dell'estensione enterprise | vuoto |
| `unverified_domain_action` | `invite` o `mirror_only`, per un utente il cui dominio email non è verificato per l'organizzazione | `invite` |
| `delete_action` | `remove_membership` o `delete_user`, per un SCIM `DELETE /Users` | `remove_membership` |
| `on_delete_memberships` | `keep`, `suspend` o `remove`, per le appartenenze provenienti dalla directory quando questa viene eliminata | `keep` |
| `mass_deprovision_guard` | `enabled`, `percent` (da 5 a 50) e `absolute_min` (da 10 a 1000); più deprovisioning di entrambi i limiti entro 5 minuti vengono sospesi in attesa di approvazione | attivo, 10, 25 |
| `send_welcome_email` | `true` o `false`: un'email di attivazione account per i nuovi utenti della directory | `false` |

- Un'impostazione non configurata mantiene il valore del server, e rimuovere un'impostazione dalla configurazione mantiene il suo ultimo valore. In `mass_deprovision_guard`, un campo non impostato mantiene il suo valore.
- Rimuovere una chiave da `attribute_allowlist` elimina quell'attributo da ogni record utente della directory nello stesso aggiornamento. Un insieme vuoto (`[]`) svuota la lista.
- `provisioning_mode` non può cambiare mentre la directory contiene record utente; l'API risponde `409`.

## Token SCIM

Il token SCIM è un segreto. L'API lo restituisce una sola volta, nella risposta che crea la directory, e nessun endpoint può leggerlo in seguito. Il provider non lo scrive mai nello state, in un plan file, in un output o in un log. Per mantenere questa garanzia, e perché non esista alcuna credenziale valida che nessuno possiede, il provider revoca subito il token restituito dalla creazione.

Crea il token per il tuo provider di identità con [`keenauth_directory_token`](/docs/terraform/directory-token). Esso conserva il token nello state solo cifrato con la tua chiave pubblica RSA, e lo decifri con la tua chiave privata.

Se il provider non riesce a revocare il token iniziale, l'apply va comunque a buon fine e stampa un avviso con il comando che lo revoca (`keenauth directories tokens delete <directory_id> <token_id>`).

## Argomenti

- `scim_host` è l'host primario dell'ambiente: il suo dominio personalizzato attivo, altrimenti `<slug>.<region>.keenauth.app`. Deve essere un nome DNS in minuscolo che instrada verso questo ambiente, altrimenti l'API risponde `422`. L'API non verifica che sia l'host primario, quindi viene accettato un dominio personalizzato secondario.
- `name` è lungo da 1 a 64 caratteri, senza caratteri di controllo e senza spazi iniziali o finali. Non deve essere univoco.
- `type` è `scim` e in GA-1 non può essere altro.
- `state`, `base_url`, `created_at`, `etag` e `id` sono di sola lettura. L'API non restituisce `scim_host`, quindi il provider lo ricava dall'host di `base_url`.

## Import

Importa tramite ID della directory:

```shell
tofu import keenauth_directory.acme_okta dir_01j9zq3v8c5m2x7k4t6r1n0b3d
```