Authentication and Login API

Most of these functions live in wp-includes/pluggable.php and are pluggable: a plugin loaded earlier can replace them (wp_hash_password(), wp_check_password(), wp_set_auth_cookie(), wp_validate_auth_cookie(), wp_authenticate(), wp_logout()). Each now has filters, so replacing one is rarely needed; see Hooks: Actions and Filters. On the REST API, a request carrying only the login cookie without a valid wp_rest nonce is treated as anonymous; see REST API: Using It.

A login sets three HttpOnly cookies. Their names end in COOKIEHASH, the MD5 of the siteurl option, so two sites on one host do not clash and changing the site URL logs everybody out:

The path restriction is a defense: the cookie that grants admin access is never sent with front-end requests. Names and paths can be redefined in wp-config.php Reference, which only renames them. A curl login as tom.author on the test site received exactly these: the test cookie, the admin cookie twice (once per path) and the logged_in cookie, all HttpOnly, and a redirect to /wp-admin/.

wp_authenticate( $username, $password ) sanitizes the username, trims the password and returns what the authenticate chain produces; an empty result becomes a generic authentication_failed error, and every error except an empty field fires wp_login_failed (username and WP_Error, the latter since 5.4). The default chain in 7.1.3 is wp_authenticate_username_password(), wp_authenticate_email_password() and wp_authenticate_application_password() (API requests only) at priority 20; wp_authenticate_cookie() at 30, added by wp_signon() only, which accepts an existing valid cookie when no credentials were posted; and wp_authenticate_spam_check() at 99, which refuses users marked as spam on Multisite.

Each callback receives the result so far (null, WP_User or WP_Error), the username and the password. A callback below 20 can replace password checking (an LDAP check returns a WP_User, which the core callbacks pass through); one above 20 sees the resolved user and can veto it. wp_authenticate_user is a narrower filter that runs only in the username and email paths, before the password is checked.

Source: Code Reference: wp_login

On the test site, with lumen-login.php active, a login as sam.reader stored lp_last_login. A login_redirect callback returning home_url( '/books/' ) for users without edit_posts when no redirect_to was requested sent sam.reader to the catalogue instead of the profile, and add_filter( 'login_headerurl', static fn() => home_url( '/' ) ) pointed the logo at the home page.

Since 6.8, wp_hash_password() uses bcrypt through PHP’s password_hash(). Because bcrypt ignores everything after 72 bytes, WordPress first takes an HMAC-SHA384 of the password (key wp-sha384), base64-encodes it, hashes that and prefixes $wp: stored hashes start with $wp$2y$ and the cost ($wp$2y$12$ under PHP 8.4, whose default cost is 12). Passwords longer than 4096 characters are refused. wp_check_password( $password, $hash, $user_id ) accepts every format WordPress has stored:

wp_password_needs_rehash() (6.8) reports whether a hash is weaker than the current algorithm and options; wp_authenticate_username_password() then calls wp_set_password(), so old hashes are upgraded one login at a time:

Source: Code Reference: wp_check_password()

The classic lock-out remedy, writing MD5('<temporary-password>') into user_pass, was tried on maria.editor: the login succeeded and the column then started with $wp$2y$12$. It works, but leaves a fast, unsalted hash until the next login; wp user update maria.editor --user_pass=<new-password> stores bcrypt directly. Extension points:

The PHP side is in PHP: Cryptography, Hashing and Passwords.

Application passwords (5.6) are per-user, revocable credentials for HTTP Basic authentication on the REST API and XML-RPC; they never work on wp-login.php. They are stored in the _application_passwords user meta as items with uuid, app_id, name, password, created, last_used and last_ip; since 6.8 password holds a BLAKE2b hash from wp_fast_hash(), marked $generic$. Availability rules are in Users, Roles and Profiles. Provisioning code uses WP_Application_Passwords:

Source: Code Reference: WP_Application_Passwords::create_new_application_password()

The plain password is returned only once, as the first array element; a missing name gives a WP_Error with status 400. On the test site, curl -u "tom.author:$TOM_APP_PASSWORD" against /wp-json/wp/v2/users/me?context=edit returned tom.author with the author role; see REST API: Using It for the request side. Posted to wp-login.php, the same password was rejected as incorrect. The other static methods are get_user_application_passwords(), get_user_application_password(), update_application_password(), record_application_password_usage() (writes at most once a day), delete_application_password() and delete_all_application_passwords(); they fire wp_create_application_password, wp_update_application_password and wp_delete_application_password. Authentication fires application_password_did_authenticate or application_password_failed_authentication, and application_password_is_api_request extends the API-only rule. WP-CLI wraps the class as wp user application-password.

An external app should not ask users to paste a password: it sends them to /wp-admin/authorize-application.php?app_name=...&app_id=<uuid>&success_url=... (advertised in the REST index under authentication), and after approval WordPress redirects to success_url with site_url, user_login and password. A plain-HTTP success_url is refused unless the host is a loopback address or the environment type is local; custom app schemes are allowed, javascript: and data: are not.

Every login creates a session in a WP_Session_Tokens store. The default WP_User_Meta_Session_Tokens keeps the session_tokens user meta, keyed by the SHA-256 of each token, with the session’s expiration, ip, ua and login time; expired sessions are filtered out whenever the store is read. attach_session_information adds fields, and session_token_manager swaps in another class (for example one backed by Redis). The cookie carries the raw token, the database only its hash:

Source: Code Reference: WP_Session_Tokens

The count is four because tom.author already had two sessions (the curl login and the cookie example). For the current user, wp_get_session_token(), wp_get_all_sessions(), wp_destroy_current_session(), wp_destroy_other_sessions() and wp_destroy_all_sessions() wrap the same methods, and WP_Session_Tokens::destroy_all_for_all_users() logs everybody out. A password change leaves stored sessions in place, but their cookies stop validating. From the shell: wp user session destroy <user> --all.

Core knows only passwords, cookies and application passwords. OpenID Connect, OAuth 2.0 or SAML sign-on comes from plugins, such as OpenID Connect Generic Client on WordPress.org, or from commercial identity suites, which hook into the places described above:

WordPress cookies outlive the provider’s session unless the plugin shortens auth_cookie_expiration, and local passwords and application passwords keep working beside SSO unless the plugin disables them. The protocols are explained in OpenID Connect, Social Login and Federation and Logout and Session Management.

More corrections are collected in Where Older Books and Tutorials Are Outdated.