OAuth 2.0 사용자 권한 부여를 구성하여 개발자 포털의 테스트 콘솔에 권한을 부여하는 방법

  • 아티클

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄

대부분의 API는 OAuth 2.0 을 지원하여 API를 보호하고 유효한 사용자만 액세스 권한이 부여되고 자격이 있는 리소스에만 액세스할 수 있도록 합니다. 이러한 API와 함께 Azure API Management의 대화형 개발자 콘솔을 사용하려면 이 서비스를 통해 OAuth 2.0 사용자 권한 부여에 대한 외부 공급자를 구성할 수 있습니다.

개발자 포털의 테스트 콘솔에서 OAuth 2.0 사용자 사용자를 구성하면 개발자가 OAuth 2.0 액세스 토큰을 쉽게 획득할 수 있습니다. 테스트 콘솔에서 토큰은 API 호출을 통해 백 엔드에 전달됩니다. 토큰 유효성 검사는 JWT 유효성 검사 정책을 사용하거나 백 엔드 서비스에서 별도로 구성해야 합니다.

필수 조건

이 문서에서는 개발자 포털의 테스트 콘솔에서 OAuth 2.0 권한 부여를 사용하도록 API Management 서비스 인스턴스를 구성하는 방법을 보여 줍니다. 그러나 OAuth 2.0 공급자를 구성하는 방법은 보여 주지 않습니다.

아직 API Management 서비스 인스턴스를 만들지 않은 경우 API Management 서비스 인스턴스 만들기를 참조하세요.

시나리오 개요

API Management에서 OAuth 2.0 사용자 권한 부여를 구성하면 개발자 포털의 테스트 콘솔(및 Azure Portal의 테스트 콘솔)이 클라이언트로 권한 부여 서버에서 토큰을 획득할 수 있습니다. 각 OAuth 2.0 공급자에 대한 구성은 서로 다르지만 단계는 비슷하며, API Management 서비스 인스턴스에서 OAuth 2.0을 구성하는 데 사용되는 필수 정보도 동일합니다. 이 문서에서는 Microsoft Entra ID를 OAuth 2.0 공급자로 사용하는 예제를 보여 줍니다.

다음은 높은 수준의 구성 단계입니다.

  1. API를 나타내기 위해 Microsoft Entra ID에 애플리케이션(backend-app) 등록합니다.

  2. Microsoft Entra ID에서 다른 애플리케이션(클라이언트 앱)을 등록하여 API를 호출해야 하는 클라이언트 애플리케이션(이 경우 개발자 포털의 테스트 콘솔)을 나타냅니다.

    Microsoft Entra ID에서 client-app에 backend-app을 호출할 수 있도록 권한을 부여합니다.

  3. 개발자 포털에서 OAuth 2.0 사용자 권한 부여를 사용하여 API를 호출하도록 테스트 콘솔을 구성합니다.

  4. OAuth 2.0 사용자 권한 부여를 사용하도록 API를 구성합니다.

  5. 들어오는 모든 요청에 대해 OAuth 2.0 토큰을 사전 승인하는 정책을 추가합니다. 모든 OAuth 2.0 공급자에 대해 validate-jwt 정책을 사용할 수 있습니다.

이 구성은 다음 OAuth 흐름을 지원합니다.

다음 흐름을 시각적으로 개념화하는 개요 그래픽.

  1. 개발자 포털은 클라이언트 앱 자격 증명을 사용하여 Microsoft Entra ID에서 토큰을 요청합니다.

  2. 유효성 검사에 성공한 후 Microsoft Entra ID는 액세스/새로 고침 토큰을 발급합니다.

  3. 개발자(개발자 포털 사용자)는 인증 헤더를 사용하여 API 호출을 수행합니다.

  4. Microsoft Entra ID의 API Management에서 validate-jwt 정책을 사용하여 토큰의 유효성을 검사합니다.

  5. 유효성 검사 결과에 따라 개발자는 개발자 포털에서 응답을 받습니다.

권한 부여 유형

