Microsoft ID 플랫폼에서 사용 권한 및 동의를 요청하는 개발자 가이드

2025-05-21

Microsoft ID 플랫폼의 애플리케이션은 필요한 리소스 또는 API에 액세스하기 위해 동의를 사용합니다. 다양한 유형의 동의는 다양한 애플리케이션 시나리오에 더 적합합니다. 앱에 동의할 최상의 방법을 선택하면 사용자 및 조직에서 더 성공적으로 앱에 동의할 수 있습니다.

이 문서에서는 다양한 유형의 동의와 동의를 통해 애플리케이션에 대한 권한을 요청하는 방법에 대해 알아봅니다.

비고

외부 테넌트의 애플리케이션의 경우 고객은 권한 자체에 동의할 수 없습니다. 관리자는 애플리케이션이 대신 리소스에 액세스하는 데 동의를 부여해야 합니다. 자세한 내용은 관리자 동의 부여를 참조하세요.

정적 사용자 동의 시나리오에서는 Microsoft Entra 관리 센터의 앱 구성에 필요한 모든 권한을 지정해야 합니다. 사용자(또는 관리자)가 이 앱에 대한 동의를 부여하지 않는 경우 Microsoft ID 플랫폼은 현재 사용자에게 동의를 제공하라는 메시지를 표시합니다.

또한 정적 사용 권한을 통해 관리자는 조직의 모든 사용자를 대신하여 동의를 얻을 수 있습니다.

정적 동의 및 단일 사용 권한 목록을 사용하면 코드가 멋지고 단순하게 유지되지만 앱이 미리 필요할 수 있는 모든 권한을 요청한다는 의미이기도 합니다. 이 설정은 사용자와 관리자가 앱의 액세스 요청을 승인하지 못하게 할 수 있습니다.

Microsoft ID 플랫폼 엔드포인트를 사용하면 Microsoft Entra 관리 센터의 애플리케이션 등록 정보에 정의된 정적 권한을 무시할 수 있습니다. 대신 증분 방식으로 권한을 요청할 수 있습니다. 고객이 더 많은 애플리케이션 기능을 사용하므로 최소한의 사용 권한 집합을 미리 요청하고 시간이 지남에 따라 더 많은 권한을 요청할 수 있습니다. 이렇게 하려면 애플리케이션 등록 정보에 미리 정의할 필요 없이 scope 때 매개 변수에 새 범위를 포함하여 애플리케이션에 필요한 범위를 언제든지 지정할 수 있습니다.

사용자가 요청에 추가된 새 범위에 동의하지 않으면 새 권한에만 동의하라는 메시지가 표시됩니다. 증분 또는 동적 동의는 위임된 권한에만 적용되며 애플리케이션 권한에는 적용되지 않습니다.

애플리케이션이 매개 변수를 통해 scope 동적으로 권한을 요청하도록 허용하면 개발자가 사용자 환경을 완전히 제어할 수 있습니다. 먼저 동의 환경을 로드하고 하나의 초기 권한 부여 요청에서 모든 권한을 요청합니다. 애플리케이션에 많은 권한이 필요한 경우 시간이 지남에 따라 애플리케이션의 특정 기능을 사용하려고 할 때 사용자로부터 이러한 권한을 증분 방식으로 수집할 수 있습니다.

중요합니다

동적 동의는 편리할 수 있지만 관리자 동의가 필요한 권한에는 상당한 문제가 있습니다. 포털의 앱 등록 및 엔터프라이즈 애플리케이션 블레이드의 관리자 동의 환경은 동의 시 이러한 동적 권한에 대해 알지 못합니다. 개발자는 포털에서 애플리케이션에 필요한 모든 관리자 권한 권한을 나열하는 것이 좋습니다.

