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

아티클
03/01/2024

적용 대상: 모든 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를 보호하려면 다음 단계를 따릅니다.

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

API에 액세스하기 위해 사용자 또는 애플리케이션은 각 API 요청을 통해 이 앱에 대한 액세스 권한을 부여하는 유효한 OAuth 토큰을 획득하고 제공합니다.
들어오는 각 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를 공개하도록 애플리케이션 구성을 참조하세요.

Azure Portal에서 앱 등록을 검색하여 선택합니다.
새 등록을 선택합니다.
애플리케이션 등록 페이지가 표시되면 애플리케이션의 등록 정보를 입력합니다.
- 이름 섹션에서 앱 사용자에게 표시되는 의미 있는 애플리케이션 이름(예: backend-app)을 입력합니다.
- 지원되는 계정 유형 섹션에서 시나리오에 적합한 옵션을 선택합니다.
리디렉션 URI 섹션을 비워 둡니다.
등록을 선택하여 애플리케이션을 만듭니다.
나중에 사용할 수 있도록 앱 개요 페이지에서 애플리케이션(클라이언트) ID 값을 찾아서 기록해 둡니다.
측면 메뉴의 관리 섹션 아래에서 API 표시를 선택하고, 애플리케이션 ID URI를 기본값으로 설정합니다. 백 엔드 앱에 액세스하기 위해 OAuth 2.0 토큰을 가져오는 별도의 클라이언트 앱을 개발하는 경우 나중에 이 값을 기록합니다.
범위 추가 단추를 선택하여 범위 추가 페이지를 표시합니다.
1. 새 범위 이름, 관리자 동의 표시 이름 및 관리자 동의 설명을 입력합니다.
2. 사용 범위 상태가 선택되어 있는지 확인합니다.
범위 추가 단추를 선택하여 범위를 만듭니다.
이전의 두 단계를 반복하여 API에서 지원하는 모든 범위를 추가합니다.
범위가 만들어지면 이후에 사용할 수 있도록 적어 둡니다.

미리 요청 권한을 부여하도록 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 정책도 제공합니다.

권한 부여 워크플로

사용자 또는 애플리케이션은 백 엔드 앱에 대한 액세스 권한을 부여하는 권한이 있는 Microsoft Entra ID에서 토큰을 획득합니다.
토큰은 API Management에 대한 API 요청의 권한 부여 헤더에 추가됩니다.
API Management는 validate-jwt 정책을 사용하여 토큰의 유효성을 검사합니다.
- 요청에 유효한 토큰이 없으면 API Management에서 차단합니다.
- 요청에 유효한 토큰이 포함된 경우 게이트웨이는 요청을 API로 전달할 수 있습니다.

다음 단계

애플리케이션을 빌드하고 OAuth 2.0을 구현하는 방법에 대해 자세히 알려보려면 Microsoft Entra 코드 샘플을 참조하세요.
API Management 개발자 포털에서 OAuth 2.0 사용자 권한 부여를 구성하는 엔드투엔드 예제는 OAuth 2.0 사용자 권한 부여를 구성하여 개발자 포털의 테스트 콘솔에 권한을 부여하는 방법을 참조하세요.

Microsoft Entra ID 및 OAuth2.0에 대해 자세히 알아봅니다.
백 엔드 서비스를 보호하는 다른 방법은 상호 인증서 인증을 참조하세요.

다음을 통해 공유