다음을 통해 공유

Microsoft ID 플랫폼 및 OAuth 2.0 리소스 소유자 암호 자격 증명

  • 아티클

Microsoft ID 플랫폼은 OAuth 2.0 ROPC(리소스 소유자 암호 자격 증명) 권한 부여지원합니다. 이를 통해 애플리케이션은 암호를 직접 처리하여 사용자에 로그인할 수 있습니다. 이 문서에서는 애플리케이션의 프로토콜에 대해 직접 프로그래밍하는 방법을 설명합니다. 가능하면 지원되는 Microsoft 인증 라이브러리(MSAL)를 사용하여 토큰을 획득하고 보안 웹 API를 호출하는 것이 좋습니다. MSAL 사용하는샘플 앱도 살펴보세요.

경고

Microsoft는 ROPC 흐름을 사용하지 않도록 권장합니다. 이는 MFA(다단계 인증)와 호환되지 않습니다. 대부분의 시나리오에서는 보다 안전한 대안을 사용할 수 있으며 권장됩니다. 이 흐름은 애플리케이션에 대한 신뢰 수준이 매우 높고 다른 흐름에 없는 위험을 수반합니다. 더 안전한 흐름이 실행 가능하지 않은 경우에만 이 흐름을 사용해야 합니다.

중요하다

  • Microsoft ID 플랫폼은 개인 계정이 아닌 Microsoft Entra 테넌트 내에서 ROPC 권한 부여만 지원합니다. 즉, 테넌트별 엔드포인트(https://login.microsoftonline.com/{TenantId_or_Name}) 또는 organizations 엔드포인트를 사용해야 합니다.
  • Microsoft Entra 테넌트에 초대된 개인 계정은 ROPC 흐름을 사용할 수 없습니다.
  • 암호가 없는 계정은 ROPC로 로그인할 수 없습니다. 즉, SMS 로그인, FIDO 및 Authenticator 앱과 같은 기능이 해당 흐름에서 작동하지 않습니다. 앱 또는 사용자에게 이러한 기능이 필요한 경우 ROPC 이외의 권한 부여 유형을 사용합니다.
  • 사용자가 MFA(다단계 인증) 사용하여 애플리케이션에 로그인해야 하는 경우 대신 차단됩니다.
  • ROPC는 하이브리드 ID 페더레이션 시나리오에서 지원되지 않습니다(예: 온-프레미스 계정을 인증하는 데 사용되는 Microsoft Entra ID 및 AD FS). 사용자가 온-프레미스 ID 공급자로 전체 페이지로 리디렉션되는 경우 Microsoft Entra ID는 해당 ID 공급자에 대해 사용자 이름 및 암호를 테스트할 수 없습니다. 그러나 통과 인증 ROPC에서 지원됩니다.
  • 하이브리드 ID 페더레이션 시나리오의 예외는 다음과 같습니다. AllowCloudPasswordValidation TRUE로 설정된 홈 영역 검색 정책을 사용하면 온-프레미스 암호가 클라우드에 동기화될 때 ROPC 흐름이 페더레이션된 사용자에게 작동할 수 있습니다. 자세한 내용은 레거시 애플리케이션 페더레이션된 사용자의 직접 ROPC 인증 사용참조하세요.
  • 선행 또는 후행 공백이 있는 암호는 ROPC 흐름에서 지원되지 않습니다.

ROPC에서 마이그레이션하는 방법

MFA가 더 널리 보급됨에 따라 일부 Microsoft 웹 API는 MFA 요구 사항을 통과한 경우에만 액세스 토큰을 수락합니다. ROPC를 사용하는 애플리케이션 및 테스트 리그는 잠깁니다. Microsoft Entra는 토큰을 발급하지 않거나 리소스가 요청을 거부합니다.

ROPC를 사용하여 토큰을 획득하여 보호된 다운스트림 API를 호출하는 경우 보안 토큰 획득 전략으로 마이그레이션합니다.

사용자 컨텍스트를 사용할 수 있는 경우

최종 사용자가 리소스에 액세스해야 하는 경우 대신 작동하는 클라이언트 애플리케이션은 대화형 인증 형식을 사용해야 합니다. 최종 사용자는 브라우저에서 메시지가 표시될 때만 MFA에 대해 이의를 제기할 수 있습니다.

  • 웹 애플리케이션의 경우:
  • 웹 API는 브라우저를 표시할 수 없습니다. 대신 클라이언트 애플리케이션에 다시 챌린지를 반환해야 합니다. 자세한 내용은 Web API 및 웹 API 까다로운 사용자를 참조하세요.
  • 데스크톱 애플리케이션은 브로커 기반 인증을 사용해야 합니다. 브로커는 브라우저 기반 인증을 사용하므로 MFA를 적용하고 가능한 가장 안전한 상태를 사용하도록 설정할 수 있습니다.
  • 또한 Broker(Authenticator, 회사 포털) 기반 인증을 사용하도록 모바일 애플리케이션을 구성해야 합니다.

사용자 컨텍스트를 사용할 수 없는 경우

사용자 컨텍스트가 포함되지 않지만 제한되지 않는 시나리오의 예는 다음과 같습니다.

  • CI 파이프라인의 일부로 실행되는 스크립트입니다.
  • 사용자 세부 정보 없이 자신을 대신하여 리소스를 호출해야 하는 서비스입니다.

애플리케이션 개발자는 디먼 샘플설명된 서비스 주체 인증사용해야 합니다. MFA는 서비스 주체에 적용되지 않습니다.

서비스 주체로 인증하는 방법에는 여러 가지가 있습니다.

  • 앱이 Azure 인프라에서 실행되는 경우 관리 ID사용합니다. 관리 ID는 비밀 및 인증서를 유지 관리하고 회전하는 오버헤드를 제거합니다.
  • 앱이 GitHub와 같은 다른 OAuth2 규격 ID 공급자가 관리하는 시스템에서 실행되는 경우 페더레이션 ID 자격 증명 사용합니다.
  • 관리 ID 또는 페더레이션 ID를 사용할 수 없는 경우 인증서 자격 증명사용합니다.

경고

사용자 컨텍스트를 사용할 수 있는 경우 서비스 주체 인증을 사용하지 마세요. 앱 전용 액세스는 기본적으로 높은 권한이며, 종종 테넌트 전체 액세스 권한을 부여하고 악의적인 행위자가 모든 사용자의 고객 데이터에 액세스할 수 있도록 허용합니다.

프로토콜 다이어그램

다음 다이어그램은 ROPC 흐름을 보여줍니다.

리소스 소유자 암호 자격 증명 흐름다이어그램

권한 부여 요청

ROPC 흐름은 단일 요청입니다. 클라이언트 ID 및 사용자의 자격 증명을 ID 공급자로 보내고 그 대가로 토큰을 받습니다. 클라이언트는 사용자의 UPN(전자 메일 주소) 및 암호를 요청해야 합니다. 요청이 성공한 직후 클라이언트는 사용자의 자격 증명을 메모리에서 안전하게 삭제해야 합니다. 저장해서는 안 됩니다.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password
매개 변수 조건 설명
tenant 필수 사용자를 로그인할 디렉터리 테넌트입니다. 테넌트는 GUID 또는 친숙한 이름 형식일 수 있습니다. 그러나 해당 매개 변수는 common 또는 consumers설정할 수 없지만 organizations설정할 수 있습니다.
client_id 필수 Microsoft Entra 관리 센터 - 앱 등록 페이지에서 당신의 앱에 할당된 애플리케이션(클라이언트) ID입니다.
grant_type 필수 password설정해야 합니다.
username 필수 사용자의 전자 메일 주소입니다.
password 필수 사용자의 암호입니다.
scope 권장 앱에 필요한 범위또는 권한의 공백으로 구분된 목록입니다. 대화형 흐름에서 관리자 또는 사용자는 이러한 범위에 미리 동의해야 합니다.
client_secret 필요한 경우가 있습니다. 앱이 공용 클라이언트인 경우 client_secret 또는 client_assertion 포함할 수 없습니다. 앱이 기밀 클라이언트인 경우 앱이 포함되어야 합니다.
client_assertion 필요한 경우가 있습니다. 인증서를 사용하여 생성된 다른 형태의 client_secret. 자세한 내용은 인증서 자격 증명을 참조하세요.

성공적인 인증 응답

다음 예제에서는 성공적인 토큰 응답을 보여줍니다.

{
    "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 Code 흐름 설명서에 설명된 것과 동일한 방법을 사용하여 새 액세스 토큰과 새로 고침 토큰을 획득할 수 있습니다.

경고

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

오류 응답

사용자가 올바른 사용자 이름 또는 암호를 제공하지 않았거나 클라이언트가 요청된 동의를 받지 못한 경우 인증이 실패합니다.

오류 묘사 클라이언트 작업
invalid_grant 인증에 실패했습니다. 자격 증명이 잘못되었거나 요청된 범위에 대한 동의가 클라이언트에 없습니다. 범위가 부여되지 않으면 consent_required 오류가 반환됩니다. 이 오류를 해결하려면 클라이언트가 웹 보기 또는 브라우저를 사용하여 사용자를 대화형 프롬프트로 보내야 합니다.
invalid_request 요청이 잘못 생성되었습니다. 권한 부여 유형은 /common 또는 /consumers 인증 컨텍스트에서 지원되지 않습니다. 대신 /organizations 또는 테넌트 ID를 사용합니다.

더 알아보세요

ROPC 흐름의 예제 구현은 GitHub의 .NET 콘솔 애플리케이션 코드 샘플을 참조하세요.