Entra ID 디렉터리 확장으로 커스텀 클레임 발급

Microsoft Entra ID에서 디렉터리 확장 속성으로 커스텀 클레임 발급하기

개요

Microsoft Entra ID(구 Azure AD)의 디렉터리 확장 속성(extensionProperties)은 애플리케이션별 커스텀 사용자 속성을 정의하고 이를 SAML 또는 OIDC 토큰의 클레임으로 발급할 수 있게 해줍니다. 이 방법은 스폰서 ID나 부서별 식별자처럼 민감하거나 특정 그룹에만 필요한 정보를 선택적으로 전달하는 데 유용합니다.

정의: 디렉터리 확장 속성 — 앱 범위로 등록된 사용자 대상의 커스텀 속성.

중요: 이미지와 코드, UI 이름은 원본 흐름을 유지하면서 한국어로 설명합니다.

요구사항 및 전제조건

Entra ID Global Administrator 또는 애플리케이션 소유자 권한
Microsoft Graph에 접근 가능한 권한(Graph Explorer 또는 적절한 토큰)
대상 애플리케이션의 AppObjectId와 ClientId, 대상 사용자/그룹 식별자
SAML/OIDC 기반 SSO 구성(테스트용으로 https://jwt.ms 사용 가능)

단계별 가이드

1 단계: 디렉터리 확장 속성 등록

Graph Explorer 또는 Graph API 호출로 대상 애플리케이션에 커스텀 확장 속성 2개(예: sponsorid1, sponsorid2)를 등록합니다.

요청 예시(POST):

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Request body:
{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

sponsorid2도 동일한 방식으로 등록합니다. 등록이 완료되면 시스템은 다음 형식의 전체 확장 속성 이름을 반환합니다.

extension__sponsorid1
extension__sponsorid2

이 정확한 이름을 이후 매핑에 사용합니다.

2 단계: 사용자에 확장 속성 할당

Graph API로 각 사용자 객체를 PATCH하여 확장 속성 값을 채웁니다.

요청 예시(PATCH):

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Request body:
{
  "extension__sponsorid1": "ABC123"
}

각 사용자에 대해 적절한 sponsorid1 또는 sponsorid2 값을 반복해서 할당합니다.

중요: 속성 이름을 정확히 사용해야 합니다. 대소문자 오류나 누락된 접두사(extension_)는 매핑 실패 원인이 됩니다.

3 단계: 엔터프라이즈 애플리케이션에서 클레임 생성

Entra ID 포털에서 해당 애플리케이션으로 이동한 뒤 Single Sign-On > Attributes & Claims로 가서 새 클레임을 추가합니다.

절차:

Add new claim 클릭
클레임 이름 입력(e.g., sponsorClaim1)
Claim 조건에서 “Member”를 선택하고 해당 클레임을 받을 그룹 선택
Source attribute에 디렉터리 확장 속성 이름 입력(e.g., extension__sponsorid1)

두 번째 그룹과 속성도 동일하게 반복합니다.

팁: 그룹 조건을 설정하지 않으면 모든 사용자에게 클레임이 발급될 수 있으니 주의하세요.

4 단계: 클레임 매핑 오류 처리

오류 메시지: “Application requires custom signing key to customize claims”

임시 우회 방법으로 애플리케이션 등록(manifest)을 다음처럼 업데이트할 수 있습니다:

"acceptMappedClaims": true

이 설정은 커스텀 서명 키 없이도 클레임 커스터마이즈를 허용합니다. 단, 프로덕션 환경에서는 보안 정책에 따라 적절한 서명 키와 검토가 필요합니다.

보안 참고: acceptMappedClaims를 사용하는 동안 클레임 발급 방식과 서명 검증 요구사항을 팀 내 보안 담당자와 확인하세요.

5 단계: 설정 테스트

다음 URL로 애플리케이션에 인증을 요청하고, 그룹에 포함된 사용자로 로그인하여 토큰을 확인합니다.

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

https://jwt.ms 에서 발급된 ID 토큰의 클레임을 확인하면 sponsorid1 또는 sponsorid2가 표시되어야 합니다. 그룹에 속하지 않은 사용자는 해당 스폰서 클레임을 받지 않습니다.

주요 실패 사례와 대비 방법

속성 이름 불일치: extension__sponsorid1 형식을 정확히 사용하지 않으면 클레임 매핑 실패.
권한 부족: Graph API 호출 권한 또는 앱 소유자 권한이 없으면 POST/PATCH 실패.
그룹 필터가 잘못 구성됨: 그룹 조건이 올바르지 않으면 잘못된 사용자에게 클레임 발급.
서명 키 요구 오류: “custom signing key” 오류가 발생하면 manifest 변경 또는 서명 키 설정이 필요.

권장 대응: 각 단계 후 소규모 사용자 그룹으로 단계적 테스트를 수행하고, 실패 시 로그와 오류 메시지를 먼저 확인합니다.

대안 접근법

Azure AD Extension Attributes 대신 Azure AD B2C의 사용자 속성 사용(주로 소비자 인증 시)
사용자 속성을 Microsoft Graph의 “onPremisesExtensionAttributes” 또는 “extensionAttributes”에 저장(조직 환경에 따라)
외부 클레임 변환 서비스(예: API Gateway 또는 애플리케이션 레이어에서 토큰 교체)로 동적 매핑

선택 기준: 관리 복잡도, 감사 요구사항, 토큰 크기 제한, 서명/보안 요구사항을 고려하세요.

역할별 체크리스트

관리자
- AppObjectId, ClientId, Tenant ID 확보
- Graph API 권한 확인
- manifest의 acceptMappedClaims 검토
애플리케이션 소유자
- 엔터프라이즈 앱의 Attributes & Claims 설정
- 클레임 이름 규칙 문서화
운영/보안 팀
- 토큰 서명 정책 검토
- 감사 로그 및 모니터링 구성
사용자 온보딩 담당자
- 각 사용자에 대한 sponsorid 값 관리 및 갱신 절차 정의

Manifest 예제 및 롤백 절차

manifest 수정(간단 예):

{
  ...,
  "acceptMappedClaims": true,
  ...
}

롤백: 문제 발생 시 manifest를 이전 버전으로 복원하고 변경 전 상태로 되돌립니다. 변경 전 항상 백업(manifest 복사본)을 보관하세요.

테스트 케이스(예)

TC1: 그룹 A에 속한 사용자로 로그인 -> 토큰에 sponsorClaim1 포함
TC2: 그룹 B에 속한 사용자로 로그인 -> 토큰에 sponsorClaim2 포함
TC3: 어느 그룹에도 속하지 않은 사용자 -> 토큰에 sponsor 클레임 없음
TC4: 잘못된 extension 이름 사용 시 클레임 미발급 및 오류 로그 생성

승인 기준: TC1~TC3 통과 및 오류 로그이상 없음.

의사결정 트리

flowchart TD
  A[시작] --> B{확장 속성이 필요한가?}
  B -- 아니오 --> C[기존 사용자 속성 사용]
  B -- 예 --> D{애플리케이션 범위인가?}
  D -- 예 --> E[extensionProperties 등록]
  D -- 아니오 --> F[애플리케이션 외부 저장 고려]
  E --> G[사용자에 속성 할당]
  G --> H[애플리케이션 클레임 매핑]
  H --> I[테스트 및 배포]

1줄 용어사전

클레임: 인증 토큰에 포함된 사용자 관련 속성(예: email, name, sponsorid).

현장 팁

토큰 크기 제한에 주의하세요. 많은 커스텀 클레임은 토큰을 비대하게 만들 수 있습니다.
감사 필요 시 사용자별 변경 이력(누가 언제 sponsorid를 변경했는지)을 기록하세요.

결론

디렉터리 확장 속성은 특정 그룹에만 민감한 정보를 안전하게 전달하려는 시나리오에 적합합니다. Graph API로 속성을 등록하고 사용자에 할당한 뒤, 엔터프라이즈 애플리케이션에서 그룹 조건을 명확히 하면 원하는 사용자에게만 커스텀 클레임을 발급할 수 있습니다.

요약: 등록 → 할당 → 클레임 매핑 → 테스트 순으로 진행하고, manifest 변경과 토큰 서명 정책은 보안 팀과 협의하세요.

참고: 본 가이드의 명령 예시는 Graph API 사용을 전제로 하며, 실제 호출 시 적절한 인증 토큰과 권한이 필요합니다.