Better documentation for refresh tokens expiry

[Blquinn]

I've been implementing this package with the following settings.

OAUTH2_PROVIDER = {
    'SCOPES': {'read': 'Read scope', 'write': 'Write scope', 'groups': 'Access to your groups'},
    'ACCESS_TOKEN_EXPIRE_SECONDS': 60*60,  # 2 hours
    'REFRESH_TOKEN_EXPIRE_SECONDS': 7*24*60*60,  # A week
    'ROTATE_REFRESH_TOKEN': True,  # Sends a new refresh token when a access token is refreshed.
}

So, I want access tokens to expire in an hour and refresh tokens to expire in a week after the last time the access token was refreshed. This is how you'd interpret these settings if you were reading them naively (as I was).

The problem is, that this is not exactly the behavior that happens. Refresh tokens in fact, live forever unless you set up a cron the run the cleartokens command. Beyond that they seem to live not for REFRESH_TOKEN_EXPIRE_SECONDS seconds, but rather ACCESS_TOKEN_EXPIRE_SECONDS seconds + REFRESH_TOKEN_EXPIRE_SECONDS seconds + the amount of time between that expiration time and the time that you run cleartokens.

This is really not a huge issue, because refresh tokens are long-lived, however it is pretty confusing when you're trying to debug. Specifically, I set the expirations to 30 and 60 seconds respectively and did not see the expected behavior because I wasn't running cleartokens.

My request is that the docs emphasize the importance of the cleartokens command. It could probably be explained in the settings page as that's where I was looking for this information at first.

I can PR that if someone asks, but I don't necessarily know if people want me to be writing the docs as a non-contributor.

Thanks!

[jturmel]

I'm not positive I'm reading your question correctly, but cleartokens is just to keep the database tidy, the access/refresh tokens aren't available to use once they're expired.

[vrevelas]

I agree that the docs need improvement in this area. @jturmel refresh tokens do not have an expiration date, which is also stated by the glossary:

Refresh Token
A token the authorization server may issue to clients and can be swapped for a brand new access token, without repeating the authorization process. It has no expire time.

This can also be confirmed by checking the fields on the relevant model.

However, the docs for cleartokens state:

The cleartokens management command allows the user to remove those refresh tokens whose lifetime is greater than the amount specified by REFRESH_TOKEN_EXPIRE_SECONDS settings. It is important that this command is run regularly (eg: via cron) to avoid cluttering the database with expired refresh tokens.

The use of the phrase "expired refresh tokens" here implies that refresh tokens have an expiration date, which is not the case. In fact, even the name of the setting REFRESH_TOKEN_EXPIRE_SECONDS initially made me assume that refresh tokens expire.

Continuing to read the docs for cleartokens:

Note: Refresh tokens need to expire before AccessTokens can be removed from the database. Using cleartokens without REFRESH_TOKEN_EXPIRE_SECONDS has limited effect.

That's incorrect. Refresh tokens need to be removed from the database by cleartokens based on the value of REFRESH_TOKEN_EXPIRE_SECONDS in order to delete expired access tokens.