권한 부여 개요

API Management 권한 부여(미리 보기)는 OAuth 2.0 백 엔드 서비스에 대한 권한 부여 토큰을 관리하는 프로세스를 간소화합니다. 지원되는 ID 공급자를 구성하고 표준화된 OAuth 2.0 흐름을 사용하여 권한 부여를 만들면 API Management는 API 관리 내에서 사용하거나 클라이언트로 다시 보낼 액세스 토큰을 검색하고 새로 고칠 수 있습니다. 이 기능을 사용하면 구독 키를 사용하거나 사용하지 않고 API를 노출할 수 있으며 백 엔드 서비스에 대한 권한 부여는 OAuth 2.0을 사용합니다.

이 기능을 통해 가능한 몇 가지 예제 시나리오는 다음과 같습니다.

  • Power Apps 또는 Power Automate를 사용하는 시민/로우 코드 개발자는 OAuth 2.0을 사용하는 SaaS 공급자에 쉽게 연결할 수 있습니다.
  • 타이머 트리거를 사용하는 Azure 함수와 같은 무인 시나리오는 이 기능을 활용하여 OAuth 2.0을 사용하여 백 엔드 API에 연결할 수 있습니다.
  • 엔터프라이즈 회사의 마케팅 팀은 OAuth 2.0을 사용하여 소셜 미디어 플랫폼과 상호 작용하는 데 동일한 권한 부여를 사용할 수 있습니다.
  • 백 엔드 서비스에 OAuth 2.0 흐름이 필요한 Logic Apps에서 사용자 지정 커넥터로 API Management에 API를 노출합니다.
  • Dropbox 또는 OAuth 2.0 흐름으로 보호되는 다른 서비스와 같은 서비스가 여러 클라이언트에서 사용되는 시나리오를 대신합니다.
  • API Management의 가상 GraphQL을 사용하여 OAuth 2.0 권한 부여가 필요한 다양한 서비스에 연결합니다.
  • 서비스 대 서비스 권한 부여를 사용하는 EAI(엔터프라이즈 애플리케이션 통합) 패턴은 OAuth 2.0을 사용하는 백 엔드 API에 대해 클라이언트 자격 증명 부여 유형을 사용할 수 있습니다.
  • OAuth 2.0을 사용하는 API에 대해 클라이언트의 SDK에서 사용할 액세스 토큰만 검색하려는 단일 페이지 애플리케이션입니다.

이 기능은 관리 및 런타임의 두 부분으로 구성됩니다.

  • 관리 파트는 ID 공급자를 구성하고, ID 공급자에 대한 동의 흐름을 사용하도록 설정하고, 권한 부여에 대한 액세스를 관리합니다.

  • 런타임 파트는 get-authorization-context 정책을 사용하여 액세스 및 새로 고침 토큰을 가져오고 저장합니다. 호출이 API Management로 들어오고 get-authorization-context 정책이 실행되면 먼저 기존 권한 부여 토큰이 유효한지 유효성을 검사합니다. 권한 부여 토큰이 만료된 경우 새로 고침 토큰은 구성된 ID 공급자에서 새 권한 부여 및 새로 고침 토큰을 가져오는 데 사용됩니다. 백 엔드 공급자에 대한 호출이 성공하면 새 권한 부여 토큰이 사용되고 권한 부여 토큰과 새로 고침 토큰이 모두 암호화되어 저장됩니다.

    정책을 실행하는 동안 액세스 정책을 사용하여 토큰에 대한 액세스도 유효성을 검사합니다.

API Management에서 OAuth 2.0 권한 부여에 사용할 수 있는 ID 공급자를 보여 주는 스크린샷

요구 사항

  • API Management 인스턴스에 대해 관리형 시스템 할당 ID를 사용하도록 설정해야 합니다.
  • API Management 인스턴스는 포트 443(HTTPS)에서 인터넷에 대한 아웃바운드 연결이 있어야 합니다.

제한 사항

퍼블릭 미리 보기에 대해 다음과 같은 제한 사항이 적용됩니다.

  • 권한 부여 기능은 서비스 주체 및 관리 ID만 액세스 정책으로 지원합니다.
  • 권한 부여 기능은 https://.../authorizationmanager 대상에 대한 토큰을 획득하는 동안 /.default 앱 전용 범위만 지원합니다.
  • 권한 부여 기능은 swedencentral, australiacentral, australiacentral2, jioindiacentral 지역에서 지원되지 않습니다.
  • 권한 부여 기능은 국가별 클라우드에서 지원되지 않습니다.
  • 권한 부여 기능은 자체 호스팅 게이트웨이에서 지원되지 않습니다.
  • 지원되는 ID 공급자는 GitHub 리포지토리에서 찾을 수 있습니다.
  • API Management 인스턴스당 최대 구성된 권한 부여 공급자 수: 1,000
  • 권한 부여 공급자당 최대 구성된 권한 부여 수: 10,000
  • 권한 부여당 최대 구성된 액세스 정책 수: 100
  • 서비스별 분당 최대 요청: 250

