사용자 지정 클레임 공급자 참조

아티클
08/01/2024

이 참조 문서에서는 사용자 지정 클레임 공급자 이벤트에 대한 REST API 스키마 및 클레임 매핑 정책 구조에 대해 알아볼 수 있습니다.

토큰 발급 시작 이벤트

사용자 지정 클레임 공급자 토큰 발급 이벤트를 사용하면 외부 시스템의 정보로 애플리케이션 토큰을 보강하거나 사용자 지정할 수 있습니다. 이 정보는 Microsoft Entra 디렉터리에서 사용자 프로필의 일부로 저장할 수 없습니다.

구성 요소 개요

사용자 지정 확장을 설정하고 애플리케이션과 통합하려면 여러 구성 요소를 연결해야 합니다. 다음 다이어그램에서는 사용자 지정 확장을 구현하기 위해 만들어진 구성 지점 및 관계에 대한 개략적인 보기를 보여 줍니다.

REST API 엔드포인트를 공개적으로 사용할 수 있어야 합니다. 이 다이어그램에서는 Azure Function으로 표시됩니다. REST API는 사용자 지정 클레임을 생성하고 사용자 지정 확장에 반환합니다. Microsoft Entra 애플리케이션 등록과 연결됩니다.
API에 연결하도록 구성된 Microsoft Entra ID에서 사용자 지정 확장을 구성해야 합니다.
사용자 지정된 토큰을 받는 애플리케이션이 필요합니다. 예를 들어 https://jwt.ms는 토큰의 디코딩된 콘텐츠를 표시하는 Microsoft 소유 웹 애플리케이션입니다.
https://jwt.ms와 같은 애플리케이션은 앱 등록을 사용하여 Microsoft Entra ID에 등록해야 합니다.
애플리케이션과 사용자 지정 확장 간에 연결을 만들어야 합니다.
필요에 따라 인증 공급자를 사용하여 Azure Function을 보호할 수 있습니다. 이 문서에서는 Microsoft Entra ID를 사용합니다.

REST API

REST API 엔드포인트는 다운스트림 서비스와의 상호 작용을 담당합니다. 예를 들어 데이터베이스, 기타 REST API, LDAP 디렉터리 또는 토큰 구성에 추가하려는 특성이 포함된 다른 저장소가 있습니다.

REST API는 특성을 포함하는 Microsoft Entra ID에 대한 HTTP 응답을 반환합니다. REST API에서 반환하는 특성은 토큰에 자동으로 추가되지 않습니다. 대신 토큰에 포함할 모든 특성에 대해 애플리케이션의 클레임 매핑 정책을 구성해야 합니다. Microsoft Entra ID에서 클레임 매핑 정책은 특정 애플리케이션에 발급된 토큰에서 내보내진 클레임을 수정합니다.

REST API 스키마

토큰 발급 시작 이벤트에 대한 고유한 REST API를 개발하려면 다음 REST API 데이터 계약을 사용합니다. 스키마는 요청 및 응답 처리기를 디자인하는 계약을 설명합니다.

Microsoft Entra ID의 사용자 지정 확장은 JSON 페이로드를 사용하여 REST API에 대한 HTTP 호출을 수행합니다. JSON 페이로드에는 사용자 프로필 데이터, 인증 컨텍스트 특성 및 사용자가 로그인하려는 애플리케이션에 대한 정보가 포함됩니다. 다음 JSON의 id 값은 Microsoft Entra 인증 이벤트 서비스를 나타내는 Microsoft 애플리케이션입니다. JSON 특성을 사용하여 API에서 추가 논리를 수행할 수 있습니다. API에 대한 요청은 다음과 같은 형식입니다.

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Azure에서 예상하는 REST API 응답 형식은 클레임 DateOfBirth 및 CustomRoles가 Azure로 반환되는 형식입니다.

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Fabrikam 조직의 B2B 사용자가 Contoso 조직에 인증할 때 REST API로 전송되는 요청 페이로드에는 다음 형식의 user 요소가 있습니다.

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

지원되는 데이터 형식

다음 표에서는 토큰 발급 시작 이벤트에 대해 사용자 지정 클레임 공급자가 지원하는 데이터 형식을 보여 줍니다.

데이터 형식	지원됨
문자열	True
문자열 ARRAY	True
부울	False
JSON	False

클레임 크기 제한

클레임 공급자가 반환할 수 있는 최대 클레임 크기는 3KB로 제한됩니다. 이는 REST API에서 반환하는 모든 키 및 값 쌍의 합계입니다.

클레임 매핑 정책

Microsoft Entra ID에서 클레임 매핑 정책은 특정 애플리케이션에 발급된 토큰에서 내보내진 클레임을 수정합니다. 여기에는 사용자 지정 클레임 공급자의 클레임과 토큰으로 발급하는 클레임이 포함됩니다.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

ClaimsSchema 요소에는 다음 특성으로 매핑할 클레임 목록이 포함됩니다.

원본은 특성의 원본인 CustomClaimsProvider를 설명합니다. 마지막 요소에는 테스트 목적으로 정책 버전이 있는 고정 값이 포함되어 있습니다. 따라서 source 특성은 생략됩니다.
ID는 사용자가 만든 Azure Function에서 반환되는 클레임의 이름입니다.

Important

ID 특성의 값은 대/소문자를 구분합니다. Azure Function에서 반환한 대로 클레임 이름을 정확히 입력해야 합니다.
JwtClaimType은 OpenID Connect 앱에 대해 내보낸 토큰의 선택적 클레임 이름입니다. JWT 토큰에서 반환하는 다른 이름을 제공할 수 있습니다. 예를 들어 API 응답의 ID 값이 dateOfBirth인 경우 토큰에서 birthdate로 내보낼 수 있습니다.

클레임 매핑 정책을 만든 후 다음 단계는 Microsoft Entra 테넌트로 업로드하는 것입니다. 테넌트에서 다음 claimsMappingPolicy Graph API를 사용합니다.

Important

정의 요소는 단일 문자열 값이 있는 배열이어야 합니다. 문자열은 클레임 매핑 정책의 문자열화되고 이스케이프된 버전이어야 합니다. https://jsontostring.com/과 같은 도구를 사용하여 클레임 매핑 정책을 문자열화할 수 있습니다.

다음을 통해 공유