OpenID Connect 및 Azure Active Directory를 사용하여 웹 애플리케이션에 대한 액세스 권한 부여

경고

이 콘텐츠는 이전 Azure AD v1.0 엔드포인트용입니다. 새 프로젝트에 Microsoft ID 플랫폼 사용합니다.

OpenID Connect 는 OAuth 2.0 프로토콜을 기반으로 빌드된 간단한 ID 계층입니다. OAuth 2.0은 액세스 토큰 을 가져오고 사용하여 보호된 리소스에 액세스하는 메커니즘을 정의하지만 ID 정보를 제공하는 표준 메서드를 정의하지는 않습니다. OpenID Connect는 OAuth 2.0 권한 부여 프로세스에 대한 확장으로 인증을 구현합니다. 최종 사용자에 대한 정보를 사용자의 ID를 id_token 확인하고 사용자에 대한 기본 프로필 정보를 제공하는 형식으로 제공됩니다.

서버에서 호스트되고 브라우저를 통해 액세스되는 웹 애플리케이션을 빌드하는 경우 OpenID Connect가 권장됩니다.

AD 테넌트에 애플리케이션 등록

먼저 Azure AD(Azure Active Directory) 테넌트에 애플리케이션을 등록합니다. 이렇게 하면 애플리케이션에 대한 애플리케이션 ID를 제공할 뿐만 아니라 토큰을 받을 수 있습니다.

Azure Portal에 로그인합니다.
페이지의 오른쪽 위 모서리에서 계정을 선택한 다음 디렉터리 전환 탐색을 선택한 다음 적절한 테넌트를 선택하여 Azure AD 테넌트를 선택합니다.
- 계정에 Azure AD 테넌트가 하나만 있거나 적절한 Azure AD 테넌트를 이미 선택한 경우 이 단계를 건너뜁니다.
Azure Portal에서 Azure Active Directory를 검색하고 선택합니다.
Azure Active Directory 왼쪽 메뉴에서 앱 등록을 선택한 다음 새 등록을 선택합니다.
프롬프트에 따라 새 애플리케이션을 만듭니다. 이 자습서의 웹 애플리케이션 또는 공용 클라이언트(모바일 및 데스크톱) 애플리케이션인지는 중요하지 않지만 웹 애플리케이션 또는 퍼블릭 클라이언트 애플리케이션에 대한 특정 예제를 원하는 경우 빠른 시작을 확인하세요.
- 이름은 애플리케이션 이름이며 최종 사용자에게 애플리케이션을 설명합니다.
- 지원되는 계정 유형 아래에서 모든 조직 디렉터리의 계정 및 개인 Microsoft 계정을 선택합니다.
- 리디렉션 URI를 제공합니다. 웹 애플리케이션의 경우 사용자가 로그인할 수 있는 앱의 기본 URL입니다. 예: http://localhost:12345. 공용 클라이언트(모바일 및 데스크톱)의 경우 Azure AD는 이를 사용하여 토큰 응답을 반환합니다. 애플리케이션과 관련된 값을 입력합니다. 예: http://MyFirstAADApp.
등록을 완료하면 Azure AD는 애플리케이션에 고유한 클라이언트 식별자( 애플리케이션 ID)를 할당합니다. 다음 섹션에서 이 값이 필요하므로 애플리케이션 페이지에서 복사합니다.
Azure Portal에서 애플리케이션을 찾으려면 앱 등록을 선택한 다음 , 모든 애플리케이션 보기를 선택합니다.

OpenID Connect를 사용하는 인증 흐름

가장 기본적인 로그인 흐름에는 다음 단계가 포함되어 있습니다. 각 단계는 아래에서 자세히 설명합니다.

OpenId Connect 인증 흐름

OpenID Connect 메타데이터 문서

OpenID Connect는 앱이 로그인을 수행하는 데 필요한 대부분의 정보를 포함하는 메타데이터 문서를 설명합니다. 여기에는 사용할 URL 및 서비스의 공개 서명 키 위치와 같은 정보가 포함됩니다. OpenID Connect 메타데이터 문서는 다음 위치에서 찾을 수 있습니다.

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