Azure API Management는 다음과 같은 OAuth 2.0 권한 부여 유형(흐름)을 지원합니다. 권한 부여 유형은 클라이언트 애플리케이션(이 컨텍스트에서 개발자 포털의 테스트 콘솔)에서 백 엔드 API에 대한 액세스 토큰을 가져오는 방법을 나타냅니다. OAuth 2.0 공급자 및 시나리오에 따라 하나 이상의 권한 부여 유형을 구성할 수 있습니다.

대략적으로 다음과 같이 요약됩니다. 권한 부여 유형에 대한 자세한 내용은 OAuth 2.0 권한 부여 프레임워크 및 OAuth 권한 부여 유형을 참조하세요.

권한 부여 유형 설명 시나리오
인증 코드 토큰에 대한 인증 코드를 교환합니다. 웹앱과 같은 서버 쪽 앱
권한 부여 코드 + PKCE 권한 부여 요청과 함께 전송되는 코드 챌린지를 만드는 권한 부여 코드 흐름 향상 비밀 또는 토큰을 보호할 수 없는 모바일 및 공용 클라이언트
암시적(사용되지 않음) 추가 인증 코드 교환 단계 없이 즉시 액세스 토큰을 반환합니다. 모바일 앱 및 단일 페이지 앱과 같이 비밀 또는 토큰을 보호할 수 없는 클라이언트

일반적으로 클라이언트에서 받는다고 확인하지 않고 HTTP 리디렉션에서 액세스 토큰을 반환하는 내재된 위험으로 인해 권장되지 않습니다.
리소스 소유자 암호 일반적으로 대화형 양식을 사용하여 사용자 자격 증명(사용자 이름 및 암호)을 요청합니다. 매우 신뢰할 수 있는 애플리케이션에서 사용합니다.

더 안전한 다른 흐름을 사용할 수 없는 경우에만 사용해야 합니다.
클라이언트 자격 증명 사용자가 아니라 앱을 인증하여 권한을 부여합니다. 백 엔드에서 실행되는 CLI, 디먼 또는 서비스와 같이 데이터에 액세스하기 위해 특정 사용자의 권한이 필요하지 않은 M2M(머신 간) 애플리케이션

보안 고려 사항

권한 부여 유형에서 토큰을 생성하는 방법, 토큰의 범위 및 토큰이 공개될 수 있는 방법을 고려합니다. 악의적인 행위자가 손상된 토큰을 사용하여 토큰 범위 내의 추가 리소스에 액세스할 수 있습니다.

개발자 포털의 테스트 콘솔에서 OAuth 2.0 사용자 권한 부여를 구성하는 경우 다음을 고려합니다.

  • 토큰의 범위를 개발자가 API를 테스트하는 데 필요한 최솟값으로 제한합니다. 범위를 테스트 콘솔 또는 영향을 받는 API로 제한합니다. 토큰 범위를 구성하는 단계는 OAuth 2.0 공급자에 따라 달라집니다.

    시나리오에 따라 백 엔드 API에 액세스하기 위해 만드는 다른 클라이언트 애플리케이션에 대해 다소 제한적인 토큰 범위를 구성할 수 있습니다.

  • 클라이언트 자격 증명 흐름을 사용하도록 설정하는 경우 특히 주의해야 합니다. 클라이언트 자격 증명 흐름을 사용하는 경우 개발자 포털의 테스트 콘솔에서는 자격 증명을 요청하지 않습니다. 액세스 토큰은 개발자 또는 개발자 콘솔의 익명 사용자에게 실수로 공개될 수 있습니다.

주요 정보 추적

이 자습서 전체에서는 나중에 참조할 키 정보를 기록하라는 메시지가 표시됩니다.

  • 백 엔드 애플리케이션(클라이언트) ID: 백 엔드 API를 나타내는 애플리케이션의 GUID
  • 백 엔드 애플리케이션 범위: API에 액세스하기 위해 만들 수 있는 하나 이상의 범위입니다. 범위 형식은 api://<Backend Application (client) ID>/<Scope Name>(예: api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
  • 클라이언트 애플리케이션(클라이언트) ID: 개발자 포털을 나타내는 애플리케이션의 GUID
  • 클라이언트 애플리케이션 비밀 값: Microsoft Entra ID의 클라이언트 애플리케이션과의 상호 작용을 위한 비밀 역할을 하는 GUID

