보호된 웹 API: 앱 등록

이 문서에서는 보호된 웹 API에 대한 앱 등록의 세부 사항을 설명합니다.

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

허용되는 토큰 버전

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

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

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

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

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

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

리디렉션 URI 없음

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

노출된 API

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

범위 및 애플리케이션 ID URI

범위는 일반적으로 resourceURI/scopeName 형식입니다. Microsoft Graph의 경우 범위에 바로 가기가 있습니다. 예를 들어 User.Readhttps://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 액세스에 대해 승인한 클라이언트 앱에 보안 토큰을 발급하도록 테넌트를 구성할 수 있습니다.

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

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

이제 Microsoft Entra ID가 웹 API에 대한 액세스 토큰을 요청하는 클라이언트 애플리케이션의 앱 역할 할당을 확인합니다. 클라이언트 앱에 앱 역할이 할당되지 않은 경우 Microsoft Entra ID는 invalid_client: AADSTS501051: 애플리케이션 <애플리케이션 이름>이 <웹 API>에 대한 역할에 할당되지 않음과 비슷한 오류 메시지가 클라이언트로 반환됩니다.

Warning

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

다음 단계

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