자격 증명 관리자 구성 - 백 엔드 API에 대한 사용자 위임 액세스

아티클
02/26/2024

적용 대상: 모든 API Management 계층

이 문서에서는 Microsoft Entra 사용자 또는 그룹에 백 엔드 OAuth 2.0 API에 대한 위임된 권한을 부여하는 관리형 연결 구성하고 사용하는 단계를 개략적으로 안내합니다. 클라이언트 앱(또는 봇)이 인증된 사용자를 대신하여 보호되는 백 엔드 온라인 리소스에 액세스해야 하는 시나리오(예: 이메일 확인 또는 주문)에서 다음 단계를 수행합니다.

시나리오 개요

참고 항목

이 시나리오는 권한 부여 코드 권한 부여 형식으로 구성된 자격 증명 공급자에만 적용됩니다.

이 시나리오에서는 클라이언트 앱(또는 봇)이 Microsoft Entra 사용자 또는 그룹을 대신하여 백 엔드 API에 액세스할 수 있는 관리되는 연결을 구성합니다. 예를 들어 백 엔드 GitHub API에 액세스하고 로그인한 사용자와 관련된 데이터에 액세스하려는 정적 웹앱이 있을 수 있습니다. 다음 다이어그램은 이 시나리오를 보여줍니다.

사용자가 위임한 권한에 대한 프로세스 흐름을 보여 주는 다이어그램

사용자는 앱이 사용자를 대신하여 보안 리소스에 액세스하도록 권한을 부여해야 하고, 앱에 권한을 부여하려면 사용자는 자신의 ID를 인증해야 합니다.
사용자를 대신하여 작업을 수행하기 위해 앱은 Microsoft Graph 또는 GitHub와 같은 외부 백 엔드 서비스를 호출합니다.
각 외부 서비스에는 이러한 호출을 보호하는 방법이 있습니다(예: 사용자를 고유하게 식별하는 사용자 토큰을 사용).
외부 서비스에 대한 호출을 보호하려면 앱은 사용자의 토큰을 얻을 수 있도록 사용자에게 로그인하도록 요청해야 합니다.
구성의 일부로 자격 증명 공급자가 API Management 인스턴스의 자격 증명 관리자를 사용하여 등록됩니다. 여기에는 유효한 OAuth 클라이언트 ID 및 비밀, 사용하도록 설정할 OAuth 범위 및 해당 ID 공급자에 필요한 기타 연결 메타데이터와 함께 사용할 ID 공급자에 대한 정보가 포함되어 있습니다.
또한 사용자를 로그인하고 사용자 토큰을 가져와 관리할 수 있도록 연결이 만들어지고 사용됩니다.

필수 조건

앱 등록을 만들고 앱 권한에 대한 관리자 동의를 부여할 수 있는 권한이 있는 Microsoft Entra 테넌트에 액세스합니다. 자세한 정보

고유의 개발자 테넌트를 만들고 싶다면 Microsoft 365 개발자 프로그램에 등록합니다.
권한을 위임할 테넌트에 있는 하나 이상의 사용자 또는 그룹.
실행 중인 API Management 인스턴스 필요한 경우 Azure API Management 인스턴스를 만듭니다.
사용자 또는 그룹을 대신하여 액세스하려는 백 엔드 OAuth 2.0 API.

Azure PowerShell을 로컬로 사용하도록 선택하는 경우:
- 최신 버전의 Az PowerShell 모듈을 설치합니다.
- Connect-AzAccount cmdlet을 사용하여 Azure 계정에 로그인합니다.
Azure Cloud Shell을 사용하도록 선택하는 경우:
- 자세한 내용은 Azure Cloud Shell 개요를 참조하세요.

1단계: Azure API Management 데이터 평면 서비스 주체 프로비전

사용자 또는 그룹에 필요한 위임된 권한을 부여하려면 Azure API Management 데이터 평면 서비스 주체를 프로비전해야 합니다. 다음 단계에 따라 Azure PowerShell을 사용하여 서비스 주체를 프로비전합니다.

