Microsoft ID 플랫폼의 OpenID Connect
OIDC(OpenID Connect)는 다른 인증 프로토콜로 사용하기 위해 OAuth 2.0 권한 부여 프로토콜을 확장합니다. OIDC에서 ID 토큰이라는 보안 토큰을 사용하여 OAuth 사용 애플리케이션 간에 SSO(Single Sign-On)를 사용하도록 설정할 수 있습니다.
OIDC의 전체 사양은 OpenID Foundation 웹 사이트의 OpenID Connect Core 1.0 사양에서 사용할 수 있습니다.
프로토콜 흐름: 로그인
다음 다이어그램에서는 기본 OpenID Connect 로그인 흐름을 보여 줍니다. 흐름 단계는 이 문서의 뒷부분에서 자세히 설명하고 있습니다.
ID 토큰 사용
OpenID Connect에서 도입한 ID 토큰은 사용자 인증 중에 클라이언트 애플리케이션에서 요청하면 권한 부여 서버(Microsoft ID 플랫폼)에서 발급합니다. ID 토큰을 사용하면 클라이언트 애플리케이션에서 사용자의 ID를 확인하고 사용자에 대한 다른 정보(클레임)를 가져올 수 있습니다.
ID 토큰은 기본적으로 Microsoft ID 플랫폼에 등록된 애플리케이션에 대해 발급되지 않습니다. 애플리케이션에 대한 ID 토큰은 다음 방법 중 하나를 사용하여 사용하도록 설정됩니다.
- Microsoft Entra 관리 센터에 로그인합니다.
- ID>애플리케이션>앱 등록><내 애플리케이션>>인증으로 이동합니다.
- 플랫폼 구성에서 플랫폼 추가를 선택합니다.
- 열리는 창에서 애플리케이션에 적합한 플랫폼을 선택합니다. 예를 들어 웹 애플리케이션에 대해서는 웹을 선택합니다.
- 리디렉션 URI에서 애플리케이션의 리디렉션 URI를 추가합니다. 예:
https://localhost:8080/. - 암시적 허용 및 하이브리드 흐름 아래에서 ID 토큰(암시적 및 하이브리드 흐름에 사용됨) 확인란을 선택합니다.
또는
- ID>애플리케이션>앱 등록><애플리케이션>>매니페스트를 선택합니다.
- 앱 등록의 애플리케이션 매니페스트에서
oauth2AllowIdTokenImplicitFlow를true로 설정합니다.
앱에 대해 ID 토큰을 사용하도록 설정하지 않고 요청된 경우 Microsoft ID 플랫폼 다음과 유사한 오류를 반환 unsupported_response 합니다.
'response_type' 입력 매개 변수에 제공된 값은 이 클라이언트에 허용되지 않습니다. 필요한 값은 'code'입니다..
id_token의 response_type을 지정하여 ID 토큰을 요청하는 방법은 이 문서 뒷부분에 있는 로그인 요청 보내기에서 설명하고 있습니다.
OpenID 구성 문서 가져오기
Microsoft ID 플랫폼과 같은 OpenID 공급자는 공급자의 OIDC 엔드포인트, 지원되는 클레임 및 기타 메타데이터가 포함된 공개적으로 액세스할 수 있는 엔드포인트에서 OpenID 공급자 구성 문서를 제공합니다. 클라이언트 애플리케이션은 메타데이터를 사용하여 인증 및 인증 서비스의 공개 서명 키에 사용할 URL을 검색할 수 있습니다.
인증 라이브러리는 인증 URL, 공급자의 공개 서명 키 및 기타 서비스 메타데이터를 검색하는 데 사용하는 OpenID 구성 문서의 가장 일반적인 소비자입니다. 앱에서 인증 라이브러리를 사용하는 경우 OpenID 구성 문서 엔드포인트의 요청 및 응답을 직접 코딩할 필요가 없습니다.
앱의 OpenID 구성 문서 URI 찾기
Microsoft Entra ID의 모든 앱 등록에는 OpenID 구성 문서를 제공하는 공개적으로 액세스 가능한 엔드포인트가 제공됩니다. 앱에 대한 구성 문서의 엔드포인트 URI를 확인하려면 잘 알려진 OpenID 구성 경로를 앱 등록의 인증 기관 URL에 추가합니다.
- 잘 알려진 구성 문서 경로:
/.well-known/openid-configuration - 인증 기관 URL:
https://login.microsoftonline.com/{tenant}/v2.0
{tenant}의 값은 다음 표와 같이 애플리케이션의 로그인 대상 그룹에 따라 달라집니다. 인증 기관 URL도 클라우드 인스턴스에 따라 달라집니다.
| 값 | 설명 |
|---|---|
common |
개인 Microsoft 계정과 Microsoft Entra ID의 회사 또는 학교 계정이 모두 있는 사용자는 애플리케이션에 로그인할 수 있습니다. |
organizations |
Microsoft Entra ID의 회사 또는 학교 계정을 가진 사용자만 애플리케이션에 로그인할 수 있습니다. |
consumers |
개인 Microsoft 계정이 있는 사용자만 애플리케이션에 로그인할 수 있습니다. |
Directory (tenant) ID 또는 contoso.onmicrosoft.com |
특정 Microsoft Entra 테넌트(회사 또는 학교 계정이 있는 디렉터리 멤버 또는 개인 Microsoft 계정이 있는 디렉터리 게스트)의 사용자만 애플리케이션에 로그인할 수 있습니다. 값은 Microsoft Entra 테넌트의 도메인 이름이거나 GUID 유형의 테넌트 ID일 수 있습니다. |
팁
개인 Microsoft 계정에 대해 common 또는 consumers 기관을 사용하는 경우 signInAudience에 따라 해당 유형의 계정을 지원하도록 소비 리소스 애플리케이션을 구성해야 합니다.
Microsoft Entra 관리 센터에서 OIDC 구성 문서를 찾으려면 Microsoft Entra 관리 센터에 로그인한 후 다음을 수행합니다.
- ID>애플리케이션>앱 등록><내 애플리케이션>>엔드포인트로 이동합니다.
- OpenID Connect 메타데이터 문서 아래에서 URI를 찾습니다.
샘플 요청
다음 요청은 Azure 퍼블릭 클라우드에 있는 common 기관의 OpenID 구성 문서 엔드포인트에서 OpenID 구성 메타데이터를 가져옵니다.
GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com
팁
사용해 보세요. 애플리케이션의 common 기관에 대한 OpenID 구성 문서를 보려면 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration으로 이동합니다.
샘플 응답
구성 메타데이터는 다음 예제와 같이 JSON 형식으로 반환됩니다(간단히 하기 위해 잘림). JSON 응답에 반환된 메타데이터는 OpenID Connect 1.0 검색 사양에서 자세히 설명하고 있습니다.
{
"authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
"token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"private_key_jwt"
],
"jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
"userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
"subject_types_supported": [
"pairwise"
],
...
}
로그인 요청 보내기
사용자를 인증하고 애플리케이션에서 사용할 ID 토큰을 요청하려면 사용자 에이전트를 Microsoft ID 플랫폼의 /authorize 엔드포인트로 전달합니다. 요청은 OAuth 2.0 권한 부여 코드 흐름의 첫 번째 레그와 비슷하지만 다음과 같은 차이점이 있습니다.
openid범위를scope매개 변수에 포함합니다.response_type매개 변수에서id_token를 지정합니다.nonce매개 변수를 포함합니다.
로그인 요청 예제(가독성을 위해서만 줄 바꿈이 포함됨):
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
| 매개 변수 | Condition | 설명 |
|---|---|---|
tenant |
필수 | 요청의 경로에 있는 {tenant} 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 common, organizations, consumers 및 테넌트 ID입니다. 자세한 내용은 프로토콜 기본 사항을 참조하세요. 한 테넌트의 사용자를 다른 테넌트로 로그인하는 게스트 시나리오의 경우, 리소스 테넌트로 올바르게 로그인하려면 테넌트 식별자를 반드시 제공해야 합니다. |
client_id |
Required | Microsoft Entra 관리 센터 – 앱 등록 환경이 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
response_type |
Required | OpenID Connect 로그인을 위한 id_token 이 포함되어야 합니다. |
redirect_uri |
권장 | 앱이 인증 응답을 보내고 받을 수 있는 앱의 리디렉션 URI입니다. URL로 인코딩해야 한다는 점을 제외하고는 포털에서 등록한 리디렉션 URI 중 하나와 정확히 일치해야 합니다. 없는 경우 엔드포인트는 사용자를 다시 보내기 위해 임의로 등록된 redirect_uri 하나를 선택합니다. |
scope |
Required | 공백으로 구분된 범위 목록입니다. OpenID Connect의 경우 동의 UI에서 로그인 권한으로 해석되는 openid범위가 포함되어야 합니다. 동의를 요청하기 위해 이 요청에 다른 범위를 포함할 수도 있습니다. |
nonce |
Required | ID 토큰에 대한 요청에서 앱이 생성하고 보낸 값입니다. 동일한 nonce 값이 Microsoft ID 플랫폼에서 앱에 반환된 ID 토큰에 포함됩니다. 토큰 재생 공격을 완화하려면 앱에서 ID 토큰의 nonce 값이 토큰을 요청할 때 보낸 값과 동일한지 확인해야 합니다. 값은 일반적으로 고유한 임의 문자열입니다. |
response_mode |
권장 | 결과 권한 부여 코드를 앱에 다시 보내는 데 사용해야 하는 방법을 지정합니다. form_post 또는 fragment일 수 있습니다. 웹 애플리케이션의 경우 애플리케이션에 대한 가장 안전한 토큰 전송을 보장하기 위해 response_mode=form_post를 사용하는 것이 좋습니다. |
state |
권장 | 토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 모든 콘텐츠의 문자열일 수 있습니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 상태는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 사용한 페이지 또는 보기)를 인코딩하는 데 사용됩니다. |
prompt |
선택 사항 | 필요한 사용자 상호 작용 유형을 나타냅니다. 이 경우 유효한 값은 login, none, consent, select_account뿐입니다. prompt=login 클레임은 사용자가 해당 요청에 자격 증명을 입력하도록 하여 Single-Sign On을 무효화합니다. prompt=none 매개 변수는 반대이며 로그인해야 하는 사용자를 나타내기 위해 login_hint와 쌍을 이루어야 합니다. 이러한 매개 변수는 사용자에게 어떤 대화형 메시지도 표시하지 않습니다. Single Sign-On을 통해 요청이 자동으로 완료될 수 없는 경우에 Microsoft ID 플랫폼은 오류를 반환합니다. 이는 로그인한 사용자가 없거나 힌트가 있는 사용자가 로그인하지 않았거나 여러 사용자가 로그인했지만 힌트가 제공되지 않았기 때문입니다. prompt=consent 클레임은 사용자가 로그인 한 후 OAuth 동의 대화 상자를 트리거합니다. 이 대화 상자에서는 앱에 권한을 부여하도록 사용자에게 요청합니다. 마지막으로 사용자에게 select_account 계정 선택기를 표시하여 Single Sign-Out을 부정하지만 사용자가 자격 증명 항목을 요구하지 않고 로그인하려는 계정을 선택할 수 있도록 합니다. login_hint 및 select_account는 모두 사용할 수 없습니다. |
login_hint |
선택 사항 | 사용자 이름을 미리 알고 있는 경우 이 매개 변수를 사용하여 사용자를 위해 로그인 페이지의 사용자 이름 및 이메일 주소 필드를 미리 채울 수 있습니다. 대개 앱은 이전 로그인에서 login_hint선택적 클레임을 이미 추출한 후 재인증 과정에서 이 매개 변수를 사용합니다. |
domain_hint |
선택 사항 | 페더레이션된 디렉터리에 있는 사용자의 영역입니다. 사용자 경험을 보다 간소화하기 위해 로그인 페이지에서 사용자가 거치는 메일 기반 검색 프로세스를 건너뜁니다. AD FS와 같은 온-프레미스 디렉터리를 통해 페더레이션된 테넌트의 경우, 기존 로그인 세션으로 인해 원활한 로그인이 이루어지는 경우가 많습니다. |
이 시점에서 사용자에게 자격 증명을 입력하고 인증을 완료하라는 메시지가 표시됩니다. Microsoft ID 플랫폼은 사용자가 scope 쿼리 매개 변수에 표시된 사용 권한에 동의했는지 확인합니다. 사용자가 이러한 사용 권한에 동의하지 않은 경우 Microsoft ID 플랫폼은 필요한 사용 권한에 동의하라는 메시지를 표시합니다. 권한, 동의 및 다중 테넌트 앱에 대해 자세히 알아볼 수 있습니다.
사용자가 인증하고 동의하면 Microsoft ID 플랫폼은 response_mode 매개 변수에 지정된 방법을 사용하여 표시된 리디렉션 URI에서 해당 앱에 응답을 반환합니다.
성공적인 응답
response_mode=form_post을 사용하는 경우 성공적인 응답은 다음과 비슷합니다.
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
| 매개 변수 | 설명 |
|---|---|
id_token |
앱이 요청한 ID 토큰입니다. id_token 매개 변수를 사용하여 사용자 ID를 확인하고 사용자와 세션을 시작할 수 있습니다. ID 토큰 및 해당 콘텐츠에 대한 자세한 내용은 ID 토큰 참조를 참조하세요. |
state |
state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
오류 응답
앱에서 처리할 수 있도록 오류 응답을 리디렉션 URI에 보낼 수도 있습니다. 예를 들어 다음과 같습니다.
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
| 매개 변수 | 설명 |
|---|---|
error |
발생한 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
인증 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다. |
권한 부여 엔드포인트 오류에 대한 오류 코드
다음 테이블은 오류 응답의 error 매개 변수에 반환될 수 있는 오류 코드를 설명합니다.
| 오류 코드 | 설명 | 클라이언트 작업 |
|---|---|---|
invalid_request |
'필수 매개 변수가 없습니다.'와 같은 프로토콜 오류입니다. | 요청을 수정하여 다시 제출하십시오. 이 개발 오류는 애플리케이션 테스트 중에 catch해야 합니다. |
unauthorized_client |
클라이언트 애플리케이션이 인증 코드를 요청할 수 없습니다. | 이 오류는 클라이언트 애플리케이션이 Microsoft Entra ID에 등록되지 않았거나 사용자의 Microsoft Entra 테넌트에 추가되지 않은 경우 발생할 수 있습니다. 애플리케이션은 사용자에게 애플리케이션을 설치하고 이를 Microsoft Entra ID에 추가하라는 지침을 표시할 수 있습니다. |
access_denied |
리소스 소유자가 동의를 거부했습니다. | 클라이언트 애플리케이션에서 사용자 동의를 받아야만 진행할 수 있다고 알릴 수 있습니다. |
unsupported_response_type |
권한 부여 서버가 요청에 해당 응답 형식을 지원하지 않습니다. | 요청을 수정하여 다시 제출하십시오. 이 개발 오류는 애플리케이션 테스트 중에 catch해야 합니다. |
server_error |
서버에 예기치 않은 오류가 발생했습니다. | 요청을 다시 시도하십시오. 이러한 오류는 일시적인 상태 때문에 발생할 수 있습니다. 클라이언트 애플리케이션이 일시적 오류 때문에 응답이 지연되었음을 사용자에게 설명할 수 있습니다. |
temporarily_unavailable |
서버가 일시적으로 사용량이 많아 요청을 처리할 수 없습니다. | 요청을 다시 시도하십시오. 클라이언트 애플리케이션이 일시적 상태 때문에 응답이 지연되었음을 사용자에게 설명할 수 있습니다. |
invalid_resource |
대상 리소스가 존재하지 않거나, Microsoft Entra ID에서 찾을 수 없거나, 잘못 구성되었기 때문에 유효하지 않습니다. | 이 오류는 리소스가 있는 경우 테넌트에 구성되지 않았음을 나타냅니다. 애플리케이션은 사용자에게 애플리케이션 설치 및 Microsoft Entra ID에 추가에 대한 지침을 묻는 메시지를 표시할 수 있습니다. |
ID 토큰 유효성 검사
앱에서 ID 토큰을 받는 것만으로는 사용자를 완전히 인증하는 데 충분하지 않을 수 있습니다. 또한 ID 토큰의 서명 유효성을 검사하고 앱의 요구 사항에 따라 해당 클레임을 확인해야 할 수도 있습니다. 모든 OpenID 공급자와 마찬가지로 Microsoft ID 플랫폼의 ID 토큰은 공개 키 암호화를 사용하여 서명된 JWT(JSON Web Token)입니다.
이러한 애플리케이션에서 데이터에 대한 액세스를 차단하므로 ID 토큰을 권한 부여에 사용하는 웹앱 및 웹 API는 유효성을 검사해야 합니다. 그러나 다른 유형의 애플리케이션은 ID 토큰 유효성 검사의 이점을 활용하지 못할 수 있습니다. 예를 들어 네이티브 및 SPA(단일 페이지 애플리케이션)는 디바이스 또는 브라우저에 물리적으로 액세스할 수 있는 엔터티가 잠재적으로 유효성 검사를 무시할 수 있기 때문에 ID 토큰 유효성 검사의 이점을 거의 누릴 수 없습니다.
토큰 유효성 검사 무시의 두 가지 예는 다음과 같습니다.
- 디바이스에 대한 네트워크 트래픽을 수정하여 가짜 토큰 또는 키 제공
- 프로그램 실행 중에 애플리케이션 디버깅 및 유효성 검사 논리 프로시저 단위 실행
애플리케이션에서 ID 토큰의 유효성을 검사하는 경우 수동으로 수행하지 않는 것이 좋습니다. 대신 토큰 유효성 검사 라이브러리를 사용하여 토큰을 구문 분석하고 유효성을 검사합니다. 토큰 유효성 검사 라이브러리는 대부분의 개발 언어, 프레임워크 및 플랫폼에서 사용할 수 있습니다.
ID 토큰에서 유효성을 검사할 항목
ID 토큰의 서명 유효성을 검사하는 것 외에도 ID 토큰 유효성 검사에서 설명한 대로 여러 클레임의 유효성을 검사해야 합니다. 서명 키 롤오버에 대한 중요한 정보도 참조하세요.
몇 가지 다른 유효성 검사는 일반적이며 다음을 포함하여 애플리케이션 시나리오에 따라 다릅니다.
- 사용자/조직이 앱에 등록했는지 확인
- 사용자에게 적절한 권한 부여/권한이 있는지 확인
- 다단계 인증과 같은 특정 강도의 인증이 발생했는지 확인합니다.
ID 토큰의 유효성이 검사되면 사용자와 세션을 시작하고, 앱 맞춤, 표시 또는 데이터 저장을 위해 토큰 클레임의 정보를 사용할 수 있습니다.
프로토콜 다이어그램: 액세스 토큰 가져오기
많은 애플리케이션에서 사용자를 로그인할 뿐만 아니라 사용자를 대신하여 웹 API와 같은 보호된 리소스에 액세스해야 합니다. 이 시나리오는 OpenID Connect를 결합하여 사용자 인증에 대한 ID 토큰을 가져오고, OAuth 2.0을 결합하여 보호된 리소스에 대한 액세스 토큰을 가져옵니다.
전체 OpenID Connect 로그인 및 토큰 획득 흐름은 다음 다이어그램과 비슷합니다.
UserInfo 엔드포인트에 대한 액세스 토큰 가져오기
ID 토큰 외에도 인증된 사용자의 정보도 OIDC UserInfo 엔드포인트에서 사용할 수 있습니다.
OIDC UserInfo 엔드포인트에 대한 액세스 토큰을 가져오려면 여기서 설명한 대로 로그인 요청을 수정합니다.
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 // Your app registration's Application (client) ID
&response_type=id_token%20token // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F // Your application's redirect URI (URL-encoded)
&response_mode=form_post // 'form_post' or 'fragment'
&scope=openid+profile+email // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token.
&state=12345 // Any value - provided by your app
&nonce=678910 // Any value - provided by your app
response_type=token 대신 권한 부여 코드 흐름, 디바이스 코드 흐름 또는 새로 고침 토큰을 사용하여 앱에 대한 액세스 토큰을 가져올 수 있습니다.
토큰 응답 성공
response_mode=form_post 사용에 따른 성공적인 응답:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
&token_type=Bearer
&expires_in=3598
&scope=email+openid+profile
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
&state=12345
응답 매개 변수는 해당 매개 변수를 획득하는 데 사용되는 흐름과 상관없이 동일한 작업을 의미합니다.
| 매개 변수 | 설명 |
|---|---|
access_token |
UserInfo 엔드포인트를 호출하는 데 사용되는 토큰입니다. |
token_type |
항상 “전달자”입니다. |
expires_in |
액세스 토큰이 만료될 때까지의 시간(초)입니다. |
scope |
액세스 토큰에 부여되는 권한입니다. UserInfo 엔드포인트는 Microsoft Graph에서 호스트되므로 scope에는 이전에 애플리케이션에 부여된 다른 엔드포인트(예: User.Read)가 포함될 수 있습니다. |
id_token |
앱이 요청한 ID 토큰입니다. ID 토큰을 사용하여 사용자 ID를 확인하고 사용자와 세션을 시작할 수 있습니다. ID 토큰 및 해당 콘텐츠에 대한 자세한 내용은 ID 토큰 참조에서 확인할 수 있습니다. |
state |
state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
Warning
코드에서 이 예제의 토큰을 포함하여 소유하지 않은 API에 대한 토큰을 확인하거나 읽으려고 시도하지 마세요. Microsoft 서비스 토큰은 JWT로 유효성을 검사하지 않는 특수 형식을 사용할 수 있으며 소비자(Microsoft 계정) 사용자에 대해 암호화될 수도 있습니다. 토큰 읽기는 유용한 디버깅 및 학습 도구이지만 코드에서 이에 대한 종속성을 취하거나 제어하는 API용이 아닌 토큰에 대한 세부 사항을 가정하지 마세요.
오류 응답
앱에서 적절히 처리할 수 있도록 오류 응답을 리디렉션 URI에 보낼 수도 있습니다.
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
error=access_denied&error_description=the+user+canceled+the+authentication
| 매개 변수 | 설명 |
|---|---|
error |
발생한 오류 유형을 분류하고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다. |
error_description |
인증 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다. |
가능한 오류 코드 및 권장되는 클라이언트 응답에 대한 설명은 권한 부여 엔드포인트 오류에 대한 오류 코드를 참조하세요.
권한 부여 코드와 ID 토큰이 있는 경우 사용자로 로그인하여 액세스 토큰을 대신 가져올 수 있습니다. 사용자를 로그인하려면 유효성 검사 토큰에 설명된 대로 ID 토큰의 유효성을 검사해야 합니다. 액세스 토큰을 가져오려면 OAuth 코드 흐름 설명서에 설명된 단계를 따릅니다.
UserInfo 엔드포인트 호출
UserInfo 설명서를 검토하여 이 토큰을 사용해 UserInfo 엔드포인트를 호출하는 방법을 확인합니다.
로그아웃 요청 보내기.
사용자를 로그아웃하려면 다음 작업을 모두 수행합니다.
- 사용자의 사용자 에이전트를 Microsoft ID 플랫폼의 로그아웃 URI로 리디렉션합니다.
- 앱의 쿠키를 지우거나 애플리케이션에서 사용자의 세션을 종료합니다.
이러한 작업 중 하나를 수행하지 못하면 사용자는 인증된 상태로 유지되고 다음에 앱을 사용할 때 로그인하라는 메시지가 표시되지 않을 수 있습니다.
OpenID Connect 구성 문서에서 보여 준 대로 사용자 에이전트를 end_session_endpoint로 리디렉션합니다. end_session_endpoint는 HTTP GET 및 POST 요청을 모두 지원합니다.
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
| 매개 변수 | Condition | 설명 |
|---|---|---|
post_logout_redirect_uri |
권장 | 성공적으로 로그아웃한 후에 사용자가 리디렉션되는 URL입니다. 매개 변수를 포함하지 않을 경우 사용자에게는 Microsoft ID 플랫폼에 의해 생성된 일반 메시지가 표시됩니다. URL은 앱 등록 포털에서 애플리케이션에 등록한 리디렉션 URI 중 하나와 일치해야 합니다. |
logout_hint |
선택 사항 | 사용자에게 계정을 선택하라는 메시지를 표시하지 않고 로그아웃을 수행할 수 있습니다. 사용logout_hint하려면 클라이언트 애플리케이션에서 선택적 클레임을 사용하도록 설정하고 login_hint 선택적 클레임의 login_hint 값을 매개 변수로 logout_hint 사용합니다. UPN 또는 전화번호를 logout_hint 매개 변수의 값으로 사용하지 마세요. |
참고 항목
로그아웃에 성공하면 활성 세션이 비활성으로 설정됩니다. 로그아웃된 사용자에 대해 유효한 PRT(기본 새로 고침 토큰)가 있고 새 로그인이 실행되면 Single Sign-Out이 중단되고 사용자에게 계정 선택기가 있는 프롬프트가 표시됩니다. 선택한 옵션이 PRT를 참조하는 연결된 계정인 경우 새 자격 증명을 삽입할 필요 없이 로그인이 자동으로 진행됩니다.
Single Sign-Out
사용자를 애플리케이션의 사용자로 end_session_endpoint 리디렉션하면 Microsoft ID 플랫폼 이 애플리케이션에 대한 사용자 세션을 종료합니다. 그러나 사용자는 인증에 동일한 Microsoft 계정을 사용하는 다른 애플리케이션에 계속 로그인할 수 있습니다.
사용자가 이 디렉터리(테넌트라고도 함)에 등록된 여러 웹 또는 SPA 애플리케이션에 로그인한 경우 이 사용자는 애플리케이션 중 하나에서 로그아웃하여 모든 애플리케이션에서 즉시 로그아웃할 수 있습니다.
Entra 애플리케이션에 대해 Single Sign-Out을 사용하도록 설정하려면 OpenID Connect 프런트 채널 로그아웃 기능을 사용해야 합니다. 이 기능을 사용하면 애플리케이션이 사용자가 로그아웃했음을 다른 애플리케이션에 알릴 수 있습니다. 사용자가 한 애플리케이션에서 로그아웃하면 Microsoft ID 플랫폼 사용자가 현재 로그인한 모든 애플리케이션의 프런트 채널 로그아웃 URL에 HTTP GET 요청을 보냅니다.
이러한 애플리케이션은 Single Sign-Out이 성공하려면 다음 두 가지 작업을 수행하여 이 요청에 응답해야 합니다.
- 사용자를 식별하는 세션을 지웁니다.
- 애플리케이션은 사용자를 식별하는 모든 세션을 지우고
200요청을 반환하여 이 요청에 응답해야 합니다.
전면 채널 로그아웃 URL이란?
프런트 채널 로그아웃 URL은 웹 또는 SPA 애플리케이션이 Entra 인증 서버에서 로그아웃 요청을 수신하고 Single Sign-Out 기능을 수행하는 위치입니다. 각 애플리케이션에는 하나의 전면 채널 로그아웃 URL이 있습니다.
언제 전면 채널 로그아웃 URL을 설정해야 하나요?
사용자 또는 개발자가 애플리케이션에 대해 Single Sign-Out이 필요하다고 결정한 경우 이 애플리케이션의 앱 등록에 대한 전면 채널 로그아웃 URL을 설정해야 합니다. 이 애플리케이션의 앱 등록에 대해 프런트 채널 로그아웃 URL이 설정되면 Microsoft ID 플랫폼 로그인한 사용자가 다른 애플리케이션에서 로그아웃한 경우 이 애플리케이션의 프런트 채널 로그아웃 URL에 HTTP GET 요청을 보냅니다.
프런트 채널 로그아웃 기능을 사용하여 Single Sign out을 설정하는 방법
애플리케이션 집합에 프런트 채널 로그아웃 기능을 사용하려면 다음 두 작업을 완료해야 합니다.
- 동시에 로그아웃해야 하는 모든 애플리케이션에 대해 Microsoft Entra 관리 센터에서 프런트 채널 로그아웃 URL을 설정합니다. 각 애플리케이션에는 일반적으로 자체 전용 프런트 채널 로그아웃 URL이 있습니다.
- 애플리케이션 코드를 편집하여 Microsoft ID 플랫폼 보낸 HTTP GET 요청을 프런트 채널 로그아웃 URL로 수신 대기하고 사용자를 식별하는 세션을 지우고 200 응답을 반환하여 이 요청에 응답합니다.
프런트 채널 로그아웃 URL을 선택하는 방법
프런트 채널 로그아웃 URL은 HTTP GET 요청을 수신하고 응답할 수 있는 URL이어야 하며 사용자를 식별하는 모든 세션을 지울 수 있어야 합니다. 프런트 채널 로그아웃 URL의 예는 다음과 같습니다.