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

[アーティクル]
04/08/2024

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 フローを構成するための以下の手順について、次の図を使用して説明します。

OAuth2.0 の On-Behalf-Of フローを示します

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

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

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

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

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

警告

中間層に発行されたアクセストークンは、そのトークンの対象以外の場所には送信しないでください。中間層に発行されるアクセストークンは、その中間層が意図された対象エンドポイントと通信するのに使用するため "だけ" のものです。

中間層リソースから、(アクセストークン自体を取得するクライアントではなく)クライアントにアクセストークンを中継する場合のセキュリティ上のリスクは次のとおりです。

侵害された SSL/TLS チャネル経由でのトークン傍受リスクの増加。
要求のステップアップ (MFA、サインイン頻度など) が必要なトークンバインディングや条件付きアクセスのシナリオを満たすことができない。
管理者が構成したデバイスベースのポリシー (MDM、場所ベースのポリシーなど) との非互換性。

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

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

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

パラメーター	型	内容
`grant_type`	必須	トークン要求の種類。 JWT を使用した要求では、この値は `urn:ietf:params:oauth:grant-type:jwt-bearer` にする必要があります。
`client_id`	必須	アプリに割り当てられている「Microsoft Entra管理センター - アプリの登録」ページのアプリケーション (クライアント) ID。
`client_secret`	必須	Microsoft Entra管理センター - アプリの登録ページでアプリ用に生成したクライアントシークレット。 RFC 6749 に従って、代わりに Authorization ヘッダーで資格情報を提供する基本認証パターンもサポートされています。
`assertion`	必須	中間層 API に送信されたアクセストークン。このトークンには、この OBO 要求を行うアプリ (`client-id` フィールドに示されるアプリ) の対象ユーザー (`aud`) 要求が必要です。アプリケーションは別のアプリ用のトークンを利用することはできません (たとえば、クライアントが API に Microsoft Graph 用のトークンを送信した場合、API は OBO を使用してそれを利用することはできません。代わりに、トークンを拒否する必要があります)。
`scope`	必須	トークン要求のスコープのスペース区切りリスト。詳細については、「スコープ」を参照してください。
`requested_token_use`	必須	要求の処理方法を指定します。 OBO フローでは、この値は `on_behalf_of` に設定する必要があります。

例

次の 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 番目のケース:証明書を使ったアクセストークン要求

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

パラメーター	型	内容
`grant_type`	必須	トークン要求の種類。 JWT を使用した要求では、この値は `urn:ietf:params:oauth:grant-type:jwt-bearer` にする必要があります。
`client_id`	必須	アプリに割り当てられている「Microsoft Entra管理センター - アプリの登録」ページのアプリケーション (クライアント) ID。
`client_assertion_type`	必須	値は `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` である必要があります。
`client_assertion`	必須	作成する必要があるアサーション (JSON Web トークン) です。このアサーションは、アプリケーションの資格情報として登録した証明書で署名する必要があります。証明書の登録方法とアサーションの形式の詳細については、証明書資格情報に関する記事を参照してください。
`assertion`	必須	中間層 API に送信されたアクセストークン。このトークンには、この OBO 要求を行うアプリ (`client-id` フィールドに示されるアプリ) の対象ユーザー (`aud`) 要求が必要です。アプリケーションは別のアプリ用のトークンを利用することはできません (たとえば、クライアントが API に MS Graph 用のトークンを送信した場合、API は OBO を使用してそれを利用することはできません。代わりに、トークンを拒否する必要があります)。
`requested_token_use`	必須	要求の処理方法を指定します。 OBO フローでは、この値は `on_behalf_of` に設定する必要があります。
`scope`	必須	トークン要求のスコープのスペース区切りリスト。詳細については、「スコープ」を参照してください。

パラメーターは、共有シークレットによる要求のパラメーターとほぼ同じであることに注意してください。唯一異なるのは、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 応答です。

パラメーター	説明
`token_type`	トークンタイプ値を指定します。 Microsoft ID プラットフォームでサポートされる種類は `Bearer` のみです。ベアラートークンの詳細については、「OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)」(OAuth 2.0 承認フレームワーク: ベアラートークンの使用法 (RFC 6750)) をご覧ください。
`scope`	トークンで付与されるアクセスのスコープ。
`expires_in`	アクセストークンが有効な時間の長さ (秒単位)。
`access_token`	要求されたアクセストークン。呼び出し元のサービスは、このトークンを使用して受信側のサービスへの認証を行うことができます。
`refresh_token`	要求されたアクセストークンの更新トークン。呼び出し元のサービスは、現在のアクセストークンの期限が切れた後に、このトークンを使用して別のアクセストークンを要求できます。更新トークンは、`offline_access` スコープが要求された場合にのみ提供されます。

