Microsoft ID 플랫폼 관련 관리자 동의

  • 아티클

일부 권한은 테넌트 내에서 부여되기 전에 관리자의 동의가 필요합니다. 관리자 동의 엔드포인트를 사용하여 전체 테넌트에 권한을 부여할 수도 있습니다.

일반적으로 관리 동의 엔드포인트를 사용하는 애플리케이션을 빌드할 때 앱에는 관리자가 앱의 사용 권한을 승인할 수 있는 페이지 또는 보기가 필요합니다. 이 페이지는 앱 로그인 흐름의 일부, 앱 설정의 일부 또는 전용 "연결" 흐름일 수 있습니다. 대부분의 경우에 사용자가 회사 또는 학교 Microsoft 계정으로 로그인한 후에 앱은 이 "연결" 보기만을 표시하게 됩니다.

사용자로 앱에 로그인하면 사용자에게 필요한 사용 권한을 승인하도록 요청하기 전에 관리자가 속해 있는 조직을 식별할 수 있습니다. 반드시 필요하지는 않지만 조직 사용자를 위한 직관적인 환경을 만들 수 있습니다.

디렉터리 관리에서 사용 권한 요청

조직 관리자의 사용 권한을 요청할 준비가 되면 Microsoft ID 플랫폼 관리자 동의 엔드포인트로 사용자를 리디렉션할 수 있습니다.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &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=fa00d692-e9c7-4460-a743-29f2956fd429
    &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+d320620c-3d56-42bc-bc45-4cdd85c41f00%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로 설정됩니다.

다음 단계