권한 부여 공급자

권한 부여 공급자 구성에는 사용되는 ID 공급자 및 권한 부여 유형이 포함됩니다. 각 ID 공급자에는 서로 다른 구성이 필요합니다.

  • 권한 부여 공급자 구성에는 하나의 권한 부여 유형만 있을 수 있습니다.
  • 하나의 권한 부여 공급자 구성에는 여러 권한 부여가 있을 수 있습니다.
  • GitHub 리포지토리에서 공개 미리 보기에 지원되는 ID 공급자를 찾을 수 있습니다.

일반 OAuth 2.0 공급자를 사용하면 OAuth 2.0 흐름의 표준을 지원하는 다른 ID 공급자를 사용할 수 있습니다.

권한 부여

권한 부여 공급자를 사용하려면 하나 이상의 권한 부여가 필요합니다. 권한 부여를 구성하는 프로세스는 사용된 권한 부여 유형에 따라 다릅니다. 각 권한 부여 공급자 구성은 하나의 권한 부여 유형만 지원합니다. 예를 들어 두 권한 부여 유형을 모두 사용하도록 Azure AD를 구성하려면 두 가지 권한 부여 공급자 구성이 필요합니다.

인증 코드 권한 부여 유형

권한 부여 코드 부여 유형은 사용자 컨텍스트에 바인딩됩니다. 즉, 사용자는 권한 부여에 동의해야 합니다. 새로 고침 토큰이 유효한 한 API Management는 새 액세스 및 새로 고침 토큰을 검색할 수 있습니다. 새로 고침 토큰이 잘못되면 사용자는 다시 인증해야 합니다. 모든 ID 공급자는 권한 부여 코드를 지원합니다. 권한 부여 코드 부여 유형에 대해 자세히 알아보세요.

클라이언트 자격 증명 부여 유형

클라이언트 자격 증명 부여 유형은 사용자에게 바인딩되지 않으며 애플리케이션-애플리케이션 시나리오에서 자주 사용됩니다. 클라이언트 자격 증명 부여 유형에 대한 동의는 필요하지 않으며 권한 부여는 무효화되지 않습니다. 클라이언트 자격 증명 부여 유형에 대해 자세히 알아보세요.

액세스 정책

액세스 정책은 액세스 정책과 관련된 권한 부여를 사용할 수 있는 ID를 결정합니다. 지원되는 ID는 관리 ID, 사용자 ID, 서비스 주체입니다. ID는 API Management 테넌트와 동일한 테넌트에 속해야 합니다.

  • 관리 ID - 사용 중인 API Management 인스턴스에 대한 시스템 또는 사용자 할당 ID입니다.
  • 사용자 ID - API Management 인스턴스와 동일한 테넌트에 있는 사용자입니다.
  • 서비스 주체 - API Management 인스턴스와 동일한 Azure AD 테넌트에 있는 애플리케이션입니다.

권한 부여를 만들기 위한 프로세스 흐름

다음 이미지는 권한 부여 형식 권한 부여 코드를 사용하여 API Management에 권한 부여를 만들기 위한 프로세스 흐름을 보여 줍니다. 퍼블릭 미리 보기의 경우 API 설명서를 사용할 수 없습니다.

권한 부여를 만들기 위한 프로세스 흐름

  1. 클라이언트는 권한 부여 공급자를 만들기 위한 요청을 보냅니다.
  2. 권한 부여 공급자가 만들어지고 응답이 다시 전송됩니다.
  3. 클라이언트는 권한 부여를 만들기 위한 요청을 보냅니다.
  4. 권한 부여가 생성되고 권한 부여가 “연결”되지 않았다는 정보와 함께 응답이 다시 전송됩니다.
  5. 클라이언트는 ID 공급자에서 OAuth 2.0 동의를 시작하기 위해 로그인 URL을 검색하는 요청을 보냅니다. 요청에는 마지막 단계에서 사용할 리디렉션 후 URL이 포함됩니다.
  6. 응답은 동의 흐름을 시작하는 데 사용해야 하는 로그인 URL과 함께 반환됩니다.
  7. 클라이언트는 이전 단계에서 제공된 로그인 URL이 있는 브라우저를 엽니다. 브라우저는 ID 공급자 OAuth 2.0 동의 흐름으로 리디렉션됩니다.
  8. 동의가 승인되면 인증 코드와 함께 브라우저가 ID 공급자에 구성된 리디렉션 URL로 리디렉션됩니다.
  9. API Management는 권한 부여 코드를 사용하여 액세스 및 새로 고침 토큰을 가져옵니다.
  10. API Management는 토큰을 수신하고 암호화합니다.
  11. API Management는 5단계에서 제공된 URL로 리디렉션됩니다.