이렇게 하면 테넌트 관리자가 포털의 모든 사용자를 대신하여 한 번 동의할 수 있습니다. 사용자는 로그인 시 해당 권한에 대한 동의 환경을 통과할 필요가 없습니다. 대안은 해당 권한에 대해 동적 동의를 사용하는 것입니다. 관리자 동의를 부여하려면 개별 관리자가 앱에 로그인하고, 적절한 권한에 대한 동의 프롬프트를 트리거하고, 동의 대화 상자에서 내 전체 조직에 대한 동의 를 선택합니다.

OpenID Connect 또는 OAuth 2.0 권한 부여 요청에서 애플리케이션은 쿼리 매개 변수를 사용하여 scope 필요한 권한을 요청할 수 있습니다. 예를 들어 사용자가 앱에 로그인하면 애플리케이션은 다음 예제와 같은 요청을 보냅니다. (가독성을 위해 줄 바꿈이 추가됨).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

scope 매개 변수는 애플리케이션이 요청하는 위임된 권한의 공백으로 구분된 목록입니다. 각 권한은 리소스 식별자(애플리케이션 ID URI)에 권한 값을 추가하여 표시됩니다. 요청 예제에서 애플리케이션은 사용자의 일정을 읽고 사용자로 메일을 보낼 수 있는 권한이 필요합니다.

로그인 후 Microsoft ID 플랫폼은 기존 사용자 동의를 확인합니다. 사용자가 요청된 사용 권한을 승인하지 않고 관리자가 승인하지 않는 경우 플랫폼은 사용자에게 동의를 부여하라는 메시지를 표시합니다.

다음 예제 offline_access 에서는 ("액세스 권한을 부여한 데이터에 대한 액세스 유지") 권한 및 User.Read ("로그인 및 프로필 읽기") 권한은 애플리케이션에 대한 초기 동의에 자동으로 포함됩니다. 이러한 권한은 적절한 애플리케이션 기능에 필요합니다.

offline_access 권한은 애플리케이션에 네이티브 앱 및 웹 앱에 중요한 새로 고침 토큰에 대한 액세스 권한을 제공합니다. User.Read 권한은 sub 클레임에 대한 액세스를 제공합니다. 이를 통해 클라이언트 또는 애플리케이션은 시간이 지남에 따라 사용자를 올바르게 식별하고 기본적인 사용자 정보에 액세스할 수 있습니다.

사용자가 권한 요청을 승인하면 동의가 기록됩니다. 사용자는 나중에 애플리케이션에 로그인할 때 다시 동의할 필요가 없습니다.

전체 테넌트에 대한 동의를 요청하려면 관리자 동의가 필요합니다. 조직을 대신하여 수행된 관리자 동의에는 앱에 대해 등록된 정적 권한이 필요합니다. 관리자가 전체 조직을 대신하여 동의해야 하는 경우 앱 등록 포털에서 해당 권한을 설정합니다.

앱 이 관리자 동의가 필요한 위임된 권한을 요청하면 사용자에게 "동의할 수 없음" 오류가 표시되고 관리자에게 액세스 권한을 요청해야 합니다. 관리자가 전체 테넌트에 대한 동의를 부여하면 동의가 취소되거나 새 권한이 추가되지 않는 한 사용자에게 다시 메시지가 표시되지 않습니다.

동일한 애플리케이션을 사용하는 관리자에게 관리자 동의 프롬프트가 표시됩니다. 관리자 동의 프롬프트는 전체 테넌트에 대한 사용자를 대신하여 애플리케이션에 요청된 데이터에 대한 액세스 권한을 부여할 수 있는 확인란을 제공합니다. 사용자 및 관리자 동의 환경에 대한 자세한 내용은 애플리케이션 동의 환경을 참조하세요.

관리자 동의가 필요한 Microsoft Graph에 대한 위임된 권한의 예는 다음과 같습니다.

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

Microsoft Graph 권한의 전체 목록을 보려면 Microsoft Graph 권한 참조를 참조하세요.

관리자 동의가 필요하도록 자체 리소스에 대한 권한을 구성할 수도 있습니다. 관리자 동의가 필요한 범위를 추가하는 방법에 대한 자세한 내용은 관리자 동의 가 필요한 범위 추가를 참조하세요.

