Validate Microsoft Entra 토큰 유효성 검사

적용 대상: 모든 API Management 계층

validate-azure-ad-token 정책은 디렉터리의 지정된 보안 주체 집합에 대해 Microsoft Entra(이전의 Azure Active Directory) 서비스에서 제공한 JWT(JSON 웹 토큰)의 존재와 유효성을 적용합니다. 지정된 HTTP 헤더, 쿼리 매개 변수 또는 정책 식 또는 컨텍스트 변수를 사용하여 제공된 값에서 JWT를 추출할 수 있습니다.

참고 항목

Microsoft Entra가 아닌 다른 ID 공급자가 제공한 JWT의 유효성을 검사하기 위해 API Management는 제네릭 validate-jwt 정책도 제공합니다.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. API Management 정책을 설정하거나 편집하는 방법에 대해 자세히 알아봅니다.

정책 문

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

특성

특성	설명	필수 항목	기본값
tenant-id	Microsoft Entra ID 테넌트의 테넌트 ID 또는 URL 또는 다음의 잘 알려진 테넌트 중 하나: - organizations 또는 https://login.microsoftonline.com/organizations - 모든 조직 디렉터리(모든 Microsoft Entra 디렉터리)의 계정에서 토큰을 허용합니다. - common 또는 https://login.microsoftonline.com/common - 모든 조직 디렉터리(모든 Microsoft Entra 디렉터리)의 계정과 개인 Microsoft 계정(예: Skype, XBox)에서 토큰을 허용합니다. 정책 식이 허용됩니다.	예	해당 없음
header-name	토큰을 보유하는 HTTP 헤더의 이름입니다. 정책 식이 허용됩니다.	header-name, query-parameter-name 또는 token-value 중 하나를 지정해야 합니다.	Authorization
query-parameter-name	토큰을 보유하는 쿼리 매개 변수의 이름입니다. 정책 식이 허용됩니다.	header-name, query-parameter-name 또는 token-value 중 하나를 지정해야 합니다.	해당 없음
token-value	토큰이 포함된 문자열을 반환하는 식입니다. 토큰 값의 일부로 Bearer를 반환할 수 없습니다. 정책 식이 허용됩니다.	header-name, query-parameter-name 또는 token-value 중 하나를 지정해야 합니다.	해당 없음
failed-validation-httpcode	JWT가 유효성 검사를 통과하지 못한 경우 반환할 HTTP 상태 코드입니다. 정책 식이 허용됩니다.	아니요	401
failed-validation-error-message	JWT가 유효성 검사를 통과하지 못한 경우 HTTP 응답 본문에 반환할 오류 메시지입니다. 이 메시지는 적절히 이스케이프된 특수 문자를 포함해야 합니다. 정책 식이 허용됩니다.	아니요	기본 오류 메시지는 유효성 검사 문제에 따라 달라집니다(예: "JWT not present(JWT 없음)").
output-token-variable-name	문자열입니다. 토큰 유효성 검사에 성공 시 유형 Jwt의 개체로 토큰 값을 수신할 컨텍스트 변수의 이름입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

Elements

요소	설명	필수
audiences	토큰에 제공할 수 있는 허용 가능한 대상 그룹 클레임 목록을 포함합니다. 여러 audience 값이 있는 경우 각 값은 모든 값이 소진(이 경우 유효성 검사 실패)되거나 한 값이 성공할 때까지 시도됩니다. 정책 식이 허용됩니다.	아니요
backend-application-ids	허용되는 백 엔드 애플리케이션 ID 목록을 포함합니다. 이는 옵션 구성에 대한 고급 사례에서만 필요하며 일반적으로 제거할 수 있습니다. 정책 식은 허용되지 않습니다.	아니요
client-application-ids	허용되는 클라이언트 애플리케이션 ID 목록을 포함합니다. 여러 application-id 요소가 있는 경우 각 값은 모든 값이 소진(이 경우 유효성 검사 실패)되거나 한 값이 성공할 때까지 시도됩니다. 클라이언트 애플리케이션 ID가 제공되지 않으면 하나 이상의 audience 클레임을 지정해야 합니다. 정책 식은 허용되지 않습니다.	아니요
required-claims	토큰에 유효한 것으로 간주될 것으로 예상되는 클레임 값에 대한 claim 요소 목록을 포함합니다. match 특성이 all로 설정되면 유효성 검사 성공을 위해 정책의 모든 클레임 값이 토큰에 있어야 합니다. match 특성이 any로 설정되면 유효성 검사 성공을 위해 하나 이상의 클레임이 토큰에 있어야 합니다. 정책 식이 허용됩니다.	아니요
decryption-keys	비대칭 키로 서명된 토큰의 key 암호를 해독하는 데 사용되는 하위 요소 목록입니다. 여러 키가 있는 경우 모든 키가 소진되거나(이 경우 유효성 검사가 실패) 키가 성공할 때까지 각 키를 시도합니다. 값이 API Management에 certificate-id 업로드된 인증서의 식별자에 설정된 특성을 사용하여 공개 키를 지정합니다.	아니요

