보호된 웹 API: 앱 등록

아티클
05/28/2024

이 문서에서는 보호된 웹 API에 애플리케이션을 등록하는 방법을 설명합니다.

앱을 등록하는 일반적인 단계는 빠른 시작: Microsoft ID 플랫폼을 사용하여 애플리케이션 등록을 참조하세요.

허용되는 토큰 버전

Microsoft ID 플랫폼은 v1.0 토큰과 v2.0 토큰을 발급할 수 있습니다. 이러한 토큰에 대한 자세한 내용은 액세스 토큰을 참조하세요.

API가 수락할 수 있는 토큰 버전은 Azure Portal에서 웹 API 애플리케이션 등록을 만들 때 선택한 지원되는 계정 유형에 따라 달라질 수 있습니다.

지원되는 계정 유형 값이 조직 디렉터리의 계정 및 개인 Microsoft 계정(예: Skype, Xbox, Outlook.com)일 경우 허용되는 토큰 버전은 v2.0이어야 합니다.
그렇지 않은 경우 허용되는 토큰 버전은 v1.0이 될 수 있습니다.

애플리케이션을 만든 후 다음 단계를 수행하여 허용되는 토큰 버전을 확인하거나 변경할 수 있습니다.

Microsoft Entra 관리 센터에서 앱을 선택한 다음 매니페스트를 선택합니다.
매니페스트에서 accessTokenAcceptedVersion 속성을 찾습니다.
이 값은 웹 API에서 허용하는 토큰 버전을 Microsoft Entra에 지정합니다.
- 이 값이 2이면 웹 API는 v2.0 토큰을 허용합니다.
- 이 값이 null이면 웹 API는 v1.0 토큰을 허용합니다.
토큰 버전을 변경한 경우 저장을 선택합니다.

웹 API는 허용하는 토큰 버전을 지정합니다. 클라이언트는 Microsoft ID 플랫폼에 웹 API에 대한 토큰을 요청할 때 웹 API가 허용하는 토큰 버전을 나타내는 토큰을 가져옵니다.

리디렉션 URI 없음

웹 API는 대화형으로 로그인된 사용자가 없기 때문에 리디렉션 URI를 등록할 필요가 없습니다.

노출된 API

웹 API와 관련된 다른 설정은 노출된 API 및 노출된 범위 또는 앱 역할입니다.

범위 및 애플리케이션 ID URI

범위는 일반적으로 resourceURI/scopeName 형식입니다. Microsoft Graph의 경우 범위에 바로 가기가 있습니다. 예를 들어 User.Read는 https://graph.microsoft.com/user.read의 바로 가기입니다.

앱 등록 중에 다음 매개 변수를 정의합니다.

리소스 URI
하나 이상의 범위
하나 이상의 앱 역할

기본적으로 애플리케이션 등록 포털에서는 리소스 URI api://{clientId}를 사용할 것을 권장합니다. 이 URI는 고유하지만 사람이 읽을 수는 없습니다. URI를 변경하는 경우 새 값이 고유한지 확인합니다. 애플리케이션 등록 포털에서 구성된 게시자 도메인을 사용하는지 확인합니다.

클라이언트 애플리케이션에는 범위가 위임 된 권한으로 표시되고, 앱 역할은 웹 API에 대한 애플리케이션 권한으로 표시됩니다.

범위는 앱의 사용자에게 표시되는 동의 창에도 표시됩니다. 따라서 범위를 설명하는 해당 문자열을 제공합니다.

사용자에게 표시되는 항목
관리자 동의를 허용할 수 있는 테넌트 관리자에게 표시되는 항목

자체적으로 사용되는 것이 아니라 웹 API를 호출하는 애플리케이션에서 사용되므로 앱 역할은 사용자가 동의할 수 없습니다. 테넌트 관리자는 앱 역할을 노출하는 웹 API의 클라이언트 애플리케이션에 동의해야 합니다. 자세한 내용은 관리자 동의를 참조하세요.

위임된 권한 노출(범위)

