AD FS OpenID Connect/OAuth 흐름 및 애플리케이션 시나리오
적용 대상: AD FS 2019 이상
| 시나리오 | 시나리오 연습에 사용되는 샘플 | OAuth 2.0 흐름/권한 부여 | 클라이언트 유형 |
|---|---|---|---|
| 단일 페이지 앱 | MSAL을 사용하는 예제 | 암시적 | 공공 사업 |
| 사용자를 로그인하는 웹앱 | OWIN을 사용하는 예제 | 권한 부여 코드 | 퍼블릭, 비밀 |
| 웹 API를 호출하는 네이티브 앱 | MSAL을 사용하는 예제 | 권한 부여 코드 | 공공 사업 |
| 웹 API를 호출하는 웹앱 | MSAL을 사용하는 예제 | 권한 부여 코드 | 비밀 |
| PKCE 구현 | 권한 부여 코드 | 공공 사업 | |
| 사용자를 대신하여(OBO) 다른 웹 API를 호출하는 웹 API | MSAL을 사용하는 예제 | On-Behalf-Of | 비밀 역할을 하는 웹앱 |
| 웹 API를 호출하는 디먼 앱 | 클라이언트 자격 증명 | 비밀 | |
| 사용자 자격 증명을 사용하여 웹 API를 호출하는 웹앱 | 리소스 소유자 암호 자격 증명 | 퍼블릭, 비밀 | |
| 웹 API를 호출하는 브라우저 없는 앱 | 디바이스 코드 | 퍼블릭, 비밀 |
암시적 권한 부여 흐름
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 암시적 허용 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 암시적 허용 흐름을 참조하세요.
단일 페이지 애플리케이션(AngularJS, Ember.js, React.js 등)의 경우 AD FS는 OAuth 2.0 암시적 권한 부여 흐름을 지원합니다. 암시적 흐름은 OAuth 2.0 사양에서 알아볼 수 있습니다. 주요 이점은 백 엔드 서버 자격 증명 교환을 수행하지 않고도 앱에서 AD FS로부터 토큰을 가져올 수 있다는 이 있습니다. 이 흐름을 통해 앱은 사용자 로그인, 세션 유지관리, 클라이언트 JavaScript 코드 내에서 다른 웹 API에 토큰을 가져올 수 있습니다. 특히 클라이언트에 관한 암시적 흐름을 사용하는 경우 고려해야 할 몇 가지 중요한 보안 고려 사항이 있습니다.
암시적 흐름과 AD FS를 사용하여 인증을 JavaScript 앱에 추가하려면 다음 섹션의 일반 단계를 따릅니다.
프로토콜 다이어그램
다음 다이어그램에서는 전체적인 암시적 로그인 흐름을 보여 주며, 이어지는 섹션에서 각 단계에 대해 자세히 설명합니다.
요청 ID 토큰 및 액세스 토큰
처음에 사용자를 앱에 로그인하려면 OpenID Connect 인증 요청을 보내고 AD FS 엔드포인트에서 id_token 및 액세스 토큰을 가져올 수 있습니다.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| response_type | 필수 | OpenID Connect 로그인을 위한 id_token 이 포함되어야 합니다. token response_type도 포함할 수 있습니다. 여기서 토큰을 사용하면 앱에서 토큰 엔드포인트에 대한 두 번째 요청을 수행하지 않고도 승인 엔드포인트에서 액세스 토큰을 즉시 받을 수 있습니다. |
| redirect_uri | 필수 | 앱에서 인증 응답을 보내고 받을 수 있는 앱의 redirect_uri입니다. AD FS에서 구성한 redirect_uri 중 하나와 정확히 일치해야 합니다. |
| nonce | 필수 | 앱에서 생성하여 요청에 포함된 값이며, 결과 id_token에 클레임으로 포함됩니다. 그러면 앱에서 이 값을 확인하여 토큰 재생 공격을 완화할 수 있습니다. 이 값은 일반적으로 요청의 출처를 식별하는 데 사용할 수 있는 임의의 고유 문자열입니다. id_token이 요청된 경우에만 필요합니다. |
| scope | 선택 사항 | 공백으로 구분된 범위 목록입니다. OpenID Connect의 경우openid 범위를 포함해야 합니다. |
| resource | 선택 사항 | 웹 API의 URL 참고 – MSAL 클라이언트 라이브러리를 사용하는 경우 리소스 매개 변수가 전송되지 않습니다. 대신 리소스 URL이 범위 매개 변수의 일부로 전송됩니다. scope = [resource url]//[scope values e.g., openid]리소스가 여기나 범위에서 전달되지 않으면 AD FS는 기본 리소스 urn:microsoft:userinfo를 사용합니다. MFA, 발급 또는 권한 부여 정책과 같은 userinfo 리소스 정책은 사용자 지정할 수 없습니다. |
| response_mode | 선택적 | 결과 토큰을 앱으로 다시 보내는 데 사용해야 하는 메서드를 지정합니다. 기본값은 fragment입니다. |
| state | 선택 사항 | 토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 콘텐츠의 문자열일 수 있습니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 state는 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 페이지 또는 보기)를 인코딩하는 데 사용됩니다. |
| prompt | 선택적 | 필요한 사용자 상호 작용 유형을 나타냅니다. 현재 유효한 값은 로그인뿐이며 아무 것도 없습니다. - prompt=login은(는) 사용자가 해당 요청에 자격 증명을 입력하도록 하여 Single Sign-On을 무효화합니다. - prompt=none은(는) 반대의 경우로, 사용자에게 대화형 프롬프트가 표시되지 않습니다. Single Sign-on을 통해 요청을 자동으로 완료할 수 없으면 AD FS에서 interaction_required 오류를 반환합니다. |
| login_hint | 선택적 | 사용자 이름을 미리 알고 있는 경우 사용자 로그인 페이지의 사용자 이름/이메일 주소 필드를 미리 채우는 데 사용할 수 있습니다. 앱에서 다시 인증하는 동안 이 매개 변수를 사용하는 경우가 많으며, id_token의 upn 클레임을 사용하여 이전 로그인에서 사용자 이름을 이미 추출했습니다. |
| domain_hint | 선택 사항 | 포함되는 경우 사용자가 로그인 페이지에서 수행하는 도메인 기반 검색 프로세스를 건너뛰어 약간 더 간소화된 사용자 환경을 제공합니다. |
이 시점에서 사용자에게 자격 증명을 입력하고 인증을 완료하라는 메시지가 표시됩니다. 사용자가 인증되면 AD FS 권한 부여 엔드포인트에서 response_mode 매개 변수에 지정된 메서드를 사용하여 표시된 redirect_uri에서 앱에 대한 응답을 반환합니다.
성공적인 응답
response_mode=fragment and response_type=id_token+token을(를) 사용한 성공적인 응답은 다음과 같습니다.
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| 매개 변수 | 설명 |
|---|---|
| access_token | response_type에 token이(가) 포함된 경우 포함됩니다. |
| token_type | response_type에 token이(가) 포함된 경우 포함됩니다. 항상 '전달자'입니다. |
| expires_in | response_type에 token이(가) 포함된 경우 포함됩니다. 캐싱을 위해 토큰이 유효한 시간(초)을 나타냅니다. |
| scope | access_token이 유효한 범위를 나타냅니다. |
| id_token | response_type에 id_token이(가) 포함된 경우 포함됩니다. 서명된 JWT(JSON 웹 토큰)입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. |
| state | state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
새로 고침 토큰
암시적 허용은 새로 고침 토큰을 제공하지 않습니다. id_tokens및 access_tokens는 모두 짧은 시간 후에 만료되므로 앱에서 이러한 토큰을 주기적으로 새로 고칠 수 있도록 준비해야 합니다. 토큰 형식 중 하나를 새로 고치려면 prompt=none 매개 변수를 통해 이전 섹션의 숨겨진 iframe 요청을 수행하여 ID 플랫폼의 동작을 제어할 수 있습니다. new id_token을 받으려면response_type=id_token을 사용해야 합니다.
인증 코드 부여 흐름
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 인증 코드 권한 부여 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 인증 코드 권한 부여 흐름을 참조하세요.
웹앱에서 OAuth 2.0 인증 코드 부여를 사용하여 웹 API와 같은 보호된 리소스에 액세스할 수 있습니다. OAuth 2.0 인증 코드 흐름은 OAuth 2.0 사양의 섹션 4.1에서 설명합니다. 웹앱 및 기본적으로 설치된 앱을 포함하여 대부분의 앱 유형에서 인증 및 권한 부여를 수행하는 데 사용됩니다. 이 흐름을 통해 앱에서 AD FS를 신뢰하는 리소스에 액세스하는 데 사용할 수 있는 access_token을 안전하게 획득할 수 있습니다.
프로토콜 다이어그램
네이티브 애플리케이션의 인증 흐름은 개략적으로 다음과 같습니다.
인증 코드 요청
인증 코드 흐름은 클라이언트에서 사용자를 /authorization 엔드포인트에 연결하면서 시작됩니다. 이 요청에서 클라이언트는 사용자로부터 획득해야 하는 권한을 나타냅니다.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| response_type | 필수 | 인증 코드 흐름에 대한 코드를 포함해야 합니다. |
| redirect_uri | 필수 | 앱에서 인증 응답을 보내고 받을 수 있는 앱의 redirect_uri입니다. AD FS에서 클라이언트에 대해 등록한 redirect_uri 중 하나와 정확히 일치해야 합니다. |
| resource | 선택 사항 | 웹 API의 URL 참고 – MSAL 클라이언트 라이브러리를 사용하는 경우 리소스 매개 변수가 전송되지 않습니다. 대신 리소스 URL이 범위 매개 변수의 일부로 전송됩니다. scope = [resource url]//[scope values e.g., openid]리소스가 여기나 범위에서 전달되지 않으면 AD FS는 기본 리소스 urn:microsoft:userinfo를 사용합니다. MFA, 발급 또는 권한 부여 정책과 같은 userinfo 리소스 정책은 사용자 지정할 수 없습니다. |
| scope | 선택 사항 | 공백으로 구분된 범위 목록입니다. |
| response_mode | 선택적 | 결과 토큰을 앱으로 다시 보내는 데 사용해야 하는 메서드를 지정합니다. 다음 방법 중 하나일 수 있습니다. - query - fragment - form_post query 이는 리디렉션 URI에서 쿼리 문자열 매개 변수로 코드를 제공합니다. 코드를 요청하는 경우 query, fragment 또는 form_post 사용할 수 있습니다. form_post는 리디렉션 URI에 대한 코드가 포함된 POST를 실행합니다. |
| state | 선택 사항 | 토큰 응답에도 반환되는 요청에 포함된 값입니다. 원하는 콘텐츠의 문자열일 수 있습니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하기 위해 임의로 생성된 고유 값이 사용됩니다. 또한 이 값은 인증 요청이 발생하기 전에 앱에서 사용자 상태에 대한 정보(예: 페이지 또는 보기)를 인코딩할 수도 있습니다. |
| prompt | 선택적 | 필요한 사용자 상호 작용 유형을 나타냅니다. 현재 유효한 값은 로그인뿐이며 아무 것도 없습니다. - prompt=login은(는) 사용자가 해당 요청에 자격 증명을 입력하도록 하여 Single Sign-On을 무효화합니다. - prompt=none은(는) 반대의 경우로, 사용자에게 대화형 프롬프트가 표시되지 않습니다. Single Sign-on을 통해 요청을 자동으로 완료할 수 없으면 AD FS에서 interaction_required 오류를 반환합니다. |
| login_hint | 선택적 | 사용자 이름을 미리 알고 있는 경우 사용자 로그인 페이지의 사용자 이름/이메일 주소 필드를 미리 채우는 데 사용할 수 있습니다. 앱에서 다시 인증하는 동안 이 매개 변수를 사용하는 경우가 많으며, id_token의 upn 클레임을 사용하여 이전 로그인에서 사용자 이름을 이미 추출했습니다. |
| domain_hint | 선택 사항 | 포함되는 경우 사용자가 로그인 페이지에서 수행하는 도메인 기반 검색 프로세스를 건너뛰어 약간 더 간소화된 사용자 환경을 제공합니다. |
| code_challenge_method | 선택 사항 | code_challenge 매개 변수의 code_verifier를 인코딩하는 데 사용되는 메서드입니다. 다음 값 중 하나일 수 있습니다. - plain - S256, 제외된 경우, code_challenge이(가) 포함된 경우 code_challenge는 일반 텍스트로 간주합니다. AD FS는 일반 및 S256을 모두 지원합니다. 자세한 내용은 PKCE RFC를 참조하세요. |
| code_challenge | 선택 사항 | 네이티브 클라이언트에서 PKCE(코드 교환용 증명 키)를 통해 인증 코드 부여를 보호하는 데 사용됩니다. code_challenge_method가 포함되면 필수입니다. 자세한 내용은 PKCE RFC를 참조하세요. |
이 시점에서 사용자에게 자격 증명을 입력하고 인증을 완료하라는 메시지가 표시됩니다. 사용자가 인증되면 AD FS에서 response_mode 매개 변수에 지정된 메서드를 사용하여 표시된 redirect_uri에서 앱에 대한 응답을 반환합니다.
성공적인 응답
response_mode=query를 사용한 성공적인 응답은 다음과 같습니다.
GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| 매개 변수 | 설명 |
|---|---|
| 코드 | 앱에서 요청한 authorization_code입니다. 앱에서 권한 부여 코드를 사용하여 대상 리소스에 대한 액세스 토큰을 요청할 수 있습니다. authorization_code는 수명이 짧으며, 일반적으로 약 10분 후에 만료됩니다. |
| state | state 매개 변수가 요청에 포함된 경우 동일한 값이 응답에 표시됩니다. 앱은 요청과 응답의 상태 값이 동일한지 확인해야 합니다. |
액세스 토큰 요청
이제 authorization_code을(를) 획득하고 사용자가 권한을 부여했으므로 access_token에 대한 코드를 원하는 리소스로 사용할 수 있습니다. /token 엔드포인트에 POST 요청을 보내 코드를 사용합니다.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| grant_type | 필수 | 인증 코드 흐름에 대한 authorization_code 여야 합니다. |
| 코드 | 필수 | 흐름의 첫 번째 레그에서 획득한 authorization_code입니다. |
| redirect_uri | 필수 | authorization_code을(를) 획득하는 데 사용된 것과 동일한 redirect_uri 값입니다. |
| client_secret | 웹앱의 경우 필수 | AD FS에서 앱을 등록하는 동안 만든 애플리케이션 비밀입니다. client_secret을 디바이스에 안정적으로 저장할 수 없으므로 네이티브 앱에서 애플리케이션 비밀을 사용하면 안 됩니다. client_secret을 서버 쪽에 안전하게 저장할 수 있는 웹앱 및 웹 API에 필요합니다. 클라이언트 암호는 보내기 전에 URL로 인코딩해야 합니다. 이러한 앱은 JWT에 서명하고 이를 client_assertion 매개 변수로 추가하여 키 기반 인증을 사용할 수도 있습니다. |
| code_verifier | 선택 사항 | authorization_code를 가져오는 데 사용된 것과 동일한 code_verifier입니다. PKCE를 인증 코드 부여 요청에 사용한 경우에 필요합니다. 자세한 내용은 PKCE RFC를 참조하세요. 이 옵션은 AD FS 2019 이상에 적용됩니다. |
성공적인 응답
성공적인 토큰 응답은 다음과 같습니다.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| 매개 변수 | 설명 |
|---|---|
| access_token | 요청된 액세스 토큰입니다. 앱에서 이 토큰을 사용하여 보안 리소스(웹 API)를 인증할 수 있습니다. |
| token_type | 토큰 형식 값을 나타냅니다. AD FS에서 지원하는 유일한 형식은 Bearer입니다. |
| expires_in | 액세스 토큰의 유효 기간(초)입니다. |
| refresh_token | OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 더 많은 액세스 토큰을 획득할 수 있습니다. refresh_token은 수명이 길며, 리소스에 대한 액세스를 오랫동안 유지하는 데 사용할 수 있습니다. |
| refresh_token_expires_in | 새로 고침 토큰의 유효 기간(초)입니다. |
| id_token | JWT(JSON 웹 토큰)입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. |
액세스 토큰 사용
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
토큰 부여 흐름 새로 고침
access_token은 수명이 짧으며, 만료된 후 새로 고쳐야 리소스에 계속 액세스할 수 있습니다. 이렇게 하려면 다른 POST 요청을 /token엔드포인트에 제출합니다. 이번에는 코드 대신 refresh_token을 제공합니다. 새로 고침 토큰은 클라이언트에서 이미 액세스 토큰을 받은 모든 권한에 유효합니다.
새로 고침 토큰에는 지정된 수명이 없습니다. 일반적으로 새로 고침 토큰의 수명은 비교적 깁니다. 그러나 경우에 따라 새로 고침 토큰이 만료되거나, 해지되거나, 원하는 작업에 대한 충분한 권한이 없습니다. 애플리케이션은 토큰 발급 엔드포인트에서 반환하는 오류를 예상하고 정확히 처리해야 합니다.
새 액세스 토큰을 획득하는 데 사용할 때 새로 고침 토큰이 해지되지 않지만, 이전의 새로 고침 토큰은 삭제해야 합니다. OAuth 2.0 사양에 따라 표시되는 메시지: '권한 부여 서버는 신규 새로 고침 토큰을 발급할 수 있습니다. 이 경우 클라이언트는 이전 새로 고침 토큰을 삭제하고 신규 새로 고침 토큰으로 바꿔야 합니다. 권한 부여 서버는 클라이언트에 새 새로 고침 토큰을 발급한 후 이전 새로 고침 토큰을 해지할 수 있습니다.' 새 새로 고침 토큰 수명이 이전 새로 고침 토큰 수명보다 길면 AD FS에서 새로 고침 토큰을 발급합니다. AD FS 새로 고침 토큰 수명에 대한 추가 정보를 보려면 AD FS SSO(Single Sign On) 설정을 참조하세요.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| grant_type | 필수 | 이 인증 코드 흐름 범례에 대한 refresh_token 이어야 합니다. |
| resource | 선택 사항 | 웹 API의 URL 참고 – MSAL 클라이언트 라이브러리를 사용하는 경우 리소스 매개 변수가 전송되지 않습니다. 대신 리소스 URL이 범위 매개 변수의 일부로 전송됩니다. scope = [resource url]//[scope values e.g., openid]리소스가 여기나 범위에서 전달되지 않으면 AD FS는 기본 리소스 urn:microsoft:userinfo를 사용합니다. MFA, 발급 또는 권한 부여 정책과 같은 userinfo 리소스 정책은 사용자 지정할 수 없습니다. |
| scope | 선택 사항 | 공백으로 구분된 범위 목록입니다. |
| refresh_token | 필수 | 흐름의 두 번째 레그에서 획득한 refresh_token입니다. |
| client_secret | 웹앱의 경우 필수 | 앱에 대한 앱 등록 포털에서 만든 애플리케이션 비밀입니다. 디바이스에 client_secret을 안정적으로 저장할 수 없으므로 네이티브 앱에서는 사용하면 안 됩니다. client_secret을 서버 쪽에 안전하게 저장할 수 있는 웹앱 및 웹 API에 필요합니다. 이러한 앱은 JWT에 서명하고 이를 client_assertion 매개 변수로 추가하여 키 기반 인증을 사용할 수도 있습니다. |
성공적인 응답
성공적인 토큰 응답은 다음과 같습니다.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| 매개 변수 | 설명 |
|---|---|
| access_token | 요청된 액세스 토큰입니다. 앱에서 이 토큰을 사용하여 보안 리소스(예: 웹 API)를 인증할 수 있습니다. |
| token_type | 토큰 형식 값을 나타냅니다. AD FS에서 지원하는 유일한 형식은 Bearer입니다. |
| expires_in | 액세스 토큰의 유효 기간(초)입니다. |
| scope | access_token의 유효 범위입니다. |
| refresh_token | OAuth 2.0 새로 고침 토큰입니다. 앱은 현재 액세스 토큰이 만료된 후 이 토큰을 사용하여 더 많은 액세스 토큰을 획득할 수 있습니다. refresh_token은 수명이 길며, 리소스에 대한 액세스를 오랫동안 유지하는 데 사용할 수 있습니다. |
| refresh_token_expires_in | 새로 고침 토큰의 유효 기간(초)입니다. |
| id_token | JWT(JSON 웹 토큰)입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. |
OAuth에 PKCE(코드 교환용 증명 키) 지원
인증 코드 권한 부여를 사용하는 OAuth 공용 클라이언트는 RFC 7636에 설명된 대로 인증 코드 가로채기 공격에 취약합니다. 이러한 공격을 완화하기 위해 Windows Server 2019부터 AD FS는 이제 OAuth 인증 코드 권한 부여 흐름에 대한 PKCE(코드 교환용 증명 키)를 지원합니다.
PKCE 지원 사양에서는 OAuth 2.0 권한 부여 및 액세스 토큰 요청에 더 많은 매개 변수를 추가합니다. 다음 다이어그램에서는 클라이언트가 Windows Server 2019에서 AD FS에 연결할 때 PKCE 프로세스의 시각적 개요를 보여 줍니다.
A라는 레이블이 지정된 섹션에서 클라이언트는 code_verifier(이)라고 지정된 비밀을 만들고 기록하며, t(code_verifier)(이)라고 하는 변환된 버전의 비밀(code_challenge(이)라고도 함)을 파생시킵니다. 그런 다음, 클라이언트는 t_m변환 메서드와 함께 OAuth 2.0 권한 부여 요청에서 비밀을 보냅니다.
B라는 레이블이 지정된 섹션에서 권한 부여 엔드포인트는 평소와 같이 응답하지만 t(code_verifier) 비밀 및 변환 메서드를 기록합니다.
그런 다음 C라는 레이블이 지정된 섹션에서 클라이언트는 평소처럼 액세스 토큰 요청에서 권한 부여 코드를 보내지만 섹션 A에서 생성된 code_verifier 비밀을 포함합니다.
D라는 레이블이 지정된 섹션의 AD FS는 code_verifier 비밀을 변환하고 B 섹션의 t(code_verifier) 비밀과 비교합니다. 이 값이 같지 않으면 AD FS는 액세스를 거부합니다.
Windows Server 2019에서 동일한 규칙 정책에 대해 여러 인증 공급자를 선택하는 방법
AD FS는 이미 클레임 규칙 정책(RP)을 기반으로 하는 추가 인증 트리거를 지원합니다. 이러한 정책은 특정 RP 또는 전역 수준에서 설정할 수 있습니다. 관리자 권한으로 PowerShell을 열고 AdditionalAuthenticationRules 또는 AdditionalAuthenticationRulesFile 매개 변수를 전달하여 Set-AdfsRelyingPartyTrust cmdlet을 실행하고 특정 RP에 대한 추가 인증 정책을 설정할 수 있습니다. 이를 전역으로 설정하려면 관리자는 Set-AdfsAdditionalAuthenticationRule cmdlet을 사용할 수 있습니다. 추가 정책을 설정하면 동일한 애플리케이션에 둘 이상의 인증 공급자를 사용할 수 있습니다.
클레임 규칙은 추가 인증을 위해 인증 공급자를 선택하는 옵션을 제공합니다. 이는 고객이 공급자 간에 전환하거나 특정 애플리케이션에 대해 고유한 공급자를 요구하는 상황에서 유용합니다. 이제 Windows Server 2019를 기준으로 클레임 규칙을 사용하여 추가 인증을 위해 호출할 다른 인증 공급자를 결정할 수 있습니다. 이 기능은 다음과 같은 두 시나리오에 유용합니다.
사용자가 한 추가 인증 공급자에서 다른 인증 공급자로 전환하려 합니다. 사용자를 최신 인증 공급자에게 온보딩할 때 그룹을 사용하여 호출되는 추가 인증 공급자를 제어할 수 있습니다.
사용자는 특정 애플리케이션에 대한 특정 추가 인증 공급자가 필요하지만 다른 애플리케이션에서는 또 다른 방법을 사용해야 합니다.
다른 인증 정책에서 다음 명령을 실행하여 이러한 설정을 구성할 수 있습니다.
Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );'
이 규칙을 설정하려면 다른 인증 정책에서 http://schemas.microsoft.com/claims/authnmethodsproviders 클레임을 발급해야 합니다. 이 클레임의 변수는 인증 공급자의 이름이어야 합니다.
사용자가 한 인증 공급자에서 다른 인증 공급자로 전환할 수 있도록 이 규칙 구성을 수정할 수도 있습니다. 예를 들어 Azure AD MFA를 사용하도록 관리하는 그룹 하나와 인증서를 추가 인증 공급자로 사용하도록 한 그룹을 수정하려고 합니다.
Azure AD MFA 및 인증서 인증에 등록하는 사용자 수를 추적하려면 다음과 같은 명령을 실행하여 값을 조직과 관련된 값으로 바꿉니다.
'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-608905689-872870963-3921916988-12345"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");
not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value=="S-1-5-21-608905689-872870963-3921916988-12345"]) => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");’
다음으로, 다음 명령을 실행하여 Azure AD MultiFactor Authentication을 추가 인증 공급자로 사용하도록 첫 번째 애플리케이션 AppA을(를) 설정할 수 있습니다.
Set-AdfsRelyingPartyTrust -TargetName AppA -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");'
마지막으로 다음 명령을 실행하여 인증서를 추가 인증 공급자로 사용하도록 두 번째 앱인 AppB을(를) 설정할 수 있습니다.
Set-AdfsRelyingPartyTrust -TargetName AppB -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");'
관리자는 둘 이상의 추가 인증 공급자를 허용하는 규칙을 만들 수도 있습니다. 이 경우 AD FS는 발급된 인증 메서드 공급자를 표시하며 사용자는 해당 공급자 중 하나를 선택할 수 있습니다. 여러 개의 추가 인증 공급자를 허용하려면 http://schemas.microsoft.com/claims/authnmethodsproviders 값을 사용하여 여러 클레임을 발급해야 합니다.
클레임 평가에서 인증 공급자를 반환하지 않는 경우, AD FS는 롤백하고 AD FS에서 관리자가 구성한 모든 추가 인증 공급자를 보여 주는 목록을 표시합니다. 그런 다음 사용자는 적절한 인증 공급자를 수동으로 선택해야 합니다.
기본 인증 공급자가 목록에 없는 경우 다음 cmdlet을 실행하여 지원되는 모든 공급자를 볼 수 있습니다.
(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
http://schemas.microsoft.com/claims/authnmethodsproviders 클레임에 사용하는 값은 반환된 공급자 AD FS 목록에서 반환된 공급자 이름 중 하나여야 합니다.
RP가 AD FS Windows Server 2016의 액세스 제어 정책을 사용하는 동안 AD FS는 특정 추가 인증 공급자 트리거를 지원하지 않습니다. 액세스 제어 정책에서 애플리케이션을 이동하면 AD FS는 액세스 제어 정책에서 해당 정책을 AdditionalAuthenticationRules 및 IssuanceAuthorizationRules로 복사합니다. 관리자가 특정 인증 공급자를 사용하려는 경우 액세스 제어 정책 사용을 중지하고 대신 AdditionalAuthenticationRules를 수정해야 합니다.
On-Behalf-Of 흐름
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 On-Behalf-Of 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 On-Behalf-Of 흐름을 참조하세요.
OAuth 2.0 OBO(On-Behalf-Of) 흐름은 애플리케이션에서 서비스/웹 API를 호출하고, 이에 따라 다른 서비스/웹 API를 호출해야 하는 사용 사례를 처리합니다. 요청 체인을 통해 위임된 사용자 ID 및 사용 권한을 전파하는 개념입니다. 중간 계층 서비스에서 다운스트림 서비스에 인증된 요청을 수행하려면 사용자를 대신하여 AD FS에서 액세스 토큰을 보호해야 합니다.
프로토콜 다이어그램
이전 섹션에서 설명한 OAuth 2.0 인증 코드 부여 흐름을 사용하여 애플리케이션에서 사용자를 인증했다고 가정합니다. 이 시점에서 애플리케이션에는 중간 계층 웹 API(API A) 액세스에 대한 사용자의 클레임 및 동의가 있는 API A에 대한 액세스 토큰(토큰 A)이 있습니다. 클라이언트에서 토큰의 user_impersonation 범위를 요청하는지 확인합니다. 이제 API A는 다운스트림 웹 API(API B)에 인증된 요청을 수행해야 합니다.
다음 단계는 OBO 흐름을 구성하며, 다음 다이어그램의 지원을 통해 설명됩니다.
- 클라이언트 애플리케이션은 토큰 A를 사용하여 API A에 요청합니다. 참고: AD FS에서 OBO 흐름을 구성하는 동안
user_impersonation범위가 선택되어 있고 클라이언트가 요청에서user_impersonation범위를 요청하는지 확인합니다. - API A는 AD FS 토큰 발급 엔드포인트에 인증하고 API B에 액세스하기 위해 토큰을 요청합니다. 참고: AD FS에서 이 흐름을 구성하는 동안 API A도 API A의 리소스 ID와 동일한 값을 가진 clientID를 사용하여 서버 애플리케이션으로 등록되어 있는지 확인합니다.
- AD FS 토큰 발급 엔드포인트에서 토큰 A를 사용하여 API A의 자격 증명에 대한 유효성을 검사하고, API B(토큰 B)에 대한 액세스 토큰을 발급합니다.
- 토큰 B가 API B에 대한 요청의 권한 부여 헤더에 설정됩니다.
- API B에서 보안 리소스의 데이터를 반환합니다.
서비스 간 액세스 토큰 요청
액세스 토큰을 요청하려면 다음 매개 변수를 사용하여 AD FS 토큰 엔드포인트에 대한 HTTP POST를 수행합니다.
첫 번째 사례: 공유 암호를 사용한 액세스 토큰 요청
공유 비밀의 경우 서비스 간 액세스 토큰 요청에 포함되는 매개 변수는 다음과 같습니다.
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| grant_type | 필수 | 토큰 요청의 유형입니다. JWT를 사용하는 요청의 경우 값은 urn:ietf:params:oauth:grant-type:jwt-bearer여야 합니다. |
| client_id | 필수 | 첫 번째 웹 API를 서버 앱(중간 계층 앱)으로 등록할 때 구성하는 클라이언트 ID입니다. 첫 번째 레그, 즉 첫 번째 웹 API의 URL에서 사용된 리소스 ID와 동일해야 합니다. |
| client_secret | 필수 | AD FS에서 서버 앱을 등록하는 동안 만든 애플리케이션 비밀입니다. |
| assertion | 필수 | 요청에 사용된 토큰의 값입니다. |
| requested_token_use | 필수 | 요청을 처리하는 방법을 지정합니다. OBO 흐름에서 이 값은 on_behalf_of로 설정해야 합니다. |
| resource | 필수 | 첫 번째 웹 API를 서버 앱(중간 계층 앱)으로 등록하는 동안 제공된 리소스 ID입니다. 이 리소스 ID는 클라이언트를 대신하여 앱에서 호출하는 두 번째 웹 API 중간 계층의 URL이어야 합니다. |
| scope | 선택 사항 | 공백으로 구분된 토큰 요청에 대한 범위의 목록입니다. |
예시
다음 HTTP POST에서 액세스 토큰 및 새로 고침 토큰을 요청합니다.
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
두 번째 사례: 인증서를 사용한 액세스 토큰 요청
인증서를 사용하는 서비스 간 액세스 토큰 요청에 포함되는 매개 변수는 다음과 같습니다.
| 매개 변수 | 필수/선택 | 설명 |
|---|---|---|
| grant_type | 필수 | 토큰 요청의 유형입니다. JWT를 사용하는 요청의 경우 값은 urn:ietf:params:oauth:grant-type:jwt-bearer여야 합니다. |
| client_id | 필수 | 첫 번째 웹 API를 서버 앱(중간 계층 앱)으로 등록할 때 구성하는 클라이언트 ID입니다. 첫 번째 레그, 즉 첫 번째 웹 API의 URL에서 사용된 리소스 ID와 동일해야 합니다. |
| client_assertion_type | 필수 | 값은 urn:ietf:params:oauth:client-assertion-type:jwt-bearer여야 합니다. |
| client_assertion | 필수 | 애플리케이션에 대한 자격 증명으로 등록한 인증서를 사용하여 만들고 서명해야 하는 어설션(JSON 웹 토큰)입니다. |
| assertion | 필수 | 요청에 사용된 토큰의 값입니다. |
| requested_token_use | 필수 | 요청을 처리하는 방법을 지정합니다. OBO 흐름에서 이 값은 on_behalf_of로 설정해야 합니다. |
| resource | 필수 | 첫 번째 웹 API를 서버 앱(중간 계층 앱)으로 등록하는 동안 제공된 리소스 ID입니다. 이 리소스 ID는 클라이언트를 대신하여 앱에서 호출하는 두 번째 웹 API 중간 계층의 URL이어야 합니다. |
| scope | 선택 사항 | 공백으로 구분된 토큰 요청에 대한 범위의 목록입니다. |
매개 변수는 거의 동일합니다. 이 예제는 client_secret 매개 변수가 client_assertion_type과 client_assertion이라는 두 매개 변수로 대체된다는 점을 제외하고 공유 비밀을 통한 요청과 유사합니다.
예시
인증서를 사용하여 웹 API에 대한 액세스 토큰을 요청하는 HTTP POST는 다음과 같습니다.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
서비스 간 액세스 토큰 응답
성공 응답은 다음 매개 변수가 JSON OAuth 2.0 응답입니다.
| 매개 변수 | 설명 |
|---|---|
| token_type | 토큰 형식 값을 나타냅니다. AD FS에서 지원하는 유일한 형식은 Bearer입니다. |
| scope | 토큰에 부여된 액세스의 범위입니다. |
| expires_in | 액세스 토큰의 유효 시간(초)입니다. |
| access_token | 요청된 액세스 토큰입니다. 호출 서비스에서 이 토큰을 사용하여 수신 서비스를 인증할 수 있습니다. |
| id_token | JWT(JSON 웹 토큰)입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. |
| refresh_token | 요청된 액세스 토큰에 대한 새로 고침 토큰입니다. 현재 액세스 토큰이 만료되면 호출 서비스에서 이 토큰을 사용하여 다른 액세스 토큰을 요청할 수 있습니다. |
| Refresh_token_expires_in | 새로 고침 토큰의 유효 시간(초)입니다. |
성공 응답 예제
다음 예제에서는 웹 API용 액세스 토큰 요청에 대한 성공 응답을 보여 줍니다.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
액세스 토큰을 사용하여 보안 리소스에 액세스합니다. 이제 중간 계층 서비스는 인증 헤더에 토큰을 설정하여 이전 응답 예제에서 획득한 토큰을 통해 다운스트림 웹 API에 인증된 요청을 수행할 수 있습니다.
예시
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
클라이언트 자격 증명 부여 흐름
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 클라이언트 자격 증명 권한 부여 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 클라이언트 자격 증명 권한 부여 흐름을 참조하세요.
RFC 6749에 지정된 OAuth 2.0 클라이언트 자격 증명 권한 부여를 사용하여 애플리케이션의 ID를 통해 웹 호스팅 리소스에 액세스할 수 있습니다. 이 유형의 권한 부여는 일반적으로 사용자의 직접적인 상호 작용 없이 백그라운드에서 실행해야 하는 서버 간 상호 작용에 사용됩니다. 이러한 유형의 애플리케이션은 종종 디먼 또는 서비스 계정이라고 합니다.
OAuth 2.0 클라이언트 자격 증명 부여 흐름은 사용자를 가장하는 대신 다른 웹 서비스를 호출할 때 웹 서비스(기밀 클라이언트)가 자체 자격 증명을 사용하여 인증하도록 허용합니다. 이 시나리오에서 클라이언트는 일반적으로 중간 계층 웹 서비스, 디먼 서비스 또는 웹 사이트입니다. 또한 AD FS는 더 높은 수준의 보증을 위해 호출 서비스에서 공유 비밀 대신 인증서를 자격 증명으로 사용할 수 있습니다.
프로토콜 다이어그램
다음 다이어그램에서는 클라이언트 자격 증명 부여 흐름을 보여 줍니다.
토큰 요청
클라이언트 자격 증명 부여를 사용하여 토큰을 가져오려면 POST 요청을 /token AD FS 엔드포인트에 보냅니다.
첫 번째 사례: 공유 암호를 사용한 액세스 토큰 요청
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| scope | 선택 사항 | 사용자가 동의하게 할 공백으로 구분된 범위 목록입니다. |
| client_secret | 필수 | 앱 등록 포털에서 앱에 대해 생성한 클라이언트 암호입니다. 클라이언트 암호는 보내기 전에 URL로 인코딩해야 합니다. |
| grant_type | 필수 | client_credentials로 설정해야 합니다. |
두 번째 사례: 인증서를 사용한 액세스 토큰 요청
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_assertion_type | 필수 | 값은 urn:ietf:params:oauth:client-assertion-type:jwt-bearer로 설정해야 합니다. |
| client_assertion | 필수 | 애플리케이션에 대한 자격 증명으로 등록한 인증서를 사용하여 만들고 서명해야 하는 어설션(JSON 웹 토큰)입니다. |
| grant_type | 필수 | client_credentials로 설정해야 합니다. |
| client_id | 선택 사항 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. client_assertion의 일부이므로 여기에 전달할 필요가 없습니다. |
| scope | 선택 사항 | 사용자가 동의하게 할 공백으로 구분된 범위 목록입니다. |
토큰 사용
이제 토큰을 획득했으므로 토큰을 사용하여 리소스에 대한 요청을 수행합니다. 토큰이 만료되면 /token 엔드포인트에 요청을 반복하여 새 액세스 토큰을 획득합니다.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
리소스 소유자 암호 자격 증명 부여 흐름(추천되지 않음)
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 리소스 소유자 암호 자격 증명 권한 부여 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 리소스 소유자 암호 자격 증명 권한 부여 흐름을 참조하세요.
ROPC(리소스 소유자 암호 자격 증명) 부여를 사용하면 애플리케이션에서 사용자의 암호를 직접 처리하여 사용자를 로그인할 수 있습니다. ROPC 흐름에는 높은 수준의 신뢰와 사용자 공개가 필요하며, 더 안전한 다른 흐름을 사용할 수 없는 경우에만 이 흐름을 사용해야 합니다.
프로토콜 다이어그램
다음 다이어그램에서는 ROPC 흐름을 보여 줍니다.
권한 부여 요청
ROPC 흐름은 단일 요청입니다. 즉, 클라이언트 ID 및 사용자의 자격 증명을 IDP로 보낸 다음, 응답으로 토큰을 받습니다. 이렇게 하려면 먼저 클라이언트에서 사용자의 이메일 주소(UPN) 및 암호를 요청해야 합니다. 요청이 성공하는 즉시 클라이언트는 메모리에서 사용자의 자격 증명을 안전하게 해제해야 합니다. 이를 저장하면 안 됩니다.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| 매개 변수 | 필수/선택 사항 | 설명 |
|---|---|---|
| client_id | 필수 | 클라이언트 ID |
| grant_type | 필수 | 암호로 설정해야 합니다. |
| 사용자 이름 | 필수 | 사용자의 전자 메일 주소입니다. |
| password | 필수 | 사용자의 암호입니다. |
| scope | 선택 사항 | 공백으로 구분된 범위 목록입니다. |
성공적인 인증 응답
다음 예제에서는 성공적인 토큰 응답을 보여 줍니다.
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| 매개 변수 | 설명 |
|---|---|
| token_type | 항상 전달자로 설정합니다. |
| scope | 액세스 토큰이 반환된 경우 이 매개 변수는 액세스 토큰의 유효 범위를 나열합니다. |
| expires_in | 포함된 액세스 토큰의 유효 시간(초)입니다. |
| access_token | 요청된 범위에 대해 발급되었습니다. |
| id_token | JWT(JSON 웹 토큰)입니다. 앱에서 이 토큰의 세그먼트를 디코딩하여 로그인한 사용자에 대한 정보를 요청할 수 있습니다. 앱에서 값을 캐시하고 표시할 수 있지만, 권한 부여 또는 보안 경계에 이러한 값을 사용하지 않아야 합니다. |
| refresh_token_expires_in | 포함된 새로 고침 토큰의 유효 시간(초)입니다. |
| refresh_token | 원본의 범위 매개 변수에 offline_access가 포함된 경우 발급됩니다. |
이 문서의 인증 코드 권한 부여 흐름 섹션에서 설명한 것과 동일한 흐름을 사용하여 새로 고침 토큰을 통해 새 액세스 토큰을 획득하고 토큰을 새로 고칠 수 있습니다.
디바이스 코드 흐름
참고 항목
Microsoft는 최신 AD FS 버전으로 업그레이드하는 대신 Microsoft Entra ID로 마이그레이션하는 것이 좋습니다. Microsoft Entra ID의 디바이스 코드 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼의 디바이스 코드 흐름을 참조하세요.
디바이스 코드 부여를 사용하면 사용자가 스마트 TV, IoT 디바이스 또는 프린터와 같은 입력 제한 디바이스에 로그인할 수 있습니다. 이 흐름을 사용하도록 설정하기 위해 디바이스에서 사용자가 다른 디바이스의 브라우저에 있는 웹 페이지를 방문하여 로그인하도록 합니다. 사용자가 로그인하면 디바이스에서 액세스 토큰을 가져오고 필요에 따라 해당 토큰을 새로 고칠 수 있습니다.
프로토콜 다이어그램
전체 디바이스 코드 흐름은 다음 다이어그램과 비슷합니다. 이 문서의 뒷부분에서 각 단계에 대해 설명합니다.
디바이스 권한 부여 요청
클라이언트에서 먼저 인증을 시작하는 데 사용되는 디바이스 및 사용자 코드에 대한 인증 서버를 확인해야 합니다. 클라이언트는 /devicecode 엔드포인트에서 이 요청을 수집합니다. 이 요청에서 클라이언트는 사용자로부터 획득해야 하는 권한도 포함해야 합니다. 사용자는 이 요청을 보낸 시점부터 15분(일반적인 terms_in 값) 동안만 로그인할 수 있으므로 사용자가 로그인할 준비가 되었음을 나타내는 경우에만 이 요청을 수행합니다.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
scope=openid
| 매개 변수 | Condition | 설명 |
|---|---|---|
| client_id | 필수 | AD FS에서 앱에 할당한 애플리케이션(클라이언트) ID입니다. |
| scope | 선택 사항 | 공백으로 구분된 범위 목록입니다. |
디바이스 권한 부여 응답
성공적인 응답은 사용자가 로그인하는 데 필요한 정보가 포함된 JSON 개체입니다.
| 매개 변수 | 설명 |
|---|---|
| device_code | 클라이언트와 권한 부여 서버 간의 세션을 확인하는 데 사용되는 긴 문자열입니다. 클라이언트에서 이 매개 변수를 사용하여 권한 부여 서버의 액세스 토큰을 요청합니다. |
| user_code | 보조 디바이스의 세션을 식별하는 데 사용되어 사용자에게 표시되는 짧은 문자열입니다. |
| verification_uri | 로그인하려면 사용자는 user_code가 포함된 URL을 사용해야 합니다. |
| verification_uri_complete | 로그인하려면 사용자는 user_code가 포함된 URL을 사용해야 합니다. user_code를 사용하여 미리 채워져 있으므로 사용자가 user_code를 입력할 필요가 없습니다. |
| expires_in | device_code 및 user_code가 만료될 때까지의 시간(초)입니다. |
| interval | 클라이언트에서 폴링 요청 간에 가 대기해야 하는 시간(초)입니다. |
| message | 사용자를 위한 지침이 포함된 사람이 읽을 수 있는 문자열입니다. 이는 쿼리 매개 변수를 ?mkt=xx-XX 형식의 요청에 포함시키고 해당 언어 문화권 코드를 입력하여 현지화할 수 있습니다. |
사용자 인증
user_code 및 verification_uri를 받은 후 클라이언트에서 사용자에게 이러한 세부 사항을 표시하여 휴대폰 또는 PC 브라우저를 통해 로그인하도록 지시합니다. 또한 클라이언트에서 QR 코드 또는 비슷한 메커니즘을 사용하여 verfication_uri_complete을 표시할 수 있습니다. 이 경우 사용자에 대한 user_code를 입력하는 단계가 수행됩니다.
사용자가 verification_uri에서 인증하는 동안 클라이언트에서 device_code를 사용하여 요청된 토큰에 대한 /token 엔드포인트를 폴링해야 합니다.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 00001111-aaaa-2222-bbbb-3333cccc4444
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| 매개 변수 | 필수 | 설명 |
|---|---|---|
| grant_type | 필수 | urn:ietf:params:oauth:grant-type:device_code여야 합니다. |
| client_id | 필수 | 초기 요청에 사용된 client_id와 일치해야 합니다. |
| 코드 | 필수 | 디바이스 권한 부여 요청에서 반환된 device_code입니다. |
성공적인 인증 응답
성공적인 토큰 응답은 다음과 같습니다.
| 매개 변수 | 설명 |
|---|---|
| token_type | 항상 '전달자'입니다. |
| scope | 액세스 토큰이 반환된 경우 이 매개 변수는 액세스 토큰의 유효 범위를 나열합니다. |
| expires_in | 포함된 액세스 토큰이 유효하게 될 때까지의 시간(초)입니다. |
| access_token | 요청된 범위에 대해 발급되었습니다. |
| id_token | 원본의 범위 매개 변수에 openid 범위가 포함된 경우 발급됩니다. |
| refresh_token | 원본의 범위 매개 변수에 offline_access가 포함된 경우 발급됩니다. |
| refresh_token_expires_in | 포함된 새로 고침 토큰이 유효하게 될 때까지의 시간(초)입니다. |
관련 콘텐츠
관련 흐름을 사용하는 방법에 대한 단계별 지침을 제공하는 전체 연습 문서 목록은 AD FS 개발을 참조하세요.