다음을 통해 공유

Microsoft ID 플랫폼의 범위와 권한

  • 아티클

Microsoft ID 플랫폼은 OAuth 2.0 권한 부여 프로토콜을 구현합니다. OAuth 2.0은 사용자 대신 타사 앱에서 웹에 호스트된 리소스에 액세스할 수 있도록 하는 방법입니다. Microsoft ID 플랫폼과 통합되는 웹 호스트팅 리소스에는 리소스 식별자 또는 애플리케이션 ID URI가 있습니다.

이 문서에서는 ID 플랫폼의 범위와 권한에 대해 알아봅니다.

다음 목록에는 Microsoft 웹 호스팅 리소스의 예제가 몇 가지 나와 있습니다.

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 메일 API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Microsoft ID 플랫폼과 통합된 타사 리소스의 경우도 마찬가지입니다. 이러한 리소스는 해당 리소스의 기능을 더 작은 청크로 나누는 데 사용할 수 있는 권한 집합도 정의할 수 있습니다. 예를 들어 Microsoft Graph는 특히 다음 작업을 수행할 수 있는 사용 권한을 정의했습니다.

  • 사용자의 일정 읽기
  • 사용자의 일정에 쓰기
  • 사용자로 메일 보내기

앱이 이러한 유형의 사용 권한 정의로 인해 리소스는 해당 데이터와 API 기능이 노출되는 방식을 세밀하게 제어할 수 있습니다. 타사 앱은 사용자 및 관리자에게 이러한 사용 권한을 요청할 수 있고, 요청을 받은 사용자 또는 관리자가 요청을 승인해야만 앱이 사용자 대신 데이터에 액세스하거나 작업을 수행할 수 있습니다.

리소스 기능이 작은 권한 집합으로 분할되면 기능을 수행하는 데 필요한 권한만 요청하도록 타사 앱을 빌드할 수 있습니다. 사용자 및 관리자는 앱이 어떤 데이터에 액세스할 수 있는지 알 수 있습니다. 그리고 앱이 악의적인 의도를 가지고 작동하지 않는다고 확신할 수 있습니다. 개발자는 항상 최소 권한 원칙에 따라 애플리케이션이 작동하는 데 필요한 사용 권한만 요청해야 합니다.

OAuth 2.0에서는 이러한 유형의 권한 집합을 범위라고 합니다. 권한이라고 하는 경우도 있습니다. Microsoft ID 플랫폼에서 권한은 문자열 값으로 표시됩니다. 앱은 scope 쿼리 매개 변수에 사용 권한을 지정하여 필요한 권한을 요청합니다. ID 플랫폼은 잘 정의된 여러 OpenID Connect 범위와 리소스 기반 권한(각 권한은 리소스의 식별자 또는 애플리케이션 ID URI에 권한 값을 추가하여 표시됨)을 지원합니다. 예를 들어 권한 문자열 https://graph.microsoft.com/Calendars.Read는 Microsoft Graph에서 사용자 일정을 읽을 수 있는 권한을 요청하는 데 사용됩니다.

Microsoft ID 플랫폼에 대한 권한 부여 서버 요청 시 리소스 식별자가 범위 매개 변수에서 생략되는 경우 리소스가 Microsoft Graph로 간주됩니다. 예를 들어 scope=User.Read는 https://graph.microsoft.com/User.Read와 같습니다.

관리 제한 권한

Microsoft ID 플랫폼의 권한은 관리자 제한으로 설정할 수 있습니다. 예를 들어, 많은 상위 권한의 Microsoft Graph 권한에는 관리자 승인이 필요합니다. 앱에 관리자 제한 권한이 필요한 경우 조직의 관리자가 조직의 사용자를 대신하여 해당 범위에 동의해야 합니다. 다음 섹션에는 이러한 종류의 권한에 대한 예제가 나와 있습니다.

  • User.Read.All: 사용자의 모든 전체 프로필 읽기
  • Directory.ReadWrite.All: 조직의 디렉터리에 데이터 쓰기
  • Groups.Read.All: 조직 디렉터리의 모든 그룹 읽기

