アプリから呼ばれた API が、その先の API を利用者の権限で呼びたいことがあります。たとえば、社内の API が利用者の代わりに Microsoft Graph でメールや予定を読む、といった場合です。このときに使うのが OBO(On-Behalf-Of)フローです。この記事では、Entra ID の OBO フローを例に、仕組みと気をつけることをまとめます。JWT そのものについては JWT は「偽造できない身分証」 に書きました。( 最初フリマや個人売買でよく見る 「or best offer」 値下げ交渉OK をイメージしましたが全くちがいましたw)
何が困るのか
利用者 → アプリ → API A(中間)→ API B(その先)
API A は、アプリから利用者のアクセストークン(JWT)を受け取ります。でも、そのトークンは API A 宛て(aud が API A)です。
- そのまま API B に渡すと、API B から見れば「自分宛てではないトークン」。
audを確かめていれば拒否され、確かめていなければ危険なまま通ってしまう(トークンのパススルー。MCP の仕様などでも禁止されている) - API A 自身の権限(アプリの権限)で API B を呼ぶと、誰の代わりに呼んだのかがわからなくなり、権限も大きくなりがち
そこで、発行元にトークンを「API B 宛て」に発行し直してもらうのが OBO フローです。
流れ
- 利用者がアプリからログインし、Entra ID が API A 宛ての JWT を発行する
- アプリが、その JWT を付けて API A を呼ぶ
- API A は、その JWT と自分の資格情報(クライアントシークレットや証明書)を Entra ID に見せて、「同じ利用者として API B を呼ぶためのトークン」を求める
- Entra ID は、受け取った JWT の署名・宛先・期限と、API A がその権限をもらってよいかを確かめ、API B 宛ての新しい JWT(利用者は同じ)を発行する
- API A が、新しい JWT を付けて API B を呼ぶ。API B は Entra ID の公開鍵で確かめるだけでよい
④ のリクエスト
API A から Entra ID のトークンの窓口へ、次のように送ります。
POST https://login.microsoftonline.com/{テナントID}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id={API A のクライアントID}
&client_secret={API A のシークレット}
&assertion={アプリから受け取った JWT}
&scope=https://graph.microsoft.com/User.Read
&requested_token_use=on_behalf_of
assertion に受け取った JWT をそのまま入れ、scope に API B の権限を書きます。シークレットの代わりに証明書(client_assertion)も使えます。
ほかのやり方との違い
| パススルー | アプリの権限で呼ぶ | OBO | |
|---|---|---|---|
| API B に届くトークン | API A 宛て(自分宛てではない) | API A 自身のトークン | API B 宛て、利用者のトークン |
| 誰の代わりか | わからない(偽物と区別できない) | わからない | 利用者とわかる |
| 権限 | API A 用の権限がそのまま流れる | アプリ全体の大きな権限になりがち | 利用者の権限 × API B 用の権限にしぼられる |
| 記録 | 残らない | 「API A が呼んだ」だけ | Entra ID に「API A が利用者の代わりに」と残る |
気をつけること
- API A は、秘密を安全に持てるサーバーであること(機密クライアント)。ブラウザやスマホのアプリは OBO を使えない
- 受け取るトークンは API A 宛てであること。ほかの API 宛てのトークン(Graph 用など)を API A に送って OBO に使うことはできない
- API A に、API B の委任されたアクセス許可を付け、同意を済ませておく。済んでいないと、④ で同意が必要というエラーになる
- API B に多要素認証などの条件付きアクセスがあると、④ でエラーになることがある。その場合は、API A からアプリに「追加の認証が必要」と返し、利用者に認証し直してもらう
- 発行し直したトークンは、利用者ごとにキャッシュする。リクエストのたびに ④ を呼ばない
OBO は Entra ID での呼び方で、標準の仕様としては OAuth 2.0 Token Exchange(RFC 8693) が同じ考え方を一般化したものです。
