Correct expiration time documentation for `wp_set_auth_cookie()`

[peterwilsoncc]

The docs for wp_set_auth_cookie() indicate that without "Remember me" checked, the login cookie is set to expire after two days.

This is incorrect, logins that are set to be forgotten are set as session cookies to expire once the browser is closed. This is in line with industry standards.

Additionally the filter auth_cookie_expiration is fired for logins set to be forgotten but the value returned by the filter is ignored by WordPress. The second instance of the filter should be removed from the function (code ref).

@himanshupathak95 We can remove the else block and initialize the variable first. The $remember condition will override it if true.

`diff

diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php
index e7ce2edb41..56b117636d 100644
--- a/src/wp-includes/pluggable.php
+++ b/src/wp-includes/pluggable.php
@@ -984,6 +984,9 @@ if ( ! function_exists( 'wp_set_auth_cookie' ) ) :

• @param string $token Optional. User's session token to use for this cookie. */

function wp_set_auth_cookie( $user_id, $remember = false, $secure = , $token = ) {

+ $expire = 0;
+ $expiration = time() + ( 2 * DAY_IN_SECONDS );
+

if ( $remember ) {

/

• Filters the duration of the authentication cookie expiration period.

@@ -1001,10 +1004,6 @@ if ( ! function_exists( 'wp_set_auth_cookie' ) ) :

• Needed for the login grace period in wp_validate_auth_cookie(). */

$expire = $expiration + ( 12 * HOUR_IN_SECONDS );

• } else {
• / This filter is documented in wp-includes/pluggable.php */
• $expiration = time() + apply_filters( 'auth_cookie_expiration', 2 * DAY_IN_SECONDS, $user_id, $remember );
• $expire = 0;

}

if ( === $secure ) {

[zodiac1978]

As the one who posted his rant on Twitter/X which was the reason for this ticket I just want to say thanks for the ticket and the patch.

Additionally, I want to add, that this should be better documented. Maybe adding this lifetime information to this page:
​https://developer.wordpress.org/advanced-administration/wordpress/cookies/

Many articles are still saying wrongly the cookie lifetime is 48 hours (or 2 days) and with "Remember me" modified to 14 days.

Especially this sentence should be changed:

The cookies lifetime can be adjusted with the auth_cookie_expiration hook. An example of this can be found at what’s the easiest way to stop wp from ever logging me out.

The filter does only affect the lifetime if "Remember me" was checked. Otherwise not. This should be added to the docs.

[siliconforks]

Replying to peterwilsoncc:

Additionally the filter auth_cookie_expiration is fired for logins set to be forgotten but the value returned by the filter is ignored by WordPress.

Isn't the value still used on the server side, though? I believe the value is checked in wp_validate_auth_cookie() (regardless of whether "remember me" was used or not):

​https://github.com/WordPress/wordpress-develop/blob/07bf0f91117629fb382ad09b6de1d138baea15e0/src/wp-includes/pluggable.php#L729

[zodiac1978]

Replying to siliconforks:

Isn't the value still used on the server side, though? I believe the value is checked in wp_validate_auth_cookie() (regardless of whether "remember me" was used or not):

​https://github.com/WordPress/wordpress-develop/blob/07bf0f91117629fb382ad09b6de1d138baea15e0/src/wp-includes/pluggable.php#L729

Looking at this code it reads the cookie via wp_parse_auth_cookie and then it casts it to integer:

$cookie_elements = wp_parse_auth_cookie( $cookie, $scheme );
// ...
$expiration = $cookie_elements['expiration'];
// ...
$expired = (int) $expiration;

For a session cookie this means the value is 0.

What do you mean with server side?

[siliconforks]

Replying to zodiac1978:

Looking at this code it reads the cookie via wp_parse_auth_cookie and then it casts it to integer:

$cookie_elements = wp_parse_auth_cookie( $cookie, $scheme );
// ...
$expiration = $cookie_elements['expiration'];
// ...
$expired = (int) $expiration;

For a session cookie this means the value is 0.

What do you mean with server side?

I mean that the expiration time is used in a couple of different places:

1. It is used as the expiration time for the browser cookie.

2. It is also stored in the cookie itself (as a Unix timestamp - seconds since 1970) and validated by the server. That's what I mean by "server-side".

If "remember me" is not checked, then (1) above does not apply (because it will be a session cookie). However (2) still applies here.

The value of $expired in wp_parse_auth_cookie should never be 0 because it is using the value stored in the cookie itself rather than the cookie's expiration time.

[siliconforks]

Replying to siliconforks:

The value of $expired in wp_parse_auth_cookie should never be 0 because it is using the value stored in the cookie itself rather than the cookie's expiration time.

Correction: I meant wp_validate_auth_cookie here: $expired in wp_validate_auth_cookie should never be 0.

[johnbillion]

There's two "expiration" values for this cookie. The $expiration variable is how long the value of the hash in the cookie remains valid (which is either 14 or 2 days depending on $remember). The $expire variable is how long the cookie remains valid in the browser, which is 14 days when $remember is set or 0 if not, meaning it's a session cookie in the latter case.

​https://github.com/WordPress/wordpress-develop/blob/07bf0f91117629fb382ad09b6de1d138baea15e0/src/wp-includes/pluggable.php#L997-L1007

[peterwilsoncc]

I realised I was mistaken about don’t remember me after reviewing the code. The second instance is used, as John points out. The docs should document authentication time as:

Remember me: Remain logged in for 14 days, the cookie is stored for 14.5 days to avoid data loss in background Ajax requests immediately after the login expires and users are prompted to log back in.

Don’t remember me: remain logged in for the current browser session or up to two days (whichever is shorter) in browsers that remain open

The copy will need a little tidying up.

[zodiac1978]

Replying to johnbillion:

There's two "expiration" values for this cookie. The $expiration variable is how long the value of the hash in the cookie remains valid (which is either 14 or 2 days depending on $remember). The $expire variable is how long the cookie remains valid in the browser, which is 14 days when $remember is set or 0 if not, meaning it's a session cookie in the latter case.

​https://github.com/WordPress/wordpress-develop/blob/07bf0f91117629fb382ad09b6de1d138baea15e0/src/wp-includes/pluggable.php#L997-L1007

Thanks for the explanation @johnbillion!

So, this is not wrong at all, but only badly documented, if I'm correct.

The grace period of 12 hours is added for the cookie, but the hash is invalid and therefore the login expires correctly after 14 days if "remember me" is checked. If it is not checked this is a session cookie, but the 48 hours still apply because the hash is invalidated. Correct? Even with a session restore from a browser this cookie will still be invalid after 48 hours, because the hash does expire. Correct?

My use case was to use auth_cookie_expiration to log out every subscriber on midnight. This would still apply even when the cookie is 12 hours longer available or a session cookie, because the hash in the DB invalidates. Correct?

This would mean we could ignore the patch and just add some more explanation to the docs. The doc page from auth_cookie_expiration and the mentioned Cookies page from the advanced administration handbook for example.

Agreed?

[khoipro]

This would mean we could ignore the patch and just add some more explanation to the docs. The doc page from auth_cookie_expiration and the mentioned Cookies page from the advanced administration handbook for example.

I actually agreed with this idea.

[wildworks]

This ticket was featured on today's Bugs Club. It seems that this ticket is a documentation issue or a bug, so I'll change its type.

Clarifies the docblock for wp_set_auth_cookie() to better explain how the
$remember parameter works.

• If $remember is true, WordPress sets a persistent cookie (14 days by default, filterable with auth_cookie_expiration).
• If $remember is false, WordPress sets a session cookie that ends when the browser closes. The auth_cookie_expiration filter still runs (2 days by default), but because the cookie’s expire value is 0, it won’t persist.

This update makes the function’s behavior easier for developers to understand.

Trac ticket: https://core.trac.wordpress.org/ticket/63230

[rollybueno]

Hi all, since the recent discussion concludes that this only needs a better documentation, I've added new PR for clariying the remember me. Let me know if the new doc block is clear.

[wildworks]

@johnbillion @peterwilsoncc, do you have the bandwidth to review ​the latest pull request? If there's no activity, I plan to puntit to 7.0 before the RC1 release next week.

There are errors on the test unit check for test_wp_insert_post_handle_malformed_post_date, which is unrelated to the patch(only inline docs are updated)

[peterwilsoncc]

In 61188:

Docs: Clarify behavior in wp_set_auth_cookie().

Clarifies how long authentication cookies are set for when setting the $remember parameter.

Props johnbillion, khoipro, rollybueno, shailu25, siliconforks, wildworks, zodiac1978.
Fixes #63230.