동의를 통한 권한 요청에 대한 Microsoft ID 플랫폼 개발자 가이드 - Microsoft identity platform

아티클
04/10/2024

Microsoft ID 플랫폼의 애플리케이션이 필요한 리소스 또는 API에 액세스하려면 동의가 필요합니다. 다양한 동의 유형이 다양한 애플리케이션 시나리오에 더 적합합니다. 앱에 가장 좋은 동의 방식을 선택하면 앱이 사용자와 조직에서 더 성공하는 데 도움이 됩니다.

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

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

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

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

Microsoft ID 플랫폼 엔드포인트를 사용하면 Microsoft Entra 관리 센터의 애플리케이션 등록 정보에 정의된 정적 권한을 무시할 수 있습니다. 대신에 권한을 점진적으로 요청할 수 있습니다. 최소한의 권한 집합을 미리 요구하고 고객이 추가 애플리케이션 기능을 사용함에 따라 더 많은 시간을 요청할 수 있습니다. 이렇게 하려면 애플리케이션 등록 정보에 미리 정의할 필요 없이, 액세스 토큰을 요청할 때 scope 매개 변수에 새 범위를 포함시켜서 언제든지 애플리케이션에 필요한 범위를 지정할 수 있습니다. 사용자가 요청에 추가된 새 범위에 아직 동의하지 않은 경우에는 새 권한에만 동의하라는 메시지가 표시됩니다. 증분 또는 동적 동의는 위임된 권한에만 적용되며 애플리케이션 권한에는 적용되지 않습니다.

scope 매개 변수를 통해 애플리케이션이 동적으로 권한을 요청할 수 있도록 허용하면 개발자가 사용자 환경을 완전히 제어할 수 있습니다. 초기 단계에 동의 환경을 배치하고 하나의 초기 권한 부여 요청으로 모든 권한을 요청할 수도 있습니다. 애플리케이션이 많은 권한을 요청하는 경우 시간의 경과에 따라 애플리케이션의 특정 기능을 사용하도록 시도하는 것처럼 점진적으로 사용자로부터 권한을 수집할 수 있습니다.

Important

동적 동의는 편리할 수 있지만 관리자 동의가 필요한 권한에는 큰 문제가 있습니다. 포털의 앱 등록 및 엔터프라이즈 애플리케이션 블레이드의 관리자 동의 환경은 동의 시 이러한 동적 권한을 알지 못합니다. 개발자는 포털에서 애플리케이션에 필요한 모든 관리자 권한을 나열하는 것이 좋습니다. 이를 통해 테넌트 관리자는 포털의 모든 사용자를 대신하여 한 번만 동의할 수 있습니다. 사용자는 로그인 시 해당 권한에 대한 동의 환경을 거칠 필요가 없습니다. 대안은 해당 권한에 대해 동적 동의를 사용하는 것입니다. 관리자 동의를 부여하기 위해 개별 관리자는 앱에 로그인하고 적절한 권한에 대한 동의 확인 프롬프트를 실행하고 동의 대화 상자에서 내 전체 조직에 대한 동의를 선택합니다.

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 플랫폼은 사용자 동의와 일치하는 레코드를 확인합니다. 사용자가 과거에 요청된 권한에 동의하지 않은 경우 관리자가 전체 조직을 대신하여 해당 권한에 동의하지 않으면 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 플랫폼에 대한 권한 부여, 토큰 또는 동의 엔드포인트에 대한 요청에서 리소스 식별자가 범위 매개 변수에서 생략되는 경우 리소스를 Microsoft Graph로 간주됩니다. 예를 들어, scope=User.Read는 https://graph.microsoft.com/User.Read와 같습니다.

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

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

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

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

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

앱 등록 흐름의 일부
앱 설정의 일부
전용 "연결" 흐름

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

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

사용자가 로그인하도록 하려면 Microsoft ID 플랫폼 프로토콜 자습서를 따르세요.

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

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

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

참고 항목

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

애플리케이션에 대해 정적으로 요청된 권한 목록을 구성하려면:

최소한 클라우드 애플리케이션 관리자로 Microsoft 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 플랫폼 엔드포인트 프로토콜 참조를 확인하세요.

동의를 통한 권한 요청

고정적 사용자 동의

증분 및 동적 사용자 동의

개별 사용자의 동의 요청

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

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

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

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

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

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

성공적인 응답

오류 응답

동의 후 권한 사용

참고 항목

추가 리소스