일부 조직에서는 테넌트에 대한 기본 사용자 동의 정책을 변경할 수 있습니다. 애플리케이션이 사용 권한에 대한 액세스를 요청하면 이러한 정책에 대해 평가됩니다. 사용자는 기본적으로 필요하지 않은 경우에도 관리자 동의를 요청해야 할 수 있습니다. 관리자가 애플리케이션에 대한 동의 정책을 관리하는 방법을 알아보려면 앱 동의 정책 관리를 참조하세요.

비고

Microsoft ID 플랫폼 권한 부여, 토큰 또는 동의 요청에서 scope 매개 변수의 리소스 식별자를 생략하는 것은 기본적으로 Microsoft Graph입니다. 예를 들어 scope=User.Read는 https://graph.microsoft.com/User.Read로 처리됩니다.

애플리케이션 권한에는 항상 관리자 동의가 필요합니다. 애플리케이션 권한에는 사용자 컨텍스트가 없으며 특정 사용자를 대신하여 동의 부여가 수행되지 않습니다. 그 대신 클라이언트 애플리케이션에 직접 권한이 부여됩니다. 이러한 유형의 권한은 디먼 서비스 및 백그라운드에서 실행되는 다른 비대화형 애플리케이션에서만 사용됩니다. 관리자는 Microsoft Entra 관리 센터를 통해 권한을 미리 구성하고 관리자 동의를 부여 해야 합니다.

권한을 요청하는 애플리케이션이 다중 테넌트 애플리케이션인 경우 해당 애플리케이션 등록은 만들어진 테넌트에만 존재하므로 로컬 테넌트에서 사용 권한을 구성할 수 없습니다. 애플리케이션이 관리자 동의가 필요한 권한을 요청하는 경우 관리자는 사용자를 대신하여 동의해야 합니다. 이러한 권한에 동의하려면 관리자가 애플리케이션 자체에 로그인해야 하므로 관리자 동의 로그인 환경이 트리거됩니다. 다중 테넌트 애플리케이션에 대한 관리자 동의 환경을 설정하는 방법을 알아보려면 다중 테넌트 로그인 사용을 참조하세요.

관리자는 다음 옵션을 사용하여 애플리케이션에 대한 동의를 부여할 수 있습니다.

사용자가 앱에 로그인하는 것이 좋습니다.

일반적으로 관리자 동의가 필요한 애플리케이션을 빌드하는 경우 애플리케이션에는 관리자가 앱의 권한을 승인할 수 있는 페이지 또는 보기가 필요합니다. 이 페이지는 다음과 같습니다.

앱 등록 흐름의 일부입니다.
앱 설정의 일부입니다.
전용 "연결" 흐름입니다.

대부분의 경우 사용자가 회사 Microsoft 계정 또는 학교 Microsoft 계정으로 로그인한 후에만 애플리케이션에서 "연결" 보기를 표시하는 것이 좋습니다.

앱에 사용자를 로그인할 때 필요한 권한을 승인하도록 요청하기 전에 관리자가 속한 조직을 식별할 수 있습니다. 이 단계는 반드시 필요한 것은 아니지만 조직 사용자를 위한 보다 직관적인 환경을 만드는 데 도움이 될 수 있습니다.

사용자를 로그인하려면 Microsoft ID 플랫폼 프로토콜 자습서를 따릅니다.

앱 등록 포털에서 사용 권한 요청

앱 등록 포털에서 애플리케이션은 위임된 권한과 애플리케이션 사용 권한을 포함하여 필요한 사용 권한을 나열할 수 있습니다. 이 설정을 통해 .default 범위와 Microsoft Entra 관리 센터의 관리자 동의 부여 옵션을 사용할 수 있습니다.

일반적으로 권한은 지정된 애플리케이션에 대해 정적으로 정의되어야 합니다. 애플리케이션이 동적으로 또는 증분적으로 요청하는 권한의 상위 집합이어야 합니다.

