Microsoft ID 플랫폼 및 OAuth 2.0 On-Behalf-Of 흐름
OBO(On-Behalf-Of) 흐름은 자체 ID 이외의 다른 ID를 사용하여 다른 웹 API를 호출하는 웹 API의 시나리오를 설명합니다. OAuth에서 위임이라고 하는 의도는 요청 체인을 통해 사용자의 ID와 권한을 전달하는 것입니다.
중간 계층 서비스에서 다운스트림 서비스에 인증된 요청을 수행하려면 Microsoft ID 플랫폼에서 액세스 토큰을 보호해야 합니다. 위임된 범위만 사용하고 애플리케이션 역할은 사용하지 않습니다. 역할은 보안 주체(사용자)에 연결된 상태로 유지되며 사용자를 대신하여 작동하는 애플리케이션에는 연결되지 않습니다. 이는 사용자가 액세스하지 않지 않아야 하는 리소스에 대한 권한을 얻지 못하도록 하기 위한 것입니다.
이 문서에서는 애플리케이션에서 프로토콜에 대해 직접 프로그래밍을 수행하는 방법을 설명합니다. 가능하다면 토큰을 획득하고 보안 웹 API를 호출하는 대신, 지원되는 MSAL(Microsoft 인증 라이브러리)을 사용하는 것이 좋습니다. 또한 예제는 MSAL을 사용하는 샘플 앱을 참조하세요.
클라이언트 제한 사항
서비스 주체가 앱 전용 토큰을 요청하여 API에 보낸 경우 해당 API는 원래 서비스 주체를 나타내지 않는 토큰을 교환합니다. 이는 OBO 흐름이 사용자 주체에 대해서만 작동하기 때문입니다. 대신 클라이언트 자격 증명 흐름을 사용하여 앱 전용 토큰을 가져와야 합니다. SPA(단일 페이지 앱)의 경우 액세스 토큰을 중간 계층 기밀 클라이언트에 전달하여 OBO 흐름을 대신 수행해야 합니다.
클라이언트에서 암시적 흐름을 사용하여 id_token을 가져오고 회신 URL에 와일드카드도 있는 경우 id_token은 OBO 흐름에 사용할 수 없습니다. 와일드카드는 * 문자로 끝나는 URL입니다. 예를 들어 https://myapp.com/*이 회신 URL인 경우 id_token은 클라이언트를 식별할 만큼 충분히 구체적이지 않으므로 사용할 수 없습니다. 이 경우 토큰이 발급되지 않습니다. 그러나 암시적 권한 부여 흐름을 통해 획득한 액세스 토큰은 시작 클라이언트에 야생 카드 회신 URL이 등록된 경우에도 기밀 클라이언트에서 사용합니다. 이는 기밀 클라이언트에서 액세스 토큰을 획득한 클라이언트를 식별할 수 있기 때문입니다. 그런 다음, 기밀 클라이언트에서 액세스 토큰을 사용하여 다운스트림 API에 대한 새 액세스 토큰을 획득할 수 있습니다.
또한 사용자 지정 서명 키가 있는 애플리케이션은 OBO 흐름에서 중간 계층 API로 사용할 수 없습니다. 여기에는 Single Sign-On용으로 구성된 엔터프라이즈 애플리케이션이 포함됩니다. 중간 계층 API에서 사용자 지정 서명 키를 사용하는 경우 다운스트림 API는 전달되는 액세스 토큰의 서명의 유효성을 검사하지 않습니다. 클라이언트에서 제어하는 키로 서명된 토큰은 안전하게 수락할 수 없으므로 오류가 발생합니다.
프로토콜 다이어그램
사용자가 OAuth 2.0 인증 코드 부여 흐름 또는 다른 로그인 흐름을 사용하여 애플리케이션을 인증한다고 가정합니다. 이 시점에서 애플리케이션에는 중간 계층 웹 API(API A) 액세스에 대한 사용자의 클레임 및 동의가 있는 API A에 대한 액세스 토큰(토큰 A)이 있습니다. 이제 API A는 다운스트림 웹 API(API B)에 인증된 요청을 수행해야 합니다.
다음 단계는 OBO 흐름을 구성하며, 다음 다이어그램의 지원을 통해 설명됩니다.
- 클라이언트 애플리케이션은 토큰 A(API A의
aud클레임 포함)를 사용하여 API A에 요청합니다. - API A는 Microsoft ID 플랫폼 토큰 발급 엔드포인트에 인증하고 API B에 액세스하기 위한 토큰을 요청합니다.
- Microsoft ID 플랫폼 토큰 발급 엔드포인트는 토큰 A와 함께 API A의 자격 증명의 유효성을 검사하고 API B에 대한 액세스 토큰(토큰 B)을 API A에 발급합니다.
- API A에 의해 토큰 B가 API B에 대한 요청의 권한 부여 헤더에 설정됩니다.
- 보안 리소스의 데이터는 API B에 의해 API A로 반환된 후 클라이언트로 반환됩니다.
이 시나리오에서 중간 계층 서비스에는 다운스트림 API에 액세스하기 위해 사용자 동의를 얻기 위한 사용자 상호 작용이 없습니다. 따라서 인증 중 동의 단계의 일부로 다운스트림 API에 대한 액세스 권한을 부여하는 옵션이 미리 제공됩니다. 앱에서 이를 구현하는 방법을 알아보려면 중간 계층 애플리케이션에 대한 동의 얻기를 참조하세요.
중간 계층 액세스 토큰 요청
액세스 토큰을 요청하려면 다음 매개 변수로 테넌트별 Microsoft ID 플랫폼 토큰 엔드포인트에 HTTP POST를 만듭니다.
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Warning
중간 계층에 발급된 액세스 토큰을 토큰에 대해 의도한 대상 그룹을 제외한 다른 곳으로 보내지 마세요. 중간 계층에 발급된 액세스 토큰은 해당 중간 계층에서만 의도한 대상 그룹 엔드포인트와 통신하는 데 사용됩니다.
클라이언트가 액세스 토큰 자체를 가져오는 대신 중간 계층 리소스에서 클라이언트로 액세스 토큰을 릴레이하면 다음과 같은 보안 위험이 있습니다.
- 손상된 SSL/TLS 채널에 대한 토큰 가로채기의 위험이 증가합니다.
- 클레임 단계가 필요한 토큰 바인딩 및 조건부 액세스 시나리오(예: MFA, 로그인 빈도)를 충족할 수 없습니다.
- 관리자가 구성한 디바이스 기반 정책(예: MDM, 위치 기반 정책)과 호환되지 않습니다.
클라이언트 애플리케이션이 공유 암호 또는 인증서 중에서 어떤 방식으로 보호되도록 선택되는지에 따라 두 가지 사례가 있습니다.
첫 번째 사례: 공유 암호를 사용한 액세스 토큰 요청
공유 비밀을 사용하는 경우 서비스 간 액세스 토큰 요청에 포함되는 매개 변수는 다음과 같습니다.
| 매개 변수 | 형식 | 설명 |
|---|---|---|
grant_type |
필수 | 토큰 요청의 유형입니다. JWT를 사용하는 요청의 경우 값은 urn:ietf:params:oauth:grant-type:jwt-bearer여야 합니다. |
client_id |
Required | Microsoft Entra 관리 센터에서 앱에 할당된 앱 등록 애플리케이션(클라이언트) ID입니다. |
client_secret |
Required | Microsoft Entra 관리 센터 - 앱 등록 페이지에서 앱에 대해 생성한 클라이언트 암호입니다. 대신 RFC 6749에 따라 권한 부여 헤더에 자격 증명을 제공하는 기본 인증 패턴도 지원됩니다. |
assertion |
Required | 중간 계층 API에 전송된 액세스 토큰입니다. 이 토큰에는 해당 OBO 요청을 수행하는 앱(client-id 필드로 표시된 앱)의 대상 그룹(aud) 클레임이 있어야 합니다. 애플리케이션에서 토큰을 다른 앱에 사용할 수 없습니다. (예를 들어 클라이언트에서 Microsoft Graph에 대한 토큰을 API에 보내는 경우 API는 OBO를 사용하여 토큰을 사용할 수 없습니다. 대신 토큰을 거부해야 합니다). |
scope |
Required | 공백으로 구분된 토큰 요청에 대한 범위의 목록입니다. 자세한 내용은 범위를 참조하세요. |
requested_token_use |
Required | 요청을 처리하는 방법을 지정합니다. OBO 흐름에서는 값을 on_behalf_of로 설정해야 합니다. |
예시
다음 HTTP POST는 user.read 범위의 https://graph.microsoft.com 웹 API용 액세스 토큰과 새로 고침 토큰을 요청합니다. 요청은 클라이언트 암호로 서명되고 기밀 클라이언트에서 수행됩니다.
//line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of
두 번째 사례: 인증서를 사용한 액세스 토큰 요청
인증서가 있는 서비스 간 액세스 토큰 요청에는 이전 예제의 매개 변수 외에도 다음 매개 변수가 포함됩니다.
| 매개 변수 | 형식 | 설명 |
|---|---|---|
grant_type |
필수 | 토큰 요청의 형식입니다. JWT를 사용하는 요청의 경우 값은 urn:ietf:params:oauth:grant-type:jwt-bearer여야 합니다. |
client_id |
Required | Microsoft Entra 관리 센터에서 앱에 할당된 앱 등록 애플리케이션(클라이언트) ID입니다. |
client_assertion_type |
Required | 값은 urn:ietf:params:oauth:client-assertion-type:jwt-bearer여야 합니다. |
client_assertion |
Required | 애플리케이션에 대한 자격 증명으로 등록한 인증서를 사용하여 만들고 서명해야 하는 어설션(JSON 웹 토큰)입니다. 인증서 등록 방법 및 어설션 형식에 대한 자세한 내용은 인증서 자격 증명을 참조하세요. |
assertion |
Required | 중간 계층 API에 전송된 액세스 토큰입니다. 이 토큰에는 해당 OBO 요청을 수행하는 앱(client-id 필드로 표시된 앱)의 대상 그룹(aud) 클레임이 있어야 합니다. 애플리케이션에서 토큰을 다른 앱에 사용할 수 없습니다. (예를 들어 클라이언트에서 MS Graph에 대한 토큰을 API에 보내는 경우 API는 OBO를 사용하여 토큰을 사용할 수 없습니다. 대신 토큰을 거부해야 합니다). |
requested_token_use |
Required | 요청을 처리하는 방법을 지정합니다. OBO 흐름에서는 값을 on_behalf_of로 설정해야 합니다. |
scope |
Required | 토큰 요청에 대해 공백으로 구분된 범위 목록입니다. 자세한 내용은 범위를 참조하세요. |
매개 변수가 두 client_assertion_type 개의 매개 변수로 대체된다는 점을 제외하고 client_secret 매개 변수는 공유 비밀에 의한 요청의 경우와 client_assertion거의 동일합니다. client_assertion_type 매개 변수는 urn:ietf:params:oauth:client-assertion-type:jwt-bearer로 설정되고, client_assertion 매개 변수는 인증서의 프라이빗 키로 서명된 JWT 토큰으로 설정됩니다.
예시
다음 HTTP POST는 인증서가 있는 user.read 범위의 https://graph.microsoft.com 웹 API용 액세스 토큰을 요청합니다. 요청은 클라이언트 암호로 서명되고 기밀 클라이언트에서 수행됩니다.
// line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access
중간 계층 액세스 토큰 응답
성공 응답은 다음 매개 변수가 JSON OAuth 2.0 응답입니다.
| 매개 변수 | 설명 |
|---|---|
token_type |
토큰 형식 값을 나타냅니다. Microsoft ID 플랫폼이 유일하게 지원하는 형식은 Bearer입니다. 전달자 토큰에 대한 자세한 내용은 OAuth 2.0 권한 부여 프레임워크: 전달자 토큰 사용(RFC 6750)을 참조하세요. |
scope |
토큰에 부여된 액세스의 범위입니다. |
expires_in |
액세스 토큰의 유효 시간(초)입니다. |
access_token |
요청된 액세스 토큰입니다. 호출 서비스에서 이 토큰을 사용하여 수신 서비스를 인증할 수 있습니다. |
refresh_token |
요청된 액세스 토큰에 대한 새로 고침 토큰입니다. 현재 액세스 토큰이 만료되면 호출 서비스에서 이 토큰을 사용하여 다른 액세스 토큰을 요청할 수 있습니다. 새로 고침 토큰은 offline_access 범위가 요청된 경우에만 제공됩니다. |
성공 응답 예제
다음 예제에서는 https://graph.microsoft.com 웹 API용 액세스 토큰 요청에 대한 성공 응답을 보여 줍니다. 응답에는 액세스 토큰과 새로 고침 토큰이 포함되며 인증서의 프라이빗 키로 서명됩니다.
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/user.read",
"expires_in": 3269,
"ext_expires_in": 0,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
"refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}
이 액세스 토큰은 Microsoft Graph에 대한 v1.0 형식의 토큰입니다. 이는 토큰 형식이 액세스되는 리소스를 기반으로 하고 리소스를 요청하는 데 사용되는 엔드포인트와 관련이 없기 때문입니다. Microsoft Graph는 v1.0 토큰을 수락하도록 설정되어 있으므로 클라이언트에서 Microsoft Graph에 대한 토큰을 요청할 때 Microsoft ID 플랫폼에서 v1.0 액세스 토큰을 생성합니다. 다른 앱은 v2.0 형식 토큰, v1.0 형식 토큰 또는 독점 또는 암호화된 토큰 형식을 원한다는 것을 나타낼 수 있습니다. v1.0 및 v2.0 엔드포인트는 모두 두 가지 토큰 형식 중 하나를 내보낼 수 있습니다. 이러한 방식으로 리소스는 클라이언트에서 토큰을 요청하는 방법 또는 위치에 관계없이 항상 올바른 형식의 토큰을 가져올 수 있습니다.
Warning
코드에서 이 예제의 토큰을 포함하여 소유하지 않은 API에 대한 토큰을 확인하거나 읽으려고 시도하지 마세요. Microsoft 서비스 토큰은 JWT로 유효성을 검사하지 않는 특수 형식을 사용할 수 있으며 소비자(Microsoft 계정) 사용자에 대해 암호화될 수도 있습니다. 토큰 읽기는 유용한 디버깅 및 학습 도구이지만 코드에서 이에 대한 종속성을 취하거나 제어하는 API용이 아닌 토큰에 대한 세부 사항을 가정하지 마세요.
오류 응답 예제
다운스트림 API에 조건부 액세스 정책(예 : 다단계 인증)이 설정된 경우 다운스트림 API에 대한 액세스 토큰을 획득하려고 할 때 토큰 엔드포인트에서 오류 응답이 반환됩니다. 중간 계층 서비스는 이 오류를 클라이언트 애플리케이션에 전달하여 클라이언트 애플리케이션이 조건부 액세스 정책을 충족하기 위한 사용자 상호 작용을 제공할 수 있도록 해야 합니다.
이 오류를 클라이언트에 다시 표시하기 위해 중간 계층 서비스는 HTTP 401 권한 없음 및 오류 및 클레임 챌린지가 포함된 WWW-Authenticate HTTP 헤더를 사용하여 회신합니다. 클라이언트는 클레임 챌린지(있는 경우)를 제시하여 이 헤더를 구문 분석하고 토큰 발급자로부터 새 토큰을 획득해야 합니다. 클라이언트는 캐시된 액세스 토큰을 사용하여 중간 계층 서비스에 액세스하기 위해 다시 시도해서는 안 됩니다.
{
"error":"interaction_required",
"error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
"error_codes":[50079],
"timestamp":"2017-05-01 22:43:20Z",
"trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
"claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}
보안 리소스에 액세스하는 데 액세스 토큰 사용
이제 중간 계층 서비스는 헤더에서 토큰을 설정하여 이전에 획득한 토큰을 사용하여 다운스트림 웹 API에 인증된 요청을 수행할 수 있습니다 Authorization .
예시
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
OAuth2.0 OBO 흐름을 통해 획득한 SAML 어설션
일부 OAuth 기반 웹 서비스는 비대화형 흐름에서 SAML 어설션을 수락하는 다른 웹 서비스 API에 액세스해야 합니다. Microsoft Entra ID는 SAML 기반 웹 서비스를 사용하는 On-Behalf-Of 흐름에 대응하여 SAML 어설션을 대상 리소스로 제공할 수 있습니다.
OAuth2 기반 애플리케이션이 SAML 토큰을 사용하는 웹 서비스 API 엔드포인트에 액세스할 수 있도록 하는 OAuth 2.0 On-Behalf-Of 흐름에 대한 비표준 확장입니다.
팁
프런트 엔드 웹 애플리케이션에서 SAML로 보호되는 웹 서비스를 호출하는 경우 간단히 API를 호출하고 사용자 기존 세션을 사용하여 일반적인 대화형 인증 흐름을 시작할 수 있습니다. 서비스 간 호출이 사용자 컨텍스트를 제공하기 위해 SAML 토큰을 요구할 경우에만 OBO 흐름을 사용해야 합니다.
공유 비밀을 통해 OBO 요청을 사용하여 SAML 토큰 가져오기
SAML 어설션에 대한 서비스 간 요청에는 다음 매개 변수가 포함됩니다.
| 매개 변수 | 형식 | 설명 |
|---|---|---|
| grant_type | 필수 | 토큰 요청의 형식입니다. JWT를 사용하는 요청의 경우 값은 urn:ietf:params:oauth:grant-type:jwt-bearer여야 합니다. |
| assertion | 필수 | 요청에 사용된 액세스 토큰 값입니다. |
| client_id | 필수 | Microsoft Entra ID에 등록하는 동안 호출 서비스에 할당된 앱 ID입니다. Microsoft Entra 관리 센터에서 앱 ID를 찾으려면 ID>애플리케이션>으로 이동한 다음앱 등록 애플리케이션 이름을 선택합니다. |
| client_secret | 필수 | Microsoft Entra ID에서 서비스를 호출하기 위해 등록된 키입니다. 이 값은 등록 시 기록해야 합니다. 대신 RFC 6749에 따라 권한 부여 헤더에 자격 증명을 제공하는 기본 인증 패턴도 지원됩니다. |
| scope | 필수 | 토큰 요청에 대해 공백으로 구분된 범위 목록입니다. 자세한 내용은 범위를 참조하세요. SAML 자체에는 범위 개념이 없지만 토큰을 받으려는 대상 SAML 애플리케이션을 식별하는 데 사용됩니다. 이 OBO 흐름에서 범위 값은 항상 /.default가 추가된 SAML 엔터티 ID여야 합니다. 예를 들어 SAML 애플리케이션의 엔터티 ID가 https://testapp.contoso.com인 경우 요청된 범위는 https://testapp.contoso.com/.default여야 합니다. 엔터티 ID가 https:와(과) 같이 URI 스키마로 시작하지 않으면 Microsoft Entra ID가 엔터티 ID에 spn: 접두사를 추가합니다. 이 경우 spn:<EntityID>/.default 범위를 요청해야 합니다. 예를 들어 엔터티 ID가 testapp이면 spn:testapp/.default입니다. 여기서 요청하는 범위 값은 SAML 토큰의 결과 Audience 요소를 결정하며 이는 토큰을 수신하는 SAML 애플리케이션에 중요할 수 있습니다. |
| requested_token_use | 필수 | 요청을 처리하는 방법을 지정합니다. On-Behalf-Of 흐름에서 이 값은 on_behalf_of여야 합니다. |
| requested_token_type | 필수 | 요청된 토큰의 형식을 지정합니다. 값은 액세스된 리소스의 요구 사항에 따라 urn:ietf:params:oauth:token-type:saml2 또는 urn:ietf:params:oauth:token-type:saml1일 수 있습니다. |
응답에는 UTF8 및 Base 64url로 인코딩된 SAML 토큰이 포함됩니다.
- OBO 호출에서 파생된 SAML 어설션에 대한 SubjectConfirmationData: 대상 애플리케이션에 값이 필요한
Recipient경우 리소스 애플리케이션 구성에서SubjectConfirmationData첫 번째 비와일드카드 회신 URL로 값을 구성해야 합니다. 기본 회신 URL은 값을 결정하는Recipient데 사용되지 않으므로 애플리케이션 구성에서 회신 URL의 순서를 변경하여 첫 번째 비와일드카드 회신 URL이 사용되는지 확인해야 할 수 있습니다. 자세한 내용은 회신 URL을 참조하세요. - SubjectConfirmationData 노드: 이 노드는 SAML 응답에 속하지 않으므로
InResponseTo특성을 포함할 수 없습니다. SAML 토큰을 수신하는 애플리케이션은InResponseTo특성이 없는 SAML 어설션을 수락할 수 있어야 합니다. - API 권한: SAML 애플리케이션의
/.default범위에 대해 토큰을 요청할 수 있도록 SAML 애플리케이션에 대해 액세스를 허용하도록 중간 계층 애플리케이션에서 필요한 API 권한을 추가해야 합니다. - 동의: OAuth 흐름에서 사용자 데이터가 포함된 SAML 토큰을 받으려면 동의를 부여해야 합니다. 자세한 내용은 중간 계층 애플리케이션에 대한 동의 얻기를 참조하세요.
SAML 어설션을 사용하여 응답
| 매개 변수 | 설명 |
|---|---|
| token_type | 토큰 형식 값을 나타냅니다. Microsoft Entra ID가 지원하는 유일한 형식은 전달자입니다. 전달자 토큰에 대한 자세한 내용은 OAuth 2.0 권한 부여 프레임워크: 전달자 토큰 사용(RFC 6750)을 참조하세요. |
| scope | 토큰에 부여된 액세스의 범위입니다. |
| expires_in | 액세스 토큰이 유효한 기간(초)입니다. |
| expires_on | 액세스 토큰이 만료되는 시간입니다. 날짜는 1970-01-01T0:0:0Z UTC부터 만료 시간까지 기간(초)으로 표시됩니다. 이 값은 캐시된 토큰의 수명을 결정하는 데 사용됩니다. |
| resource | 수신 서비스(보안 리소스)의 앱 ID URI입니다. |
| access_token | SAML 어설션을 반환하는 매개 변수입니다. |
| refresh_token | 새로 고침 토큰입니다. 호출 서비스는 이 토큰을 사용하여 현재 SAML 어설션이 만료된 후 다른 액세스 토큰을 요청할 수 있습니다. |
- token_type: 전달자
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- resource:
https://api.contoso.com - access_token: <SAML 어설션>
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
- refresh_token: <토큰 새로 고침>
중간 계층 애플리케이션에 대한 동의 얻기
OBO 흐름의 목표는 클라이언트 앱에서 중간 계층 앱을 호출할 수 있고 중간 계층 앱에서 백 엔드 리소스를 호출할 수 있는 권한을 가질 수 있도록 적절한 동의가 제공되는지 확인하는 것입니다. 애플리케이션의 아키텍처 또는 사용량에 따라 OBO 흐름이 성공적으로 수행되도록 다음을 고려해야 합니다.
.default 및 결합된 승인
중간 계층 애플리케이션은 매니페스트의 알려진 클라이언트 애플리케이션 목록(knownClientApplications)에 클라이언트를 추가합니다. 클라이언트에서 동의 프롬프트를 트리거하는 경우 동의 흐름은 자체 및 중간 계층 애플리케이션 모두에 적용됩니다. Microsoft ID 플랫폼에서 이 작업은 .default 범위를 사용하여 수행됩니다. .default 범위는 애플리케이션에 권한이 있는 모든 범위에 액세스하기 위한 동의를 요청하는 데 사용되는 특수 범위입니다. 이는 애플리케이션에서 여러 리소스에 액세스해야 하지만 사용자에게 한 번만 동의하라는 메시지가 표시되어야 하는 경우에 유용합니다.
알려진 클라이언트 애플리케이션 .default을 사용하여 동의 화면을 트리거하는 경우 동의 화면에는 클라이언트가 중간 계층 API에 대한 권한을 표시 하고 중간 계층 API에 필요한 권한도 요청합니다. 사용자가 두 애플리케이션에 대한 동의를 제공하면 OBO 흐름이 작동합니다.
요청에서 식별된 리소스 서비스(API)는 클라이언트 애플리케이션이 사용자 로그인의 결과로 액세스 토큰을 요청하는 API여야 합니다. 예를 들어 scope=openid https://middle-tier-api.example.com/.default(중간 계층 API에 대한 액세스 토큰을 요청함) 또는 scope=openid offline_access .default(리소스가 식별되지 않으면 기본적으로 Microsoft Graph로 설정됨)입니다.
권한 부여 요청에서 식별되는 API에 관계없이 동의 프롬프트는 클라이언트 앱에 대해 구성된 모든 필수 권한과 결합됩니다. 클라이언트를 알려진 클라이언트 애플리케이션으로 식별한 클라이언트의 필수 권한 목록에 나열된 각 중간 계층 API에 대해 구성된 모든 필수 권한도 포함됩니다.
사전 인증된 애플리케이션
리소스는 지정된 애플리케이션이 항상 특정 범위를 수신할 수 있는 권한이 있음을 나타낼 수 있습니다. 이는 프런트 엔드 클라이언트와 백 엔드 리소스 간에 더 원활하게 연결되도록 하는 데 유용합니다. 리소스는 매니페스트에서 여러 사전 인증된 애플리케이션(preAuthorizedApplications)을 선언할 수 있습니다. 이러한 애플리케이션은 OBO 흐름에서 이러한 권한을 요청하고 사용자의 동의 없이 해당 권한을 받을 수 있습니다.
관리자 동의
테넌트 관리자는 중간 계층 애플리케이션에 대한 관리자 동의를 제공하여 애플리케이션이 필요한 해당 API를 호출할 수 있는 권한을 갖도록 보장할 수 있습니다. 이렇게 하기 위해 관리자는 해당 테넌트에서 중간 계층 애플리케이션을 찾고, 필수 사용 권한 페이지를 열고, 앱에 대한 권한을 부여하도록 선택할 수 있습니다. 관리자 동의에 대한 자세한 내용은 동의 및 권한 설명서를 참조하세요.
단일 애플리케이션 사용
일부 시나리오에서는 중간 계층 및 프런트 엔드 클라이언트의 단일 페어링만 가질 수 있습니다. 이 시나리오에서는 중간 계층 애플리케이션의 필요성을 모두 부정하는 단일 애플리케이션으로 쉽게 만들 수 있습니다. 프런트 엔드 및 Web API 간에 인증을 수행하기 위해 쿠키, id_token 또는 애플리케이션 자체에서 요청한 액세스 토큰을 사용할 수 있습니다. 그런 다음 이 단일 애플리케이션에서 백 엔드 리소스로의 동의를 요청합니다.
참고 항목
OAuth 2.0 프로토콜 및 클라이언트 자격 증명을 사용하여 서비스 간 인증을 수행하는 다른 방법에 대해 자세히 알아보세요.