目次

Better Authは、ClaudeなどのAIエージェントがログイン中のユーザーとしてアプリを操作できるOAuthトークンを発行できます。ログインは引き続きMicrosoft Entra IDに任せ、リソース制限、スコープ、失効はアプリ側で適用します。

要点#

  • Entra IDのトークンはサーバー内に保持し、MCPエンドポイント用には別のトークンを発行します。
  • PKCEと、MCPのURLに一致する明示的なresourceを必須にします。
  • トークン発行時とすべてのMCPリクエストで同意を検証し、クライアントの接続解除によってアクセスを遮断します。
  • ここで説明する追加チェックは内部実装の詳細に依存するため、Better Authのバージョンを固定します。

ログインと認可を分離する#

2つの独立した信頼境界を設けます。Entra IDはSSOでユーザーを認証し、Better AuthはAIクライアントにアプリへのアクセスを認可します。MCPサーバーはアプリが発行したトークンだけを受け入れ、Entra IDのトークンは受け入れません。

OAuthリソースには、https://example.com/mcpのような単一の正確なURLを設定します。これはトークンの想定される受信先を識別します。AIクライアントの登録と同意はアプリで管理し、Entra IDのアプリ登録を変更せずにユーザーがクライアントの接続を解除できるようにします。

提示する実装は、Better Auth 1.7.12とMCP 2026-07-28メタデータプロファイルを対象としています。以下の動作はバージョン固有のものとして扱い、設定を採用する前にインストール済みのパッケージで確認してください。

OAuthフローを設定する#

既存のsocialProviders.microsoft設定に加えて、mcp()とcimd()を追加します。loginPage、consentPage、resourceを設定し、authorization_codeとrefresh_tokenを許可して、items:read、items:write、offline_accessを公開します。アクセストークンを不透明トークンにするためdisableJwtPlugin: trueを設定し、storeTokens: "hashed"を維持します。Honoでは、/api/auth/*と/.well-known/*をBetter Authハンドラーにルーティングします。

接続は次の順序で進みます。

1. MCPエンドポイントは、resource_metadataのURLを含むWWW-Authenticateヘッダーを付けて401を返します。 2. クライアントは認可サーバーを検出し、Client ID Metadata Documents(CIMD)で自身を識別するか、動的クライアント登録(DCR)を使って/oauth2/registerから登録します。 3. クライアントはPKCEチャレンジと正確なMCPのresourceを指定して認可を要求します。アプリは署名付きOAuthクエリをEntra IDログインの間も保持し、その後に同意画面を表示します。 4. 承認後、クライアントは認可コードをアクセストークンとリフレッシュトークンに交換します。

ログインへの引き継ぎでは、sigを含む署名付きクエリ全体をoauth_queryとして渡します。同意画面には、クライアント名とともに要求されたスコープとリダイレクト先のホストを表示します。登録名は自己申告であり、身元の証明ではありません。

トークン発行前にチェックを追加する#

提示する実装では、Better Authのデフォルトに4つの制限を追加します。

  • 認可時にリソースを必須にする。 resourceがMCPのURLと完全に一致しない限り、/oauth2/authorizeをinvalid_targetで拒否します。そうしないと、リソースを指定しないリクエストでも、後からリソース固有のトークンを取得できてしまいます。
  • パブリッククライアントだけを登録する。 認証なしのDCRでは、token_endpoint_auth_method: "none"を必須にします。RFC 7591では、省略時のデフォルトはclient_secret_basicです。
  • 両方の経路にリダイレクトルールを適用する。 HTTPSリダイレクトとHTTPループバックリダイレクトを許可します。DCRのメタデータは登録時に、CIMDのリダイレクトはvalidateRedirectUriで検証します。CIMDは登録エンドポイントを経由しません。
  • トークン交換前に同意を再確認する。 元の同意が存在しなくなった認可コードとリフレッシュトークンは、invalid_grantで拒否します。

CIMDのリダイレクト検証を除き、これらのチェックはhooks.beforeに配置します。プラグインが読み取るのと同じパラメーターソースを検査してください。登録ではボディを使い、認可では最初のPOSTにボディ、GETとログイン継続にクエリを使います。両方を無差別にチェックすると、プラグインが無視するパラメーターで検証を通過できてしまう可能性があります。

CIMDでは、サーバーがクライアントの管理するURLにアクセスすることにもなります。公開HTTPS宛先を必須とし、ループバックアドレスや特殊用途アドレスは拒否します。DNS解決とリダイレクトを安全に処理するfetch実装を使ってください。最初のURLを確認するだけでは不十分です。

アクセス制御と接続解除を適用する#

/mcpでは、Bearerトークンのみで認証します。トークンをハッシュ化し、有効期限、失効、リソースの完全一致、同意の継続をデータベースで確認します。このBearer専用経路では、DPoPにバインドされたトークンを拒否します。検証済みのユーザー、クライアント、スコープ、有効期限をMCPハンドラーに渡します。

データベースのチェックで即座にアクセスを遮断できるよう、不透明トークンを使います。書き込みツールにはitems:writeを必須とし、Webインターフェースと同じサービス層を呼び出して、所有権チェックと入力検証の一貫性を保ちます。ツールのアノテーションは動作を説明するものであり、権限を強制するものではありません。取り消せない操作は、初期のツールセットから除外します。

接続解除は、同意、アクセストークン、リフレッシュトークンを削除する単一のトランザクションとして実装します。共有のクライアントレコードは保持します。別の同意削除経路や/get-access-tokenなど、アプリが必要としないプラグインエンドポイントは無効にします。削除だけでは、同時進行のリフレッシュによる別のトークンの書き込みを防げないため、リクエスト時の同意チェックも引き続き必要です。

残る制限を把握する#

タイムスタンプに基づく同意チェックには、同一秒内の処理を区別できない制約があります。失効、同時進行のリフレッシュ、再同意によって、古い認可が有効と見なされる可能性があります。同意の世代識別子を使えば、より確実に区別できます。また、提示する設定では、直前のリフレッシュトークンの再利用を受け入れる30秒間のリフレッシュ再試行猶予を残しています。

Entra IDのアカウントを無効にしても、アプリが発行したトークンは自動的には失効しません。アプリ側に失効処理を追加してください。実際のクライアントのOriginヘッダーがポリシーに適合するかテストし、フックは内部データ構造に依存するため、Better Authのバージョンを固定して認可、リフレッシュ、接続解除をテストしてください。

次のステップ#

クライアントの接続を解除した後、既存のアクセストークンとリフレッシュトークンが両方とも拒否されることを確認する統合テストを追加します。

出典: https://zenn.dev/sakagi/articles/8caa896e649005

目次