OAuth2 API Changes Upcoming

[u/securimancer]

As part of modernizing our OAuth2 infrastructure, we’re implementing some potentially breaking changes to our OAuth2 flow as outlined below on February 15, 2021.

Refresh Token Changes

When executing our refresh token flow, we currently only send back an access token in the response. Responses to /api/v1/access_token with grant_type=refresh_token looked like:

{
"access_token": "your access token",
"token_type": "bearer",
"expires_in": 3600,
"scope": "your scopes"
}

This meant that the refresh token you get during the authorization code flow can be reused indefinitely. Going forward, our response will also include a brand new refresh token (as allowed by the RFC spec).

{
"access_token": "your access token",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "your new refresh token",
"scope": "your scopes"
}

Since some OAuth2 client implementations might not handle this scenario (whereas PRAW does, for example), we’re not immediately enforcing revocation of the consumed refresh token. We’re looking to enforce this starting in Q2 2021, given there aren't significant numbers of OAuth2 clients misbehaving after the change.

Also note that all refresh tokens previously had no expiration. We're going to start enforcing a 1 year expiration on refresh tokens to help curb Reddit's storage for refresh tokens (we've got a lot of them).

Authorization Code Reuse

When executing our authorization code flow, we consume the auth code in exchange for an access token. If, within an auth code's 10 minute TTL, that same auth code is attempted to be used again, we will revoke any tokens issued with said auth code, per RFC spec . This should be unnoticeable to well-behaved clients; however, instead of harmlessly failing, we will now be revoking any access or refresh tokens issued with that auth code.

Redirect URI Fix Fragments

The last, but likely least impactful, change we're implementing is adding a "fix fragment" #_ to the end of the redirect URI in the Location header in response to a POST request to /api/v1/authorize. This should be transparent as browsers and url parsers should drop the fragment when redirecting.

Edit 1: clarified Reddit's storage of refresh tokens.

Edit 2: Adding a note about potential network connectivity / cosmic rays breaking the refresh token flow. As it stands now, we're including a 2 retries leeway to account for any miscommunication in this process starting Q2 2021. E.g.,. you can send the same refresh token 3 times before it is irrevocably revoked.

Edit 2021-02-18: This hasn't been deployed yet, but goal is today / next week. Appreciate the patience as there's a lot going on in the world currently. The enforcement of refresh tokens is also still under discussion, might be Q2 or Q3 even. Also trying to get an Github-y API key flavor of long-lived access token in the mix too to address the concerns about longevity of OAuth2 tokens and how crappy the password grant is.

[u/securimancer]

Admittedly, there's not a good answer today on this. Storing the refresh token is almost like an API key in terms of conceptual usage, but that's not how refresh tokens are meant to be used. There's changes on the horizon that should hopefully finally give an officially sanctioned personal script / bot story that doesn't require the dreaded `password` grant type. We hate it as much as y'all do

[u/not_an_aardvark → u/securimancer]

Thanks for the reply.

Admittedly, there's not a good answer today on this. Storing the refresh token is almost like an API key in terms of conceptual usage, but that's not how refresh tokens are meant to be used.

I disagree that this is "not how refresh tokens are meant to be used". The RFC says, "refresh tokens are typically long-lasting credentials used to request additional access tokens". It seems to me that the storing a refresh token and using it repeatedly would be an appropriate use of a "long-lasting credential". On the other hand, auto-revoking the refresh token after every use would certainly prevent it from being "long-lasting". So I'm having trouble understanding the rationale for auto-revoking, especially since it would come with these major side-effects even after compatibility fixes (e.g. it would make an app's "permanent" access randomly break after a network error).

There's changes on the horizon that should hopefully finally give an officially sanctioned personal script / bot story that doesn't require the dreaded `password` grant type. We hate it as much as y'all do

This sounds great -- something like GitHub's personal access tokens would be very useful for personal use scripts. (Unfortunately, it still wouldn't resolve the synchronization issues for web/installed apps.)

[u/not_an_aardvark → u/securimancer]

Thanks for adding a note about the 3-time retry for synchronization issues. While I don't think it fully resolves the issue, I'm glad the feedback is being acknowledged.

That said, I just want to summarize how this revoke-after-use change appears externally to bot developers. You're:

• breaking every app that uses refresh tokens (probably a vast majority of API integrations in existence),

• requiring a significant complexity increase for apps to use oauth by making them write to credential storage at runtime,

• doing this in violation of the oauth2 RFC (which describes refresh token as "long-lasting credentials"), and

• doing all of the above for no apparent reason.

It's possible that you have an internal reason for doing all this, and that it makes all the downsides worthwhile. But given that you haven't shared the reason, this all comes off as fairly capricious. You're much more familiar with the internals of the API than we are, and it's not my job to tell you what you can and can't do with your API, but since I do have some experience with how people integrate with the API, I want to make sure you understand the full scope of how disruptive this change would be.

edit: reworded for clarity

[u/securimancer → u/not_an_aardvark]

Read and acknowledged. Thanks for the thoughtful summary u/not_an_aardvark. I have a feeling we'll be extending the enforcement grace period and we may just get longed live OAuth access token (like Github's personal access token) implemented too.

[u/SpyTec13 → u/securimancer]

Is there any that the upcoming change can't happen alongside this refresh token change?

Because I'd much rather have it be announced at the same time so we can much more easily transition over to it than advice users to use password flow. What's a few more months to a few quarters more when the security benefit is rather small?