Microsoft ID 플랫폼 및 OAuth 2.0 인증 코드 흐름
OAuth 2.0 인증 코드 권한 부여 유형 또는 인증 코드 흐름을 사용하면 클라이언트 애플리케이션에서 웹 API와 같은 보호된 리소스에 대한 권한 있는 액세스를 얻을 수 있습니다. 인증 코드 흐름에는 권한 부여 서버(Microsoft ID 플랫폼)에서 애플리케이션으로 다시 리디렉션하도록 지원하는 사용자 에이전트가 필요합니다. 예를 들어 사용자가 앱에 로그인하고 데이터에 액세스하기 위해 운영하는 웹 브라우저, 데스크톱 또는 모바일 애플리케이션입니다.
이 문서에서는 흐름을 실행하기 위해 원시 HTTP 요청을 수동으로 만들고 발급하는 경우에만 필요한 하위 수준의 프로토콜 세부 정보를 설명합니다. 이는 권장되지 않습니다. 대신 Microsoft에서 빌드하고 지원하는 인증 라이브러리를 사용하여 앱에서 보안 토큰을 가져오고 보호된 웹 API를 호출합니다.
인증 코드 흐름을 지원하는 애플리케이션
PKCE(Proof Key for Code Exchange) 및 OIDC(OpenID Connect)와 페어링되는 인증 코드 흐름을 사용하여 다음 유형의 앱에서 액세스 토큰 및 ID 토큰을 가져옵니다.
프로토콜 세부 정보
OAuth 2.0 인증 코드 흐름은 OAuth 2.0 사양의 섹션 4.1에서 설명합니다. OAuth 2.0 인증 코드 흐름을 사용하는 앱은 access_token을 획득하여 Microsoft ID 플랫폼(일반적으로 API)에서 보호하는 리소스에 대한 요청에 포함합니다. 또한 앱에서 새로 고침 메커니즘을 사용하여 이전에 인증된 엔터티에 대한 새 ID 및 액세스 토큰을 요청할 수도 있습니다.
이 다이어그램에서는 인증 흐름의 개략적인 보기를 보여 줍니다.
SPA(단일 페이지 앱)에 대한 리디렉션 URI
인증 코드 흐름을 사용하는 SPA에 대한 리디렉션 URI에는 특별한 구성이 필요합니다.
- PKCE 및 CORS(원본 간 리소스 공유)를 사용하여 인증 코드 흐름을 지원하는 리디렉션 URI 추가: 리디렉션 URI: 인증 코드 흐름을 사용하는 MSAL.js 2.0의 단계를 따릅니다.
- 리디렉션 URI 업데이트: Microsoft Entra 관리 센터에서 애플리케이션 매니페스트 편집기를 사용하여 URI 리디렉션을
type에서spa로 설정합니다.
spa 리디렉션 유형은 이전 버전의 암시적 흐름과 호환됩니다. 현재 암시적 흐름을 사용하여 토큰을 가져오는 앱은 이슈 없이 spa 리디렉션 URI 형식으로 이동하고 암시적 흐름을 계속 사용할 수 있습니다. 이전 버전과의 호환성에도 불구하고 SPA용 PKCE와 함께 인증 코드 흐름을 사용하는 것이 좋습니다.
리디렉션 URI에 대해 CORS를 설정하지 않고 권한 부여 코드 흐름을 사용하면 콘솔에 다음 오류가 표시됩니다.
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
이 경우, 앱 등록을 방문하고 앱의 리디렉션 URI를 spa 형식을 사용하도록 업데이트합니다.
애플리케이션은 비 SPA 흐름(예: 원시 애플리케이션 또는 클라이언트 자격 증명 흐름)에서 spa 리디렉션 URI를 사용할 수 없습니다. Origin 헤더 없이 spa 리디렉션 URI를 사용하면 보안 및 모범 사례를 보장하기 위해 Microsoft ID 플랫폼에서 오류가 반환됩니다. 마찬가지로, Microsoft ID 플랫폼은 Origin 헤더가 있을 경우 모든 흐름에서 클라이언트 자격 증명 사용을 차단하여 브라우저 내에서 비밀이 사용되지 않도록 합니다.
인증 코드 요청
인증 코드 흐름은 클라이언트가 사용자를 /authorize 엔드포인트로 보내는 것으로 시작됩니다. 이 예제 요청에서 클라이언트는 사용자의 openid, offline_access 및 https://graph.microsoft.com/mail.read 권한을 요청합니다.
예를 들어, Directory.ReadWrite.All을 사용하여 조직의 디렉터리에 데이터를 쓰는 것과 같은 일부 권한은 관리자가 제한합니다. 애플리케이션이 조직 사용자에게 이러한 사용 권한 중 하나에 대한 액세스를 요청하는 경우 사용자에게는 앱의 사용 권한에 동의할 권한이 부여되지 않음을 나타내는 오류 메시지가 표시됩니다. 관리자 제한 범위에 대한 액세스를 요청하려면 글로벌 관리자에게 직접 요청해야 합니다. 자세한 내용은 관리자 제한 권한을 참조하세요.
달리 지정하지 않는 한 선택적 매개 변수에 대한 기본값은 없습니다. 그러나 선택적 매개 변수를 생략하는 요청에 대한 기본 동작이 있습니다. 기본 동작은 유일한 현재 사용자를 로그인시키거나, 여러 사용자가 있는 경우 계정 선택기를 표시하거나, 로그인한 사용자가 없는 경우 로그인 페이지를 표시하는 것입니다.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
tenant |
필수 | 요청의 경로에 있는 {tenant} 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 common, organizations, consumers 및 테넌트 ID입니다. 한 테넌트의 사용자를 다른 테넌트로 로그인하는 게스트 시나리오의 경우, 리소스 테넌트로 로그인하려면 테넌트 식별자를 반드시 제공해야 합니다. 자세한 내용은 엔드포인트를 참조하세요. |
client_id |
필수 | Microsoft Entra 관리 센터 – 앱 등록 환경이 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
response_type |
필수 | 인증 코드 흐름에 대한 code를 포함해야 합니다. 하이브리드 흐름을 사용하는 경우 id_token이나 token도 포함할 수 있습니다. |
redirect_uri |
필수 | 앱에서 인증 응답을 보내고 받을 수 있는 앱의 redirect_uri입니다. URL로 인코딩되어야 한다는 점을 제외하고 Microsoft Entra 관리 센터에 등록한 리디렉션 URI 중 하나와 정확히 일치해야 합니다. 원시 앱과 모바일 앱의 경우 권장되는 값 https://login.microsoftonline.com/common/oauth2/nativeclient(포함된 브라우저를 사용하는 앱의 경우) 또는 http://localhost(시스템 브라우저를 사용하는 앱의 경우) 중 하나를 사용해야 합니다. |
scope |
필수 | 사용자가 동의하게 할 공백으로 구분된 범위 목록입니다. 요청의 /authorize 구간에 대해 이 매개 변수는 여러 리소스를 포함할 수 있습니다. 이 값을 사용하면 앱에서 호출하려는 여러 웹 API에 대한 동의를 얻을 수 있습니다. |
response_mode |
권장 | ID 플랫폼이 앱에 요청된 토큰을 반환하는 방법을 지정합니다. 지원되는 값: - query: 액세스 토큰을 요청할 때 기본값입니다. 리디렉션 URI에 코드를 쿼리 문자열 매개 변수로 제공합니다. 암시적 흐름을 사용하여 ID 토큰을 요청할 때는 query 매개 변수가 지원되지 않습니다. - fragment: 암시적 흐름을 사용하여 ID 토큰을 요청할 때 기본값입니다. 코드만 요청하는 경우에도 지원됩니다.- form_post: 리디렉션 URI에 대한 코드가 포함된 POST를 실행합니다. 코드를 요청할 때 지원됩니다. |
state |
권장 | 토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 콘텐츠의 문자열일 수 있습니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 이 값은 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보를 인코딩하는 데에도 사용됩니다. 예를 들어 페이지를 인코딩하거나 해당 페이지가 있는 보기를 인코딩할 수 있습니다. |
prompt |
선택적 | 필요한 사용자 상호 작용 유형을 나타냅니다. 유효한 값은 login, none, consent 및 select_account입니다.- prompt=login은 Single-Sign On을 무효화면서, 사용자가 요청에 자신의 자격 증명을 입력하도록 합니다.- prompt=none은 그 반대입니다. 이는 사용자에게 어떤 대화형 메시지도 표시되지 않도록 합니다. Single Sign-On을 사용하여 요청이 자동으로 완료될 수 없는 경우에 Microsoft ID 플랫폼은 interaction_required 오류를 반환합니다.- prompt=consent는 사용자가 로그인한 후에 OAuth 동의 대화 상자를 트리거하여 앱에 권한을 부여할 것을 사용자에게 요청합니다.- prompt=select_account는 세션의 모든 계정 또는 저장된 계정을 나열하는 계정 선택 환경이나 다른 계정을 모두 사용하도록 선택하는 옵션을 제공하면서 Single Sign-On을 중단시킵니다. |
login_hint |
선택적 | 이 매개 변수를 사용하여 사용자를 위해 로그인 페이지의 사용자 이름 및 이메일 주소 필드를 미리 채울 수 있습니다. 앱은 이전 로그인에서 선택적 클레임을 이미 추출한 login_hint 후 재인증하는 동안 이 매개 변수를 사용할 수 있습니다. |
domain_hint |
선택적 | 포함된 경우, 로그인 페이지를 거친 사용자가 좀 더 효율적인 사용자 경험을 가질 수 있도록 이메일 기반 검색 프로세스를 건너뜁니다. 예를 들어 페더레이션 ID 공급자로 보냅니다. 앱이 이전 로그인 작업에서 tid를 추출하여 재인증 과정에서 이 매개 변수를 사용할 수 있습니다. |
code_challenge |
권장/필수 | PKCE(Proof Key for Code Exchange)를 사용하여 권한 부여 코드를 보호하는 데 사용됩니다. code_challenge_method가 포함되면 필수입니다. 자세한 내용은 PKCE RFC를 참조하세요. 이제 이 매개 변수는 모든 애플리케이션 형식(공개 및 기밀 클라이언트 모두)에 권장되며 권한 부여 코드 흐름을 사용하는 단일 페이지 앱의 Microsoft ID 플랫폼에 필요합니다. |
code_challenge_method |
권장/필수 | code_challenge 매개 변수에 대한 code_verifier를 인코딩하는 데 사용되는 메서드입니다. 이는 S256이어야 하지만, 클라이언트에서 SHA256을 지원할 수 없으면 사양에 따라 plain을 사용할 수 있습니다. 제외할 경우 code_challenge가 포함되면 code_challenge가 일반 텍스트로 간주됩니다. Microsoft ID 플랫폼은 plain 및 S256을 모두 지원합니다. 자세한 내용은 PKCE RFC를 참조하세요. 이 매개 변수는 인증 코드 흐름을 사용하는 단일 페이지 앱에 필요합니다. |
이 시점에서 사용자에게 자격 증명을 입력하고 인증을 완료하라는 메시지가 표시됩니다. Microsoft ID 플랫폼은 사용자가 scope 쿼리 매개 변수에 표시된 사용 권한에 동의했는지도 확인합니다. 사용자가 이러한 사용 권한 중 하나에 동의하지 않은 경우 필요한 사용 권한에 동의하라는 메시지가 표시됩니다. 자세한 내용은 Microsoft ID 플랫폼의 권한 및 동의를 참조하세요.
사용자가 인증하고 동의하면 Microsoft ID 플랫폼이 response_mode 매개 변수에 지정된 방법을 사용하여 표시된 redirect_uri에서 해당 앱에 응답을 반환합니다.
성공적인 응답
이 예제에서는 response_mode=query를 사용한 성공적인 응답을 보여줍니다.
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| 매개 변수 | 설명 |
|---|---|
code |
앱에서 요청한 authorization_code입니다. 앱에서 권한 부여 코드를 사용하여 대상 리소스에 대한 액세스 토큰을 요청할 수 있습니다. 인증 코드는 수명이 매우 짧습니다. 일반적으로 약 10분 후에 만료됩니다. |
state |
state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
ID 토큰을 요청하고 애플리케이션 등록에서 암시적 부여를 사용하도록 설정한 경우 해당 ID 토큰도 받을 수 있습니다. 이 동작을 하이브리드 흐름이라고도 합니다. 이는 ASP.NET 같은 프레임워크에서 사용됩니다.
오류 응답
앱이 적절하게 처리할 수 있도록 redirect_uri 에 오류 응답을 보낼 수도 있습니다.
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| 매개 변수 | 설명 |
|---|---|
error |
오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. 이 오류 부분은 앱이 오류에 적절하게 대응할 수 있도록 제공되지만 오류가 발생한 이유를 자세히 설명하지는 않습니다. |
error_description |
개발자가 인증 오류의 근본 원인을 파악하도록 도울 수 있는 특정 오류 메시지입니다. 이 오류 부분에는 오류가 발생한 이유에 대한 대부분의 유용한 정보가 포함되어 있습니다. |
권한 부여 엔드포인트 오류에 대한 오류 코드
다음 테이블은 오류 응답의 error 매개 변수에 반환될 수 있는 여러 오류 코드를 설명합니다.
| 오류 코드 | 설명 | 클라이언트 작업 |
|---|---|---|
invalid_request |
프로토콜 오류(예: 필수 매개 변수 누락). | 요청을 수정하여 다시 제출하십시오. 이 오류는 일반적으로 초기 테스트 중에 발견되는 개발 오류입니다. |
unauthorized_client |
클라이언트 애플리케이션이 인증 코드를 요청할 수 없습니다. | 이 오류는 일반적으로 클라이언트 애플리케이션이 Microsoft Entra ID에 등록되지 않았거나 사용자의 Microsoft Entra 테넌트에 추가되지 않은 경우에 발생합니다. 애플리케이션은 사용자에게 애플리케이션 설치 및 Microsoft Entra ID에 추가에 대한 지침을 묻는 메시지를 표시할 수 있습니다. |
access_denied |
리소스 소유자가 동의 거부 | 클라이언트 응용 프로그램에서 사용자 동의를 받아야만 진행할 수 있다고 알릴 수 있습니다. |
unsupported_response_type |
권한 부여 서버가 요청에 해당 응답 형식을 지원하지 않습니다. | 요청을 수정하여 다시 제출하십시오. 이 오류는 일반적으로 초기 테스트 중에 발견되는 개발 오류입니다. 하이브리드 흐름에서 볼 때 이 오류는 클라이언트 앱 등록에서 ID 토큰 암시적 허용 설정을 사용하도록 설정해야 한다는 신호를 보냅니다. |
server_error |
서버에 예기치 않은 오류가 발생했습니다. | 요청을 다시 시도하십시오. 이러한 오류는 일시적인 상태 때문에 발생할 수 있습니다. 클라이언트 애플리케이션은 일시적 오류로 인해 응답이 지연되었음을 사용자에게 설명할 수 있습니다. |
temporarily_unavailable |
서버가 일시적으로 사용량이 많아 요청을 처리할 수 없습니다. | 요청을 다시 시도하십시오. 클라이언트 애플리케이션이 일시적 상태 때문에 응답이 지연되었음을 사용자에게 설명할 수 있습니다. |
invalid_resource |
대상 리소스가 존재하지 않거나, Microsoft Entra ID에서 찾을 수 없거나, 올바르게 구성되지 않았기 때문에 유효하지 않습니다. | 이 오류는 리소스가 존재하는 경우 테넌트에 구성되지 않았음을 나타냅니다. 애플리케이션은 사용자에게 애플리케이션 설치 및 Microsoft Entra ID에 추가에 대한 지침을 묻는 메시지를 표시할 수 있습니다. |
login_required |
사용자가 너무 많거나 없습니다. | 클라이언트에서 자동 인증(prompt=none)을 요청했지만 단일 사용자를 찾을 수 없습니다. 이 오류는 세션에서 여러 사용자가 활성 상태이거나 사용자가 없음을 의미할 수 있습니다. 이 오류는 선택한 테넌트가 고려됩니다. 예를 들어, 두 개의 Microsoft Entra 계정이 활성화되어 있고 하나의 Microsoft 계정이 있고 consumers를 선택한 경우 자동 인증이 작동합니다. |
interaction_required |
요청을 위해 사용자 상호 작용이 필요합니다. | 다른 인증 단계 또는 동의가 필요합니다. prompt=none을 사용하지 않고 요청을 다시 시도하세요. |
ID 토큰 및 하이브리드 흐름 요청
권한 부여 코드를 사용하기 전에 사용자가 누구인지 알아보려면 일반적으로 애플리케이션이 권한 부여 코드를 요청할 때 ID 토큰도 요청합니다. 이 접근 방식은 OIDC를 OAuth2 승인 코드 흐름과 혼합하므로, 하이브리드 흐름이라고 합니다.
하이브리드 흐름은 코드 사용을 차단하지 않고 사용자를 위해 페이지를 렌더링하는 웹앱, 특히 ASP.NET에서 일반적으로 사용됩니다. 단일 페이지 앱과 기존 웹앱 모두 이 모델에서 대기 시간이 감소하는 혜택을 얻습니다.
하이브리드 흐름은 앞에서 설명한 권한 부여 코드 흐름과 동일하지만 세 가지가 추가되었습니다. 새 범위, 새 response_type 및 새 nonce 쿼리 매개 변수와 같은 ID 토큰을 요청하려면 모두 추가되어야 합니다.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| 업데이트된 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
response_type |
필수 | id_token을 추가하면 애플리케이션이 /authorize 엔드포인트의 응답에서 ID 토큰을 원한다는 것을 서버에 나타냅니다. |
scope |
필수 | ID 토큰의 경우 이 매개 변수는 ID 토큰 범위(openid 및 선택적으로 profile, email)를 포함하도록 업데이트해야 합니다. |
nonce |
필수 | 결과 id_token에 클레임으로 포함되는, 앱에서 생성한 요청에 포함되는 값입니다. 그러면 앱에서 이 값을 확인하여 토큰 재생 공격을 완화할 수 있습니다. 이 값은 일반적으로 요청의 출처를 식별하는 데 사용할 수 있는 임의의 고유 문자열입니다. |
response_mode |
권장 | 결과 토큰을 앱으로 다시 보내는 데 사용해야 하는 메서드를 지정합니다. 기본값은 query 권한 부여 코드에만 해당하지만 fragment 요청에 OpenID 사양에 지정된 대로 포함 id_token response_type 되는 경우입니다. 특히 리디렉션 URI로 사용하는 경우 앱을 사용하는 form_posthttp://localhost 것이 좋습니다. |
fragment를 응답 모드로 사용하면 리디렉션에서 코드를 읽는 웹앱에 문제가 발생합니다. 브라우저는 조각을 웹 서버에 전달하지 않습니다. 이 상황에서 앱은 모든 데이터가 서버로 전송되도록 form_post 응답 모드를 사용해야 합니다.
성공적인 응답
이 예제에서는 response_mode=fragment를 사용한 성공적인 응답을 보여줍니다.
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| 매개 변수 | 설명 |
|---|---|
code |
앱이 요청한 권한 부여 코드입니다. 앱에서 권한 부여 코드를 사용하여 대상 리소스에 대한 액세스 토큰을 요청할 수 있습니다. 권한 부여 코드는 수명이 매우 짧으며, 일반적으로 약 10분 후에 만료됩니다. |
id_token |
암시적 허용을 통해 발급된 사용자의 ID 토큰입니다. 같은 요청에 있는 code의 해시인 특수 c_hash 클레임을 포함합니다. |
state |
state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
액세스 토큰에 대한 코드 사용
모든 기밀 클라이언트는 클라이언트 암호 또는 인증서 자격 증명을 사용할 수 있습니다. 대칭 공유 비밀은 Microsoft ID 플랫폼에서 생성됩니다. 인증서 자격 증명은 개발자가 업로드한 비대칭 키입니다. 자세한 내용은 Microsoft ID 플랫폼 애플리케이션 인증 인증서 자격 증명을 참조하세요.
최상의 보안을 위해 인증서 자격 증명을 사용하는 것이 좋습니다. 원시 애플리케이션 및 단일 페이지 앱을 포함하는 공개 클라이언트는 권한 부여 코드를 사용할 때 비밀 또는 인증서를 사용하지 않아야 합니다. 항상 리디렉션 URI에 애플리케이션 유형이 포함되고 고유해야 합니다.
client_secret를 사용하여 액세스 토큰 요청
authorization_code를 획득하고 사용자가 권한을 부여했으므로 code를 리소스에 대한 access_token으로 사용할 수 있습니다. /token 엔드포인트에 POST 요청을 보내 code를 사용합니다.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
tenant |
필수 | 요청의 경로에 있는 {tenant} 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 common, organizations, consumers 및 테넌트 ID입니다. 자세한 내용은 엔드포인트를 참조하세요. |
client_id |
필수 | Microsoft Entra 관리 센터 – 앱 등록 페이지가 사용자 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
scope |
선택적 | 공백으로 구분된 범위 목록입니다. 이 범위는 OIDC 범위(profile, openid, email)와 마찬가지로 모두 단일 리소스에 속해야 합니다. 자세한 내용은 Microsoft ID 플랫폼의 권한 및 동의를 참조하세요. 이 매개 변수는 권한 부여 코드 흐름의 Microsoft 확장이며, 토큰 사용 중에 앱에서 토큰을 원하는 리소스를 선언하는 데 사용합니다. |
code |
필수 | 흐름의 첫 번째 레그에서 획득한 authorization_code입니다. |
redirect_uri |
필수 | authorization_code를 획득하는 데 사용된 것과 동일한 redirect_uri 값입니다. |
grant_type |
필수 | 인증 코드 흐름에 대한 authorization_code 여야 합니다. |
code_verifier |
권장 | authorization_code를 가져오는 데 사용된 것과 동일한 code_verifier입니다. PKCE를 인증 코드 부여 요청에 사용한 경우에 필요합니다. 자세한 내용은 PKCE RFC를 참조하세요. |
client_secret |
기밀 웹앱에 필요 | 앱에 대한 앱 등록 포털에서 만든 애플리케이션 비밀입니다. 디바이스 또는 웹 페이지에 client_secret을 안정적으로 저장할 수 없기 때문에 원시 앱 또는 단일 페이지 앱에서 애플리케이션 비밀을 사용하면 안 됩니다. 서버 쪽에서 client_secret을 안전하게 저장할 수 있는 웹앱과 Web API에 필요합니다. 여기에 있는 모든 매개 변수와 마찬가지로 클라이언트 암호는 전송되기 전에 URL로 인코딩되어야 합니다. 이 단계는 SDK에서 수행됩니다. URI 인코딩에 관한 자세한 내용은 URI 일반 구문 사양을 참고하세요. 대신 RFC 6749에 따라 권한 부여 헤더에 자격 증명을 제공하는 기본 인증 패턴도 지원됩니다. |
인증서 자격 증명을 사용하여 액세스 토큰 요청
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
tenant |
필수 | 요청의 경로에 있는 {tenant} 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 common, organizations, consumers 및 테넌트 ID입니다. 자세한 내용은 엔드포인트를 참조하세요. |
client_id |
필수 | Microsoft Entra 관리 센터 – 앱 등록 페이지가 사용자 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
scope |
선택적 | 공백으로 구분된 범위 목록입니다. 이 범위는 OIDC 범위(profile, openid, email)와 마찬가지로 모두 단일 리소스에 속해야 합니다. 자세한 내용은 사용 권한, 동의 및 범위를 참조하세요. 이 매개 변수는 권한 부여 코드 흐름에 대한 Microsoft 확장입니다. 이 확장을 사용하면 앱이 토큰 사용 중에 원하는 리소스를 선언하는 데 토큰을 사용할 수 있습니다. |
code |
필수 | 흐름의 첫 번째 레그에서 획득한 authorization_code입니다. |
redirect_uri |
필수 | authorization_code를 획득하는 데 사용된 것과 동일한 redirect_uri 값입니다. |
grant_type |
필수 | 인증 코드 흐름에 대한 authorization_code 여야 합니다. |
code_verifier |
권장 | authorization_code을 가져오는 데 사용한 것과 동일한 code_verifier입니다. PKCE를 인증 코드 부여 요청에 사용한 경우에 필요합니다. 자세한 내용은 PKCE RFC를 참조하세요. |
client_assertion_type |
기밀 웹앱에 필요 | 인증서 자격 증명을 사용하려면 값을 urn:ietf:params:oauth:client-assertion-type:jwt-bearer로 설정해야 합니다. |
client_assertion |
기밀 웹앱에 필요 | 애플리케이션의 자격 증명으로 등록한 인증서를 사용하여 만들고 서명해야 하는 어설션인 JWT(JSON Web Token)입니다. 인증서 등록 방법 및 어설션 형식에 대한 자세한 내용은 인증서 자격 증명을 참조하세요. |
해당 매개 변수는 client_secret 매개 변수가 두 개의 매개 변수 client_assertion_type 및 client_assertion으로 바뀐다는 것을 제외하고 공유 비밀에 따른 요청과 동일합니다.
성공적인 응답
다음 예제에서는 성공적인 토큰 응답을 보여줍니다.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| 매개 변수 | 설명 |
|---|---|
access_token |
요청된 액세스 토큰입니다. 앱에서 이 토큰을 사용하여 보안 리소스(예: 웹 API)를 인증할 수 있습니다. |
token_type |
토큰 형식 값을 나타냅니다. Microsoft Entra ID가 지원하는 유일한 형식은 Bearer입니다. |
expires_in |
액세스 토큰이 유효한 기간(초)입니다. |
scope |
access_token이 유효한 범위입니다. 선택 사항. 이 매개 변수는 표준이 아니며, 생략된 경우 토큰은 흐름의 초기 구간에서 요청된 범위에 사용됩니다. |
refresh_token |
OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 다른 액세스 토큰을 획득할 수 있습니다. 새로 고침 토큰은 장기적으로 존재합니다. 오랜 기간 동안 리소스에 대한 액세스를 유지할 수 있습니다. 액세스 토큰 새로 고침에 대한 자세한 내용은 이 문서의 뒷 부분에 있는 액세스 토큰 새로 고침을 참조하세요. 참고: offline_access 범위가 요청된 경우에만 제공됩니다. |
id_token |
JSON Web Token. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱은 값을 캐시하고 표시할 수 있으며 기밀 클라이언트는 권한 부여에 이 토큰을 사용할 수 있습니다. id_tokens에 대한 자세한 내용은 id_token reference를 참조하세요. 참고: openid 범위가 요청된 경우에만 제공됩니다. |
오류 응답
이 예제는 오류 응답입니다.
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| 매개 변수 | 설명 |
|---|---|
error |
오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
개발자가 인증 오류의 근본 원인을 파악하도록 도울 수 있는 특정 오류 메시지입니다. |
error_codes |
진단에 도움이 될 수 있는 STS 특정 오류 코드의 목록입니다. |
timestamp |
오류가 발생한 시간입니다. |
trace_id |
진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
correlation_id |
여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
토큰 엔드포인트 오류에 대한 오류 코드
| 오류 코드 | 설명 | 클라이언트 작업 |
|---|---|---|
invalid_request |
프로토콜 오류(예: 필수 매개 변수 누락). | 요청 또는 앱 등록을 수정하고 요청을 다시 제출합니다. |
invalid_grant |
권한 부여 코드 또는 PKCE 코드 확인자가 잘못되었거나 만료되었습니다. | /authorize 엔드포인트에 대한 새 요청을 시도하고 code_verifier 매개 변수가 올바른지 확인합니다. |
unauthorized_client |
인증된 클라이언트가 이 권한 부여 유형을 사용할 권한이 없습니다. | 이 오류는 일반적으로 클라이언트 애플리케이션이 Microsoft Entra ID에 등록되지 않았거나 사용자의 Microsoft Entra 테넌트에 추가되지 않은 경우에 발생합니다. 애플리케이션은 사용자에게 애플리케이션 설치 및 Microsoft Entra ID에 추가에 대한 지침을 묻는 메시지를 표시할 수 있습니다. |
invalid_client |
클라이언트 인증에 실패했습니다. | 클라이언트 자격 증명이 잘못되었습니다. 이 문제를 해결하려면 애플리케이션 관리자가 자격 증명을 업데이트합니다. |
unsupported_grant_type |
권한 부여 서버가 해당 권한 부여 유형을 지원하지 않습니다. | 요청에서 권한 부여 유형을 변경하십시오. 이 유형의 오류는 개발 중에만 발생하며 초기 테스트 중에 검색됩니다. |
invalid_resource |
대상 리소스가 존재하지 않거나, Microsoft Entra ID에서 찾을 수 없거나, 올바르게 구성되지 않았기 때문에 유효하지 않습니다. | 이 코드는 리소스가 존재하는 경우 테넌트에 구성되지 않았음을 나타냅니다. 애플리케이션은 사용자에게 애플리케이션 설치 및 Microsoft Entra ID에 추가에 대한 지침을 묻는 메시지를 표시할 수 있습니다. |
interaction_required |
OIDC 사양이 /authorize 엔드포인트에서만 이 코드를 호출하므로 비표준입니다. 요청을 위해 사용자 상호 작용이 필요합니다. 예를 들어 다른 인증 단계가 필요합니다. |
같은 범위를 사용하여 /authorize 요청을 다시 시도합니다. |
temporarily_unavailable |
서버가 일시적으로 사용량이 많아 요청을 처리할 수 없습니다. | 약간 연기된 후 요청을 다시 시도합니다. 클라이언트 애플리케이션이 일시적 상태 때문에 응답이 지연되었음을 사용자에게 설명할 수 있습니다. |
consent_required |
요청하려면 사용자가 동의해야 합니다. 이 오류는 비표준입니다. 일반적으로 OIDC 사양당 /authorize 엔드포인트만 반환됩니다. 클라이언트 앱에 요청 권한이 없는 코드 사용 흐름에서 scope 매개 변수를 사용하면 반환됩니다. |
클라이언트는 동의를 트리거하기 위해 올바른 범위를 사용하여 사용자를 /authorize 엔드포인트로 다시 보내야 합니다. |
invalid_scope |
앱에서 요청한 범위가 잘못되었습니다. | 인증 요청에서 scope 매개 변수 값을 유효한 값으로 업데이트합니다. |
참고 항목
단일 페이지 앱에는 '단일 페이지 애플리케이션' 클라이언트 유형에 대해서만 원본 간 토큰 상환이 허용됨을 나타내는 invalid_request 오류가 표시될 수 있습니다. 이것은 토큰을 요청하는 데 사용되는 리디렉션 URI가 spa 리디렉션 URI로 표시되지 않았음을 나타냅니다. 이 흐름을 사용하도록 설정하는 방법에 대해서는 애플리케이션 등록 단계를 검토합니다.
액세스 토큰 사용
access_token을 성공적으로 획득했으므로 이제 Authorization 헤더에 포함하여 Web API에 대한 요청에 토큰을 사용할 수 있습니다.
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
액세스 토큰 새로 고침
액세스 토큰은 수명이 짧습니다. 만료된 후 새로 고쳐서 리소스에 계속 액세스합니다. 이렇게 하려면 다른 POST 요청을 /token 엔드포인트에 제출하면 됩니다. code 대신 refresh_token을 입력합니다. 새로 고침 토큰은 클라이언트가 이미 동의를 받은 모든 권한에 유효합니다. 예를 들어 scope=mail.read 요청에 대해 발급된 새로 고침 토큰을 사용하여 scope=api://contoso.com/api/UseResource에 대한 새 액세스 토큰을 요청할 수 있습니다.
웹앱 및 원시 앱에 대한 새로 고침 토큰에는 지정된 수명이 없습니다. 일반적으로 새로 고침 토큰의 수명은 비교적 깁니다. 그러나 새로 고침 토큰이 만료되거나 철회되거나 작업을 위한 충분한 권한이 없는 경우가 있습니다. 애플리케이션은 토큰 발급 엔드포인트에서 반환하는 오류를 예상하고 처리해야 합니다. 단일 페이지 앱은 수명이 24시간인 토큰을 가져와서 매일 새 인증을 요구합니다. 이 작업은 타사 쿠키를 사용하도록 설정된 경우 iframe에서 자동으로 수행할 수 있습니다. Safari와 같은 타사 쿠키가 없는 브라우저에서 전체 페이지 탐색 또는 팝업 창의 최상위 프레임에서 수행해야 합니다.
새로 고침 토큰을 새 액세스 토큰을 획득하는 데 사용하는 경우 철회되지 않습니다. 이전 새로 고침 토큰을 삭제해야 합니다. OAuth 2.0 사양에 따르면 "권한 부여 서버는 새 새로 고침 토큰을 발급할 수 있지만 이 경우 클라이언트는 이전 새로 고침 토큰을 삭제하고 새 새로 고침 토큰으로 바꾸어야 합니다. 권한 부여 서버는 신규 새로 고침 토큰을 클라이언트에 발급한 후에 이전 새로 고침 토큰을 해지할 수 있습니다."
Important
spa로 등록된 리디렉션 URI로 전송되는 새로 고침 토큰의 경우 24시간 후에 만료됩니다. 초기 새로 고침 토큰을 사용하여 획득한 추가 새로 고침 토큰은 해당 만료 시간까지 계속 사용되므로 앱은 대화형 인증을 사용하여 인증 코드 흐름을 다시 실행함으로써 24시간마다 새 새로 고침 토큰을 가져올 수 있도록 준비해야 합니다. 사용자는 자격 증명을 입력할 필요가 없으며 일반적으로 애플리케이션을 다시 로드하는 사용자 환경도 볼 수 없습니다. 브라우저는 로그인 세션을 보려면 최상위 프레임의 로그인 페이지를 방문해야 합니다. 이는 타사 쿠키를 차단하는 브라우저의 개인 정보 보호 기능 때문입니다.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| 매개 변수 | 형식 | 설명 |
|---|---|---|
tenant |
필수 | 요청의 경로에 있는 {tenant} 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 common, organizations, consumers 및 테넌트 ID입니다. 자세한 내용은 엔드포인트를 참조하세요. |
client_id |
필수 | Microsoft Entra 관리 센터 – 앱 등록 환경이 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
grant_type |
필수 | 이 인증 코드 흐름 범례에 대한 refresh_token 이어야 합니다. |
scope |
선택적 | 공백으로 구분된 범위 목록입니다. 이 구간에서 요청된 범위가 원래 authorization_code 요청 구간에서 요청된 범위와 동일하거나 하위 집합이어야 합니다. 이 요청에 지정된 범위가 여러 리소스 서버에 걸쳐 있는 경우 Microsoft ID 플랫폼은 첫 번째 범위에 지정된 리소스에 대한 토큰을 반환합니다. 자세한 내용은 Microsoft ID 플랫폼의 권한 및 동의를 참조하세요. |
refresh_token |
필수 | 흐름의 두 번째 구간에서 얻은 refresh_token입니다. |
client_secret |
웹앱의 경우 필수 | 앱에 대한 앱 등록 포털에서 만든 애플리케이션 비밀입니다. 디바이스에 client_secret을 안정적으로 저장할 수 없으므로 원시 앱에서는 사용하면 안 됩니다. 서버 쪽에서 client_secret을 안전하게 저장할 수 있는 웹앱과 Web API에 필요합니다. 이 암호는 URL로 인코딩해야 합니다. 자세한 내용은 URI 일반 구문 사양을 참조하세요. |
성공적인 응답
다음 예제에서는 성공적인 토큰 응답을 보여줍니다.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| 매개 변수 | 설명 |
|---|---|
access_token |
요청된 액세스 토큰입니다. 앱에서 이 토큰을 사용하여 보안 리소스(예: 웹 API)를 인증할 수 있습니다. |
token_type |
토큰 형식 값을 나타냅니다. Microsoft Entra ID가 지원하는 유일한 형식은 Bearer입니다. |
expires_in |
액세스 토큰이 유효한 기간(초)입니다. |
scope |
access_token이 유효한 범위입니다. |
refresh_token |
새 OAuth 2.0 새로 고침 토큰입니다. 이전 새로 고침 토큰을 새로 얻은 새로 고침 토큰으로 대체하여 새로 고침 토큰을 최대한 오랫동안 유효한 상태로 유지해야 합니다. 참고: offline_access 범위가 요청된 경우에만 제공됩니다. |
id_token |
서명되지 않은 JSON Web Token입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. id_token에 대한 자세한 내용은 Microsoft ID 플랫폼 ID 토큰을 참조하세요. 참고: openid 범위가 요청된 경우에만 제공됩니다. |
Warning
코드에서 이 예제의 토큰을 포함하여 소유하지 않은 API에 대한 토큰을 확인하거나 읽으려고 시도하지 마세요. Microsoft 서비스 토큰은 JWT로 유효성을 검사하지 않는 특수 형식을 사용할 수 있으며 소비자(Microsoft 계정) 사용자에 대해 암호화될 수도 있습니다. 토큰 읽기는 유용한 디버깅 및 학습 도구이지만 코드에서 이에 대한 종속성을 취하거나 제어하는 API용이 아닌 토큰에 대한 세부 사항을 가정하지 마세요.
오류 응답
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| 매개 변수 | 설명 |
|---|---|
error |
오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
개발자가 인증 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다. |
error_codes |
진단에 도움이 될 수 있는 STS 특정 오류 코드의 목록입니다. |
timestamp |
오류가 발생한 시간입니다. |
trace_id |
진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
correlation_id |
여러 구성 요소에서 진단에 도움이 될 수 있는 요청에 대한 고유 식별자입니다. |
오류 코드 및 권장되는 클라이언트 작업에 대한 설명은 토큰 엔드포인트 오류에 대한 오류 코드를 참조하세요.
다음 단계
- MSAL JS 샘플을 검토하여 코딩을 시작합니다.
- 토큰 교환 시나리오에 대해 알아봅니다.