메타데이터는 간단한 JSON(JavaScript Object Notation) 문서입니다. 예제는 다음 코드 조각을 참조하세요. 코드 조각의 내용은 OpenID Connect 사양에 완전히 설명되어 있습니다. 위의 {tenant} 대신 테넌트 ID common 를 제공하면 JSON 개체에서 테넌트별 URI가 반환됩니다.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

클레임 매핑 기능을 사용한 결과로 앱에 사용자 지정 서명 키가 있는 경우 앱의 서명 키 정보를 가리키려면 jwks_uri 앱 ID가 포함된 쿼리 매개 변수를 추가 appid 해야 합니다. 예를 들어: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e는 https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e의 jwks_uri를 포함합니다.

웹 애플리케이션에서 사용자를 인증해야 하는 경우 사용자를 엔드포인트로 전달 /authorize 해야 합니다. 이 요청은 OAuth 2.0 인증 코드 흐름의 첫 번째 레그와 유사하며 몇 가지 중요한 차이점이 있습니다.

요청에는 openid 범위가 scope 매개 변수에 포함되어야 합니다.
매개 변수 response_type는 id_token를 포함해야 합니다.
요청에는 매개 변수가 nonce 포함되어야 합니다.

따라서 샘플 요청은 다음과 같습니다.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

매개 변수	유형	설명
테넌트	필수	요청의 경로에 있는 `{tenant}` 값을 사용하여 애플리케이션에 로그인할 수 있는 사용자를 제어할 수 있습니다. 허용되는 값은 테넌트 식별자이며, 예를 들어 테넌트에 독립적인 토큰의 경우 `8eaef023-2b34-4da1-9baa-8bc8c9d6a490` 또는 `contoso.onmicrosoft.com` 또는 `common`입니다.
클라이언트_아이디	필수	Azure AD에 등록할 때 앱에 할당된 애플리케이션 ID입니다. Azure Portal에서 찾을 수 있습니다. Azure Active Directory를 클릭하고, 앱 등록을 클릭하고, 애플리케이션을 선택하고, 애플리케이션 페이지에서 애플리케이션 ID를 찾습니다.
응답 유형	필수	OpenID Connect 로그인을 위한 `id_token` 이 포함되어야 합니다. 다른 response_types 포함할 수도 있습니다( 예: `code` 또는 `token`.
범위	권장	OpenID Connect 사양에는 동의 UI의 "로그인" 권한으로 변환되는 범위 `openid`가 필요합니다. 이 범위 및 기타 OIDC 범위는 v1.0 엔드포인트에서 무시되지만 여전히 표준 규격 클라이언트에 대한 모범 사례입니다.
논스	필수	요청에 포함되며 앱에서 생성된 값으로, 결과 `id_token`에 클레임으로 포함됩니다. 그러면 앱에서 이 값을 확인하여 토큰 재생 공격을 완화할 수 있습니다. 값은 일반적으로 요청의 원본을 식별하는 데 사용할 수 있는 임의로 고유한 문자열 또는 GUID입니다.
redirect_uri	권장	앱의 redirect_uri는 인증 응답을 보내고 받을 수 있는 주소입니다. URL로 인코딩되어야 한다는 점을 제외하고 포털에 등록한 redirect_uris 중 하나와 정확히 일치해야 합니다. 누락된 경우 사용자 에이전트는 임의로 앱에 등록된 리디렉션 URI 중 하나로 다시 전송됩니다. 최대 길이는 255바이트입니다.
응답 모드	선택 사항	결과 인증 코드를 앱으로 다시 보내는 데 사용해야 하는 메서드를 지정합니다. 지원되는 값은 `form_post`HTTP 양식 게시물 및 `fragment`URL 조각에 대한 값입니다. 웹 애플리케이션의 경우 애플리케이션에 토큰을 가장 안전하게 전송하는 데 사용하는 `response_mode=form_post` 것이 좋습니다. id_token 포함한 모든 흐름의 기본값은 .입니다 `fragment`.
주	권장	토큰 응답에 반환되는 요청에 포함된 값입니다. 원하는 콘텐츠의 문자열일 수 있습니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 state는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 페이지 또는 보기)를 인코딩하는 데 사용됩니다.
프롬프트	선택 사항	필요한 사용자 상호 작용 유형을 나타냅니다. 현재 유효한 값은 'login', 'none' 및 'consent'뿐입니다. `prompt=login`은 Single-Sign On을 무효화면서, 사용자가 요청에 자신의 자격 증명을 입력하도록 합니다. `prompt=none` 는 반대입니다. 즉, 사용자에게 대화형 프롬프트가 표시되지 않도록 합니다. Single Sign-On을 통해 요청을 자동으로 완료할 수 없는 경우 엔드포인트는 오류를 반환합니다. `prompt=consent` 는 사용자가 로그인한 후 OAuth 동의 대화 상자를 트리거하여 사용자에게 앱에 대한 사용 권한을 부여하도록 요청합니다.
로그인 힌트	선택 사항	사용자 이름을 미리 알고 있는 경우 사용자 로그인 페이지의 사용자 이름/이메일 주소 필드를 미리 채우는 데 사용할 수 있습니다. 앱은 `preferred_username` 클레임을 사용하여 이전 로그인에서 사용자 이름을 이미 추출한 상태에서, 재인증하는 동안 이 매개 변수를 자주 사용합니다.