OAuth 서버에 애플리케이션 등록

OAuth 2.0 공급자에 두 개의 애플리케이션을 등록해야 합니다. 하나는 보호할 백 엔드 API를 나타내고, 다른 하나는 API를 호출하는 클라이언트 애플리케이션(이 경우 개발자 포털의 테스트 콘솔)을 나타냅니다.

다음은 OAuth 2.0 공급자로 Microsoft Entra ID를 사용하는 예제 단계입니다. 앱 등록에 대한 자세한 내용은 빠른 시작: 웹 API를 공개하도록 애플리케이션 구성을 참조하세요.

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

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

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

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

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

  4. 리디렉션 URI 섹션을 비워 둡니다. 나중에 API Management의 OAuth 2.0 구성에서 생성된 리디렉션 URI를 추가합니다.

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

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

  7. 측면 메뉴의 관리 섹션 아래에서 API 표시를 선택하고, 애플리케이션 ID URI를 기본값으로 설정합니다. 나중에 사용하기 위해 이 값을 기록해 둡니다.

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

    1. API에서 지원하는 범위의 범위 이름을 입력합니다(예: Files.Read).
    2. 누가 동의할 수 있나요?에서 관리자 및 사용자와 같은 시나리오를 선택합니다. 더 높은 권한을 가진 시나리오의 경우 관리자 전용을 선택합니다.
    3. 관리자 동의 표시 이름 및 관리자 동의 설명을 입력합니다.
    4. 사용 범위 상태가 선택되어 있는지 확인합니다.

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

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

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

클라이언트 애플리케이션을 나타내기 위해 Microsoft Entra ID에 다른 애플리케이션 등록

Microsoft Entra ID에서 API를 호출하는 모든 클라이언트 애플리케이션을 애플리케이션으로 등록해야 합니다.

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

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

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

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

  4. 리디렉션 URI 섹션에서 웹을 선택한 뒤 일단 URL 입력란을 비워 둡니다.

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

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

  7. 후속 단계에서 사용하기 위해 이 애플리케이션에 대한 클라이언트 암호를 만듭니다.

    1. 측면 메뉴의 관리 섹션 아래에서 인증서 및 비밀을 선택합니다.
    2. 클라이언트 비밀 아래에서 + 새 클라이언트 비밀을 선택합니다.
    3. 클라이언트 암호 추가 아래에서 설명을 제공하고 키가 만료되는 시기를 선택합니다.
    4. 추가를 선택합니다.

비밀이 만들어지면 이후 단계에서 사용할 키 값을 적어 둡니다. 포털에서 비밀에 다시 액세스할 수 없습니다.

Microsoft Entra ID에서 권한 부여

API 및 테스트 콘솔을 나타내는 두 개의 애플리케이션을 등록했으니 클라이언트 앱이 백 엔드 앱을 호출할 수 있도록 권한을 부여합니다.

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

  2. 클라이언트 앱을 선택합니다. 그런 다음, 측면 메뉴에서 API 권한을 선택합니다.

  3. + 권한 추가를 선택합니다.

  4. API 선택에서 내 API를 선택한 다음, 백 엔드 앱을 찾아 선택합니다.

  5. 위임된 권한을 선택한 다음, 백 엔드 앱에 대한 적절한 권한을 선택합니다.

  6. 권한 추가를 선택합니다.

필요할 경우 다음을 선택합니다.

  1. 클라이언트 앱의 API 권한 페이지로 이동합니다.

  2. 이 디렉터리의 모든 사용자를 대신하여 동의를 허용하려면 <your-tenant-name>에 대한 관리자 동의 허용을 선택합니다.