참고 항목

Microsoft ID 플랫폼에 대한 권한 부여, 토큰 또는 동의 엔드포인트에 대한 요청에서 리소스 식별자가 범위 매개 변수에서 생략되는 경우 리소스를 Microsoft Graph로 간주됩니다. 예를 들어 scope=User.Read는 https://graph.microsoft.com/User.Read와 같습니다.

소비자인 사용자가 이러한 종류의 데이터에 대한 액세스 권한을 애플리케이션에 부여할 수 있더라도 조직 사용자는 동일한 종류의 중요한 회사 데이터 세트에 대한 액세스 권한을 부여할 수 없습니다. 애플리케이션이 조직 사용자에게 이러한 사용 권한 중 하나에 대한 액세스를 요청하는 경우 사용자에게는 앱의 사용 권한에 동의할 권한이 부여되지 않음을 나타내는 오류 메시지가 표시됩니다.

애플리케이션에서 애플리케이션 권한을 요청하고 관리자가 이러한 권한을 부여하는 경우, 이 권한 부여는 특정 사용자를 대신하여 수행되지 않습니다. 그 대신 클라이언트 애플리케이션에 직접 권한이 부여됩니다. 이러한 유형의 권한은 백그라운드에서 실행되는 디먼 서비스와 기타 비대화형 애플리케이션에서만 사용되어야 합니다. 직접 액세스 시나리오에 대한 자세한 내용은 Microsoft ID 플랫폼 액세스 시나리오를 참조하세요.

웹 API에서 범위를 노출하는 방법에 대한 단계별 가이드는 웹 API를 노출하도록 애플리케이션 구성을 참조하세요.

OpenID Connect 범위

OpenID Connect의 Microsoft ID 플랫폼 구현에는 Microsoft Graph에도 호스팅되는 잘 정의된 몇 가지 범위(openid, email, profile, offline_access)가 있습니다. address 및 phone OpenID Connect 범위는 지원되지 않습니다.

OpenID Connect 범위와 토큰을 요청하면 UserInfo 엔드포인트를 호출하는 토큰을 받게 됩니다.

openid 범위

앱이 OpenID Connect를 사용하여 로그인하는 경우 openid 범위를 요청해야 합니다. openid 범위는 회사 계정 동의 페이지에 사용자를 로그인 권한으로 표시됩니다.

이 사용 권한을 사용하여 앱은 sub 클레임 형식으로 사용자에 대한 고유 식별자를 받을 수 있습니다. 이 권한은 앱에 UserInfo 엔드포인트에 대한 액세스 권한도 부여합니다. openid 범위는 Microsoft ID 플랫폼 토큰 엔드포인트에서 ID 토큰을 획득하는 데 사용할 수 있습니다. 앱은 이러한 토큰을 인증에 사용할 수 있습니다.

email 범위

email 범위는 openid 범위 및 기타 범위와 함께 사용할 수 있습니다. 이는 앱이 email 클레임의 형식으로 사용자의 기본 전자 메일 주소에 액세스할 수 있도록 해줍니다.

email 클레임은 이메일 주소가 사용자 계정과 연결된 경우에만 토큰에 포함되며, 항상 그런 것은 아닙니다. 앱에서 email 범위를 사용하는 경우 앱은 토큰에 email 클레임이 없는 경우를 처리할 수 있어야 합니다.

profile 범위

profile 범위는 openid 범위 및 기타 범위와 함께 사용할 수 있습니다. 이를 통해 앱은 사용자에 대한 많은 양의 정보에 액세스할 수 있습니다. 액세스할 수 있는 정보에는 사용자 이름, 성, 기본 설정된 사용자 이름, 개체 ID 등이 포함됩니다.

