Azure API Management에서 Microsoft Entra ID를 사용하여 개발자 계정에 권한 부여

아티클
04/10/2024

이 문서에서는 다음을 수행하는 방법을 알아봅니다.

Microsoft Entra ID를 통해 사용자가 개발자 포털에 액세스할 수 있도록 합니다.
사용자가 포함된 외부 그룹을 추가하여 Microsoft Entra 사용자 그룹을 관리합니다.

개발자 포털을 보호하는 옵션에 대한 개요는 API Management 개발자 포털에 대한 액세스 보안을 참조하세요.

Important

이 문서는 MSAL(Microsoft 인증 라이브러리)을 사용하여 Microsoft Entra 앱을 구성하는 단계로 업데이트되었습니다.
마이그레이션에 ADAL(Azure AD 인증 라이브러리)을 사용하여 사용자 로그인을 위해 Microsoft Entra 앱을 구성한 경우 MSAL로 마이그레이션하는 것이 좋습니다.

필수 조건

Azure API Management 인스턴스 만들기 빠른 시작을 완료합니다.
Azure API Management 인스턴스에서 API를 가져오고 게시합니다.

Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
- 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
- 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
- az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

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

API Management 인스턴스로 이동

Azure Portal에서 API Management 서비스를 검색하여 선택합니다.
API Management 서비스 페이지에서 API Management 인스턴스를 선택합니다.

구성을 간소화하기 위해 API Management는 개발자 포털 사용자에 대해 Microsoft Entra 애플리케이션 및 ID 공급자를 자동으로 사용하도록 설정할 수 있습니다. 또는 Microsoft Entra 애플리케이션 및 ID 공급자를 수동으로 사용하도록 설정할 수 있습니다.

Microsoft Entra 애플리케이션 및 ID 공급자를 자동으로 사용하도록 설정합니다.

API Management 인스턴스의 왼쪽 메뉴에 있는 개발자 포털에서 포털 개요를 선택합니다.
포털 개요 페이지에서 Microsoft Entra ID로 사용자 로그인 사용까지 아래로 스크롤합니다.
Microsoft Entra ID 사용을 선택합니다.
Microsoft Entra ID 사용 페이지에서 Microsoft Entra ID 사용을 선택합니다.
닫기를 선택합니다.

Microsoft Entra 공급자가 사용하도록 설정된 후:

지정된 Microsoft Entra 인스턴스의 사용자는 Microsoft Entra 계정을 사용하여 개발자 포털에 로그인할 수 있습니다.
포털의 개발자 포털>ID 페이지에서 Microsoft Entra 구성을 관리할 수 있습니다.
필요에 따라 ID>설정을 선택하여 다른 로그인 설정을 구성합니다. 예를 들어 익명 사용자를 로그인 페이지로 리디렉션할 수 있습니다.
구성이 변경된 후 개발자 포털을 다시 게시합니다.

Microsoft Entra 애플리케이션 및 ID 공급자를 수동으로 사용하도록 설정

API Management 인스턴스의 왼쪽 메뉴에 있는 개발자 포털에서 ID를 선택합니다.
위쪽에서 + 추가를 선택하여 오른쪽에 있는 ID 공급업체 추가 창을 엽니다.
형식 아래 드롭다운 메뉴에서 Microsoft Entra ID를 선택합니다. 선택되면 다른 필요한 정보를 입력할 수 있습니다.
- 클라이언트 라이브러리 드롭다운에서 MSAL을 선택합니다.
- 클라이언트 ID 및 클라이언트 암호를 추가하려면 문서 뒷부분의 단계를 참조하세요.
나중에 사용할 수 있도록 리디렉션 URL을 저장합니다.
참고 항목