이 시점에서 사용자에게 자격 증명을 입력하고 인증을 완료하라는 메시지가 표시됩니다.

샘플 응답

사용자가 인증한 후 로그인 요청에 지정된 응답 redirect_uri 으로 전송되는 샘플 응답은 다음과 같습니다.

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

매개 변수	설명
id_token (아이디 토큰)	앱에서 요청한 `id_token`입니다. 이 기능을 사용하여 `id_token` 사용자의 ID를 확인하고 사용자와 세션을 시작할 수 있습니다.
주	토큰 응답에도 반환되는 요청에 포함된 값입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 state는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 페이지 또는 보기)를 인코딩하는 데 사용됩니다.

오류 응답

앱이 적절하게 처리할 수 있도록 redirect_uri 에 오류 응답을 보낼 수도 있습니다.

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

매개 변수	설명
오류	발생하는 오류 유형을 분류하는 데 사용할 수 있고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
오류 설명	개발자가 인증 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다.

권한 부여 엔드포인트 오류에 대한 오류 코드

다음 테이블은 오류 응답의 error 매개 변수에 반환될 수 있는 여러 오류 코드를 설명합니다.

오류 코드	설명	클라이언트 작업
잘못된_요청	프로토콜 오류(예: 필수 매개 변수 누락).	요청을 수정하여 다시 제출하십시오. 이는 개발 오류이며 일반적으로 초기 테스트 중에 catch됩니다.
승인되지 않은 클라이언트	클라이언트 애플리케이션은 권한 부여 코드를 요청할 수 없습니다.	이는 일반적으로 클라이언트 애플리케이션이 Azure AD에 등록되지 않았거나 사용자의 Azure AD 테넌트에 추가되지 않은 경우에 발생합니다. 애플리케이션은 사용자에게 애플리케이션을 설치하고 Azure AD에 추가하라는 명령을 표시할 수 있습니다.
액세스 거부	리소스 소유자가 동의 거부	클라이언트 애플리케이션은 사용자가 동의하지 않는 한 계속 진행할 수 없음을 사용자에게 알릴 수 있습니다.
지원되지 않는 응답 유형	권한 부여 서버는 요청의 응답 유형을 지원하지 않습니다.	요청을 수정하여 다시 제출하십시오. 이는 개발 오류이며 일반적으로 초기 테스트 중에 catch됩니다.
서버 오류	서버에 예기치 않은 오류가 발생했습니다.	요청을 재시도합니다. 이러한 오류는 일시적인 상태 때문에 발생할 수 있습니다. 클라이언트 애플리케이션은 사용자에게 일시적인 오류로 인해 응답이 지연되었음을 설명할 수 있습니다.
일시적으로 이용 불가능	서버가 일시적으로 사용량이 많아 요청을 처리할 수 없습니다.	요청을 재시도합니다. 클라이언트 애플리케이션은 임시 조건으로 인해 응답이 지연되었음을 사용자에게 설명할 수 있습니다.
잘못된_리소스	대상 리소스가 없거나, Azure AD에서 찾을 수 없거나, 올바르게 구성되지 않았기 때문에 유효하지 않습니다.	이는 리소스가 존재하는 경우 테넌트에 구성되지 않음을 나타냅니다. 애플리케이션은 사용자에게 애플리케이션을 설치하고 Azure AD에 추가하라는 명령을 표시할 수 있습니다.

