Microsoft ID 플랫폼 및 OAuth 2.0 디바이스 권한 부여 흐름

  • 아티클

Microsoft ID 플랫폼은 디바이스 권한 부여를 지원합니다. 디바이스 권한 부여를 사용하면 사용자가 스마트 TV, IoT 디바이스 또는 프린터와 같은 입력 제한된 디바이스에 로그인할 수 있습니다. 이 흐름을 활성화하기 위해 해당 디바이스는 사용자가 로그인할 웹 페이지를 다른 디바이스의 브라우저에서 방문하도록 합니다. 사용자가 로그인하면 디바이스에서 액세스 토큰을 가져오고 필요에 따라 해당 토큰을 새로 고칠 수 있습니다.

이 문서에서는 애플리케이션에서 프로토콜에 대해 직접 프로그래밍을 수행하는 방법을 설명합니다. 가능하다면 토큰을 획득하고 보안 웹 API를 호출하는 대신, 지원되는 MSAL(Microsoft 인증 라이브러리)을 사용하는 것이 좋습니다. 예제는 MSAL을 사용하는 샘플 앱을 참조할 수 있습니다.

프로토콜 다이어그램

전체 디바이스 코드 흐름은 다음 다이어그램에 표시됩니다. 각 단계는 이 문서 전반에 걸쳐 설명되어 있습니다.

Device code flow

디바이스 권한 부여 요청

클라이언트는 먼저 인증을 시작하는 데 사용되는 디바이스 및 사용자 코드에 대한 인증 서버와 검사 합니다. 클라이언트는 /devicecode 엔드포인트에서 이 요청을 수집합니다. 요청에서 클라이언트는 사용자로부터 획득해야 하는 권한을 포함해야 합니다.

요청이 전송되는 순간부터 사용자는 로그인하는 데 15분이 걸립니다. expires_in의 기본값입니다. 요청은 사용자가 로그인할 준비가 되었음을 나타내는 경우에만 이루어져야 합니다.

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile
매개 변수 Condition 설명
tenant 필수 /common, /consumers 또는 /organizations일 수 있습니다. GUID 또는 식별 이름 형식의 사용 권한을 요청하려는 디렉터리 테넌트가 될 수도 있습니다.
client_id Required Microsoft Entra 관리 센터 – 앱 등록 환경이 앱에 할당한 애플리케이션(클라이언트) ID입니다.
scope Required 사용자가 동의하게 할 공백으로 구분된 범위 목록입니다.

디바이스 권한 부여 응답

성공적인 응답은 사용자가 로그인할 수 있도록 하는 데 필요한 정보를 포함하는 JSON 개체입니다.

매개 변수 서식 설명
device_code 문자열 클라이언트와 권한 부여 서버 간의 세션을 확인하는 데 사용되는 긴 문자열입니다. 클라이언트에서 이 매개 변수를 사용하여 권한 부여 서버의 액세스 토큰을 요청합니다.
user_code 문자열 보조 디바이스에서 세션을 식별하는 데 사용되는 사용자에게 표시되는 짧은 문자열입니다.
verification_uri URI 로그인하기 위해 사용자가 user_code을(를) 사용하여 이동하는 URI입니다.
expires_in int device_code 및 user_code의 만료 전 시간(초)입니다.
interval int 클라이언트에서 폴링 요청 간에 가 대기해야 하는 시간(초)입니다.
message 문자열 사용자를 위한 지침이 포함된 사람이 읽을 수 있는 문자열입니다. 이는 ?mkt=xx-XX 양식의 요청에 쿼리 매개 변수를 포함하고 적절한 언어 문화권 코드를 채워서 지역화할 수 있습니다.

참고 항목

verification_uri_complete 응답 필드는 현재 포함되어 있지 않거나 지원되지 않습니다. 이 사항을 언급하는 이유는 표준을 참조하는 경우 verification_uri_complete가 디바이스 코드 흐름 표준의 선택적 부분으로 나열된 것을 볼 수 있기 때문입니다.

사용자 인증

클라이언트가 수신 user_code 하고 verification_uri나면 값이 표시되고 사용자가 모바일 또는 PC 브라우저를 통해 로그인하도록 지시됩니다.

사용자가 개인 계정 인증하는 /consumers경우 인증 /common 상태를 디바이스로 전송하기 위해 다시 로그인하라는 메시지가 표시됩니다. 디바이스가 사용자의 쿠키에 액세스할 수 없기 때문입니다. 클라이언트가 요청한 권한에 동의하라는 메시지가 표시됩니다. 그러나 인증하는 데 사용되는 회사 또는 학교 계정에는 적용되지 않습니다.

사용자가 verification_uri에서 인증하는 동안 클라이언트는 device_code을(를) 사용하여 요청된 토큰에 대한 /token 엔드포인트를 폴링해야 합니다.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
매개 변수 필수 설명
tenant 필수 초기 요청에 사용된 것과 동일한 테넌트 또는 테넌트 별칭입니다.
grant_type Required urn:ietf:params:oauth:grant-type:device_code이어야 합니다.
client_id Required 초기 요청에 사용된 client_id과(와) 일치해야 합니다.
device_code Required 디바이스 권한 요청에서 반환된 device_code입니다.

예상 오류

디바이스 코드 흐름은 폴링 프로토콜이므로 사용자 인증을 완료하기 전에 클라이언트에 제공된 오류가 예상되어야 합니다.

오류 설명 클라이언트 작업
authorization_pending 사용자가 아직 인증을 완료하지 않았지만 흐름을 취소하지 않았습니다. 최소 interval초 후에 요청을 반복하세요.
authorization_declined 일반 사용자가 권한 요청을 거부했습니다. 폴링을 중지하고 인증되지 않은 상태로 되돌립니다.
bad_verification_code /token 엔드포인트로 보낸 device_code가 인식되지 않았습니다. 클라이언트가 요청에서 올바른 device_code을(를) 보내는지 확인하세요.
expired_token expires_in 값이 초과되었으며 device_code를 사용하여 인증을 더 이상 사용할 수 없습니다. 폴링을 중지하고 인증되지 않은 상태로 되돌립니다.

성공적인 인증 응답

성공적인 토큰 응답은 다음과 같습니다.

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
매개 변수 서식 설명
token_type 문자열 항상 Bearer입니다.
scope 공백으로 구분된 문자열 액세스 토큰이 반환된 경우 이는 액세스 토큰이 유효한 범위를 나열합니다.
expires_in int 포함된 액세스 토큰이 유효한 시간(초)입니다.
access_token 불투명 문자열 요청된 범위에 대해 발급되었습니다.
id_token JWT 원래 scope 매개 변수에 openid 범위가 포함된 경우에 발급됩니다.
refresh_token 불투명 문자열 원래 scope 매개 변수에 offline_access가 포함된 경우에 발급됩니다.

새로 고침 토큰은 OAuth 코드 흐름 문서에 설명된 동일한 흐름을 사용하여 새 액세스 토큰과 새로 고침 토큰을 가져올 수 있습니다.

Warning

코드에서 이 예제의 토큰을 포함하여 소유하지 않은 API에 대한 토큰을 확인하거나 읽으려고 시도하지 마세요. Microsoft 서비스 토큰은 JWT로 유효성을 검사하지 않는 특수 형식을 사용할 수 있으며 소비자(Microsoft 계정) 사용자에 대해 암호화될 수도 있습니다. 토큰 읽기는 유용한 디버깅 및 학습 도구이지만 코드에서 이에 대한 종속성을 취하거나 제어하는 API용이 아닌 토큰에 대한 세부 사항을 가정하지 마세요.