keenauth_directory

The keenauth_directory resource creates a SCIM 2.0 directory for an organization. A directory is the endpoint that the organization's identity provider (Okta, Entra ID and others) provisions users and groups to.

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 is https://<scim_host>/scim/v2/<id>. Give it to the identity provider together with a SCIM token.

Changes in place and replacements

name and the directory settings change in place. The provider sends a JSON merge patch with only the changed fields and the ETag of the last read as If-Match; if the directory changed outside this configuration after that read, the API answers 412, nothing is changed, and you run plan again. The API takes no settings when it creates a directory, so the settings you configure are applied right after the create, in the same apply.

Changing organization_id, scim_host or type replaces the directory.

A replacement deletes the old directory first. Deleting a directory is immediate and hard: its tokens, provisioned users, groups, group memberships and pending deprovision holds go with it, and the identity provider's SCIM requests get 401. A new directory has a new ID and a new base URL, and the identity provider must be pointed at it with a new token.
Protect a directory you cannot afford to lose with lifecycle { prevent_destroy = true }.
A new directory is inactive. The provider does not activate or deactivate it (keenauth directories activate and deactivate do); state is only read.
Deleting the organization deletes its directories. A directory deleted outside the provider is removed from state and planned again.

Settings

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

Setting	Values	Default
`provisioning_mode`	`user_store` (environment users, organization memberships and group roles are written) or `mirror` (only directory records are kept)	`user_store`
`attribute_allowlist`	Up to 40 optional SCIM attributes kept on directory users: `title`, `usertype`, `phonenumbers` and the enterprise extension keys	empty
`unverified_domain_action`	`invite` or `mirror_only`, for a user whose email domain is not verified for the organization	`invite`
`delete_action`	`remove_membership` or `delete_user`, for a SCIM `DELETE /Users`	`remove_membership`
`on_delete_memberships`	`keep`, `suspend` or `remove`, for memberships from the directory when it is deleted	`keep`
`mass_deprovision_guard`	`enabled`, `percent` (5 to 50) and `absolute_min` (10 to 1000); more deprovisionings than both within 5 minutes are held for approval	on, 10, 25
`send_welcome_email`	`true` or `false`: an account activation email for new directory users	`false`

A setting you do not configure keeps the server value, and removing a setting from the configuration keeps its last value. In mass_deprovision_guard, a field you do not set keeps its value.
Removing a key from attribute_allowlist deletes that attribute from every user record of the directory in the same update. An empty set ([]) clears the list.
provisioning_mode cannot change while the directory holds user records; the API answers 409.

SCIM tokens

The SCIM token is a secret. The API returns it once, in the response that creates the directory, and no endpoint can read it afterwards. The provider never writes it to state, a plan file, an output or a log. To keep that guarantee, and so that no valid credential exists that nobody holds, the provider revokes the token that the create returns right away.

Create the token for your identity provider with keenauth_directory_token. It keeps the token in state only encrypted to your RSA public key, and you decrypt it with your private key.

If the provider cannot revoke the initial token, the apply still succeeds and prints a warning with the command that revokes it (keenauth directories tokens delete <directory_id> <token_id>).

Arguments

scim_host is the primary host of the environment: its active custom domain, otherwise <slug>.<region>.keenauth.app. It must be a lower-case DNS name that routes to this environment, or the API answers 422. The API does not check that it is the primary host, so a secondary custom domain is accepted.
name is 1 to 64 characters, without control characters and without leading or trailing whitespace. It does not need to be unique.
type is scim and cannot be anything else in GA-1.
state, base_url, created_at, etag and id are read-only. The API does not return scim_host, so the provider derives it from the host of base_url.

Import

Import by directory ID:

tofu import keenauth_directory.acme_okta dir_01j9zq3v8c5m2x7k4t6r1n0b3d