id_token 유효성 검사

사용자를 인증하기 위해 id_token을(를) 받는 것만으로는 충분하지 않습니다. 앱 요구 사항에 따라 서명의 유효성을 검사하고 id_token의 클레임을 확인해야 합니다. Azure AD 엔드포인트는 JWT(JSON 웹 토큰) 및 공개 키 암호화를 사용하여 토큰에 서명하고 유효한지 확인합니다.

클라이언트 코드에서 id_token 유효성을 검사하도록 선택할 수 있지만, 일반적인 방법은 백 엔드 서버로 보내고 id_token 유효성 검사를 수행하는 것입니다.

시나리오에 따라 추가 클레임의 유효성을 검사할 수도 있습니다. 몇 가지 일반적인 유효성 검사에는 다음이 포함됩니다.

사용자/조직이 앱에 등록했는지 확인
사용자에게 또는 roles 클레임을 사용하여 wids 적절한 권한 부여/권한이 있는지 확인합니다.
다단계 인증과 같은 특정 인증 강도가 발생했는지 확인합니다.

유효성을 id_token검사한 후에는 사용자와 세션을 시작하고 해당 클레임을 id_token 사용하여 앱에서 사용자에 대한 정보를 얻을 수 있습니다. 이 정보는 표시, 레코드, 개인 설정 등에 사용할 수 있습니다. 클레임 및 클레임에 대한 id_tokens 자세한 내용은 AAD id_tokens 읽어보세요.

로그아웃 요청 보내기.

앱에서 사용자를 로그아웃하려는 경우 앱의 쿠키를 지우거나 사용자와 세션을 종료하는 것으로 충분하지 않습니다. 또한 로그아웃을 위해 end_session_endpoint 사용자를 리디렉션해야 합니다. 이렇게 하지 않으면 사용자는 Azure AD 엔드포인트와 유효한 Single Sign-On 세션이 있기 때문에 자격 증명을 다시 입력하지 않고 앱에 다시 인증할 수 있습니다.

OpenID Connect 메타데이터 문서에 나열된 사용자로 간단히 리디렉션할 end_session_endpoint 수 있습니다.

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

매개 변수	유형	설명
post_logout_redirect_uri	권장	로그아웃에 성공한 후 사용자가 리디렉션해야 하는 URL입니다. 이 URL은 앱 등록 포털에서 애플리케이션에 등록된 리디렉션 URI 중 하나와 일치해야 합니다. post_logout_redirect_uri 포함되지 않으면 사용자에게 일반 메시지가 표시됩니다.

단일 로그아웃

사용자를 end_session_endpoint리디렉션하면 Azure AD는 브라우저에서 사용자의 세션을 지웁니다. 그러나 사용자는 인증에 Azure AD를 사용하는 다른 애플리케이션에 여전히 로그인될 수 있습니다. 이러한 애플리케이션이 사용자를 동시에 로그아웃할 수 있도록 Azure AD는 사용자가 현재 로그인한 모든 애플리케이션의 등록된 LogoutUrl HTTP GET 요청을 보냅니다. 애플리케이션은 사용자를 식별하는 모든 세션을 지우고 200 요청을 반환하여 이 요청에 응답해야 합니다. 애플리케이션에서 싱글 로그아웃을 지원하려면 애플리케이션 코드에서 이를 LogoutUrl 구현해야 합니다. Azure 포털에서 LogoutUrl을(를) 설정할 수 있습니다.

