MSAL의 인증 흐름 지원

  • 아티클

MSAL(Microsoft 인증 라이브러리)은 다양한 애플리케이션 형식 및 시나리오에서 사용할 수 있는 여러 권한 부여 및 관련 토큰 흐름을 지원합니다.

인증 흐름 사용 지원되는 애플리케이션 유형
인증 코드 사용자 로그인 및 사용자를 대신하여 웹 API에 액세스합니다. 데스크톱
모바일
단일 페이지 앱(SPA)(PKCE 필요)
웹
클라이언트 자격 증명 애플리케이션 자체의 ID를 사용하여 웹 API에 액세스합니다. 일반적으로 사용자 상호 작용이 필요 없는 서버 간 통신 및 자동화된 스크립트에 사용됩니다. 디먼
디바이스 코드 스마트 TV 및 IoT 디바이스와 같이 입력이 제한된 디바이스에서 사용자를 대신하여 웹 API에 로그인하고 액세스합니다. CLI(명령줄 인터페이스) 애플리케이션에서도 사용됩니다. Desktop, Mobile
암시적 부여 사용자 로그인 및 사용자를 대신하여 웹 API에 액세스합니다. 암시적 허용 흐름은 더 이상 권장되지 않습니다. 대신 PKCE와 함께 인증 코드를 사용합니다. * SPA(단일 페이지 앱)
* 웹
OBO(On-Behalf-Of) 사용자를 대신하여 "업스트림" 웹 API에서 "다운스트림" 웹 API로 액세스합니다. 사용자의 ID와 위임된 권한은 업스트림 API에서 다운스트림 API로 전달됩니다. 웹 API
사용자 이름/암호(ROPC) 암호를 직접 처리하여 애플리케이션에 사용자가 로그인할 수 있도록 허용합니다. ROPC 흐름은 권장되지 않습니다. Desktop, Mobile
IWA(Windows 통합 인증) 도메인 또는 Microsoft Entra 조인된 컴퓨터의 애플리케이션에서 사용자의 UI 상호 작용 없이 자동으로 토큰을 획득할 수 있습니다. Desktop, Mobile

토큰

애플리케이션은 하나 이상의 인증 흐름을 사용할 수 있습니다. 각 흐름은 인증, 권한 부여 및 토큰 새로 고침에 특정 토큰 형식을 사용하고 일부는 인증 코드도 사용합니다.

인증 흐름 또는 작업 필요 ID 토큰 액세스 토큰 새로 고침 토큰 인증 코드
인증 코드 흐름 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다. 인증 흐름은 새로 고침 토큰에 대해 작동합니다. 권한 부여 코드가 작동합니다.
클라이언트 자격 증명 인증 흐름은 액세스 토큰에 대해 작동합니다. (앱 전용)
디바이스 코드 흐름 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다. 인증 흐름은 새로 고침 토큰에 대해 작동합니다.
암시적 흐름 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다.
On-Behalf-Of 흐름 액세스 토큰 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다. 인증 흐름은 새로 고침 토큰에 대해 작동합니다.
사용자 이름/암호(ROPC) 사용자 이름, 암호 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다. 인증 흐름은 새로 고침 토큰에 대해 작동합니다.
하이브리드 OIDC 흐름 ID 토큰에 대해 인증 흐름이 작동합니다. 권한 부여 코드가 작동합니다.
새로 고침 토큰 상환 새로 고침 토큰 ID 토큰에 대해 인증 흐름이 작동합니다. 인증 흐름은 액세스 토큰에 대해 작동합니다. 인증 흐름은 새로 고침 토큰에 대해 작동합니다.

대화형 및 비대화형 인증

이러한 흐름 중 몇 가지는 대화형 토큰 획득 및 비대화형 토큰 획득을 모두 지원합니다.

  • 대화형 - 권한 부여 서버에서 사용자에게 입력하라는 메시지가 표시될 수 있습니다. 예를 들어 로그인하거나, MFA(다단계 인증)를 수행하거나, 더 많은 리소스 액세스 권한에 대한 동의를 부여합니다.
  • 비대화형(자동) - 사용자에게 입력하라는 메시지가 표시되지 않을 수 있습니다. "자동" 토큰 획득이라고도 하는 애플리케이션은 권한 부여 서버가 사용자에게 입력을 요청하지 않을 방법을 사용하여 토큰을 얻으려고 합니다.

