Buffer for renewing both id_tokens and access_tokens when they are about to expire, but not actually expired.

[jabbera]

Proposed change

If the id_token or access_token are going to expire within the next N minutes, I'd like to be able to have the refresh process renew them.

We use the tokens as part of the oauth OBO flow in hooks and actively on servers while they are running. Knowing the access/id token isn't expired exactly when the refresh process runs isn't helpful. First the id_token expiration isn't checked at all it seems, second the access/id_token could not be expired at T + 0 when refresh_runs but at T+1 when we need it in the hook it could be expired.

Alternative options

We have implemented the following hook:

It's ugly because it depends on the internal implementation of an HTTPClientError with a 400 error code is what causes the refresh process:

    async def modify_auth_state_hook(self, _, auth_state: dict[str, Any]) -> dict[str, Any]:
        if not (self._token_almost_expired(auth_state.get("access_token", None)) or self._token_almost_expired(auth_state.get("id_token", None))):
            self.log.error(f"Tokens are not expired for: {auth_state['user']['name']}")
            return auth_state

        raise HTTPClientError(
            401,
            "Tokens are expired. Please re-authenticate.",
        )


    def _token_almost_expired(self, str_token: str | None):
        """Returns True if the token is expired."""
        if not str_token:
            return True

        decoded_token = jwt.decode(str_token, options={"verify_signature": False})
        token_expiration = datetime.fromtimestamp(decoded_token["exp"], tz=timezone.utc)
        deadline = datetime.now(timezone.utc) + self._token_expiration_buffer
        return token_expiration < deadline

Who would use this feature?

Anyone who needs to use the access_token or id_token during hooks or server lifetime

(Optional): Suggest a solution

[minrk]

Absolutely! I tried to figure this out in a generic way, but couldn't since OAuth doesn't standardize this, though OIDC does.

It might be that the refresh_user_hook is what you want, which is where we check if access tokens are still valid.

We could provide a default OIDC implementation of this with a max age config so you can import one instead of reimplementing it.

[jabbera]

but couldn't since OAuth doesn't standardize this, though OIDC does.

I didn't realize this. I went to do an implementation, and the testing was where I ran into issues because real tokens aren't generated, just markers.

It might be that the refresh_user_hook is what you want,

This would be nice if there was a way for the hook to request a forced refresh. Right now, I would need to re-implement all of the refresh logic that exists that is awesome and I want to use. If the hook could return "FORCE" or something, then make this part of the refresh code not run, that would be better IMO.

oauthenticator/oauthenticator/oauth2.py

Lines 1382 to 1392 in 643227a

	try:
	auth_model = await self._token_to_auth_model(token_info)
	except HTTPClientError as e:
	# assume any client error means an expired token
	# most likely 401 or 403 for well-behaved providers
	if 400 <= e.code < 500:
	self.log.info(
	f"Error refreshing auth with current access_token for {user.name}: {e}. Will try to refresh, if possible."
	)
	else:
	raise

[jabbera]

Another idea would be an additional hook:

if not self._call_should_force_token_refresh_hook(auth_state):
    try:
        auth_model = await self._token_to_auth_model(token_info)
    except HTTPClientError as e:
        # assume any client error means an expired token
        # most likely 401 or 403 for well-behaved providers
        if 400 <= e.code < 500:
            self.log.info(
                f"Error refreshing auth with current access_token for {user.name}: {e}. Will try to refresh, if possible."
            )
        else:
            raise

[minrk]

This would be nice if there was a way for the hook to request a forced refresh

Ah, right. There's a way to force a whole new login but not specifically a refresh. A should_refresh_token_hook or something makes sense.