SCIM으로 Vault ID 프로비저닝하기

SCIM으로 Vault ID 프로비저닝하기

Vault Enterprise는 외부 ID 플랫폼에서 ID 사용자와 그룹을 프로비저닝하기 위한 SCIM 2.0 (System for Cross-domain Identity Management) 지원을 베타 기능으로 제공합니다.

출처: 문서

본문

베타 기능: 베타 기능은 안정적이지만 불완전할 수 있고 변경될 수 있습니다. Vault의 프로덕션 배포에는 베타 기능 사용을 강력히 권장하지 않습니다.

Vault는 identity 시크릿 엔진을 통해 SCIM을 노출합니다.

• SCIM 사용자는 Vault 엔티티(entity) 에 매핑됩니다.
• alias_mount_accessor를 구성하면 SCIM 사용자도 마운트 바인딩 엔티티 별칭을 생성합니다.
• SCIM 그룹은 Vault 내부 ID 그룹에 매핑됩니다.
• SCIM 클라이언트는 자신이 만든 사용자와 그룹만 보고 관리할 수 있습니다.
• SCIM은 Vault 정책을 관리하지 않습니다.

시작하기 전에

• Vault Enterprise 2.x.x 이상이 있어야 합니다.
• 인증 메서드를 활성화하고 ID 리소스를 관리할 권한이 있어야 합니다.
• SCIM 클라이언트에 사용할 인증 메서드를 알아야 합니다.

인증이 SCIM 클라이언트의 접근 부여 주체(access_grant_principal)로 구성된 Vault 엔티티로 해석되면, 어떤 Vault 인증 메서드든 SCIM에 대해 작동할 수 있습니다.

일부 SCIM 클라이언트는 정적 베어러 토큰(static bearer token)만 지원합니다. 이런 경우 엔티티 별칭에 연결된 토큰을 발행해 커넥터에 직접 전달할 수 있으므로 token 인증이 대개 가장 간단한 설정입니다.

SCIM 활성화

Vault는 SCIM 기능을 활성화 플래그(activation flag) 뒤에 둡니다. 기능을 활성화할 때까지 Vault는 SCIM 구성 및 프로토콜 요청에 오류를 반환합니다.

$ vault write -f sys/activation-flags/enable-scim/activate

$ curl \
    --request PUT \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/activation-flags/enable-scim/activate

SCIM 플래그 활성화는 일회성 작업입니다. 자세한 내용은 activation flags API를 참고하세요.

SCIM 엔드포인트와 네임스페이스

활성화 후 Vault는 다음 엔드포인트 아래에 SCIM 엔드포인트를 노출합니다.

• /v1/identity/scim/v2: /Users, /Groups, /ServiceProviderConfig, /Schemas, /ResourceTypes용 SCIM 기본 경로
• /v1/identity/scim/client(및 /clients): Vault SCIM 클라이언트 관리

Vault Enterprise 네임스페이스를 사용한다면 다음 두 방법 중 하나로 SCIM을 처리할 수 있습니다.

• 요청 경로에 네임스페이스를 넣기(예: /v1/admin/identity/scim/v2/Users)
• 표준 Vault 네임스페이스 헤더를 네임스페이스 없는 경로와 함께 사용하기

SCIM 클라이언트 구성하기

SCIM 프로토콜 요청을 보내기 전에 SCIM 클라이언트를 만드세요. 각 SCIM 클라이언트는 하나의 외부 프로비저닝 시스템을 나타냅니다. SCIM 클라이언트 구성은 다음 필드로 구성됩니다.

• client_name(URL의 일부): 외부 시스템에 대한 네임스페이스 범위 이름
• access_grant_principal: 해당 클라이언트의 SCIM API 요청을 승인하는 Vault 엔티티의 ID
• alias_mount_accessor: 선택적 인증 마운트 액세서. 설정하면 Vault가 각 SCIM 사용자에 대한 마운트 바인딩 엔티티 별칭도 생성합니다.

Vault는 다음 규칙을 강제합니다.

• access_grant_principal은 같은 네임스페이스의 기존 엔티티를 참조해야 합니다.
• alias_mount_accessor는 설정 시 같은 네임스페이스의 기존 비로컬 인증 마운트를 참조해야 합니다.
• alias_mount_accessor는 생성 후 변경할 수 없습니다(불변).
• SCIM 클라이언트는 자신이 만든 사용자와 그룹만 관리할 수 있습니다.

Vault는 alias_mount_accessor를 비로컬 인증 마운트로 제한합니다.

인증 모델 (Authentication model)

SCIM 클라이언트는 지원되는 인증 메서드를 통해 Vault에 인증하고, Vault 토큰을 얻은 뒤 그 토큰을 SCIM 요청에 사용합니다. Vault는 토큰 엔티티를 기반으로 SCIM 클라이언트 ID를 유추합니다.

높은 수준에서:

1. SCIM 클라이언트를 나타내는 Vault 엔티티를 만듭니다.
2. access_grant_principal로 엔티티를 SCIM 클라이언트에 바인딩합니다.
3. 그 엔티티로 해석되는 인증 메서드를 통해 인증합니다.
4. 결과 Vault 토큰을 SCIM API 호출에 사용합니다.

토큰이 구성된 엔티티로 해석되지 않거나, 엔티티에 연결된 SCIM 클라이언트가 없으면 Vault는 SCIM 요청을 거부합니다.

간단한 베어러 토큰 설정

