External Authentication
A helper module that provides services for authenticating users using external sites or services and storing identification details in an authmap table.
externalauth
インストール
composer require 'drupal/externalauth:^2.0'
概要
External Authenticationモジュールは、外部サイトやサービスに対して認証されたユーザーのログインと登録、および認証詳細の保存のための汎用サービスを提供します。Drupal 8以降におけるuser_external_login_register()および関連関数の同等機能として機能し、Drupal 6および7のコアに存在していたauthmapテーブルの役割も担います。
このモジュールは、他の外部認証モジュール（SAML、LDAP、OAuthなど）が構築するための基盤APIとして設計されています。外部認証データの保存と取得、外部IDとDrupalユーザーアカウントのマッピングのための一貫したAPIを提供します。
モジュールは認証マッピングを'authmap'データベーステーブルに保存し、認証プロバイダーが提供する外部認証名（authname）をDrupalユーザーアカウントにリンクします。各マッピングには、認証プロバイダー固有のシリアライズされた追加データも保存できます。
Features
- 外部認証名に基づいてDrupalユーザーの読み込み、ログイン、登録、リンクを行うサービスを提供
- 認証マッピングデータ（authnameからDrupalユーザーIDへ）を専用のauthmapデータベーステーブルに保存
- プロバイダー固有の情報のために、各認証マッピングに追加のシリアライズデータを保存可能
- ログイン、登録、authmap変更時にイベントを発火し、他のモジュールが反応または動作を変更可能
- ユーザーとプロバイダー間の外部認証リンクを管理するViewsベースの管理インターフェースを含む
- Drupalユーザーが削除されると自動的にauthmapエントリをクリーンアップ
- Drupal 6および7インストールからauthmapデータをアップグレードするためのmigrateプラグインを提供
- ユーザーごとに複数の認証プロバイダーをサポートし、異なる外部サービスを通じてログイン可能
Use Cases
SAML Single Sign-On Integration
When implementing SAML-based SSO using a module like samlauth, the externalauth module stores the mapping between SAML NameID (external identifier) and Drupal user accounts. The samlauth module calls externalauth.externalauth->loginRegister() to handle user authentication, automatically creating new Drupal accounts for first-time SAML users.
LDAP Authentication
For LDAP authentication, the externalauth module maps LDAP Distinguished Names (DN) or usernames to Drupal accounts. When a user authenticates via LDAP, the authentication module uses externalauth services to find or create the corresponding Drupal user and establish the login session.
OAuth/OpenID Connect Login
Social login implementations using OAuth or OpenID Connect can use externalauth to map external user identifiers (like Google or Facebook user IDs) to Drupal accounts. This enables 'Login with Google' type functionality while maintaining proper user account mapping.
Multi-Provider Authentication
Organizations allowing users to authenticate through multiple external systems (e.g., both SAML and LDAP) can use externalauth to manage mappings for each provider. A single Drupal user can have multiple authmap entries, one per provider, enabling flexible authentication options.
Site Migration from Drupal 6/7
When migrating from Drupal 6 or 7 sites that used external authentication, the migration templates (d6_authmap and d7_authmap) preserve existing authentication mappings, ensuring users can continue logging in with their external credentials after migration.
Custom Authentication Provider Development
Developers creating custom authentication modules can use externalauth as a foundation. By calling the provided services, custom modules can focus on the authentication logic specific to their provider while relying on externalauth for user registration, login finalization, and mapping storage.
Tips
- Use the ExternalAuthAuthmapAlterEvent to customize the Drupal username generated during registration, preventing default provider_authname format if needed
- The authmap view at /admin/people/authmap accepts contextual filters, so you can access provider-specific lists at /admin/people/authmap/{provider}
- Store provider-specific data in the authmap_data parameter when calling register() or linkExistingAccount() - this data is serialized and stored with the mapping
- Subscribe to externalauth.register event to perform additional user setup after external registration (e.g., assigning roles based on external attributes)
- The linkExistingAccount() method returns FALSE if the account is already linked with the same authname, allowing idempotent operations
- When multiple external auth providers are used, consider customizing the authmap view to show the provider column for clarity
Technical Details
Admin Pages 2
/admin/people/authmap
A Views-based administrative page that displays all external authentication name mappings registered by external authentication methods for each user. The page shows the Authentication Name (external identifier), Drupal User ID, Drupal User Name (with link to user profile), and a delete operation link. The list can be filtered by authentication name and Drupal user. Provider-specific views are available at /admin/people/authmap/{provider} (e.g., /admin/people/authmap/samlauth).
/admin/people/authmap/{provider}/{uid}/delete
Confirmation form for deleting a specific external authentication link between an authentication name and a Drupal user account. The form displays the authentication name and Drupal username being unlinked and requires confirmation before deletion.
権限 2
Hooks 1
hook_user_delete
Automatically deletes all authmap entries for a user when the user account is deleted, ensuring data integrity.
Troubleshooting 4
Check the authmap table to verify a mapping exists for the user's external authname and provider. Use the admin view at /admin/people/authmap to search for the authentication name. If no mapping exists, the user may need to be registered first or have their account linked.
This typically occurs when multiple authentication providers are active. Add the 'provider' field to the view configuration, or use provider-specific URLs like /admin/people/authmap/samlauth to filter by provider.
This exception is thrown when a user with the same Drupal username already exists. Either ensure unique usernames are generated (default is provider_authname) or handle the exception by linking to the existing account instead.
The module implements hook_user_delete to clean up authmap entries automatically. Ensure the module is enabled and working correctly. Manual cleanup can be done via the admin interface or directly in the database.
Security Notes 5
- External authentication modules should validate authnames and user data from external sources before passing to externalauth services
- The delete operation for authmap entries requires the 'delete authmap' permission - grant this only to trusted administrators
- Authnames are not exposed in delete form URLs to prevent leaking external identifiers in HTTP referrer logs
- The authmap table stores sensitive mapping data - ensure proper database access controls are in place
- When implementing custom authentication providers, validate that the external authentication response is legitimate before calling login/register services