Microsoft Entra ID에서 OAuth 2.0 권한 부여를 사용하여 Azure API Management에서 API 보호

  • 아티클

적용 대상: 모든 API Management 계층

이 문서에서는 Microsoft Entra ID에서 OAuth 2.0 프로토콜을 사용하여 API를 보호하도록 Azure API Management 인스턴스를 구성하는 대략적인 단계에 대해 알아봅니다.

API 인증의 개념적 개요는 API Management의 API에 대한 인증 및 권한 부여를 참조하세요.

필수 조건

이 문서의 단계를 수행하기 전에 다음이 필요합니다.

  • API Management 인스턴스
  • API Management 인스턴스를 사용하여 게시된 API
  • Microsoft Entra 테넌트

개요

Microsoft Entra ID에서 OAuth 2.0 권한 부여를 사용하여 API Management에서 API를 보호하려면 다음 단계를 따릅니다.

  1. Microsoft Entra ID에서 애플리케이션(이 문서에서 백 엔드 앱이라고 함)을 등록하여 API에 대한 액세스를 보호합니다.

    API에 액세스하기 위해 사용자 또는 애플리케이션은 각 API 요청을 통해 이 앱에 대한 액세스 권한을 부여하는 유효한 OAuth 토큰을 획득하고 제공합니다.

  2. 들어오는 각 API 요청에 표시되는 OAuth 토큰의 유효성을 검사하도록 API Management에서 validate-jwt 정책을 구성합니다. 유효한 요청은 API에 전달될 수 있습니다.

OAuth 권한 부여 흐름 및 필요한 OAuth 토큰을 생성하는 방법에 대한 자세한 내용은 이 문서의 범위를 벗어납니다. 일반적으로 별도의 클라이언트 앱은 API에 대한 액세스 권한을 부여하는 Microsoft Entra ID에서 토큰을 획득하는 데 사용됩니다. 자세한 내용에 대한 링크는 다음 단계를 참조하세요.

API를 나타내기 위해 Microsoft Entra ID에 애플리케이션 등록

Azure Portal을 사용하여 API를 나타내는 애플리케이션을 먼저 등록하여 Microsoft Entra ID에서 API를 보호합니다.

앱 등록에 대한 자세한 내용은 빠른 시작: 웹 API를 공개하도록 애플리케이션 구성을 참조하세요.

  1. Azure Portal에서 앱 등록을 검색하여 선택합니다.

  2. 새 등록을 선택합니다.

  3. 애플리케이션 등록 페이지가 표시되면 애플리케이션의 등록 정보를 입력합니다.

    • 이름 섹션에서 앱 사용자에게 표시되는 의미 있는 애플리케이션 이름(예: backend-app)을 입력합니다.
    • 지원되는 계정 유형 섹션에서 시나리오에 적합한 옵션을 선택합니다.

  4. 리디렉션 URI 섹션을 비워 둡니다.

  5. 등록을 선택하여 애플리케이션을 만듭니다.

  6. 나중에 사용할 수 있도록 앱 개요 페이지에서 애플리케이션(클라이언트) ID 값을 찾아서 기록해 둡니다.

  7. 측면 메뉴의 관리 섹션 아래에서 API 표시를 선택하고, 애플리케이션 ID URI를 기본값으로 설정합니다. 백 엔드 앱에 액세스하기 위해 OAuth 2.0 토큰을 가져오는 별도의 클라이언트 앱을 개발하는 경우 나중에 이 값을 기록합니다.

  8. 범위 추가 단추를 선택하여 범위 추가 페이지를 표시합니다.

    1. 새 범위 이름, 관리자 동의 표시 이름 및 관리자 동의 설명을 입력합니다.
    2. 사용 범위 상태가 선택되어 있는지 확인합니다.

  9. 범위 추가 단추를 선택하여 범위를 만듭니다.

  10. 이전의 두 단계를 반복하여 API에서 지원하는 모든 범위를 추가합니다.

  11. 범위가 만들어지면 이후에 사용할 수 있도록 적어 둡니다.

미리 요청 권한을 부여하도록 JWT 유효성 검사 정책 구성

다음 정책 예제가 <inbound> 정책 섹션에 추가되면 인증 헤더에 표시되는 Microsoft Entra ID에서 가져온 액세스 토큰의 대상 그룹 클레임 값을 확인합니다. 토큰이 유효하지 않은 경우 오류 메시지를 반환합니다. 시나리오에 적합한 정책 범위에서 이 정책을 구성합니다.

  • openid-config URL에서 aad-tenant는 Microsoft Entra ID의 테넌트 ID입니다. Azure Portal에서, 예를 들어 Microsoft Entra 리소스의 개요 페이지에서 이 값을 찾습니다. 표시된 예에서는 단일 테넌트 Microsoft Entra 앱과 v2 구성 엔드포인트를 가정합니다.
  • claim 값은 Microsoft Entra에서 등록한 백 엔드 앱의 클라이언트 ID입니다.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

참고 항목

위의 openid-config URL은 v2 엔드포인트에 해당합니다. v1 openid-config 엔드포인트의 경우 https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration을 사용합니다.

정책을 구성하는 방법에 대한 내용은 정책 설정 또는 편집을 참조하세요. JWT 유효성 검사에 대한 자세한 사용자 지정은 validate-jwt 참조를 참조하세요. Microsoft Entra 서비스에서 제공한 JWT의 유효성을 검사하기 위해 API Management는 validate-azure-ad-token 정책도 제공합니다.

권한 부여 워크플로

  1. 사용자 또는 애플리케이션은 백 엔드 앱에 대한 액세스 권한을 부여하는 권한이 있는 Microsoft Entra ID에서 토큰을 획득합니다.

  2. 토큰은 API Management에 대한 API 요청의 권한 부여 헤더에 추가됩니다.

  3. API Management는 validate-jwt 정책을 사용하여 토큰의 유효성을 검사합니다.

    • 요청에 유효한 토큰이 없으면 API Management에서 차단합니다.

    • 요청에 유효한 토큰이 포함된 경우 게이트웨이는 요청을 API로 전달할 수 있습니다.

다음 단계