런타임에 대한 프로세스 흐름

다음 이미지는 구성된 권한 부여에 따라 권한 부여 및 새로 고침 토큰을 가져오고 저장하는 프로세스 흐름을 보여 줍니다. 토큰을 검색한 후 백 엔드 API에 대한 호출이 이루어집니다.

런타임 만들기를 위한 프로세스 흐름을 보여 주는 다이어그램.

  1. 클라이언트는 API Management 인스턴스에 요청을 보냅니다.
  2. 정책 get-authorization-context는 액세스 토큰이 현재 권한 부여에 유효한지 확인합니다.
  3. 액세스 토큰이 만료되었지만 새로 고침 토큰이 유효한 경우 API Management는 구성된 ID 공급자에서 새 액세스 및 새로 고침 토큰을 가져오려고 시도합니다.
  4. ID 공급자는 액세스 토큰과 새로 고침 토큰을 모두 반환하며, 이 토큰은 암호화되어 API Management에 저장됩니다.
  5. 토큰을 검색한 후 백 엔드 API에 보내는 요청에 대한 권한 부여 헤더로 set-header 정책을 사용하여 액세스 토큰이 연결됩니다.
  6. 응답이 API Management로 반환됩니다.
  7. 응답이 클라이언트로 반환됩니다.

오류 처리

권한 부여 컨텍스트를 획득하면 오류가 발생하는 경우 결과는 정책 get-authorization-context에서 특성 ignore-error를 구성하는 방법에 따라 달라집니다. 값을 false(기본값)로 설정하면 500 Internal Server Error와 함께 오류가 반환됩니다. 값이 true로 설정되면 오류가 무시되고 실행은 컨텍스트 변수를 null로 설정하여 진행합니다.

값이 false로 설정되고 정책의 오류 발생 섹션이 구성된 경우 속성 context.LastError에서 오류를 사용할 수 있습니다. 오류 발생 섹션을 사용하여 클라이언트로 다시 전송되는 오류를 조정할 수 있습니다. API Management의 오류는 표준 Azure 경고를 사용하여 catch할 수 있습니다. 정책의 오류 처리에 대해 자세히 알아보세요.

권한 부여 FAQ

피드백을 제공하고 이 기능에 대한 로드맵에 영향을 주려면 어떻게 해야 하나요?

피드백을 제공하려면 양식을 사용하세요.

토큰은 API Management에 어떻게 저장되나요?

액세스 토큰 및 기타 비밀(예: 클라이언트 비밀)은 봉투 암호화로 암호화되고 내부 다중 테넌트 스토리지에 저장됩니다. 데이터는 데이터당 고유한 키를 사용하여 AES-128로 암호화됩니다. 이러한 키는 Azure Key Vault에 저장되고 매달 회전되는 마스터 인증서를 사용하여 비대칭적으로 암호화됩니다.

액세스 토큰은 언제 새로 고쳐지나요?

런타임에 정책 get-authorization-context가 실행되면 API Management는 저장된 액세스 토큰이 유효한지 확인합니다. 토큰이 만료되었거나 만료에 가까운 경우 API Management는 새로 고침 토큰을 사용하여 구성된 ID 공급자에서 새 액세스 토큰 및 새 새로 고침 토큰을 가져옵니다. 새로 고침 토큰이 만료되면 오류가 throw되고 권한 부여가 다시 인증되어야 작동합니다.

ID 공급자에서 클라이언트 암호가 만료되면 어떻게 되나요?

런타임에 API Management는 새 토큰을 가져올 수 없으며 오류가 발생합니다.

  • 권한 부여가 인증 코드 형식인 경우 권한 부여 공급자 수준에서 클라이언트 암호를 업데이트해야 합니다.

  • 권한 부여가 클라이언트 자격 증명 형식인 경우 권한 부여 수준에서 클라이언트 암호를 업데이트해야 합니다.

이 기능은 VNet 내에서 실행되는 API Management를 사용하여 지원되나요?

예, API Management 게이트웨이의 포트 443에서 아웃바운드 인터넷 연결이 있는 한 지원됩니다.

권한 부여 공급자가 삭제되면 어떻게 되나요?

모든 기본 권한 부여 및 액세스 정책도 삭제됩니다.

API Management에서 액세스 토큰을 캐시하나요?

액세스 토큰은 토큰 만료 시간 3분 전까지 API 관리에 의해 캐시됩니다.

지원되는 권한 부여 유형은 무엇인가요?

퍼블릭 미리 보기의 경우 Azure AD ID 공급자는 권한 부여 코드 및 클라이언트 자격 증명을 지원합니다.

다른 ID 공급자는 권한 부여 코드를 지원합니다. 퍼블릭 미리 보기 후에는 더 많은 ID 공급자 및 권한 부여 유형이 추가됩니다.

다음 단계