Microsoft ID プラットフォームと OAuth2.0 On-Behalf-Of フロー

On-Behalf-Of (OBO) フローでは、独自の ID 以外の ID を使用して別の Web API を呼び出す Web API のシナリオについて説明します。 OAuth では委任と呼ばれ、この目的は、要求チェーンを介してユーザーの ID とアクセス許可を渡すことです。

中間層サービスでは、ダウンストリーム サービスに認証済み要求を発行するために、Microsoft ID プラットフォームからのアクセス トークンをセキュリティ保護する必要があります。 アプリケーション ロールでなく、委任されたスコープのみを使用します。 "ロール" は、ユーザーに代わって動作するアプリケーションではなく、プリンシパル (ユーザー) にアタッチされたままになります。 これは、アクセス許可を持つべきではないリソースに対し、ユーザーがアクセス許可を取得できないようにするために発生します。

この記事では、アプリケーションでプロトコルに対して直接プログラミングする方法について説明します。 可能な場合は、トークンを取得してセキュリティで保護された Web API を呼び出す代わりに、サポートされている Microsoft 認証ライブラリ (MSAL) を使用することをお勧めします。 例については、MSAL を使用するサンプル アプリも参照してください。

クライアントの制限事項

サービス プリンシパルがアプリ専用トークンを要求して API に送信した場合、その API は、元のサービス プリンシパルを表さないトークンを交換します。 これは、OBO フローはユーザー プリンシパルに対してのみ機能するためです。 代わりに、クライアント資格情報フローを使用してアプリ専用トークンを取得する必要があります。 シングルページ アプリ (SPA) の場合、中間層の機密クライアントにアクセス トークンを渡して、OBO フローを代わりに実行する必要があります。

クライアントで暗黙的フローを使って id_token を取得する場合、また、応答 URL にワイルドカードが含まれている場合には、id_token を OBO フローで使用することはできません。 ワイルドカードは、* 文字で終わる URL です。 たとえば、https://myapp.com/* が応答 URL の場合、id_token は、クライアントを識別するのに十分に明確でないため、使用できません。 これにより、トークンが発行されるのが回避されます。 ただし、開始元のクライアントが登録済みのワイルドカード応答 URL を持っている場合でも、機密クライアントでは、暗黙的な付与フローを通じて取得したアクセス トークンが利用されます。 これは、機密クライアントがアクセス トークンを取得したクライアントを識別できるためです。 その後、機密クライアントはアクセス トークンを使用して、ダウンストリーム API の新しいアクセス トークンを取得できます。

また、カスタム署名キーを持つアプリケーションは、OBO フローで中間層 API として使用することはできません。 これには、シングル サインオン用に構成されたエンタープライズ アプリケーションが含まれます。 中間層 API がカスタム署名キーを使用している場合、その下層の API は、それに渡されるアクセス トークンの署名を検証しません。 クライアントによって制御されるキーを使用して署名されたトークンを安全に承諾することができないため、これによりエラーが発生します。

プロトコルの図

OAuth 2.0 認証コード付与フローまたは他のログイン フローを使用するアプリケーションで、ユーザーが認証されているとします。 この時点で、そのアプリケーションには、中間層 Web API (API A) にアクセスするためのユーザーの要求と同意を含む API A のアクセス トークン (トークン A) があります。 ここで、API A はダウンストリーム Web API (API B) に認証済み要求を発行する必要があります。

OBO フローを構成するための以下の手順について、次の図を使用して説明します。

1. クライアント アプリケーションは、トークン A (API A の aud 要求) を使用して API A に要求を発行します。
2. API A が Microsoft ID プラットフォーム トークン発行エンドポイントに対して認証を行い、API B にアクセスするためのトークンを要求します。
3. Microsoft ID プラットフォーム トークン発行エンドポイントはトークン A を使用して API A の資格情報を検証し、API B (トークン B) から API B へのアクセス トークンを発行します。
4. API A によって、API B への要求の承認ヘッダー内にトークン B が設定されます。
5. セキュリティで保護されたリソースからのデータが API B によって API A に返され、次に、クライアントに返されます。

このシナリオでは、中間層サービスに、ダウンストリーム API にアクセスするユーザーの同意を得るためのユーザー操作はありません。 そのため、ダウンストリーム API へのアクセス権を付与するオプションは、認証中の同意手順の一部として事前に提供されます。 ご使用のアプリに対してこれを実装する方法について詳しくは、「中間層アプリケーションの同意の取得」を参照してください。

中間層アクセス トークン要求

アクセス トークンを要求するには、次のパラメーターを使用して、テナントに固有の Microsoft ID プラットフォーム トークン エンドポイントへの HTTP POST を作成します。

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

クライアント アプリケーションのセキュリティ保護に共有シークレットまたは証明書のどちらを使うかに応じて、2 つのケースがあります。

最初のケース:共有シークレットを使ったアクセス トークン要求

共有シークレットを使用する場合、サービス間のアクセス トークン要求には、次のパラメーターが含まれてます。

例