Azure Portal에 로그인합니다.
페이지의 오른쪽 위 모서리에 있는 계정을 클릭하여 Active Directory를 선택합니다.
왼쪽 탐색 패널에서 Azure Active Directory를 선택한 다음 , 앱 등록을 선택하고 애플리케이션을 선택합니다.
설정을 클릭한 다음 속성을 클릭하고 로그아웃 URL 텍스트 상자를 찾습니다.

토큰 획득

많은 웹앱은 사용자를 로그인할 뿐만 아니라 OAuth를 사용하여 해당 사용자를 대신하여 웹 서비스에 액세스해야 합니다. 이 시나리오에서는 사용자 인증을 위해 OpenID Connect를 결합하며 동시에 OAuth 인증 코드 흐름을 사용하는 데 필요한 authorization_code를 획득할 수 있습니다, 이를 통해 access_tokens를 얻을 수 있습니다.

액세스 토큰 가져오기

액세스 토큰을 획득하려면 위에서 로그인 요청을 수정해야 합니다.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

요청에 사용 권한 범위를 포함하고 사용하면 response_type=code+id_tokenauthorize 엔드포인트는 사용자가 쿼리 매개 변수에 표시된 권한에 동의했는지 확인하고 앱에 scope 액세스 토큰을 교환할 권한 부여 코드를 반환합니다.

성공적인 응답

response_mode=form_post을 사용하여 redirect_uri에 전송된 성공적인 응답은 다음과 같습니다.

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345

매개 변수	설명
id_token (아이디 토큰)	앱에서 요청한 `id_token`입니다. 이 기능을 사용하여 `id_token` 사용자의 ID를 확인하고 사용자와 세션을 시작할 수 있습니다.
코드	앱이 요청한 authorization_code입니다. 앱에서 권한 부여 코드를 사용하여 대상 리소스에 대한 액세스 토큰을 요청할 수 있습니다. Authorization_codes 수명이 짧으며 일반적으로 약 10분 후에 만료됩니다.
주	state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다.

오류 응답

앱이 적절하게 처리할 수 있도록 redirect_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

매개 변수	설명
오류	발생하는 오류 유형을 분류하는 데 사용할 수 있고 오류에 대응하는 데 사용할 수 있는 오류 코드 문자열입니다.
오류 설명	개발자가 인증 오류의 근본 원인을 식별하도록 도울 수 있는 특정 오류 메시지입니다.

가능한 오류 코드 및 권장 클라이언트 작업에 대한 설명은 권한 부여 엔드포인트 오류에 대한 오류 코드를 참조하세요.

권한 부여 code 및 id_token인증을 받으면 사용자를 대신하여 로그인하고 액세스 토큰을 가져올 수 있습니다. 사용자를 로그인시키려면 위에서 설명한 대로 정확하게 id_token의 유효성을 검사해야 합니다. 액세스 토큰을 가져오려면 OAuth 코드 흐름 설명서의 "권한 부여 코드를 사용하여 액세스 토큰 요청" 섹션에 설명된 단계를 따를 수 있습니다.

다음 단계

액세스 토큰에 대해 자세히 알아봅니다.
id_token 및 클레임에 대해 자세히 알아봅니다.

Last updated on 2019-09-05

다음을 통해 공유

OpenID Connect 및 Azure Active Directory를 사용하여 웹 애플리케이션에 대한 액세스 권한 부여

AD 테넌트에 애플리케이션 등록

OpenID Connect를 사용하는 인증 흐름

OpenID Connect 메타데이터 문서

로그인 요청 보내기

샘플 응답

오류 응답

권한 부여 엔드포인트 오류에 대한 오류 코드

id_token 유효성 검사

로그아웃 요청 보내기.

단일 로그아웃

토큰 획득

액세스 토큰 가져오기

성공적인 응답

오류 응답

다음 단계

추가 리소스