API Management에서 OAuth 2.0 권한 부여 서버 구성

  1. Azure Portal에서 API Management 인스턴스로 이동합니다.

  2. 사이드 메뉴의 개발자 포털에서 OAuth 2.0 + OpenID Connect를 선택합니다.

  3. OAuth 2.0 탭 아래에서 + 추가를 선택합니다.

    OAuth 2.0 메뉴

  4. 이름 필드에 이름을 입력하고 원하는 경우 설명 필드에 설명을 입력합니다.

    참고 항목

    이러한 필드는 현재 API Management 서비스 내에서 OAuth 2.0 권한 부여 서버를 식별합니다. 해당 값은 OAuth 2.0 서버에서 제공되지 않습니다.

  5. 클라이언트 등록 페이지 URL을 입력합니다(예: https://contoso.com/login). 이 페이지에서는 OAuth 2.0 공급자가 계정의 사용자 관리를 지원하는 경우 사용자가 자신의 계정을 만들고 관리할 수 있습니다. 페이지는 사용되는 OAuth 2.0 공급자에 따라 달라집니다.

    OAuth 2.0 공급자에 계정의 사용자 관리가 구성되지 않은 경우 회사의 URL 또는 http://localhost 등의 URL과 같은 자리 표시자 URL을 여기에 입력합니다.

    OAuth 2.0 새 서버

  6. 양식의 다음 섹션에는 권한 부여 유형, 권한 부여 엔드포인트 URL 및 권한 부여 요청 방법 설정이 포함되어 있습니다.

    • 원하는 권한 부여 유형을 하나 이상 선택합니다. 이 예제에서는 권한 부여 코드(기본값)를 선택합니다. 자세한 정보

    • 권한 부여 엔드포인트 URL을 입력합니다. 앱 등록 중 하나의 엔드포인트 페이지에서 엔드포인트 URL을 가져올 수 있습니다. Microsoft Entra ID의 단일 테넌트 앱의 경우 이 URL은 다음 URL 중 하나와 유사합니다. 여기서 {aad-tenant}는 Microsoft Entra 테넌트의 ID로 변경됩니다.

      v2 엔드포인트를 사용하는 것이 좋습니다. 그러나 API Management는 v1 및 v2 엔드포인트를 모두 지원합니다.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize(v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize(v1)

    • 권한 부여 요청 방법 은 권한 부여 요청이 OAuth 2.0 서버로 전송되는 방법을 지정합니다. POST를 선택합니다.

    권한 부여 설정 지정

  7. 토큰 엔드포인트 URL, 클라이언트 인증 방법, 액세스 토큰 전송 방법 및 기본 범위를 지정합니다.

    • 토큰 엔드포인트 URL을 입력합니다. Microsoft Entra ID의 단일 테넌트 앱의 경우 다음 URL 중 하나와 유사합니다. 여기서 {aad-tenant}는 Microsoft Entra 테넌트의 ID로 변경됩니다. 이전에 선택한 것과 동일한 엔드포인트 버전(v2 또는 v1)을 사용합니다.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token(v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/token(v1)

    • v1 엔드포인트를 사용하는 경우 본문 매개 변수를 추가합니다.
      * 이름: 리소스
      * 값: 백 엔드 앱 애플리케이션(클라이언트) ID

    • v2 엔드포인트를 사용하는 경우:
      * 기본 범위 필드에서 만든 백 엔드 앱 범위를 입력합니다.
      * 백 엔드 앱 및 클라이언트 앱 등록 모두에 대한 애플리케이션 매니페스트의 accessTokenAcceptedVersion 속성 값을 2로 설정합니다.

    • 클라이언트 인증 방법 및 액세스 토큰 전송 방법에 대한 기본 설정을 적용합니다.

  8. 클라이언트 자격 증명에 클라이언트 앱을 만들고 구성하는 과정에서 얻은 클라이언트 ID와 클라이언트 암호를 입력합니다.

  9. 클라이언트 ID 및 클라이언트 암호가 지정되면 인증 코드에 대한 리디렉션 URI가 생성됩니다. 이 URI를 사용하여 OAuth 2.0 서버 구성에서 리디렉션 URI를 구성합니다.

    개발자 포털에서 URI 접미사의 형식은 다음과 같습니다.

    • /signin-oauth/code/callback/{authServerName} 인증 코드 권한 부여 흐름
    • /signin-oauth/implicit/callback 임시적 권한 부여 흐름

    OAuth 2.0 서비스에 대한 클라이언트 자격 증명 추가

    클라이언트 앱 등록의 인증 페이지에 적절한 리디렉션 URI를 복사합니다. 앱 등록에서 인증>+ 플랫폼 추가>웹을 선택한 다음 리디렉션 URI를 입력합니다.

  10. 권한 부여 유형을 리소스 소유자 암호로 설정한 경우 리소스 소유자 암호 자격 증명 섹션에서 해당 자격 증명을 지정합니다. 그렇지 않은 경우에는 자격 증명을 비워 두면 됩니다.

  11. 만들기를 선택하여 API Management OAuth 2.0 권한 부여 서버 구성을 저장합니다.

  12. 개발자 포털을 다시 게시합니다.

    Important

    OAuth 2.0 관련 변경 내용을 적용할 때는 관련 변경 내용(예: 범위 변경)으로 수정할 때마다 개발자 포털을 다시 게시해야 합니다. 그렇지 않으면 포털에 전파한 후 API를 테스트하는 데 사용할 수 없습니다.

OAuth 2.0 사용자 권한 부여를 사용하도록 API 구성

OAuth 2.0 서버 구성을 저장한 후 이 구성을 사용하도록 API를 구성합니다.

Important

  • API에 대한 OAuth 2.0 사용자 권한 부여 설정을 구성하면 API Management Azure Portal 또는 개발자 포털에서 테스트 콘솔을 사용할 때 권한 부여 서버에서 토큰을 획득할 수 있습니다. 권한 부여 서버 설정도 API 정의 및 설명서에 추가됩니다.
  • 런타임 시 OAuth 2.0 권한 부여의 경우 클라이언트 앱은 토큰을 획득하고 제공해야 하며 API Management 또는 백 엔드 API에서 토큰 유효성 검사를 구성해야 합니다. 예는 Microsoft Entra ID에서 OAuth 2.0 권한 부여를 사용하여 Azure API Management에서 API 보호를 참조하세요.

  1. 왼쪽의 API Management 메뉴에서 API를 선택합니다.

  2. 원하는 API의 이름을 선택하고, 설정 탭을 선택합니다. 보안 섹션까지 스크롤한 다음 OAuth 2.0을 선택합니다.

  3. 드롭다운 목록에서 원하는 권한 부여 서버를 선택하고, 저장을 선택합니다.

    OAuth 2.0 권한 부여 서버 구성

개발자 포털 - OAuth 2.0 사용자 권한 부여 테스트

OAuth 2.0 권한 부여 서버가 구성되고 API에서 해당 서버를 사용하도록 구성되면 개발자 포털로 이동하고 API를 호출하여 이러한 구성을 테스트할 수 있습니다.

  1. Azure API Management 인스턴스 개요 페이지의 위쪽 메뉴에서 개발자 포털을 선택합니다.

  2. 개발자 포털의 API 아래에서 작업을 찾습니다.

  3. 사용해 보기를 선택하여 개발자 콘솔로 이동합니다.

  4. 방금 추가한 권한 부여 서버에 해당하는 권한 부여 섹션의 새 항목을 참고합니다.

  5. 권한 부여 드롭다운 목록에서 인증 코드를 선택합니다.

    인증 코드 권한 부여 선택

  6. 메시지가 표시되면 Microsoft Entra 테넌트에 로그인합니다.

    • 이미 계정에 로그인한 경우 메시지가 표시되지 않을 수 있습니다.

  7. 성공적으로 로그인한 후 Authorization 헤더가 Microsoft Entra ID의 액세스 토큰과 함께 요청에 추가됩니다. 간략하게 표시한 샘플 토큰(Base64 인코딩)은 다음과 같습니다.

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. 나머지 매개 변수에 대해 원하는 값을 구성하고 보내기를 선택하여 API를 호출합니다.

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

지금까지의 구성에서 API Management는 액세스 토큰의 유효성을 검사하지 않습니다. 권한 부여 헤더의 토큰만 백 엔드 API에 전달합니다.

요청을 미리 인증하려면 validate-jwt 정책을 구성하여 들어오는 각 요청의 액세스 토큰에 대한 유효성을 검사합니다. 요청에 유효한 토큰이 없으면 API Management에서 차단합니다.

다음 정책 예제가 <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 정책도 제공합니다.

관련 콘텐츠