Validate Microsoft Entra 토큰 유효성 검사

아티클
03/18/2024

적용 대상: 모든 API Management 계층

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

참고 항목

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

참고 항목

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

정책 문

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

특성

특성	설명	필수 항목	기본값
tenant-id	Microsoft Entra 서비스의 테넌트 ID 또는 URL입니다. 정책 식이 허용됩니다.	예	해당 없음
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`로 설정되면 유효성 검사 성공을 위해 하나 이상의 클레임이 토큰에 있어야 합니다. 정책 식이 허용됩니다.	아니요

클레임 특성

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

사용

정책 섹션: 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 Entra 테넌트 ID 및 클라이언트 애플리케이션 ID는 명명된 값을 사용하여 제공됩니다. 디코딩된 JWT는 유효성 검사 후 jwt 변수에서 제공됩니다.

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

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" 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>

인증 및 권한 부여

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