Rolling refresh token expiry introduced a completely new "iat" behavior on token refresh

[robinnydahl]

Subject of the issue

Release 2.5.0 (see #256) changed the behavior of the iat (issued at) timestamp during token refresh. Previously, the iat value remained unchanged across refreshes, creating a fixed refresh window from the original token’s creation. However, the new behavior issues a fresh iat with every refresh, resulting in a rolling refresh token expiry.

The description in the config do not reflect this change and this change also causes users of the package that expected the old behavior to have possibility of indefinite sessions which was not possible in the previous version when refresh_ttl was set.

The config states the following today:

    /*
    |--------------------------------------------------------------------------
    | Refresh time to live
    |--------------------------------------------------------------------------
    |
    | Specify the length of time (in minutes) that the token can be refreshed
    | within. I.E. The user can refresh their token within a 2 week window of
    | the original token being created until they must re-authenticate.
    | Defaults to 2 weeks.
    |
    | You can also set this to null, to yield an infinite refresh time.
    | Some may want this instead of never expiring tokens for e.g. a mobile app.
    | This is not particularly recommended, so make sure you have appropriate
    | systems in place to revoke the token if necessary.
    |
    */

    'refresh_ttl' => env('JWT_REFRESH_TTL', 20160),

Impact

This change modifies how refresh token expiry is calculated, as each refresh now resets the refresh window based on the most recent refresh time. This can lead to unexpected behavior for users expecting a fixed refresh window.

Suggested Solution

To support both behaviors, we suggest to introduce an optional config parameter:

'refresh_iat' => env('JWT_REFRESH_IAT', true),

Setting refresh_iat to false reverts to the previous behavior, maintaining a fixed refresh window from the original token creation. However, this change is not yet reflected in the configuration comments, which may cause confusion.

Your environment:

Q	A
Bug?	yes & no
New Feature?	yes
Framework	Laravel
Framework version	11.x
Package version	2.7.2
PHP version	8.3

[robinnydahl]

I have opened up a pull request with a suggested solution/fix to this issue, #269.

The default behavior has been set to how the package works today, so it will not break existing users on new releases from 2.5.0. The 2.5.0 release did however technically break intended behavior based on the documentation in the config.php.

[mfn]

https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6 says

The "iat" (issued at) claim identifies the time at which the JWT was
issued. This claim can be used to determine the age of the JWT. Its
value MUST be a number containing a NumericDate value. Use of this
claim is OPTIONAL.

When using the refresh flow, a copied over iat would lead to a wrong validation in \PHPOpenSourceSaver\JWTAuth\Claims\IssuedAt::validateRefresh().

Refreshing essentially creates a new token: why would we carry over the iat? What's the purpose of, let me put it in striking words, "lying" about the tokens issued at?

You describe the problem with the change of the bevaiour, but can you also describe your use-case here?

[robinnydahl]

Hi @mfn,

Thanks for getting back to me! Sorry for the delayed response, I just got back from a vacation.

When using the refresh flow, a copied over iat would lead to a wrong validation in \PHPOpenSourceSaver\JWTAuth\Claims\IssuedAt::validateRefresh().

We managed to run all the rests successfully, might not be that there is a test case covering this? I'll let us sort out the other question below before we tackle that.

Refreshing essentially creates a new token: why would we carry over the iat? What's the purpose of, let me put it in striking words, "lying" about the tokens issued at?

You describe the problem with the change of the bevaiour, but can you also describe your use-case here?

The use-case; A user authenticates and checks "remember me". We should then allow the session to be active for a specified time-frame (for example 30 days) before the user is forced out and need to do the auth flow again. This way we will never get infinite activate sessions that can be misused or high-jacked without ever getting an expiry.

We do not wish to issue an access token that is usable for 30 days without making any refresh, we want short lived tokens. As this package uses a concept of JWT where the JWT (active and expired) can used to issue a new token, rather than a specific refresh token, the old implementation made a lot of sense as it combined the JWT and Refresh Token into one.

I understand this change might be helpful/needed for other use-cases, but it also causes issues based on the original intention and the documentation was not updated to reflect this or explain the reason for the change. The attached PR should allow for the old behavior without causing issues (we'll of course need to check the \PHPOpenSourceSaver\JWTAuth\Claims\IssuedAt::validateRefresh() you mentioned).

Does this clear up your question on the use case?

[specialtactics]

I agree with the author of the PR. Security is becoming a bigger and bigger concern nowdays, so the use-case is, what if the package user wants to set a maximum time-frame for the session of the user (including all refreshes) - before they need to re-authenticate. The security problem is, once you have a JWT, you can infinitely refresh it - even if for example the user is banned or judged to be a bad actor. Sure while it's possible to blacklist - that shouldn't be the permanent solution for these situations.

I have seen such security requirements as necessary when complying with some security frameworks, so I think it's important that we allow for this requirement to be met easily when using the package, and I think a config option is the best way to go from the perspective of developer experience.

I don't have any strong opinions for how to implement it specifically, I think an opt-in or even default (in my view it's best practice to limit it) to something that the developer can change is a good approach.