비고

애플리케이션 권한은 .default를 사용해야만 요청할 수 있습니다. 따라서 애플리케이션에 애플리케이션 권한이 필요한 경우 앱 등록 포털에 나열되어 있는지 확인합니다.

애플리케이션에 대해 정적으로 요청된 권한 목록을 구성하려면 다음을 수행합니다.

적어도 클라우드 애플리케이션 관리자로서 Microsoft Entra 관리 센터에 로그인하세요.
Entra ID>앱 등록> 이동합니다.
애플리케이션을 선택하거나 아직 앱을 만들지 않은 경우 만듭니다.
애플리케이션의 개요 페이지의 관리 아래에서 API 사용 권한>추가 권한을 선택합니다.
사용 가능한 API 목록에서 Microsoft Graph를 선택합니다. 그런 다음 애플리케이션에 필요한 권한을 추가합니다.
권한 추가를 선택합니다.

성공적인 응답

관리자가 앱에 대한 사용 권한을 승인하는 경우 성공적인 응답은 다음과 같습니다.

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True

매개 변수	설명
`tenant`	애플리케이션에 요청한 권한을 GUID 형식으로 부여한 디렉터리 테넌트입니다.
`state`	토큰 응답에 반환된 요청에 포함된 값입니다. 원하는 모든 콘텐츠의 문자열일 수 있습니다. 상태는 인증 요청이 발생하기 전에 애플리케이션의 사용자 상태에 대한 정보를 인코딩하는 데 사용됩니다(예: 페이지 또는 보기).
`admin_consent`	로 설정됩니다 `True`.

관리자 동의 엔드포인트에서 성공적인 응답을 받으면 애플리케이션에 요청한 권한이 부여됩니다. 다음으로 원하는 리소스에 대한 토큰을 요청할 수 있습니다.

오류 응답

관리자가 앱에 대한 사용 권한을 승인하지 않으면 실패한 응답은 다음과 같습니다.

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request

매개 변수	설명
`error`	발생하는 오류 유형을 분류하는 데 사용할 수 있는 오류 코드 문자열입니다. 오류에 대응하는 데 사용할 수도 있습니다.
`error_description`	개발자가 오류의 근본 원인을 식별하는 데 도움이 되는 특정 오류 메시지입니다.

사용자가 앱에 대한 권한에 동의하면 애플리케이션은 일부 용량의 리소스에 액세스할 수 있는 앱의 권한을 나타내는 액세스 토큰을 획득할 수 있습니다. 액세스 토큰은 단일 리소스에만 사용할 수 있습니다. 그러나 액세스 토큰 내부에 인코딩된 모든 권한은 해당 리소스에 대해 애플리케이션에 부여되는 모든 권한입니다. 액세스 토큰을 획득하기 위해 애플리케이션은 다음과 같이 Microsoft ID 플랫폼 토큰 엔드포인트에 요청할 수 있습니다.

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

리소스에 대한 HTTP 요청에서 결과 액세스 토큰을 사용할 수 있습니다. 애플리케이션에 특정 작업을 수행할 수 있는 적절한 권한이 있음을 리소스에 안정적으로 나타냅니다.

OAuth 2.0 프로토콜 및 액세스 토큰을 가져오는 방법에 대한 자세한 내용은 Microsoft ID 플랫폼 엔드포인트 프로토콜 참조를 참조하세요.

다음을 통해 공유

고정적 사용자 동의

증분 및 동적 사용자 동의

개별 사용자의 동의 요청

관리자 동의를 통해 전체 테넌트에 대한 동의 요청

위임된 권한에 대한 관리자 동의

애플리케이션 권한에 대한 관리자 동의

다중 테넌트 애플리케이션에 대한 관리자 동의

사용자가 앱에 로그인하는 것이 좋습니다.

앱 등록 포털에서 사용 권한 요청

성공적인 응답

오류 응답

동의 후 사용 권한 사용

관련 콘텐츠

피드백

추가 리소스