리디렉션 URL에는 다음 두 가지가 있습니다.
- 리디렉션 URL은 API Management의 최신 개발자 포털을 가리킵니다.
- 리디렉션 URL(사용되지 않는 포털)은 API Management의 사용되지 않는 개발자 포털을 가리킵니다.
최신 개발자 포털 리디렉션 URL을 사용하는 것이 좋습니다.
브라우저의 새 탭에서 Azure Portal을 엽니다.
앱 등록으로 이동하여 앱을 Active Directory에 등록합니다.
새 등록을 선택합니다. 응용 프로그램 등록 페이지에서 다음과 같이 값을 설정하세요.
- 이름을 개발자 포털과 같은 의미 있는 이름으로 설정
- 지원되는 계정 유형을 조직 디렉터리의 계정으로 설정합니다.
- 리디렉션 URI에서 SPA(단일 페이지 애플리케이션)을 선택하고 이전 단계에서 저장한 리디렉션 URL을 붙여넣습니다.
- 등록을 선택합니다.
애플리케이션이 등록되면 개요 페이지에서 애플리케이션(클라이언트) ID를 복사합니다.
API Management 인스턴스를 사용하여 브라우저 탭으로 전환합니다.
ID 공급자 추가 창의 클라이언트 ID 상자에 애플리케이션(클라이언트) ID 값을 붙여넣습니다.
앱 등록을 사용하여 브라우저 탭으로 전환합니다.
적절한 앱 등록을 선택합니다.
측면 메뉴의 관리 섹션 아래에서 인증서 및 비밀을 선택합니다.
인증서 및 비밀 페이지의 클라이언트 암호 아래에서 새 클라이언트 암호 단추를 선택합니다.
- 설명을 입력합니다.
- 만료에 대한 옵션을 선택합니다.
- 추가를 선택합니다.
페이지를 나가기 전에 클라이언트 암호 값을 복사합니다. 이 시간은 나중에 필요합니다.
측면 메뉴의 관리 아래에서 인증을 선택합니다.
1. 암시적 허용 및 하이브리드 흐름 섹션 아래에서 ID 토큰 확인란을 선택합니다.
2. 저장을 선택합니다.
측면 메뉴의 관리에서 토큰 구성>+ 선택적 클레임 추가를 선택합니다.
1. 토큰 형식에서 ID를 선택합니다.
2. 이메일, family_name, given_name 클레임을 선택(확인)합니다.
3. 추가를 선택합니다. 메시지가 표시되면 Microsoft Graph 이메일, 프로필 권한 켜기를 선택합니다.
API Management 인스턴스를 사용하여 브라우저 탭으로 전환합니다.
비밀을 ID 공급자 추가 창의 클라이언트 암호 필드에 붙여넣습니다.

Important

키가 만료되기 전에 클라이언트 암호를 업데이트합니다.
ID 공급자 추가 창의 허용된 테넌트 필드에서 API Management 서비스 인스턴스 API에 대한 액세스 권한을 부여할 Microsoft Entra 인스턴스의 도메인을 지정합니다.
- 줄바꿈, 공백 또는 쉼표로 여러 도메인을 구분할 수 있습니다.
참고 항목

허용된 테넌트 섹션에서 여러 도메인을 지정할 수 있습니다. 사용자가 원래 앱 등록 도메인과 다른 도메인에서 로그인하기 전에 전역 관리에서 디렉터리 데이터에 대한 액세스 권한을 애플리케이션에 부여해야 합니다. 사용 권한을 부여하려면 전역 관리자는 다음을 수행해야 합니다.
1. https://<URL of your developer portal>/aadadminconsent로 이동합니다(예: https://contoso.portal.azure-api.net/aadadminconsent).
2. 액세스 권한을 부여하려는 Microsoft Entra 테넌트의 도메인 이름을 입력합니다.
3. 제출을 선택합니다.
원하는 구성을 지정한 후에 추가를 선택합니다.
Microsoft Entra 구성을 적용하려면 개발자 포털을 다시 게시합니다. 왼쪽 메뉴의 개발자 포털에서 포털 개요>게시를 선택합니다.

Microsoft Entra 공급자가 사용하도록 설정된 후:

지정된 Microsoft Entra 인스턴스의 사용자는 Microsoft Entra 계정을 사용하여 개발자 포털에 로그인할 수 있습니다.
포털의 개발자 포털>ID 페이지에서 Microsoft Entra 구성을 관리할 수 있습니다.
필요에 따라 ID>설정을 선택하여 다른 로그인 설정을 구성합니다. 예를 들어 익명 사용자를 로그인 페이지로 리디렉션할 수 있습니다.
구성이 변경된 후 개발자 포털을 다시 게시합니다.

MSAL로 마이그레이션

마이그레이션에 ADAL을 사용하여 사용자 로그인을 위해 Microsoft Entra 앱을 구성한 경우 포털을 사용하여 앱을 MSAL로 마이그레이션하고 API Management에서 ID 공급자를 업데이트할 수 있습니다.