MSAL 기반 애플리케이션은 먼저 토큰을 자동으로 획득하려고 시도하고 비대화형 시도가 실패한 경우에만 대화형 방법으로 대체해야 합니다. 이 패턴에 대한 자세한 내용은 MSAL(Microsoft 인증 라이브러리)을 사용하여 토큰 획득 및 캐싱을 참조하세요.

인증 코드

웹앱, SPA(단일 페이지 앱), 네이티브(모바일 및 데스크톱) 앱에서 OAuth 2.0 인증 코드 부여를 사용하여 웹 API와 같은 보호된 리소스에 액세스할 수 있습니다.

사용자가 웹 애플리케이션에 로그인하면 애플리케이션은 웹 API를 호출하기 위해 액세스 토큰으로 교환할 수 있는 인증 코드를 받습니다.

다음 다이어그램에서 애플리케이션은 다음을 수행합니다.

  1. 액세스 토큰에 대해 교환된 권한 부여 코드를 요청합니다.
  2. 액세스 토큰을 사용하여 웹 API 호출, Microsoft Graph

권한 부여 코드 흐름의 다이어그램.

인증 코드에 대한 제약 조건

  • 단일 페이지 애플리케이션에는 인증 코드 부여 흐름을 사용할 때 PKCE(Proof Key for Code Exchange)가 필요합니다. PKCE는 MSAL에서 지원됩니다.

  • OAuth 2.0 사양을 사용하려면 인증 코드를 사용하여 액세스 토큰을 한 번만 사용해야 합니다.

    동일한 인증 코드로 액세스 토큰을 여러 번 얻으려고 하면 Microsoft ID 플랫폼에서 다음과 유사한 오류가 반환됩니다. 일부 라이브러리 및 프레임워크는 자동으로 인증 코드를 요청하며 이러한 경우 수동으로 코드를 요청하면 이 오류가 발생합니다.

    AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

클라이언트 자격 증명

OAuth 2.0 클라이언트 자격 증명 흐름을 사용하면 애플리케이션의 ID를 사용하여 웹 호스팅 리소스에 액세스할 수 있습니다. 이 유형의 권한 부여는 일반적으로 사용자의 직접적인 상호 작용 없이 백그라운드에서 실행해야 하는 서버 간 상호 작용에 사용됩니다. 이러한 유형의 애플리케이션은 종종 디먼 또는 서비스 계정이라고 합니다.

클라이언트 자격 증명 부여 흐름은 사용자를 가장하는 대신 다른 웹 서비스를 호출할 때 웹 서비스(기밀 클라이언트)가 자체 자격 증명을 사용하여 인증하도록 허용합니다. 이 시나리오에서 클라이언트는 일반적으로 중간 계층 웹 서비스, 데몬 서비스 또는 웹 사이트입니다. 더 높은 수준의 보증을 위해 Microsoft ID 플랫폼은 호출 서비스가 자격 증명으로 인증서(공유 비밀 대신)를 사용할 수 있도록 합니다.

애플리케이션 비밀

다음 다이어그램에서 애플리케이션은 다음을 수행합니다.

  1. 애플리케이션 비밀 또는 암호 자격 증명을 사용하여 토큰 획득
  2. 토큰을 사용하여 리소스 요청

암호가 있는 기밀 클라이언트의 다이어그램.

인증서

다음 다이어그램에서 애플리케이션은 다음을 수행합니다.

  1. 인증서 자격 증명을 사용하여 토큰 획득
  2. 토큰을 사용하여 리소스 요청

인증서가 있는 기밀 클라이언트의 다이어그램.

이러한 클라이언트 자격 증명은 다음과 같아야 합니다.

  • Microsoft Entra ID에 등록됨
  • 코드에서 기밀 클라이언트 애플리케이션 개체를 생성할 때 전달됩니다.

클라이언트 자격 증명에 대한 제약 조건

기밀 클라이언트 흐름은 Android, iOS 또는 UWP와 같은 모바일 플랫폼에서 지원되지 않습니다. 모바일 애플리케이션은 자격 증명의 기밀성을 보장할 수 없는 공용 클라이언트 애플리케이션으로 간주됩니다.

디바이스 코드

