# keenauth_directory

`keenauth_directory` 리소스는 조직의 SCIM 2.0 디렉터리를 생성합니다. 디렉터리는 조직의 ID 공급자(Okta, Entra ID 등)가 사용자와 그룹을 프로비저닝하는 엔드포인트입니다.

```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>` 형식입니다. 이 값을 SCIM 토큰과 함께 ID 공급자에 전달하십시오.

## 인플레이스 변경과 교체

`name`과 디렉터리 설정은 인플레이스로 변경됩니다. 프로바이더는 변경된 필드만 포함한 JSON 병합 패치와 마지막 읽기 시점의 ETag를 `If-Match`로 전송합니다. 마지막 읽기 이후 이 구성 외부에서 디렉터리가 변경되었다면 API가 `412`를 응답하고 아무것도 변경되지 않으므로, plan을 다시 실행하십시오. API는 디렉터리를 생성할 때 설정을 받지 않으므로, 구성한 설정은 생성 직후 같은 apply에서 적용됩니다.

`organization_id`, `scim_host` 또는 `type`을 변경하면 디렉터리가 교체됩니다.

- 교체 시 기존 디렉터리가 먼저 삭제됩니다. 디렉터리 삭제는 즉시 이루어지며 되돌릴 수 없습니다. 토큰, 프로비저닝된 사용자, 그룹, 그룹 멤버십, 대기 중인 디프로비저닝 보류 항목이 모두 함께 삭제되고, ID 공급자의 SCIM 요청은 `401`을 받게 됩니다. 새 디렉터리는 새 ID와 새 base URL을 가지므로, ID 공급자가 새 토큰으로 새 디렉터리를 가리키도록 설정해야 합니다.
- 잃으면 안 되는 디렉터리는 `lifecycle { prevent_destroy = true }`로 보호하십시오.
- 새 디렉터리는 `inactive` 상태입니다. 프로바이더는 디렉터리를 활성화하거나 비활성화하지 않습니다(`keenauth directories activate` 및 `deactivate` 명령을 사용하십시오). `state`는 읽기 전용입니다.
- 조직을 삭제하면 해당 조직의 디렉터리도 삭제됩니다. 프로바이더 외부에서 삭제된 디렉터리는 state에서 제거되고 다음 plan에서 다시 계획됩니다.

## 설정

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

| 설정 | 값 | 기본값 |
|---|---|---|
| `provisioning_mode` | `user_store`(환경 사용자, 조직 멤버십, 그룹 역할이 기록됨) 또는 `mirror`(디렉터리 레코드만 보관됨) | `user_store` |
| `attribute_allowlist` | 디렉터리 사용자에 보관할 선택적 SCIM 속성 최대 40개: `title`, `usertype`, `phonenumbers` 및 엔터프라이즈 확장 키 | 비어 있음 |
| `unverified_domain_action` | `invite` 또는 `mirror_only`. 이메일 도메인이 조직에서 인증되지 않은 사용자에 적용됨 | `invite` |
| `delete_action` | `remove_membership` 또는 `delete_user`. SCIM `DELETE /Users` 요청에 적용됨 | `remove_membership` |
| `on_delete_memberships` | `keep`, `suspend` 또는 `remove`. 디렉터리 삭제 시 디렉터리에서 생성된 멤버십에 적용됨 | `keep` |
| `mass_deprovision_guard` | `enabled`, `percent`(5~50) 및 `absolute_min`(10~1000). 5분 이내 디프로비저닝 건수가 두 기준을 모두 넘으면 승인 대기 상태로 보류됨 | 켜짐, 10, 25 |
| `send_welcome_email` | `true` 또는 `false`. 새 디렉터리 사용자에게 계정 활성화 이메일을 보냄 | `false` |

- 구성하지 않은 설정은 서버 값을 유지하며, 구성에서 설정을 제거해도 마지막 값이 유지됩니다. `mass_deprovision_guard`에서 설정하지 않은 필드는 기존 값을 유지합니다.
- `attribute_allowlist`에서 키를 제거하면 같은 업데이트에서 디렉터리의 모든 사용자 레코드에서 해당 속성이 삭제됩니다. 빈 집합(`[]`)을 지정하면 목록이 비워집니다.
- 디렉터리에 사용자 레코드가 있는 동안에는 `provisioning_mode`를 변경할 수 없으며, API는 `409`를 응답합니다.

## SCIM 토큰

SCIM 토큰은 비밀 값입니다. API는 디렉터리를 생성하는 응답에서 한 번만 토큰을 반환하며, 이후에는 어떤 엔드포인트로도 읽을 수 없습니다. 프로바이더는 토큰을 state, plan 파일, 출력값, 로그 어디에도 기록하지 않습니다. 이 보장을 유지하고, 아무도 보유하지 않은 유효한 자격 증명이 남지 않도록 프로바이더는 생성 시 반환된 초기 토큰을 즉시 해지합니다.

ID 공급자용 토큰은 [`keenauth_directory_token`](/docs/terraform/directory-token)으로 생성하십시오. 이 리소스는 토큰을 사용자의 RSA 공개 키로 암호화된 상태로만 state에 보관하며, 사용자는 개인 키로 복호화할 수 있습니다.

프로바이더가 초기 토큰을 해지하지 못하더라도 apply는 성공하며, 토큰을 해지하는 명령(`keenauth directories tokens delete <directory_id> <token_id>`)과 함께 경고를 출력합니다.

## 인수

- `scim_host`는 환경의 기본 호스트입니다. 활성 사용자 지정 도메인이 있으면 그 도메인을, 없으면 `<slug>.<region>.keenauth.app`을 사용합니다. 소문자 DNS 이름이어야 하며 이 환경으로 라우팅되어야 합니다. 그렇지 않으면 API가 `422`를 응답합니다. API는 기본 호스트인지 확인하지 않으므로 보조 사용자 지정 도메인도 허용됩니다.
- `name`은 1~64자이며 제어 문자와 앞뒤 공백을 포함할 수 없습니다. 고유할 필요는 없습니다.
- `type`은 `scim`이며 GA-1에서는 다른 값을 사용할 수 없습니다.
- `state`, `base_url`, `created_at`, `etag`, `id`는 읽기 전용입니다. API는 `scim_host`를 반환하지 않으므로, 프로바이더는 `base_url`의 호스트에서 이 값을 도출합니다.

## 가져오기

디렉터리 ID로 가져옵니다:

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