Posted by Michael Winser, Product Lead, Google Apps and Wesley Chun , Developer Advocate, Google
Apps
Last week , we clarified the expectations and
responsibilities when accessing Google user data via OAuth 2.0. Today, we’re
announcing that in order to better protect users, we are increasing account
security for enterprise Gmail users effective October 5, 2016 .
At this time, a new policy will take effect whereby users in a Google Apps
domain, while changing their passwords on or after this date , will
result in the revocation of the OAuth 2.0 tokens of apps that access their
mailboxes using Gmail-based authorization scopes. Please note that users
will not notice any specific changes on this date and their
applications will continue to work . It is only when a user changes
their password from that point moving forward that their Gmail-related tokens
become invalid.
Developers should modify their applications to handle HTTP 400 or 401 error
codes resulting from revoked tokens and prompt their users to go through the
OAuth flow again to re-authorize those apps, such that they can access the
user’s mailbox again (additional details below). Late last year, we announced
a similar, planned change to our security policy that impacted a broader set of
authorization scopes. We later decided
not to move forward with that change for Apps customers and began working on a
less impactful update as described above.
What is a revoked token?
A revoked OAuth 2.0 token no longer provides access to a user’s resources. Any
attempt to use a revoked token in API calls will result in an error. Any
existing token strings will no longer have any value and should be discarded.
Applications accessing Google APIs should be modified to handle failed API
calls.
Token revocation itself is not a new feature. Users have always been able to
revoke access to applications in Security
Checkup , and Google Apps admins have the ability to do the same in the Admin
console. In addition, tokens that were not used for extended periods of time
have always been subject to expiration or revocation. This change in our
security policy will likely increase the rate of revoked tokens that
applications see, since in some cases the process will now take place
automatically.
What APIs and scopes are impacted?
To achieve the security benefits of this policy change with minimal admin
confusion and end-user disruption, we’ve decided to limit its application to
mail
scopes exclude Apps Script tokens. Apps
installed via the Google Apps
Marketplace are also not subject to the token revocation. Once this change
is in effect, third-party mail apps like Apple Mail and Thunderbird―as well as other applications that use multiple scopes that include at least one mail scope ―will
stop accessing data upon password reset until a new OAuth 2.0 token has been
granted. Your application will need to detect this scenario, notify the user
that your application has lost access to their account data, and prompt them to
go through the OAuth 2.0 flow again.
Mobile mail applications are also included in this policy change. For example,
users who use the native mail application on iOS will have to re-authorize with
their Google account credentials when their password has been changed. This new
behavior for third-party mail apps on mobile aligns with the current behavior of
the Gmail apps on iOS and Android, which also require re-authorization upon
password reset.
How can I determine if my token was revoked?
Both short-lived access tokens and long-lived refresh tokens will be revoked
when a user changes their password. Using a revoked access token to access an
API or to generate a new access token will result in either HTTP 400 or 401
errors. If your application uses a library to access the API or handle the OAuth
flow, then these errors will likely be thrown as exceptions. Consult the
library’s documentation for information on how to catch these exceptions. NOTE:
because HTTP 400 errors may be caused by a variety of reasons, expect the
payload from a 400 due to a revoked token to be similar to the following:
{
"error_description": "Token has been revoked.",
"error": "invalid_grant"
}
How should my application handle revoked tokens?
This change emphasizes that token revocation should be considered a normal
condition, not an error scenario. Your application should expect and detect the
condition, and your UI should be optimized for restoring tokens.
To ensure that your application works correctly, we recommend doing the
following:
Add error handling code around API calls and token refreshes that can detect
revoked tokens.
Upon detecting a revoked token, disable any application features that rely
on Google API access until the user can re-authorize your application. For
example, suspend any recurring background jobs that sync data with a Google API
which may be affected.
Notify the user that access has been revoked and prompt them to re-authorize
access to their resources.
If your app interacts directly with the user, you will need to
prompt the user to re-authorize, i.e., send an email to the user and/or show
them an alert the next time they open your application.
However, if your app runs independently of the user, say a
background app that uses the Gmail API, you'll need to notify the user through
email or some other mechanism.
Provide a streamlined UI for re-authorizing access. Avoid having users
navigate through your application to find the original setting.
Note that revoked tokens will result in similar error messages regardless of
how the token was revoked. Your messaging should not assume that the token was
revoked due to a password change.
If your application uses incremental
authorization to accrue multiple scopes in the same token, you should track
which features and scopes a given user has enabled. The end result is that if
your app requested and obtained authorization for multiple scopes, and at least
one of them is a mail scope, that token will be revoked, meaning you will need
to prompt your user to re-authorize for all scopes originally granted.
Many applications use tokens to perform background or server-to-server API
calls. Users expect this background activity to continue reliably. Since this
policy change also affects those apps, this makes prompt notification
requesting re-authorization even more important.
What is the timeline for this change?
To summarize, properly configured applications should be expected to handle
invalid tokens in general, whether they be from expiration, non-existence, and
revocation as normal conditions. We encourage developers to make any necessary
changes to give their users the best experience possible. The policy change is
planned to take effect on October 5, 2016 .
Please see this Help
Center article and FAQ for more details and the full list of mail scopes .
Moving forward, any additional scopes to be added to the policy will be
communicated in advance. We will provide those details as they become available.
