OAuth2 Client
DrupalがOAuth2クライアントとして動作し、外部のOAuth2サーバーと認証するためのOAuth2クライアント機能を提供します。
oauth2_client
インストール
composer require 'drupal/oauth2_client:^4.1'
composer require 'drupal/oauth2_client:8.x-3.2'
概要
OAuth2 Clientモジュールは、DrupalサイトがOAuth2プロトコルを使用して外部サービスと統合することを可能にします。OAuth2クライアントを作成するためのプラグインベースのアーキテクチャを提供し、トークンの取得、更新、削除に関するすべてのバックエンド機能を処理します。
このモジュールは、The League of Extraordinary Packagesが提供する広く使用されているLeague OAuth2 Client PHPライブラリを活用しており、堅牢で標準準拠のOAuth2実装を保証します。開発者は、ベースクラスを拡張し、必要なエンドポイント、グラントタイプ、スコープを設定することで、カスタムOAuth2クライアントプラグインを作成できます。
各プラグインに対して設定エンティティが自動的に作成され、認証情報を管理するための管理インターフェースを提供します。このモジュールは、DrupalのState APIを使用したローカルストレージ、または本番環境でのセキュリティ強化のためのKeyモジュールを通じた安全な認証情報の保存をサポートします。
Features
- 最小限のコードでOAuth2クライアントを作成するためのプラグインベースのアーキテクチャ
- 複数のOAuth2グラントタイプをサポート：Authorization Code、Client Credentials、Resource Owner Password
- トークンの有効期限が切れ、リフレッシュトークンが利用可能な場合の自動トークン更新
- 2つのトークン保存戦略：共有トークン用のStateTokenStorageとユーザーごとのトークン用のTempStoreTokenStorage
- ローカルストレージまたはKeyモジュール統合による安全な認証情報管理
- 各OAuth2クライアントプラグインに対する設定エンティティの自動作成
- 認可コード取得後のカスタムリダイレクトURI処理
- 認可コード取得ルートのカスタムアクセス制御
- League OAuth2 Clientライブラリのプロバイダーエコシステムを通じたカスタムOAuth2プロバイダーのサポート
- クライアントごとに設定可能なスコープ、スコープ区切り文字、および追加リクエストオプション
- 認可コードフローにおける状態パラメータ検証によるCSRF保護
Use Cases
サードパーティAPIとの統合
DrupalサイトがOAuth2を認証に使用する外部サービス（Google API、Microsoft Graph、またはカスタムエンタープライズサービスなど）からデータにアクセスする必要がある場合、OAuth2クライアントプラグインを作成します。ユーザーコンテキストが不要なサーバー間通信にはclient_credentialsグラントタイプを使用します。
ユーザー認可による外部サービスアクセス
サイトが個々のユーザーに代わって外部リソースにアクセスする必要がある場合（ユーザーのDropboxファイルへのアクセスやソーシャルメディアへの投稿など）、TempStoreTokenStorageとともにauthorization_codeグラントタイプを使用します。各ユーザーがアクセスを認可し、プライベートテンプストアに保存された独自のトークンを受け取ります。
シングルサインオン統合
完全なSSOソリューションではありませんが、このモジュールをカスタム認証コードと組み合わせて、OAuth2ベースのログインフローを有効にできます。authorization_codeグラントを使用して外部OAuth2プロバイダーに対してユーザーを認証し、Drupalアカウントを作成またはリンクします。
マイクロサービス認証
DrupalがOAuth2で保護された他のサービスと通信する必要があるマイクロサービスアーキテクチャでは、StateTokenStorageとともにclient_credentialsグラントタイプを使用して、すべてのサーバーサイドリクエストで共有トークンを維持します。
パスワードグラントによるレガシーシステム統合
直接的なユーザー名/パスワードの収集が許容される信頼されたファーストパーティアプリケーションや内部ツールの場合、resource_ownerグラントタイプを使用します。認証情報はトークンの取得にのみ使用され、保存されません。
Tips
- League OAuth2 Clientライブラリが正しくインストールされるよう、必ずComposerを使用してこのモジュールをインストールしてください
- 本番環境では、Keyモジュールを使用してデータベース外に認証情報を保存してください。特にWebルート外の場所にファイルストレージを使用する場合に有効です
- 外部リソースがすべてのサイトユーザーで共有される場合はStateTokenStorageトレイトを使用し、各ユーザーが個別の認可を必要とする場合はTempStoreTokenStorageを使用してください
- authorization_codeグラントのリダイレクトURIは自動的に/oauth2-client/{plugin_id}/codeとして生成されます - このURLをOAuth2プロバイダーに登録してください
- 認可コードフローを完了できるユーザーをカスタマイズするにはOauth2ClientPluginAccessInterfaceを実装してください
- 認可成功後にユーザーをカスタムページにリダイレクトするにはOauth2ClientPluginRedirectInterfaceを実装してください
- getProvider()メソッドをオーバーライドすることで、Leagueエコシステムの専用サードパーティOAuth2プロバイダーパッケージを使用できます
- request_optionsプラグイン属性により、非標準のOAuth2実装のトークンリクエストにカスタムパラメータを追加できます
Technical Details
Admin Pages 3
/admin/config/system/oauth2-client
すべてのOAuth2クライアント設定エンティティを一覧表示します。各クライアントプラグインは対応する設定エンティティを自動的に作成し、認証情報を追加するために編集できます。このページから、管理者はクライアントの有効化/無効化や、各クライアントの編集フォームへのナビゲーションが可能です。
/admin/config/system/oauth2-client/{oauth2_client}/edit
OAuth2クライアントの認証情報と設定を構成するための編集フォーム。フォームはグラントタイプと利用可能な認証情報プロバイダーに基づいてフィールドを動的に表示します。
/admin/config/system/oauth2-client/{oauth2_client}/disable
OAuth2クライアントを無効にするための確認フォーム。無効なクライアントはOauth2ClientServiceからトークンを返しません。
権限 1
Hooks 1
hook_oauth2_client_info_alter
OAuth2 Clientプラグイン定義が使用される前に変更します。システムに登録されたOAuth2クライアントプラグインの設定をモジュールが変更することを可能にします。
Troubleshooting 5
編集フォームの「保存してトークンをリクエスト」ボタンを使用して設定をテストします。返されたエラーメッセージを確認してください。client_id、client_secret、authorization_uri、token_uriが正しいことを確認します。外部サービスに登録されたリダイレクトURIがモジュールによって生成されたもの（/oauth2-client/{plugin}/code）と一致していることを確認してください。
OAuth2クライアント設定エンティティが有効になっていることを確認してください。セッションが正しく機能していることを確認して、stateパラメータが一致するかチェックしてください。Drupalキャッシュをクリアして再試行してください。
authorization_codeおよびresource_ownerグラントの場合、リフレッシュトークンなしで有効期限が切れたトークンは自動的に更新できません。ユーザーを再認証するか、元のグラントフローを通じて新しいトークンを取得する必要があります。
Keyモジュールがインストールされており、Keyのタイプが'oauth2_client'であることを確認してください。Key値は、client_idとclient_secretフィールドを持つ有効なJSONである必要があります。OAuth2クライアント設定でcredential_providerが'key'に設定されていることを確認してください。
プラグイン検出をトリガーするためにDrupalキャッシュをクリアしてください。プラグインクラスが正しい名前空間（Plugin/Oauth2Client）を持ち、Oauth2ClientPluginBaseを拡張し、すべての必須パラメータを持つ有効な#[Oauth2Client]属性を持っていることを確認してください。
Security Notes 6
- ローカルストレージ（State API）に保存されたクライアントシークレットはデータベースに保存されます - 本番環境ではファイルストレージを使用するKeyモジュールを使用してセキュリティを向上させてください
- 設定ストレージオプションを使用する場合、Keyモジュールのキーをバージョン管理にコミットしないでください - これはローカル開発専用です
- 認可コードフローには、stateパラメータ検証によるCSRF保護が含まれています
- 'administer oauth2 clients'権限は制限付きアクセスとしてマークされています - 信頼できる管理者にのみ付与してください
- resource_ownerグラントタイプの場合、ユーザー名とパスワードはトークンの取得にのみ使用され、永続化されません
- デフォルトの権限ベースのアクセスがユースケースに適切でない場合は、Oauth2ClientPluginAccessInterfaceを通じてカスタムアクセスチェックを実装してください