Hi All,
This week's Firefox Accounts deployment will bring with it an important
change to the way that OAuth tokens work: refresh tokens.
After our next deployment, access tokens will be short-lived rather than
being valid until explicitly revoked. I expect this change to be
backwards-compatible with the behavior of all our existing OAuth
reliers, but it does affect the way that existing access tokens work.
If you were using OAuth tokens once and then discarding them, this
change will not affect you. Everything should keep working as before.
If you store OAuth tokens to get ongoing access to an FxA-authenticated
service, then hopefully I've already spoken to you about this change.
You will need to start requesting a "refresh token" that can be used to
generate fresh access tokens on demand. Read on for details, and reach
out to me if you'd like to discuss migrating your existing tokens to
this framework.
A much more detailed description follows.
Cheers,
Ryan
The Old Way
-----------
In our existing OAuth flow, reliers obtain a single OAuth token that
they can use for ongoing access FxA services such as profile data. It
is passed in the authorization header as a "Bearer" token, and it is
valid until explicitly revoked by the relier or the user.
This setup is not great from a security perspective. Reliers end up
passing a single long-lived token over the wire every time they need to
access an FxA-authenticated service. If that token has multiple scopes,
all of those scopes are implicitly granted to all services that ever
receive the token.
Fortunately our existing suite of services is quite small, and our
existing reliers only tend to use tokens once and then discard them.
But as the FxA ecosystem grows, this approach is unsustainable.
The New Way
-----------
Going forward, we have split the powers granted to an OAuth relier into
two separate tokens. In line with the OAuth spec we now offer separate
"access tokens" and "refresh tokens":
http://tools.ietf.org/html/rfc6749#section-5.1
The "access token" grants you access to an FxA-authenticated resource.
For example, it's the thing you would pass in the authorization header
as a "Bearer" token when reading a users profile data. These tokens are
now short-lived. Current expiry is two weeks, but we plan to shorten
this considerably once we're comfortable with the deployment.
The "refresh token" gives you the power to mint additional access tokens
as needed. It's the thing that you might store in your database to get
ongoing access to an FxA-authenticated service.
This might sound familiar to anyone who has used "offline access" in the
Google identity platform; it is indeed almost exactly the same, and is
based on the same parts of the underlying OAuth2 spec:
https://developers.google.com/identity/protocols/OAuth2WebServer#offline
Refresh tokens are not generated by default. To request one, specify
"access_type=offline" when initiating the OAuth dance:
https://github.com/mozilla/fxa-oauth-server/blob/master/docs/api.md#get-v1authorization
This will produce an additional "refresh_token" field in the token
response at the end of the dance. Stash it away for later use.
To use the refresh token, POST it to /v1/token in the same way you would
trade a code for a token, but specify "grant_type=refresh_token":
https://github.com/mozilla/fxa-oauth-server/blob/master/docs/api.md#post-v1token
This will produce a normal access-token response with a fresh,
short-lived access token.
You can test this out right now in our staging environment:
https://accounts.stage.mozaws.net/
And we expect it to be live in production later this week.
Enjoy!
_______________________________________________
Dev-fxacct mailing list
[email protected]
https://mail.mozilla.org/listinfo/dev-fxacct