다음 예시는 정적 베어러 토큰을 기대하는 SCIM 제품에 연결하기 쉬우므로 token 인증 메서드를 사용합니다. 하지만 SCIM 클라이언트용으로 구성된 엔티티로 매핑되는 어떤 인증 메서드든 사용할 수 있습니다.

1. SCIM 클라이언트 토큰용 정책 만들기

$ vault policy write scim-client - <<'EOF'
path "identity/scim/v2/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

2. SCIM 클라이언트용 Vault 엔티티 만들기

$ vault write -format=json identity/entity name="scim-client"

반환된 엔티티 ID를 저장하세요.

3. SCIM 클라이언트 구성 만들기

$ vault write identity/scim/client/example-client \
    access_grant_principal="<entity_id>"

프로비저닝된 사용자에 대한 별칭도 Vault가 만들게 하려면 alias_mount_accessor 매개변수를 포함하세요.

4. token 인증 마운트에 엔티티 별칭 만들기

인증 마운트를 나열하고 token/의 액세서를 기록하세요.

$ vault auth list

SCIM 클라이언트 엔티티에 대한 해당 마운트에 별칭을 만듭니다.

$ vault write identity/entity-alias \
    name="example-client" \
    mount_accessor="<token_mount_accessor>" \
    canonical_id="<entity_id>"

5. 토큰 역할 만들고 베어러 토큰 발행하기

$ vault write auth/token/roles/example-scim \
    allowed_entity_aliases="example-client" \
    orphan=true \
    token_no_default_policy=true

$ vault token create \
    -role=example-scim \
    -entity-alias=example-client \
    -policy=scim-client \
    -no-default-policy

반환된 토큰 값을 SCIM 요청의 베어러 토큰으로 사용하세요. 토큰 인증 마운트에 구성된 TTL을 중심으로 토큰 갱신·교체를 계획하는 것을 강력히 권장합니다.

SCIM 요청 보내기

요청 헤더에 Vault 토큰을 사용해 SCIM 엔드포인트를 호출합니다.

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --header "Content-Type: application/scim+json" \
    ${VAULT_ADDR}/v1/identity/scim/v2/ServiceProviderConfig

Vault가 SCIM 리소스를 매핑하는 방식

SCIM 리소스	Vault 리소스	동작
User	엔티티	userName은 엔티티 이름에, externalId는 엔티티 외부 ID에 매핑됩니다.
Group	내부 ID 그룹	displayName은 그룹 이름에 매핑됩니다.

중요한 동작:

• externalId는 SCIM 사용자 생성 시 필수입니다.
• externalId는 생성 후 고정됩니다.
• 그룹 구성원은 Vault 사용자 리소스 ID를 참조해야 합니다.
• SCIM 클라이언트는 자신이 소유한 사용자만 그룹에 추가할 수 있습니다.

SCIM 클라이언트가 alias_mount_accessor를 설정하면 Vault는 각 프로비저닝된 사용자에 대한 마운트 바인딩 엔티티 별칭을 만들고 별칭 이름을 SCIM userName과 일치시킵니다.

지원되는 프로토콜 표면

Vault는 다음 SCIM 영역을 지원합니다.

• /identity/scim/client를 통한 SCIM 클라이언트 구성
• 사용자 생성, 읽기, 목록, 교체, 패치, 삭제
• 그룹 생성, 읽기, 목록, 교체, 패치, 삭제
• Schemas, ResourceTypes, ServiceProviderConfig용 검색(discovery) 엔드포인트

Vault는 SCIM 응답을 application/scim+json으로 반환합니다.

현재 제한 사항

• Vault는 /Me를 지원하지 않습니다.
• Vault는 SCIM 벌크(bulk) 작업을 지원하지 않습니다.
• Vault는 정렬(sort), ETag, 비밀번호 변경 작업을 지원하지 않습니다.
• 사용자 PATCH는 active에 대한 단일 replace 작업만 지원합니다.
• 그룹 PATCH는 구성원 추가·제거 작업만 지원합니다.
• Vault는 목록 엔드포인트에서 제한적 필터링을 지원합니다. /Users는 userName, externalId, active에 대한 eq를 지원합니다. /Users와 /Groups는 meta.lastModified에 대한 gt, ge, lt, le를 지원합니다. /Groups는 displayName에 대한 eq를 지원합니다.
• Vault는 문서화된 필드와 연산자 외의 임의 SCIM 필터 표현식을 지원하지 않습니다.
• 그룹 구성원은 사용자 이름이나 externalId가 아닌 Vault 사용자 리소스 ID를 사용해야 합니다.
• 사용자 groups는 같은 SCIM 클라이언트가 관리하는 그룹의 직접 구성원만 보여줍니다.
• externalId는 사용자 생성 시 필수이며 나중에 업데이트할 수 없습니다.
• alias_mount_accessor는 클라이언트 생성 후 불변하며, 해당 클라이언트에 선택한 인증 마운트 전략에 묶여 있습니다.

SCIM 클라이언트 삭제

SCIM 클라이언트를 삭제하면 비동기 정리 워크플로가 시작됩니다.

• Vault는 해당 클라이언트의 새 SCIM 요청을 차단합니다.
• Vault는 해당 클라이언트가 소유한 사용자와 그룹을 제거합니다.
• Vault가 관리 리소스와 SCIM 클라이언트 구성을 삭제할 때까지 정리가 백그라운드에서 계속됩니다.

삭제하기 전에 SCIM 클라이언트가 소유한 리소스를 검토하세요.

관련 문서

• Identity 개념
• Identity 시크릿 엔진
• SCIM API

더 알아보기 (Learn more)

• Vault 네임스페이스