成功応答の例

次の例に、 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 について、トークンの検証や読み取りを行わないでください。 Microsoft サービスのトークンには、JWT として検証されない特殊な形式を使用できます。また、コンシューマー (Microsoft アカウント) ユーザーに対して暗号化される場合もあります。トークンの読み取りは便利なデバッグおよび学習ツールですが、コード内でこれに対する依存関係を取得したり、自分で制御する API 用ではないトークンについての詳細を想定したりしないでください。

エラー応答の例

ダウンストリーム 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\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}

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

これで、中間層サービスは以前に取得されたトークンを使用して、そのトークンを 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 フローの非標準の拡張機能です。

ヒント

フロントエンド Web アプリケーションから SAML で保護された Web サービスを呼び出す場合、API を呼び出すだけで、ユーザーの既存のセッションで通常の対話型認証フローを開始できます。サービス間の呼び出しでユーザーコンテキストを提供するために SAML トークンが必要なときのみ OBO フローを使用する必要があります。

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

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

パラメーター	型	説明
grant_type	required	トークン要求の種類。 JWT を使用する要求の場合、値は `urn:ietf:params:oauth:grant-type:jwt-bearer` である必要があります。
assertion	required	要求で使用されるアクセストークンの値。
client_id	必須	Microsoft Entra ID での登録時に呼び出し元のサービスに割り当てられるアプリ ID。 Microsoft Entra管理センターでアプリ ID を見つけるには、ID>アプリケーション>アプリの登録を参照し、アプリケーション名を選択します。
client_secret	必須	呼び出し元のサービスに対して Microsoft Entra ID に登録されているキー。登録時にこの値をメモしておくようにしてください。 RFC 6749 に従って、代わりに Authorization ヘッダーで資格情報を提供する基本認証パターンもサポートされています。
scope	required	トークン要求のスコープのスペース区切りリスト。詳細については、「スコープ」を参照してください。 SAML 自体にはスコープの概念がありませんが、トークンを受信するターゲットの SAML アプリケーションを識別するために使用されます。この OBO フローでは、スコープ値は常に、`/.default` が追加された SAML エンティティ ID である必要があります。たとえば、SAML アプリケーションのエンティティ ID が `https://testapp.contoso.com` の場合、要求されたスコープは `https://testapp.contoso.com/.default` となります。エンティティ ID の先頭が `https:` などの URI スキームではない場合、そのエンティティ ID には、Microsoft Entra によって `spn:` がプレフィックスとして付けられます。その場合は、スコープ `spn:<EntityID>/.default` を要求する必要があります (たとえば、エンティティ ID が `testapp` の場合は `spn:testapp/.default`)。ここで要求するスコープ値によって、SAML トークン内で得られる `Audience` 要素が決まります。これは、トークンを受け取る SAML アプリケーションにとっては重要なものとなる場合があります。
requested_token_use	必須	要求の処理方法を指定します。 On-Behalf-Of フローでは、値は `on_behalf_of` である必要があります。
requested_token_type	required	要求するトークンの種類を指定します。アクセス先のリソースの要件に応じて、値は `urn:ietf:params:oauth:token-type:saml2` または `urn:ietf:params:oauth:token-type:saml1` のいずれかです。

応答には、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	トークンの種類の値を示します。 Microsoft Entra ID でサポートされる種類はベアラーのみです。ベアラートークンの詳細については、「OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)」(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: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 フローを確実に成功させるために、次の事項を検討することをお勧めします。

中間層アプリケーションを使用すると、そのマニフェストの既知のクライアントアプリケーションの一覧 (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、またはアクセストークンを使用できます。その後、この単一アプリケーションからバックエンドリソースへの同意を要求します。

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

クライアントの制限事項

プロトコルの図

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

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

例

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

例

中間層アクセストークン応答

成功応答の例

エラー応答の例

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

例

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

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

SAML アサーションの応答

事前に認証されたアプリケーション

単一アプリケーションの使用

関連項目

その他のリソース

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

クライアントの制限事項

プロトコルの図

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

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

例

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

例

中間層アクセス トークン応答

成功応答の例

エラー応答の例

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

例

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

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

SAML アサーションの応答

中間層アプリケーションの同意の取得

.default と組み合わせ同意

事前に認証されたアプリケーション

管理者の同意

単一アプリケーションの使用

関連項目

その他のリソース

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

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

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

中間層アクセストークン応答

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