Posted by Michael Winser, Product Lead, Google Apps and Wesley Chun, Developer Advocate, Google
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
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
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
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
scopes only and to 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
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.",
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
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.