Azure PowerShell에 로그인합니다.
AzureAD 모듈이 아직 설치되지 않은 경우 다음 명령을 사용하여 설치합니다.
```
Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
```
다음 명령을 사용하여 테넌트에 연결합니다.
```
Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
```
메시지가 표시되면 테넌트의 관리자 계정 자격 증명으로 로그인합니다.

다음 명령을 사용하여 Azure API Management 데이터 평면 서비스 주체를 프로비전합니다.

New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"

2단계: Microsoft Entra 앱 등록 만들기

사용자 위임을 위한 Microsoft Entra ID 애플리케이션을 만들고 API Management에서 연결을 읽을 수 있는 적절한 권한을 부여합니다.

테넌트에 충분한 권한이 있는 계정으로 Azure Portal에 로그인합니다.
Azure 서비스에서 Microsoft Entra ID를 검색합니다.
왼쪽 메뉴에서 앱 등록을 선택한 다음, + 새 등록을 선택합니다.
애플리케이션 등록 페이지에서 애플리케이션 등록 설정을 입력합니다.
1. 이름에 ‘UserPermissions’와 같이 앱 사용자에게 표시될 의미 있는 이름을 입력합니다.
2. 지원되는 계정 유형에서 시나리오에 적합한 옵션을 선택합니다(예: 이 조직 디렉터리에만 계정(단일 테넌트)).
3. 리디렉션 URI를 웹으로 설정하고 https://www.postman-echo.com/get을 입력합니다.
왼쪽 메뉴에서 API 권한을 선택한 다음 + 권한 추가를 선택합니다.
1. 내 조직에서 사용하는 API 탭을 선택하고 ‘Azure API Management Data Plane’을 입력한 다음 선택합니다.
2. 권한에서 Authorizations.Read를 선택한 다음 권한 추가를 선택합니다.
왼쪽 메뉴에서 개요를 선택합니다. 개요 페이지에서 애플리케이션(클라이언트) ID 값을 찾아 이후 단계에서 사용할 수 있도록 기록해 둡니다.
왼쪽 메뉴에서 인증서 및 비밀를 선택한 다음 + 새 클라이언트 암호를 선택합니다.
1. 설명을 입력합니다.
2. 만료 옵션을 선택합니다.
3. 추가를 선택합니다.
4. 페이지를 떠나기 전에 클라이언트 암호의 값을 복사합니다. 나중에 필요합니다.

3단계: API Management에서 자격 증명 공급자 구성

포털에 로그인하고 API Management 인스턴스로 이동합니다.
왼쪽 메뉴에서 인증 정보 관리자를 선택한 다음 + 만들기를 선택합니다.
자격 증명 공급자 만들기 페이지에서 API의 자격 증명 공급자에 대한 설정을 입력합니다. 이 시나리오의 경우 권한 부여 유형에서 권한 부여 코드를 선택해야 합니다. 자세한 내용은 자격 증명 관리자에서 자격 증명 공급자 구성을 참조하세요.
만들기를 실행합니다.
메시지가 표시되면 표시된 OAuth 리디렉션 URL을 검토하고 예를 선택하여 앱 등록 시 입력한 URL과 일치하는지 확인합니다.

4단계: 연결 구성

자격 증명 공급자를 만든 후에는 공급자에 대한 연결을 추가할 수 있습니다. 연결 탭에서 연결 단계를 완료합니다.

연결 이름을 입력한 다음 저장을 선택합니다.
2단계: 연결에 로그인에서 자격 증명 공급자에 로그인할 링크를 선택합니다. 액세스 권한을 부여하는 단계를 완료하고 API Management로 돌아갑니다.
3단계: 이 연결에 액세스할 수 있는 사용자 결정(액세스 정책) 아래에서 + 추가를 선택합니다. 위임 시나리오에 따라 사용자 또는 그룹을 선택합니다.
항목 선택 창에서 다음 순서대로 선택합니다.
1. 먼저 하나 이상의 사용자(또는 그룹)를 검색하여 추가하고 선택 상자를 선택합니다.
2. 그런 다음 표시되는 목록에서 이전 섹션에서 만든 앱 등록을 검색합니다.
3. 그런 다음, 선택을 클릭합니다.
Complete(완료) 를 선택합니다.