클레임 특성

attribute	설명	필수 항목	기본값
name	토큰에 표시될 것으로 예상되는 클레임의 이름입니다. 정책 식이 허용됩니다.	예	해당 없음
match	claim 요소에 있는 match 특성에 따라 유효성 검사 성공을 위해 정책에 있는 모든 클레임 값이 토큰에 표시되어야 하는지가 지정됩니다. 가능한 값은 다음과 같습니다. - all - 유효성 검사 성공을 위해 정책에 있는 모든 클레임 값이 토큰에 표시되어야 합니다. - any - 유효성 검사 성공을 위해 하나 이상의 클레임 값이 토큰에 표시되어야 합니다. 정책 식이 허용됩니다.	아니요	all
separator	문자열입니다. 다중 값 클레임에서 값 세트를 추출하는 데 사용할 구분 기호(예: “,”)를 지정합니다. 정책 식이 허용됩니다.	아니요	해당 없음

키 특성

attribute	설명	필수 항목	기본값
certificate-id	비대칭 키로 서명된 토큰을 확인하기 위해 공개 키를 지정하는 데 사용되는 API Management에 업로드된 인증서 엔터티의 식별자입니다.	예	해당 없음

사용

• 정책 섹션: inbound
• 정책 범위: 전역, 작업 영역, 제품, API, 작업
• 게이트웨이: 클래식, v2, 사용량, 자체 호스팅, 작업 영역

사용법 참고 사항

• 다양한 용도로 서로 다른 범위에서 액세스 제한 정책을 사용할 수 있습니다. 예를 들어 API 레벨에서 validate-azure-ad-token 정책을 적용하여 Microsoft Entra 인증으로 전체 API를 보호하거나 보다 세부적인 제어가 가능하도록 API 작업 레벨에서 적용하고 claims를 사용할 수 있습니다.
• 고객용 Microsoft Entra ID(미리 보기)는 지원되지 않습니다.

예제

단순 토큰 유효성 검사

다음 정책은 validate-azure-ad-token 정책의 최소 형식입니다. Bearer 체계를 사용하여 기본 Authorization 헤더에 JWT가 제공될 것으로 예상합니다. 이 예제에서는 명명된 값을 사용하여 Microsoft Entra 테넌트 ID 및 클라이언트 애플리케이션 ID를 제공합니다.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

대상 그룹 및 클레임이 올바른지 유효성 검사

다음 정책은 대상 그룹이 API Management 인스턴스의 호스트 이름이고 ctry 클레임이 US인지 확인합니다. Microsoft 테넌트 ID는 잘 알려진 organizations 테넌트로, 모든 조직 디렉터리의 계정에서 토큰을 허용합니다. 호스트 이름은 정책 식을 사용하여 제공되며, 클라이언트 애플리케이션 ID는 명명된 값을 사용하여 제공됩니다. 디코딩된 JWT는 유효성 검사 후 jwt 변수에서 제공됩니다.

선택적 클레임에 대한 자세한 내용은 앱에 선택적 클레임 제공을 참조하세요.

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

관련 정책

• 인증 및 권한 부여

관련 콘텐츠

정책 작업에 대한 자세한 내용은 다음을 참조하세요.

• 자습서: API 변환 및 보호
• 정책 문 및 해당 설정에 대한 전체 목록에 대한 정책 참조
• 정책 식
• 정책 설정 또는 편집
• 정책 구성 재사용
• 정책 코드 조각 리포지토리
• Azure의 Microsoft Copilot을 사용하는 작성자 정책