위임된 권한 또는 범위를 노출하려면 웹 API를 노출하도록 애플리케이션 구성의 단계를 수행합니다.

이 문서 집합에 설명된 웹 API 시나리오를 따르는 경우 다음 설정을 사용합니다.

애플리케이션 ID URI: 제안된 애플리케이션 ID URI(api://< clientId>) 수락(요청되는 경우)
범위 이름: access_as_user
동의할 수 있는 사람: 관리자 및 사용자
관리자 동의 표시 이름: Access TodoListService as a user
관리자 동의 설명: Accesses the TodoListService web API as a user
사용자 동의 표시 이름: Access TodoListService as a user
사용자 동의 설명: Accesses the TodoListService web API as a user
상태: 사용

팁

애플리케이션 ID URI의 경우 API의 실제 권한(예: https://graph.microsoft.com)으로 설정하는 옵션이 있습니다. 이는 호출해야 하는 API의 URL을 알고 있는 경우에 유용할 수 있습니다.

서비스 또는 디먼 앱에서 웹 API를 호출하는 경우

디먼, 서비스 또는 다른 비대화형(사람에 의한) 애플리케이션에서 API에 액세스해야 하는 경우 위임된 권한 대신 애플리케이션 권한을 노출합니다. 디먼 및 서비스 유형 애플리케이션은 무인으로 실행되고 자체 ID로 인증되므로 권한을 "위임"할 사용자가 없습니다.

애플리케이션 권한 노출(앱 역할)

애플리케이션 권한을 노출하려면 앱에 앱 역할 추가의 단계를 수행합니다.

허용되는 멤버 유형 아래의 앱 역할 만들기 창에서 애플리케이션을 선택합니다. 또는 문서에 설명된 대로 애플리케이션 매니페스트 편집기를 사용하여 역할을 추가합니다.

액세스 토큰을 특정 클라이언트 앱으로 제한

앱 역할은 애플리케이션 개발자가 앱의 권한을 노출하는 데 사용하는 메커니즘입니다. 웹 API의 코드는 호출자로부터 수신하는 액세스 토큰에서 앱 역할을 확인해야 합니다.

다른 보안 계층을 추가하기 위해 Microsoft Entra 테넌트 관리자는 Microsoft ID 플랫폼이 API 액세스에 대해 승인한 클라이언트 앱에만 보안 토큰을 발급하도록 테넌트를 구성할 수 있습니다.

앱 역할이 할당된 클라이언트 앱으로만 토큰 발급을 제한하여 보안을 강화하려면 다음을 수행합니다.

Microsoft Entra 관리 센터에서 ID>애플리케이션>앱 등록을 선택합니다.
애플리케이션의 개요 페이지에서 Essentials의 로컬 디렉터리의 관리 앱 링크를 선택하여 엔터프라이즈 애플리케이션 개요 페이지로 이동합니다.
관리에서 속성을 선택합니다.
할당 필요?를 예로 설정합니다.
저장을 선택합니다.

이제 Microsoft Entra ID가 웹 API에 대한 액세스 토큰을 요청하는 클라이언트 애플리케이션의 앱 역할 할당을 확인합니다. 클라이언트 앱에 앱 역할이 할당되지 않은 경우 Microsoft Entra ID는 _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_와(과) 유사한 오류 메시지를 클라이언트에 반환합니다.

Warning

AADSTS 오류 코드 사용 안 함 또는 해당 메시지 문자열을 애플리케이션 코드에서 리터럴로 사용하지 마세요. "AADSTS" 오류 코드 및 Microsoft Entra ID에서 반환된 오류 메시지 문자열은 변경할 수 없으며 언제든지 Microsoft에서 사용자 모르게 변경될 수 있습니다. AADSTS 코드 또는 해당 메시지 문자열의 값에 따라 코드에서 분기 결정을 내리는 경우 애플리케이션의 기능과 안정성에 문제가 될 수 있습니다.

다음 단계

이 시리즈의 다음 문서는 앱 코드 구성입니다.

다음을 통해 공유