특정 사용자에 대한 id_tokens 매개 변수에서 사용할 수 있는 profile 클레임의 전체 목록은 id_tokens 참조를 확인하세요.

offline_access 범위

offline_access 범위를 사용하면 앱이 연장된 기간 동안 사용자 대신 리소스에 액세스할 수 있습니다. 동의 페이지에서 이 범위는 액세스 권한을 부여한 데이터에 대한 액세스 유지 권한으로 나타납니다.

사용자가 offline_access 범위를 승인하면 앱은 Microsoft ID 플랫폼 토큰 엔드포인트에서 새로 고침 토큰을 받을 수 있습니다. 새로 고침 토큰은 장기적으로 존재합니다. 오래된 액세스 토큰이 만료되면 앱에서 새 액세스 토큰을 가져올 수 있습니다.

참고 항목

이 권한은 현재 모든 동의 페이지에 표시되며 새로 고침 토큰을 제공하지 않는 흐름(예: 암시적 흐름)에 대해서도 마찬가지입니다. 이러한 설정은 클라이언트가 암시적 흐름 내에서 시작한 다음, 새로 고침 토큰이 필요한 코드 흐름으로 이동할 수 있는 시나리오를 해결합니다.

Microsoft ID 플랫폼(v2.0 엔드포인트에 대한 요청)에서 앱은 새로 고침 토큰을 받기 위해 offline_access 범위를 명시적으로 요청해야 합니다. 따라서 OAuth 2.0 인증 코드 흐름에서 인증 코드를 교환하는 경우 /token 엔드포인트에서 액세스 토큰만 받게 됩니다.

액세스 토큰은 일반적으로 약 1시간 동안 유효합니다. 이 시점에 앱은 사용자를 /authorize 엔드포인트로 다시 리디렉션하여 새 인증 코드를 요청해야 합니다. 이 리디렉션 중에 앱 형식에 따라 사용자는 자격 증명을 다시 입력하거나 권한에 다시 동의해야 할 수도 있습니다.

새로 고침 토큰은 액세스 토큰보다 만료 시간이 길며 일반적으로 하루 동안 유효합니다. 새로 고침 토큰을 가져오고 사용하는 방법에 대한 자세한 내용은 Microsoft ID 플랫폼 프로토콜 참조를 확인하세요.

응답에 새로 고침 토큰을 포함하는 것은 애플리케이션의 특정 구성 및 권한 부여 프로세스 중에 요청된 범위를 포함하여 여러 가지 요인에 따라 달라질 수 있습니다. 응답에서 새로 고침 토큰을 받을 것으로 예상하지만 실패하는 경우 다음 요소를 고려합니다.

  • 범위 요구 사항: 필요한 다른 범위와 함께 범위를 요청하고 offline_access 있는지 확인합니다.
  • 권한 부여 유형: 새로 고침 토큰은 일반적으로 권한 부여 코드 부여 유형을 사용할 때 제공됩니다. 흐름이 다른 경우 응답에 영향을 줄 수 있습니다.
  • 클라이언트 구성: ID 플랫폼에서 애플리케이션의 설정을 확인합니다. 특정 구성은 refresh_tokens 발급을 제한할 수 있습니다.

.default 범위

.default 범위는 특정 권한을 식별하지 않고 요청에서 일반적으로 리소스 서비스(API)를 참조하는 데 사용됩니다. 동의가 필요한 경우 .default를 사용하면 애플리케이션 등록에 나열된 모든 필수 권한(목록의 모든 API에 대해)에 대해 동의 메시지가 표시되어야 합니다.

범위 매개 변수 값은 리소스 및 .default에 대한 식별자 URI를 사용하여 생성되고 슬래시(/)로 구분됩니다. 예를 들어 리소스의 식별자 URI가 https://contoso.com인 경우 요청할 범위는 https://contoso.com/.default입니다. 토큰을 올바르게 요청하기 위해 두 번째 슬래시를 포함해야 하는 경우 후행 슬래시에 대한 섹션을 참조하세요.

