# keenauth_role

La risorsa `keenauth_role` gestisce un ruolo dell'ambiente e il suo insieme completo di autorizzazioni. Un ruolo che appartiene a un'organizzazione è una risorsa diversa, `keenauth_organization_role`. La data source `keenauth_role` legge un ruolo tramite `id` o `key`.

```terraform
resource "keenauth_permission" "invoices_read" {
  api_id = "api_01j9zq3v8c5m2x7k4t6r1n0b3d"
  value  = "invoices:read"
}

resource "keenauth_role" "billing" {
  key         = "billing"
  name        = "Billing"
  description = "Invoices and payment methods."

  permission_ids = [keenauth_permission.invoices_read.id]
}

data "keenauth_role" "billing" {
  key = "billing"
}
```

## Ciclo di vita

- `key` è unica nell'ambiente, compare nel claim `org_roles` e non può essere modificata: una nuova key sostituisce il ruolo.
- `name` ha da 1 a 128 caratteri e `description` al massimo 1024. Nessuno dei due può iniziare o terminare con uno spazio bianco, perché l'API li tronca.
- `permission_ids` è l'insieme completo (al massimo 500). Viene scritto con una richiesta separata dopo i campi del ruolo; se quella richiesta fallisce in fase di creazione, il ruolo resta nello state come tainted e viene sostituito al successivo apply. Un'autorizzazione aggiunta o rimossa altrove viene ripristinata dal successivo apply.
- `is_privileged` contrassegna un ruolo privilegiato. In self-service solo un amministratore che possiede il ruolo di admin dell'organizzazione può assegnarlo, e un mapping di gruppo esterno che lo riguarda richiede `roles:write` e un'approvazione. Rendere privilegiato un ruolo esistente lascia i suoi mapping di gruppo non approvati finché non vengono approvati. Il valore predefinito è `false`; quando importi un ruolo privilegiato, scrivi esplicitamente `is_privileged = true`, altrimenti il successivo apply renderà il ruolo non privilegiato.
- Gli aggiornamenti e le eliminazioni inviano `If-Match` con l'ETag letto per ultimo. Se il ruolo è cambiato dopo la creazione del piano, l'API risponde `412` e nulla cambia; esegui di nuovo `plan`.
- Con `force_destroy = true` anche un ruolo assegnato viene eliminato e le sue assegnazioni vengono rimosse nella stessa richiesta; altrimenti l'eliminazione di un ruolo assegnato fallisce con `409 role_in_use`. Un ruolo usato come ruolo di admin o di membro predefinito di un'organizzazione non può essere eliminato in alcun modo. Modificare solo `force_destroy` non invia alcuna richiesta.
- Le assegnazioni di ruoli a utenti e le appartenenze non sono risorse. Sono dati personali e non finiscono mai nello state; gestiscile con l'API, la CLI o la dashboard.

## Import

Importa per key o per ID:

```shell
tofu import keenauth_role.billing billing
tofu import keenauth_role.billing rol_01j9zq3v8c5m2x7k4t6r1n0b3d
```