MSAL 호환성을 위해 Microsoft Entra 앱 업데이트

단계는 단일 페이지 애플리케이션 형식으로 리디렉션 URI 전환을 참조하세요.

ID 공급자 구성 업데이트

API Management 인스턴스의 왼쪽 메뉴에 있는 개발자 포털에서 ID를 선택합니다.
목록에서 Microsoft Entra ID를 선택합니다.
클라이언트 라이브러리 드롭다운에서 MSAL을 선택합니다.
업데이트를 선택합니다.
개발자 포털을 다시 게시합니다.

외부 Microsoft Entra 그룹 추가

이제 Microsoft Entra 테넌트의 사용자에 대한 액세스를 사용하도록 설정했으므로 다음을 수행할 수 있습니다.

API Management에 Microsoft Entra 그룹을 추가합니다.
Microsoft Entra 그룹을 사용하여 제품 표시 여부를 제어합니다.

이전 섹션에서 등록한 애플리케이션에 대한 앱 등록 페이지로 이동합니다.
API 사용 권한을 선택합니다.
Microsoft Graph API에 대해 다음과 같은 최소 애플리케이션 권한을 추가합니다.
- User.Read.All 애플리케이션 권한 – API Management는 사용자가 로그인할 때 그룹 동기화를 수행하기 위해 사용자의 그룹 멤버 자격을 읽을 수 있습니다.
- Group.Read.All 애플리케이션 권한 – 관리자가 포털의 그룹 블레이드를 사용하여 API Management에 그룹을 추가하려고 할 때 API Management가 Microsoft Entra 그룹을 읽을 수 있도록 합니다.
이 디렉터리의 모든 사용자에 게 액세스 권한을 부여하도록 {tenantname}에 대한 관리자 동의 부여를 선택합니다.

이제 API Management 인스턴스의 그룹 탭에서 외부 Microsoft Entra 그룹을 추가할 수 있습니다.

측면메뉴의 개발자 포털 아래에서 그룹을 선택합니다.
Microsoft Entra 그룹 추가 단추를 선택합니다.
드롭다운에서 테넌트를 선택합니다.
추가하려는 그룹을 검색하여 선택합니다.
선택 단추를 누릅니다.

외부 Microsoft Entra 그룹을 추가하면 해당 속성을 검토하고 구성할 수 있습니다.

그룹의 이름을 그룹 탭에서 선택합니다.
그룹에 대한 이름 및 설명 정보를 편집합니다.

구성된 Microsoft Entra 인스턴스의 사용자는 이제 다음을 수행할 수 있습니다.

개발자 포털에 로그인합니다.
가시성이 있는 그룹을 보고 구독합니다.

참고 항목

Microsoft ID 플랫폼의 권한 및 동의 문서에서 위임된 권한 유형과 애플리케이션 권한 유형의 차이점에 대해 자세히 알아봅니다.

Microsoft Entra 그룹을 API Management와 동기화

Microsoft Entra에 구성된 그룹은 인스턴스에 추가할 수 있도록 API Management와 동기화되어야 합니다. 그룹이 자동으로 동기화되지 않으면 다음 중 하나를 수행하여 그룹 정보를 수동으로 동기화합니다.

로그아웃한 후 Microsoft Entra ID에 로그인합니다. 이 작업은 일반적으로 그룹 동기화를 트리거합니다.
API Management의 구성 설정에서 Microsoft Entra 로그인 테넌트가 동일한 방식(테넌트 ID 또는 도메인 이름 중 하나 사용)으로 지정되었는지 확인합니다. 개발자 포털에 대한 Microsoft Entra ID 공급자의 로그인 테넌트를 지정하고 Microsoft Entra 그룹을 API Management에 추가할 때 지정합니다.

개발자 포털: Microsoft Entra 계정 인증 추가

개발자 포털에서는 기본 개발자 포털 콘텐츠의 로그인 페이지에 포함된 로그인 단추: OAuth 위젯을 사용하여 Microsoft Entra ID로 로그인할 수 있습니다.

개발자 포털에서 OAuth 위젯을 보여 주는 스크린샷.

새로운 사용자가 Microsoft Entra ID로 로그인하면 새 계정이 자동으로 만들어지지만 등록 페이지에 동일한 위젯을 추가하는 것이 좋습니다. 등록 양식: OAuth 위젯은 OAuth로 등록하는 데 사용되는 양식을 나타냅니다.