次の HTTP POST は、 https://graph.microsoft.com Web API に対する user.read スコープを含むアクセス トークンと更新トークンを要求します。 要求はクライアント シークレットで署名され、機密クライアントによって作成されます。

//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

2 番目のケース:証明書を使ったアクセス トークン要求

証明書を含むサービス間アクセス トークン要求には、前の例のパラメーターに加えて、次のパラメーターが含まれています。

パラメーターは、共有シークレットによる要求のパラメーターとほぼ同じであることに注意してください。唯一異なるのは、client_secret パラメーターが、client_assertion_type と client_assertion の 2 つのパラメーターに置き換えられている点です。 client_assertion_type パラメーターが urn:ietf:params:oauth:client-assertion-type:jwt-bearer に設定され、client_assertion パラメーターが証明書の秘密キーで署名された JWT トークンに設定されます。

例

次の HTTP POST は、証明書を使用して https://graph.microsoft.com Web API に対する user.read スコープを含むアクセス トークンを要求します。 要求はクライアント シークレットで署名され、機密クライアントによって作成されます。

// 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 応答です。

成功応答の例

次の例に、 https://graph.microsoft.com Web 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 のエンドポイントは両方とも、どちらの形式のトークンも出力できます。 この方法では、クライアントによってトークンが要求された方法や場所に関係なく、リソースは常に適切な形式のトークンを取得できます。

エラー応答の例

ダウンストリーム API に条件付きアクセス ポリシー (多要素認証など) が設定されている場合は、ダウンストリーム API のアクセス トークンを取得しようとすると、トークン エンドポイントからエラー応答が返されます。 クライアント アプリケーションが条件付きアクセス ポリシーを満たすためのユーザー操作を提供できるように、中間層サービスでこのエラーをクライアント アプリケーションに示す必要があります。

このエラーを表面化して クライアントに返すために、中間層サービスは HTTP 401 Unauthorized と、エラーと要求チャレンジを含む 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\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

アクセス トークンを使用して、セキュリティ保護されたリソースにアクセスする

これで、中間層サービスは以前に取得されたトークンを使用して、そのトークンを Authorization ヘッダー内に設定することによってダウンストリーム Web API に認証済み要求を発行できます。

例

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

OAuth2.0 OBO フローにより取得した SAML アサーション

一部の OAuth ベースの Web サービスは、非対話型フローで SAML アサーションを受け入れるその他の Web サービス API にアクセスする必要があります。 Microsoft Entra ID は、SAML ベースの Web サービスをターゲット リソースとして使用する On-Behalf-Of フローに応答して SAML アサーションを提供できます。

これは、OAuth2 ベースのアプリケーションが SAML トークンを使用する Web サービス API エンドポイントにアクセスできる、OAuth 2.0 の On-Behalf-Of フローの非標準の拡張機能です。

共有シークレットを持つ OBO 要求を使用して SAML トークンを取得する

サービス間の SAML アサーション要求には、次のパラメーターが含まれています。

応答には、UTF8 および Base 64url でエンコードされた SAML トークンが含まれています。

• OBO 呼び出しから提供される SAML アサーションの SubjectConfirmationData: ターゲット アプリケーションで SubjectConfirmationData の Recipient の値が必要な場合、その値はリソース アプリケーション構成内の最初の非ワイルドカードの応答 URL として構成されている必要があります。 既定の応答 URL は Recipient の値の決定に使用されないため、最初の非ワイルドカード応答 URL が使用されるように、アプリケーション構成で応答 URL の順序を変更する必要がある場合があります。 詳細については、「応答 URL」を参照してください。
• SubjectConfirmationData ノード:このノードは SAML 応答の一部ではないため、InResponseTo 属性を含めることはできません。 SAML トークンを受け取るアプリケーションは、InResponseTo 属性なしで SAML アサーションを受け入れることができる必要があります。
• API のアクセス許可: SAML アプリケーションへのアクセスを許可するには、中間層アプリケーションに必要な API のアクセス許可を追加する必要があります。これにより、SAML アプリケーションの /.default スコープのトークンを要求できるようになります。
• 同意:OAuth フローでユーザー データを含む SAML トークンを受信するためには、同意が付与されている必要があります。 詳細については、「中間層アプリケーションの同意の取得」を参照してください。

SAML アサーションの応答

• token_type:Bearer
• 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 スコープは、アプリケーションがアクセス許可を持つすべてのスコープにアクセスするための同意を要求するために使用される特殊なスコープです。 これは、アプリケーションが複数のリソースにアクセスする必要があるときに、ユーザーに 1 回だけ同意を求めるようにする場合に便利です。

既知のクライアント アプリケーションと .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 間で認証を行うために、アプリケーション自体に要求された cookie、id_token、またはアクセス トークンを使用できます。 その後、この単一アプリケーションからバックエンド リソースへの同意を要求します。

関連項目

OAuth 2.0 プロトコルと、クライアント資格情報を使用したサービス間認証を実行する別の方法について詳しく学びます。

• Microsoft ID プラットフォームでの OAuth 2.0 クライアント資格情報の付与
• Microsoft ID プラットフォームでの OAuth 2.0 コード フロー
• /.default スコープの使用