Microsoft ID 플랫폼 관련 관리자 동의
일부 권한은 테넌트 내에서 부여되기 전에 관리자의 동의가 필요합니다. 관리자 동의 엔드포인트를 사용하여 전체 테넌트에 권한을 부여할 수도 있습니다.
사용자가 앱에 로그인하는 것이 좋습니다.
일반적으로 관리 동의 엔드포인트를 사용하는 애플리케이션을 빌드할 때 앱에는 관리자가 앱의 사용 권한을 승인할 수 있는 페이지 또는 보기가 필요합니다. 이 페이지는 앱 로그인 흐름의 일부, 앱 설정의 일부 또는 전용 "연결" 흐름일 수 있습니다. 대부분의 경우에 사용자가 회사 또는 학교 Microsoft 계정으로 로그인한 후에 앱은 이 "연결" 보기만을 표시하게 됩니다.
사용자로 앱에 로그인하면 사용자에게 필요한 사용 권한을 승인하도록 요청하기 전에 관리자가 속해 있는 조직을 식별할 수 있습니다. 반드시 필요하지는 않지만 조직 사용자를 위한 직관적인 환경을 만들 수 있습니다.
디렉터리 관리에서 사용 권한 요청
조직 관리자의 사용 권한을 요청할 준비가 되면 Microsoft ID 플랫폼 관리자 동의 엔드포인트로 사용자를 리디렉션할 수 있습니다.
https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
&redirect_uri=http://localhost/myapp/permissions
&state=12345
| 매개 변수 | Condition | 설명 |
|---|---|---|
tenant |
필수 | 사용 권한을 요청하려는 디렉터리 테넌트입니다. GUID에서 제공한 이름이거나, 친근한 이름 형식이거나, 예제에서처럼 organizations으로 일반 참조될 수 있습니다. 개인 계정에서는 테넌트의 컨텍스트를 제외하고는 관리자 동의를 제공할 수 없으므로 'common'을 사용하지 마세요. 테넌트를 관리하는 개인 계정과 가장 잘 호환되도록 하려면 가능하면 테넌트 ID를 사용합니다. |
client_id |
Required | Microsoft Entra 관리 센터 – 앱 등록 환경이 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
redirect_uri |
필수 | 리디렉션 URI는 처리할 앱에 응답을 전송하려는 위치입니다. 앱 등록 포털에 등록한 리디렉션 URI 중 하나와 정확히 일치해야 합니다. |
state |
권장 | 토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 모든 콘텐츠의 문자열일 수 있습니다. 상태를 사용하여 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 사용한 페이지 또는 보기)를 인코딩할 수 있습니다. |
scope |
필수 | 애플리케이션에서 요청하는 사용 권한 세트를 정의합니다. 이는 정적(/.default 사용) 또는 동적 범위일 수 있습니다. 여기에는 OIDC 범위(openid, profile, email)가 포함될 수 있습니다. |
이 시점에서 Microsoft Entra ID는 테넌트 관리자에게 요청을 완료하기 위해 로그인하도록 요구합니다. 관리자는 scope 매개 변수로 요청한 모든 권한을 승인하라는 요청을 받습니다. 정적(/.default) 값을 사용한 경우 이 값은 v1.0 관리자 동의 엔드포인트처럼 작동하고 필요한 권한(사용자 및 앱 모두)에 있는 모든 범위에 대한 동의를 요청합니다. 앱 권한을 요청하려면 /.default 값을 사용해야 합니다. /.default를 사용할 때 관리자가 항상 관리자 동의 화면에서 지정된 권한을 볼 수 없도록 하려면 필수 권한 섹션에 권한을 두지 않는 것이 가장 좋습니다. 대신 /.default를 사용하는 대신 동적 동의를 사용하여 런타임에 동의 화면에 표시하려는 권한을 추가할 수 있습니다.
성공적인 응답
관리자가 앱에 대한 사용 권한을 승인하는 경우 성공적인 응답은 다음과 같습니다.
http://localhost/myapp/permissions
?admin_consent=True
&tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee
&scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
&state=12345
| 매개 변수 | 설명 |
|---|---|
tenant |
디렉터리 테넌트는 GUID 형식으로 요청한 권한을 애플리케이션에 부여합니다. |
state |
토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 모든 콘텐츠의 문자열일 수 있습니다. 상태는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 사용한 페이지 또는 보기)를 인코딩하는 데 사용됩니다. |
scope |
애플리케이션에 대한 액세스 권한이 부여된 권한 집합입니다. |
admin_consent |
True로 설정합니다. |
Warning
tenant 매개 변수의테넌트 ID 값을 사용하여 사용자를 인증하거나 권한을 부여하지 마세요. 잘못된 행위자가 테넌트 ID 값을 업데이트하고 전송하여 앱에 대한 응답을 가장할 수 있습니다. 이로 인해 애플리케이션이 보안 인시던트에 노출될 수 있습니다.
오류 응답
http://localhost/myapp/permissions
?admin_consent=True
&error=consent_required
&error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+0000aaaa-11bb-cccc-dd22-eeeeee333333%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
&state=12345
성공적인 응답에서 보았던 매개 변수에 오류 매개 변수를 추가하면 아래와 같이 나타납니다.
| 매개 변수 | 설명 |
|---|---|
error |
발생하는 오류 유형을 분류하는 데 사용할 수 있고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
개발자가 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다. |
state |
토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 모든 콘텐츠의 문자열일 수 있습니다. 상태는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 사용한 페이지 또는 보기)를 인코딩하는 데 사용됩니다. |
admin_consent |
이 응답이 관리자 동의 흐름에서 발생했음을 나타내기 위해 True로 설정됩니다. |
다음 단계
- 앱을 다중 테넌트로 변환하는 방법 참조
- 인증 코드 부여 흐름 중에 OAuth 2.0 프로토콜 계층에서 동의가 지원되는 방식에 대해 알아봅니다.
- 다중 테넌트 애플리케이션이 동의 프레임워크를 사용하여 "user" 및 "admin" 동의를 구현하고 좀 더 수준 높은 다중 계층 애플리케이션 패턴을 지원하는 방법을 알아봅니다.
- Microsoft Entra 애플리케이션 동의 환경 이해