scope={resource-identifier}/.default를 사용하는 것은 v1.0 엔드포인트의 resource={resource-identifier}와 기능적으로 동일합니다(여기서 {resource-identifier}는 API의 식별자 URI(예: Microsoft Graph의 경우 https://graph.microsoft.com)임).

.default 범위는 모든 OAuth 2.0 흐름에서 사용하고 관리자 동의를 시작하는 데 사용할 수 있습니다. On-Behalf-Of 흐름 및 클라이언트 자격 증명 흐름에서 이를 사용해야 합니다.

클라이언트는 정적(.default) 동의와 동적 동의를 단일 요청에 결합할 수 없습니다. 따라서 scope=https://graph.microsoft.com/.default Mail.Read는 범위 유형을 결합하기 때문에 오류가 발생합니다.

.default 범위 매개 변수는 로그인한 사용자를 대신하여 클라이언트와 리소스 간에 위임된 권한에 동의하지 않은 경우에만 동의 확인 프롬프트를 트리거합니다.

동의한 경우 반환된 토큰에는 해당 리소스에 대해 로그인한 사용자에게 부여된 모든 범위가 포함됩니다. 그러나 요청된 리소스에 대한 권한이 부여되지 않은 경우(또는 prompt=consent 매개 변수가 제공된 경우) 목록의 모든 API에 대해 클라이언트 애플리케이션 등록에 구성된 모든 필수 권한에 대한 동의 확인 프롬프트가 표시됩니다.

예를 들어 범위 https://graph.microsoft.com/.default를 요청하는 경우 애플리케이션은 Microsoft Graph API에 대한 액세스 토큰을 요청합니다. 로그인한 사용자를 대신하여 Microsoft Graph에 위임된 권한이 하나 이상 부여된 경우, 계속 로그인되며 해당 사용자에게 부여된 모든 Microsoft Graph 위임된 권한이 액세스 토큰에 포함됩니다. 요청된 리소스에 대한 권한이 부여되지 않은 경우(이 예제에서는 Microsoft Graph) 목록의 모든 API에 대해 애플리케이션에 구성된 모든 필수 권한에 대한 동의 확인 프롬프트가 표시됩니다.

예제 1: 사용자 또는 테넌트 관리자가 권한을 부여한 경우

이 예제에서는 사용자 또는 테넌트 관리자가 클라이언트에 Mail.Read 및 User.Read Microsoft Graph 권한을 부여했습니다.

클라이언트가 scope=https://graph.microsoft.com/.default를 요청하면 Microsoft Graph에 대한 클라이언트 애플리케이션의 등록된 권한 내용에 관계없이 동의 프롬프트가 표시되지 않습니다. 반환된 토큰에는 Mail.Read 및 User.Read 범위가 포함됩니다.

예제 2: 사용자가 클라이언트와 리소스 간에 권한을 부여하지 않은 경우

이 예제에서는 사용자가 클라이언트와 Microsoft Graph 간에 동의를 부여하지 않았으며 관리자도 없습니다. 클라이언트는 User.Read 및 Contacts.Read 권한에 등록했습니다. Azure Key Vault 범위 https://vault.azure.net/user_impersonation에도 등록했습니다.

클라이언트가 scope=https://graph.microsoft.com/.default에 대한 토큰을 요청하면 Microsoft Graph User.Read 및 Contacts.Read 범위와 Azure Key Vault user_impersonation 범위에 대한 동의 페이지가 사용자에게 표시됩니다. 반환된 토큰에는 User.Read 및 Contacts.Read 범위만 포함되며 Microsoft Graph에 대해서만 사용할 수 있습니다.

예제 3: 사용자가 동의했고 클라이언트가 범위를 더 요청하는 경우

이 예에서 사용자는 클라이언트의 Mail.Read에 이미 동의했습니다. 클라이언트는 Contacts.Read 범위에 등록했습니다.

클라이언트는 먼저 scope=https://graph.microsoft.com/.default를 사용하여 로그인을 수행합니다. 응답의 scopes 매개 변수에 따라 애플리케이션의 코드는 Mail.Read가 부여된 것만 검색합니다. 그런 다음, 클라이언트는 scope=https://graph.microsoft.com/.default를 사용하여 두 번째 로그인을 시작하고 이번에는 prompt=consent를 사용하여 동의를 강제합니다. 사용자가 애플리케이션에서 등록한 모든 권한에 동의할 수 있는 경우 동의 확인 프롬프트가 표시됩니다. 그렇지 않은 경우에는 오류 메시지 또는 관리자 동의 요청 양식이 표시됩니다. Contacts.Read와 Mail.Read 모두 동의 확인 프롬프트에 표시됩니다. 동의가 부여되고 로그인이 계속되면 반환되는 토큰은 Microsoft Graph용이며 Mail.Read 및 Contacts.Read를 포함합니다.

클라이언트와 함께 .default 범위 사용

클라이언트가 자체 .default 범위를 요청하는 경우도 있습니다. 다음 예제에서는 이 시나리오를 보여 줍니다.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

이 코드 예제는 동의 및 .default에 대한 앞의 설명이 시나리오에 적용되는 경우 등록된 모든 권한에 대한 동의 페이지를 생성합니다. 그런 다음, 코드는 액세스 토큰이 아닌 id_token을 반환합니다.

Microsoft ID 플랫폼을 대상으로 하는 새 클라이언트에는 이 설정을 사용해서는 안 됩니다. ADAL(Azure AD 인증 라이브러리)에서 MSAL(Microsoft 인증 라이브러리)로 마이그레이션합니다.

클라이언트 자격 증명 부여 흐름 및 .default

.default의 다른 용도는 클라이언트 자격 증명 부여 흐름을 사용하여 웹 API를 호출하는 디먼 앱과 같은 비대화형 애플리케이션에서 앱 역할(애플리케이션 권한이라고도 함)을 요청하는 것입니다.

웹 API에 대한 앱 역할(애플리케이션 권한)을 정의하려면 애플리케이션에서 앱 역할 추가를 참조하세요.

클라이언트 서비스의 클라이언트 자격 증명 요청에는 scope={resource}/.default가 포함되어야 합니다. 여기서 {resource}는 앱이 호출하고 액세스 토큰을 가져오려는 하는 웹 API입니다. 개별 애플리케이션 권한(역할)을 사용하여 클라이언트 자격 증명 요청을 실행하는 것은 지원되지 않습니다. 반환된 액세스 토큰에는 웹 API에 대해 부여된 모든 앱 역할(애플리케이션 권한)이 포함됩니다.

정의한 앱 역할에 대한 액세스 권한을 부여하려면(애플리케이션에 대한 관리자 동의 부여 포함) 웹 API에 액세스하도록 클라이언트 애플리케이션 구성을 참조하세요.

후행 슬래시 및 .default

일부 리소스 URI에는 후행 슬래시가 있습니다(예: https://contoso.com과 달리 https://contoso.com/). 후행 슬래시는 토큰 유효성 검사에 문제를 일으킬 수 있습니다. Azure Resource Manager(https://management.azure.com/)에 대해 토큰이 요청될 때 주로 문제가 발생합니다.

이 경우 리소스 URI의 후행 슬래시는 토큰이 요청될 때 슬래시가 있어야 한다는 의미입니다. 따라서 https://management.azure.com/에 대한 토큰을 요청하고 .default를 사용할 때는 https://management.azure.com//.default를 요청해야 합니다(이중 슬래시 확인!).

일반적으로 토큰이 발행되고 있음을 확인하고 토큰을 수락해야 하는 API가 토큰을 거부한 경우에는 두 번째 슬래시를 추가하고 다시 시도해보십시오.

참고 항목