I’m implementing an API wrapper for an OAuth API (in particular, TD Ameritrade) and I’ve encountered an interesting piece of functionality. Unlike most OAuth implementations I’ve seen, in which refresh token is valid for some time period and then the user has to re-authenticate, this API supports refreshing the refresh token itself.
In particular, if you send a request with the following format to the authentication endpoint, you will be rewarded with a brand new refresh token that’s good for 90 days:
grant_type: refresh_token refresh_token: <Refresh Token> access_type: offline client_id: <OAuth API Key>
A few things stand out as weird. First off, I’ve never seen this functionality before. Most of the APIs I work with don’t seem to support this refresh. Second, I can’t seem to find any straightforward way to implement this using common OAuth client library implementations like authlib. These libraries typically support transparent access token refreshing, but I have yet to see anything like transparent refresh token refreshing. Finally, I believe using the refresh_token grant type is overloaded in this case, since the same grant type is used to refresh the access token, not the refresh token. The only difference between the two is the use of the access_type: offline.
My question, then: is this standard OAuth behavior that is described in some RFC I simply haven’t managed to dig up yet, or is this something that is nonstandard that the developers of this API hacked into an otherwise standards-compliant API? The answer will decide whether I implement transparent refresh in my own library as a one-off, or whether I try to submit a patch to my favorite OAuth client implementation.
Advertisement
Answer
The access_type: offline parameter is not a standard in OAuth, but it’s used e.g. by Google in their token endpoint request – you must pass it to get a refresh token.
On the other refreshing refresh tokens is part of the OAuth standard. The RFC 6749 states that in a response to the token endpoint:
The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client. If a new refresh token is issued, the refresh token scope MUST be identical to that of the refresh token included by the client in the request.
So it is part of the standard to refresh refresh tokens, but it should be done differently than in their API.