새 연결이 연결 목록에 나타나고 연결됨 상태로 표시됩니다. 자격 증명 공급자에 대한 다른 연결을 만들려면 이전 단계를 완료합니다.

팁

포털을 사용하여 언제든지 자격 증명 공급자에 대한 연결을 추가, 업데이트 또는 삭제할 수 있습니다. 자세한 내용은 다중 연결 구성을 참조하세요.

5단계: Microsoft Entra ID 액세스 토큰 얻기

백 엔드 API에 대한 사용자 위임 액세스를 사용하도록 설정하려면 get-authorization-context 정책에서 런타임에 위임된 사용자 또는 그룹에 대한 액세스 토큰을 제공해야 합니다. 일반적으로 이 작업은 클라이언트 앱에서 MSAL(Microsoft 인증 라이브러리)을 사용하여 프로그래밍 방식으로 수행됩니다. 이 섹션에서는 테스트를 위한 액세스 토큰을 만드는 수동 단계를 제공합니다.

다음 URL을 브라우저에 붙여넣고 <tenant-id> 및 <client-id>의 값을 Microsoft Entra 앱 등록의 값으로 바꿉니다.

https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`

메시지가 표시되면 로그인합니다. 응답 본문에서 제공된 code의 값을 복사합니다(예: "0.AXYAh2yl…").
다음 POST 요청을 토큰 엔드포인트로 보냅니다. 이때 <tenant-id>를 테넌트 ID로 바꾸고 앱 등록의 표시된 헤더 및 본문 매개 변수와 이전 단계에서 복사한 코드를 포함합니다.
```
POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
```
Header

Content-Type: application/x-www-form-urlencoded

본문
```
grant_type: "authorization_code"
client_id: <client-id>
client_secret: <client-secret>
redirect_uri: <redirect-url> 
code: <code>   ## The code you copied in the previous step
```
응답 본문에서 제공된 access_token의 값을 복사합니다(예: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). 이 값은 다음 단계에서 정책 구성에 전달합니다.

6단계: 백 엔드 API에 대한 get-authorization-context 정책 구성

사용자 또는 그룹을 대신하여 액세스하려는 백 엔드 API에 대한 get-authorization-context 정책을 구성합니다. 테스트를 위해 이전 섹션에서 얻은 사용자의 Microsoft Entra ID 액세스 토큰을 사용하여 정책을 구성할 수 있습니다.

포털에 로그인하고 API Management 인스턴스로 이동합니다.
왼쪽 메뉴에서 API를 선택한 다음, OAuth 2.0 백 엔드 API를 선택합니다.
모든 작업을 선택합니다. 인바운드 처리 섹션에서 코드 편집기(</>) 아이콘을 선택합니다.

inbound 섹션에서 identity-type을 jwt로 설정하여 get-authorization-context 정책을 구성합니다.

<policies>
    <inbound>
        [...]
        <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
        [...]
    </inbound> 
</policies>

앞의 정책 정의에서

<credential-provider-id> 및 <connection-id>를 각각 이전 단계에서 구성한 자격 증명 공급자 및 연결의 이름으로 바꿉니다.
<access-token>을 이전 단계에서 생성한 Microsoft Entra ID 액세스 토큰으로 바꿉니다.

7단계: API 테스트

테스트 탭에서 구성한 작업을 하나 선택합니다.
보내기를 선택합니다.

성공적인 응답은 백 엔드 API에서 사용자 데이터를 반환합니다.

인증 및 권한 부여 정책에 대해 자세히 알아보기
Microsoft Entra ID의 범위 및 권한에 대해 자세히 알아봅니다.