OAuth 2.0 디바이스 코드 흐름을 사용하면 사용자가 스마트 TV, IoT 디바이스 및 프린터와 같은 입력이 제한된 디바이스에 로그인할 수 있습니다. Microsoft Entra ID를 사용한 대화형 인증에는 웹 브라우저가 필요합니다. 디바이스 또는 운영 체제에서 웹 브라우저를 제공하지 않는 경우 사용자는 디바이스 코드 흐름을 통해 컴퓨터 또는 휴대폰 같은 다른 디바이스를 사용하여 대화형으로 로그인할 수 있습니다.

애플리케이션은 디바이스 코드 흐름을 사용하여 이러한 디바이스 및 운영 체제용으로 설계된 2단계 프로세스를 통해 토큰을 가져옵니다. 이러한 애플리케이션의 예로는 IoT 디바이스 또는 CLI(명령줄 인터페이스) 도구에서 실행되는 애플리케이션이 있습니다.

다음 다이어그램대로 작업이 수행됩니다.

  1. 사용자 인증이 필요할 때마다 앱은 코드를 제공하고, 다른 디바이스(예: 인터넷에 연결된 스마트폰)를 사용하여 URL(예: https://microsoft.com/devicelogin)로 이동하도록 사용자에게 요청합니다. 그런 다음 사용자에게 코드를 입력하라는 메시지가 표시되고 필요한 경우 동의 프롬프트 및 다단계 인증을 비롯한 일반적인 인증 환경을 진행합니다.
  2. 인증에 성공하면 명령줄 앱은 백 채널을 통해 필요한 토큰을 수신하고 이를 사용하여 필요한 웹 API 호출을 수행합니다.

디바이스 코드 흐름의 다이어그램.

디바이스 코드에 대한 제약 조건

  • 디바이스 코드 흐름은 공용 클라이언트 애플리케이션에만 사용할 수 있습니다.
  • MSAL에서 공용 클라이언트 애플리케이션을 초기화할 때 다음 권한 형식 중 하나를 사용합니다.
    • 테넌트: https://login.microsoftonline.com/{tenant}/, 테 {tenant} 넌트 ID 또는 테넌트에 연결된 do기본 이름입니다.
    • 회사 및 학교 계정: https://login.microsoftonline.com/organizations/.

암시적 허용

암시적 권한 부여 흐름은 클라이언트 쪽 SPA(단일 페이지 애플리케이션)에 대한 기본 설정 및 보다 안전한 토큰 부여 흐름으로 PKCE를 사용하여 권한 부여 코드 흐름으로 대체되었습니다. 암시적 허용 흐름을 더 이상 사용하지 않는 것이 좋습니다. SPA를 빌드하는 경우 대신 PKCE와 함께 인증 코드 흐름을 사용합니다.

JavaScript(Angular, Vue.js 또는 React.js와 같은 프레임워크 포함)로 작성된 단일 페이지 웹앱은 서버에서 다운로드되고 해당 코드는 브라우저에서 직접 실행됩니다. 클라이언트 쪽 코드는 웹 서버가 아닌 브라우저에서 실행되기 때문에 기존의 서버 쪽 웹 애플리케이션과 보안 특성이 다릅니다. 인증 코드 흐름에 대한 PKCE(Proof Key for Code Exchange)를 사용할 수 있기 전에는 SPA에서 액세스 토큰을 가져올 때 응답성과 효율성을 개선하기 위해 암시적 허용 흐름을 사용했습니다.

OAuth 2.0 암시적 권한 부여 흐름을 사용하면 앱이 백 엔드 서버 자격 증명 교환을 수행하지 않고도 Microsoft ID 플랫폼 액세스 토큰을 가져올 수 있습니다. 암시적 허용 흐름을 통해 앱은 사용자 에이전트(일반적으로 웹 브라우저)에서 다운로드 및 실행하는 JavaScript 코드 내에서 사용자 로그인, 세션 유지, 다른 웹 API용 토큰 가져오기를 수행할 수 있습니다.

암시적 허용 흐름 다이어그램

암시적 허용에 대한 제약 조건

암시적 허용 흐름에는 Electron 또는 React Native와 같은 플랫폼 간 JavaScript 프레임워크를 사용하는 애플리케이션 시나리오가 포함되지 않습니다. 이와 같은 플랫폼 간 프레임워크에는 실행되는 네이티브 데스크톱 및 모바일 플랫폼과의 상호 작용을 위한 추가 기능이 필요합니다.

암시적 흐름 모드로 발급된 토큰은 URL을 통해 브라우저로 반환되었기 때문에 길이 제한이 있습니다(response_mode가 query 또는 fragment인 경우). 어떤 브라우저는 브라우저 표시줄에 입력하는 URL 길이에 제한을 두며 너무 긴 경우 실패합니다. 따라서 이러한 암시적 흐름 토큰은 groups 또는 wids 클레임을 포함하지 않습니다.

OBO(On-Behalf-Of)

OAuth 2.0 대신 인증 흐름 흐름은 애플리케이션이 다른 서비스 또는 웹 API를 호출해야 하는 서비스 또는 웹 API를 호출할 때 사용됩니다. 요청 체인을 통해 위임된 사용자 ID 및 사용 권한을 전파하는 개념입니다. 중간 계층 서비스가 다운스트림 서비스에 대해 인증된 요청을 수행하도록 하려면 사용자를 대신하여 Microsoft ID 플랫폼에서 액세스 토큰을 보호해야 합니다.

다음 다이어그램대로 작업이 수행됩니다.

  1. 애플리케이션은 웹 API에 대한 액세스 토큰을 획득합니다.
  2. 클라이언트(웹, 데스크톱, 모바일 또는 단일 페이지 애플리케이션)는 HTTP 요청의 인증 헤더에 액세스 토큰을 전달자 토큰으로 추가하여 보호된 웹 API를 호출합니다. 웹 API는 사용자를 인증합니다.
  3. 클라이언트에서 웹 API를 호출하면 웹 API는 사용자를 대신해 다른 토큰을 요청합니다.
  4. 보호된 웹 API는 이 토큰을 사용하여 사용자 대신 다운스트림 웹 API를 호출합니다. 웹 API는 나중에 다른 다운스트림 API에 대한 토큰을 요청할 수도 있습니다(계속해서 같은 사용자를 대신함).

On-Behalf-of 흐름의 다이어그램.

사용자 이름/암호(ROPC)

Warning

ROPC(리소스 소유자 암호 자격 증명) 흐름은 권장되지 않습니다. ROPC에는 높은 수준의 신뢰 및 자격 증명 노출이 필요합니다. 보다 안전한 흐름을 사용할 수 없는 경우에만 ROPC를 사용합니다. 자세한 내용은 What’s the solution to the growing problem of passwords?(늘어나는 암호 문제에 대한 해결책)를 참조하세요.

OAuth 2.0 ROPC(리소스 소유자 암호 자격 증명) 부여를 사용하면 애플리케이션이 암호를 직접 처리하여 사용자를 로그인할 수 있습니다. 데스크톱 애플리케이션에서 사용자 이름/암호 흐름을 사용하여 토큰을 자동으로 가져올 수 있습니다. 애플리케이션을 사용하는 경우 UI가 필요하지 않습니다.

DevOps와 같은 일부 애플리케이션 시나리오에서는 ROPC가 유용할 수 있지만 사용자 로그인을 위한 대화형 UI를 제공하는 모든 애플리케이션에서는 ROPC를 피해야 합니다.

다음 다이어그램에서 애플리케이션은 다음을 수행합니다.

  1. ID 공급자에게 사용자 이름 및 암호를 전송하여 토큰을 획득합니다.
  2. 토큰을 사용하여 웹 API 호출

사용자 이름/암호 흐름의 다이어그램

Windows 도메인에 조인된 컴퓨터에서 자동으로 토큰을 가져오려면 ROPC 대신 IWA(Windows 통합 인증)를 권장합니다. 다른 시나리오의 경우 디바이스 코드 흐름을 사용합니다.

ROPC에 대한 제약 조건

ROPC 흐름을 사용하는 애플리케이션에는 다음 제약 조건이 적용됩니다.

  • Single Sign-On은 지원되지 않습니다.
  • MFA(다단계 인증)는 지원되지 않습니다.
    • 이 흐름을 사용하기 전에 테넌트 관리자에게 확인합니다. MFA는 일반적으로 사용되는 기능입니다.
  • 조건부 액세스는 지원되지 않습니다.
  • ROPC는 회사 및 학교 계정에서만 적용됩니다.
  • 개인 MSA(개인 Microsoft 계정)는 ROPC에서 지원되지 않습니다.
  • ROPC는 .NET 데스크톱 및 ASP.NET Core 애플리케이션에서 지원 됩니다.
  • ROPC는 UWP(유니버설 Windows 플랫폼) 애플리케이션에서 지원되지 않습니다.
  • Azure AD B2C의 ROPC는 로컬 계정에 대해서만 지원됩니다.

IWA(Windows 통합 인증)

MSAL은 도메인에 가입되거나 Microsoft Entra에 가입된 Windows 컴퓨터에서 실행되는 데스크톱 및 모바일 애플리케이션에 대해 IWA(Windows 통합 인증)를 지원합니다. 이러한 애플리케이션은 IWA를 사용하여 사용자의 UI 상호 작용 없이도 토큰을 자동으로 획득할 수 있습니다.

다음 다이어그램에서 애플리케이션은 다음을 수행합니다.

  1. 통합 Windows 인증 사용하여 토큰을 획득합니다.
  2. 토큰을 사용하여 리소스 요청

통합 Windows 인증 다이어그램

IWA에 대한 제약 조건

호환성

IWA(통합 Windows 인증)는 .NET 데스크톱, .NET 및 Windows 유니버설 플랫폼 앱에 대해 사용하도록 설정됩니다.

IWA는 AD FS 페더레이션 사용자(Active Directory에서 만들어지고 Microsoft Entra ID에서 지원하는 사용자)만 지원합니다. Active Directory 지원 없이 Microsoft Entra ID에서 직접 만들어진 사용자(관리형 사용자)는 이 인증 흐름을 사용할 수 없습니다.

MFA(다단계 인증)

Microsoft Entra 테넌트에서 MFA를 사용하도록 설정하고 Microsoft Entra ID에서 MFA 챌린지를 발행하면 IWA의 비대화형(자동) 인증이 실패할 수 있습니다. IWA가 실패하면 앞에서 설명한 대로 대화형 인증 방법으로 대체해야 합니다.

Microsoft Entra ID는 AI를 사용하여 2단계 인증이 필요한 시기를 결정합니다. 2단계 인증은 일반적으로 사용자가 다른 국가/지역에서 로그인할 때, VPN을 사용하지 않고 회사 네트워크에 연결되어 있을 때, 때로는 VPN을 통해 연결된 때 필요합니다. MFA의 구성 및 챌린지 빈도는 개발자가 제어할 수 없기 때문에 애플리케이션은 IWA의 자동 토큰 획득 실패를 정상적으로 처리해야 합니다.

기관 URI 제한

공용 클라이언트 애플리케이션을 구성할 때 전달되는 인증 기관은 다음 중 하나여야 합니다.

  • https://login.microsoftonline.com/{tenant}/ - 이 권한은 로그인 대상 그룹이 지정된 Microsoft Entra 테넌트의 사용자로 제한된 단일 테넌트 애플리케이션을 나타냅니다. {tenant} 값은 GUID 형식의 테넌트 ID 또는 테넌트와 연결된 도메인 이름일 수 있습니다.
  • https://login.microsoftonline.com/organizations/ - 이 권한은 로그인 대상 그룹이 Microsoft Entra 테넌트의 사용자인 다중 테넌트 애플리케이션을 나타냅니다.

개인 MSA(Microsoft 계정)가 IWA에서 지원되지 않기 때문에 권한 값에는 /common 또는 /consumers가 포함되어서는 안 됩니다.

동의 요구 사항

IWA는 자동 흐름이기 때문에:

  • 애플리케이션의 사용자가 사전에 애플리케이션 사용에 동의했어야 합니다.

    OR

  • 테넌트 관리자는 테넌트의 모든 사용자에게 사전에 애플리케이션 사용 동의를 받아야 합니다.

두 요구 사항 중 하나를 충족하려면 다음 작업 중 하나가 완료되어야 합니다.

  • 애플리케이션 개발자가 Azure Portal에서 직접 부여를 선택했습니다.
  • 테넌트 관리자가 Azure Portal에 있는 앱 등록의 API 권한 탭에서 {테넌트 도메인}에 대한 관리자 동의 권한 부여/해지를 선택했습니다. 웹 API 액세스 권한 추가를 참조하세요.
  • 사용자가 애플리케이션에 동의할 수 있는 방법을 제공했습니다. 사용자 동의를 참조하세요.
  • 테넌트 관리자가 애플리케이션에 동의할 수 있는 방법을 제공했습니다. 관리주제 동의를 참조하세요.

동의에 대한 자세한 내용은 권한 및 동의를 참조하세요.

다음 단계

이러한 흐름에 사용되는 토큰을 획득하고 캐싱하는 방법에 대해 알아봅니다.

MSAL(Microsoft 인증 라이브러리)을 사용하여 토큰 획득 및 캐싱