User authentication

User authentication is how Drupal confirms which account sends a request. In core, a person submits a username and password to the login form, Drupal checks the password against the stored hash, and a session cookie identifies the account on later requests. Authentication answers who you are; permissions decide what you may do.

How it works in Drupal 11

The login form lives at /user/login and is built by UserLoginForm. The form calls the service user.auth, whose class UserAuthentication implements UserAuthenticationInterface. The method lookupAccount() finds the account by username, and authenticateAccount() compares the password with the stored hash. If the hash uses an outdated scheme, Drupal rehashes the password after a successful check and saves the account. The login form separately refuses blocked accounts with the message that the username has not been activated or is blocked.

Older code may call authenticate(), which returns a user ID. That method is deprecated since Drupal 10.3.0 and scheduled for removal in Drupal 12.0.0. New code should use the two methods above.

Failed logins are counted by flood control, the service user.flood_control. The shipped user.flood configuration sets user_limit: 5 with user_window: 21600, ip_limit: 50 with ip_window: 3600, and uid_only: false. Windows are in seconds. With uid_only off, the per-account count is kept per account and IP address.

After login, requests are recognized by an authentication provider. The provider with the ID cookie, registered as a global provider, reads the user ID from the session. It treats the request as anonymous when the account no longer exists or is blocked. Core also includes the HTTP Basic Authentication module, which provides a provider for the PHP_AUTH_USER and PHP_AUTH_PW values of a request. It counts its failed logins separately, with the same user.flood limits. A successfully identified visitor is authenticated; otherwise the visitor stays anonymous.

Example

An editor opens /user/login and keeps entering the wrong password. After five failures from the same IP address, Drupal answers that the account is temporarily blocked. A developer who needs access for testing can run drush user:login --name=anna, which generates a one-time login link for that username. Without options, the command targets user ID 1.

Common mistakes

• Mixing up authentication and authorization. Logging in proves identity. It does not grant rights; roles do.
• Assuming a second factor is built in. The core login checks a password only. Two-factor needs a contributed module.
• Calling the deprecated method. Custom code that uses authenticate() will fail when Drupal 12 removes it.
• Sharing the user 1 login. Shared credentials make the site log useless.

For marketing and content teams

You sign in at /user/login. If a login fails repeatedly, Drupal says the account is temporarily blocked; wait or use the password reset at /user/password instead of trying again. If your site holds customer data or can publish to the public, ask your developers about two-factor authentication for editors and administrators.

Sources

• UserAuthentication class, Drupal core source
• UserAuthenticationInterface, Drupal core source
• UserLoginForm, Drupal core source (11.2.0)
• user.flood configuration, Drupal core source (11.2.0)
• Cookie authentication provider, Drupal core source (11.2.0)
• User module services, Drupal core source (11.2.0)
• User module routing, Drupal core source (11.2.0)
• HTTP Basic authentication provider, Drupal core source
• Two-factor Authentication (TFA), Drupal.org project page
• Drush user:login command