Making Google OAuth interactions safer by using more secure OAuth flows

Posted by Vikrant Rana, Product Manager and Badi Azad, Group Product Manager, Google

At Google, we constantly strive to provide safer ways for users to sign-in and share their Google account data with third-party applications. In the spirit of that work, we will be rolling out a set of protections against phishing and app impersonation attacks during the OAuth interactions.

The Google sign-in and authorization flows are powered by the Google OAuth platform and over the years we have developed and supported a number of ways for app developers to integrate with supported OAuth flows. With the goal of keeping users safer online, we will end support for two legacy flows and will require developers to migrate to alternative implementation methods that offer greater protections.

To ensure a smooth transition and avoid any service interruption we will give ample time to implement and meet the compliance dates which are specified below. We will share further updates on this rollout via email so please make sure your support email address is up to date in project settings on the Google API console.

Loopback IP address flow will be disallowed for native iOS, Android and Chrome OAuth client types

The Loopback IP address flow is vulnerable to man in the middle attack where a malicious app, accessing the same loopback interface on some operating systems, may intercept the OAuth response and gain access to the authorization code. We intend to remove this threat vector by disallowing this flow for iOS, Android and Chrome app OAuth client types. The existing clients will be able to migrate to more secure implementation methods. New clients will be unable to use this flow starting on March 14, 2022.

What do I need to do

Determine if your app is using the Loopback IP address flow

You can inspect your app code or the outgoing network call (in case your app is using an OAuth library) to determine if the Google OAuth authorization request your app is making has the following values for “redirect_uri” parameter.

redirect_uri=http://127.0.0.1:port or http://[::1]:port”>http://[::1]:port or

http://localhost:port

Migrate to an alternative flow

If your app is using the Loopback IP address method you need to migrate to another method which is more secure by default. Please consider the following alternative methods for migration.

Key dates for compliance

  • Mar 14, 2022 – new OAuth usage will be blocked for the Loopback IP address flow
  • Aug 1, 2022 – a user-facing warning message may be displayed to non-compliant OAuth requests one month before the compliance date
  • Aug 31, 2022 – the Loopback IP address flow is blocked for existing clients

OAuth out-of-band (oob) flow will be deprecated

OAuth out-of-band (OOB) is a legacy flow developed to support native clients which do not have a redirect URI like web apps to accept the credentials after a user approves an OAuth consent request. The OOB flow poses a remote phishing risk and clients must migrate to an alternative method to protect against this vulnerability. New clients will be unable to use this flow starting on Feb 28, 2022.

What do I need to do

Determine if your app is using the OOB flow

You can inspect your app code or the outgoing network call (in case your app is using an OAuth library) to determine if the Google OAuth authorization request your app is making has the following values for “redirect_uri” parameter.

redirect_uri=urn:ietf:wg:oauth:2.0:oob or urn:ietf:wg:oauth:2.0:oob:auto or oob

Migrate to an alternative flow

If your app is using the OOB method you need to migrate to another method which is more secure by default. Please consider the following alternative methods for migration.

Key dates for compliance

  • Feb 28, 2022 – new OAuth usage will be blocked for the OOB flow
  • Sep 5, 2022 – a user-facing warning message may be displayed to non-compliant OAuth requests
  • Oct 3, 2022 – the OOB flow is deprecated for existing clients

User-facing warning message

A user-facing warning message may be displayed for non-compliant requests one month before the aforementioned OAuth methods are due to be blocked. The message will convey to the users that the app may be blocked soon while displaying the support email that you have registered in the OAuth consent screen in Google API Console.

[Sample user-facing warning]

The developers can acknowledge the user-facing warning message and suppress it by passing a query parameter in the authorization call as shown below.

  • Go to the code in your app where you send requests to Google’s OAuth 2.0 Authorization Endpoint.
  • Add a parameter with a value of the enforcement date
    • For OOB: Add an ack_oob_shutdown parameter with a value of the enforcement date: 2022-10-03. Example: ack_oob_shutdown=2022-10-03
    • For Loopback IP address: Add an ack_loopback_shutdown parameter with a value of the enforcement date: 2022-08-31. Example: ack_loopback_shutdown=2022-08-31

User-facing error message

If an app is not updated to meet compliance by the required date the authorization requests will be blocked and users may encounter an invalid request error screen (sample shown below).

[Sample user-facing error]

Google OAuth incremental authorization improvement

Posted by Vikrant Rana, Product Manager, and Badi Azad, Group Product Manager

Summary

Google Identity strives to be the best stewards for Google Account users who entrust us to protect their data. At the same time, we want to help our developer community build apps that give users amazing experiences. Together, Google and developers can provide users three important ways to manage sharing their data:

  1. Give users control in deciding who has access to their account data
  2. Make it easier and safer for users to share their Google Account data with your app when they choose to do so
  3. Make it clear to users the specific data they are sharing with apps

What we are doing today

In service of that stewardship, today we are announcing an OAuth consent experience that simplifies how users can share data with apps. This experience also improves the consent conversion for apps that use incremental authorization, which requests only one scope. Users can now easily share this kind of request with a single tap.

Screenshot compares the previous screen and the new screen you see when Example app wants to access your account

Previous Screen                                               New Screen

A quick recap

Let’s summarize a few past improvements so you have a full picture of the work we have been doing on the OAuth consent flow.

In mid-2019, we significantly overhauled the consent screen to give users fine-grained control over the account data they chose to share with a given app. In that flow, when an app requested access to multiple Google resources, the user would see one screen for each scope.

In July 2021, we consolidated these multiple-permission requests into a single screen, while still allowing granular data sharing control for users. Our change today represents a continuation of improvements on that experience.

Screenshot that shows the option to select what Example app can access

The Identity team will continue to gather feedback and further enhance the overall user experience around Google Identity Services and sharing account data.

What do developers need to do?

There is no change you need to make to your app. However, we recommend using incremental authorization and requesting only one resource at the time your app needs it. We believe that doing this will make your account data request more relevant to the user and therefore improve the consent conversion. Read more about incremental authorization in our developer guides.

If your app requires multiple resources at once, make sure it can handle partial consent gracefully and reduce its functionality appropriately as per the OAuth 2.0 policy.

Related content

Upcoming security changes to Google’s OAuth 2.0 authorization endpoint in embedded webviews

Posted by Badi Azad, Group Product Manager (@badiazad)

The Google Identity team is continually working to improve Google Account security and create a safer and more secure experience for our users. As part of that work, we recently introduced a new secure browser policy prohibiting Google OAuth requests in embedded browser libraries commonly referred to as embedded webviews. All embedded webviews will be blocked starting on September 30, 2021.

Embedded webview libraries are problematic because they allow a nefarious developer to intercept and alter communications between Google and its users by acting as a “man in the middle.” An application embedding a webview can modify or intercept network requests, insert custom scripts that can potentially record every keystroke entered in a login form, access session cookies, or alter the content of the webpage. These libraries also allow the removal of key elements of a browser that hold user trust, such as the guarantee that the response originates from Google’s servers, display of the website domain, and the ability to inspect the security of a connection. Additionally the OAuth 2.0 for Native Apps guidelines from IETF require that native apps must not use embedded user-agents such as webviews to perform authorization requests.

Embedded webviews not only affect account security, they could affect usability of your application. The sandboxed storage environment of an embedded webview disconnects a user from the single sign-on features they expect from Google. A full-featured web browser supports multiple tools to help a logged-out user quickly sign-in to their account including password managers and Web Authentication libraries. Google’s users also expect multiple-step login processes, including two-step verification and child account authorizations, to function seamlessly when a login flow involves multiple devices, when switching to another app on the device, or when communicating with peripherals such as a security key.

Instructions for impacted developers

Developers must register an appropriate OAuth client for each platform (Desktop, Android, iOS, etc.) on which your app will run, in compliance with Google’s OAuth 2.0 Policies. You can verify the OAuth client ID used by your installed application is the most appropriate choice for your platform by visiting the Google API Console’s Credentials page. A “Web application” client type in use by an Android application is an example of mismatched use. Reference our OAuth 2.0 for Mobile & Desktop Apps guide to properly integrate the appropriate client for your app’s platform.

Applications opening all links and URLs inside an embedded webview should follow the following instructions for Android, iOS, macOS, and captive portals:

Android

Embedded webviews implementing or extending Android WebView do not comply with Google’s secure browser policy for its OAuth 2.0 Authorization Endpoint. Apps should allow general, third-party links to be handled by the default behaviors of the operating system, enabling a user’s preferred routing to their chosen default web browser or another developer’s preferred routing to its installed app through Android App Links. Apps may alternatively open general links to third-party sites in Android Custom Tabs.

iOS & macOS

Embedded webviews implementing or extending WKWebView, or the deprecated UIWebView, do not comply with Google’s secure browser policy for its OAuth 2.0 Authorization Endpoint. Apps should allow general, third-party links to be handled by the default behaviors of the operating system, enabling a user’s preferred routing to their chosen default web browser or another developer’s preferred routing to its installed app through Universal Links. Apps may alternatively open general links to third-party sites in SFSafariViewController.

Captive portals

If your computer network intercepts network requests, redirecting to a web portal supporting authorization with a Google Account, your web content could be displayed in an embedded webview controlled by a captive network assistant. You should provide potential viewers instructions on how to access your network using their default web browser. For more information reference the Google Account Help article Sign in to a Wi-Fi network with your Google Account.

New IETF standards adopted by Android and iOS may help users access your captive pages in a full-featured web browser. Captive networks should integrate Captive-Portal Identification in DHCP and Router Advertisements (RAs) proposed IETF standard to inform clients that they are behind a captive portal enforcement device when joining the network, rather than relying on traffic interception. Networks should also integrate the Captive Portal API proposed IETF standard to quickly direct clients to a required portal URL to access the Internet. For more information reference Captive portal API support for Android and Apple’s How to modernize your captive network developer articles.

Test for compatibility

If you’re a developer that currently uses an embedded webview for Google OAuth 2.0 authorization flows, be aware that embedded webviews will be blocked as of September 30, 2021. To verify whether the authorization flow launched by your application is affected by these changes, test your application for compatibility and compliance with the policies outlined in this post.

You can add a query parameter to your authorization request URI to test for potential impact to your application before September 30, 2021. The following steps describe how to adjust your current requests to Google’s OAuth 2.0 Authorization Endpoint to include an additional query parameter for testing purposes.

  1. Go to where you send requests to Google’s OAuth 2.0 Authorization Endpoint. Example URI: https://accounts.google.com/o/oauth2/v2/auth
  2. Add the disallow_webview parameter with a value of true to the query component of the URI. Example: disallow_webview=true

An implementation affected by the planned changes will see a disallowed_useragent error when loading Google’s OAuth 2.0 Authorization Endpoint, with the disallow_webview=true query string, in an embedded webview instead of the authorization flows currently displayed. If you do not see an error message while testing the effect of the new embedded webview policies your app’s implementation might not be impacted by this announcement.

Note: A website’s ability to request authorization from a Google Account may be impacted due to another developer’s decision to use an embedded webview in their app. For example, if a messaging or news application opens links to your site in an embedded webview, the features available on your site, including Google OAuth 2.0 authorization flows, may be impacted. If your site or app is impacted by the implementation choice of another developer please contact that developer directly.

User-facing warning message

A warning message may be displayed in non-compliant authorization requests after August 30, 2021. The warning message will include the user support email defined in your project’s OAuth consent screen in Google API Console and direct the user to visit our Sign in with a supported browser support article.

A screenshot showing an example Google OAuth authorization dialog including a warning message: To help protect your account, Google will soon block apps that don't comply with Google's embedded webview policy. You can let the app developer (moo@gmail.com) know that this app should stop using embedded webviews

Developers may acknowledge the upcoming enforcement and suppress the warning message by passing a specific query parameter to the authorization request URI. The following steps explain how to adjust your authorization requests to include the acknowledgement parameter:

  1. Go to where you send requests to Google’s OAuth 2.0 Authorization Endpoint. Example URI: https://accounts.google.com/o/oauth2/v2/auth
  2. Add an ack_webview_shutdown parameter with a value of the enforcement date: 2021-09-30. Example: ack_webview_shutdown=2021-09-30

A successful request to Google’s OAuth 2.0 Authorization Endpoint including the acknowledgement query parameter and enforcement date will suppress the warning message in non-compliant authorization requests. All non-compliant authorization requests will display a disallowed_useragent error when loading Google’s OAuth 2.0 Authorization Endpoint after the enforcement date.

Related content

Get smart about preparing your app for OAuth verification

Posted by Nafis Zebarjadi, Product Manager and Adam Dawes, Senior Product Manager

Project Strobe was started to help users have control over their data while giving developers more explicit rules of the road to ensure everyone is confident that their data is secure. One result of this effort has been to expand our app verification program to cover more apps and more types of data access. It is important to understand how the process works so that you can optimally build your app and streamline the verification process. Here we walk you through the process of preparing your app for OAuth verification.

Getting prepared for verification

The first thing you should do is confirm whether your app needs verification. App verification is only required if you want to launch your app widely to consumer or enterprise users and the app requests sensitive or restricted scopes. Apps that use non-sensitive scopes, are under development, or are built just for your own G Suite users are not required to go through verification. If the app is just for users within your own organization, choose the ‘Internal’ application type to restrict the app to use within your own organization and skip verification.

Once you initiate app verification, it is not easy to make updates to your app’s Google API configuration. If you make any changes while in the process, you will need to start over again, so it’s critical that you get your app ready before initiating verification to avoid delays.

Determining if your app is using sensitive or restricted scopes

The first thing you need to do is look at your code on each platform to determine which OAuth scopes (Google APIs) your service needs. Be sure to do this on every client; we often see that apps will request different scopes on different platforms, and then initiate app verification on a subset of scopes than your clients actually use. Often, you can find the scopes by searching your code for the string “www.googleapis.com/auth”. Not all legacy scopes contain that string so you may also want to find the code related to the Google API library you’re using (on the specific platform) to see what scopes are being requested, or look at our directory of scopes.

Once you have identified all of the scopes that your apps use, you can check to see whether they are sensitive or restricted by going to the Cloud Console (APIs & Services -> Credentials -> OAuth consent screen -> Scopes for Google APIs) and pressing the ‘Add scope’ button. This will bring up the following window:

Google Cloud Console’s ‘Add Scope’ to your OAuth client tool and how it highlights sensitive scopes.

If the scope has a lock icon, it means that the scope is either sensitive or restricted and that you’ll need to go through app verification before you can widely launch to Google users.

[Note that the tool only lists scopes for APIs that you’ve enabled for your project. If you don’t see a scope listed, you’ll first need to enable the corresponding API for your project from the API Library. The fact that you’re not seeing the scope used in your code may mean that you have clients set up in different projects.]

Setting up the right project structure

Apps are reviewed and approved at the project level so you’ll want to make sure that you’ve configured your clients properly before starting app verification. If you have multiple projects, each one will have to independently go through app verification.

When to add multiple clients to a project: You may have multiple clients for your app to support different platforms like Android, Web and iOS. Ideally, all of these clients should be in the same project because it will smooth out the cross-client consent experience. When clients are in the same project, users only need to provide consent to one of the clients. Other clients can automatically get tokens without forcing the user to go through the consent flow for the same requested scopes again. The user is agreeing to share data with your service regardless of which platform they happen to be using and your service terms should be the same across platforms.

When to separate clients into separate projects: Your company may also have multiple apps that you publish to users. You may or may not want to host the clients related to your different apps in the same project. Generally, if the different apps use the same login system, have the same privacy policy and users recognize the brand of the publisher of all the apps, then it makes sense to have all the clients in the same project. For example, if PersonalFinance Corp has accounting, budgeting and tax apps that all share the same login, privacy policy and users recognize the PersonalFinance Corp brand, then it is best to structure those all in the same project. However, if CoolGames publisher has lots of titles that have different login systems and different privacy policies, or users are more familiar with the individual game titles than the CoolGames brand, then you should use separate projects.

Reorganizing projects: It is not possible to move or reorganize clients once they are created. If you want to make changes, you can either choose to create new clients in a centralized project or get each app verified independently. If you create new clients in a centralized project, you’ll update your apps to use the new client and abandon the old clients. The issue you may encounter with this approach is that your app may have to obtain user consent all over again (if the user hasn’t also consented to your other client). Alternately, you can leave your clients in separate projects; however, each project will have to go through app verification independently and users will have to consent to each of your clients individually.

Setting up test vs production projects: For many developers, it is also helpful to have a parallel test project to your production project. This allows you to easily change scopes or other app properties and test behavior without having to go through app verification.

Configuring your project

If your app does need to be verified, you’ll want to make sure the information about your project is up-to-date to avoid delay.

Project Owners

As we roll out changes across our API ecosystem, it is important to make sure your projects have up-to-date contact information. We often need to send notifications about changes, and have had developers miss important updates because of incorrect contact information which has resulted in their app being unexpectedly disabled. One way to help ensure your team gets notifications is to create a Google Group that aliases to a stable group within your company (and be sure to configure the group to receive emails from non-members). Another option is to create an Organizational Resource in the Cloud Console so that your client assets can be centrally administered and recovered when owners leave the company. It’s also very good practice to ensure the owners of the Android/iOS/Web clients are also owners or editors of the project. Domain verification is also required for every app, so you will also want to add your DNS administrator to the project so that person can easily go through the process.

To update project owners, use Cloud IAM in the Cloud Console (Cloud Console -> IAM and admin -> IAM).

Branding Info and Domain Verification

Branding info includes your app’s name and logo. It is critical that these are accurate because users use these to decide whether they know and trust your app. In the verification process, we will validate that you own the brand and logo and that it matches the information on your web site. If you make changes, your previously approved branding will continue to be shown until the new information can be verified.

OAuth consent screen showing a redirect domain

You will also need to verify the domain associated with your brand. This is true even if you only have Android/iOS versions of your app because you must have a website to publicly host your privacy policy. You start the domain verification process by linking your domain to your project in the Cloud Console (APIs & Services -> Domain verification). You’ll then need to go to the Search Console to prove that you own and control the domain.

Domain verification is a key security feature for your web clients. If you have web clients in your project, each of those must have their Authorized Redirect URIs or Authorized JavaScript Origins match an already verified domain. This enables us to guarantee that OAuth tokens are only returned to your application.

Adding an authorized domain for a Google Cloud Project in the domain verification tab

Scopes

Since you’ve already identified the scopes that your app uses, you should now check to see if you can change scopes to minimize your data access. Our API User Data Policy requires that you only request information that your app needs and that you’re clear to the user about how you will use it. It’s inappropriate to gain access to Google user data for alternate purposes such as advertising and market research.

In particular, you’ll want to try to avoid the use of restricted scopes. The verification process for restricted scopes can take several weeks longer than sensitive scopes. It also requires significant documentation and may involve a third-party security assessment that you must pay for. Currently, only specific Gmail scopes are restricted, but we have announced that most Drive scopes are also becoming restricted in early 2020.

If your app does need to access a restricted scope, consider architecting your app such that the Google user data is only ever stored client-side on the user’s device (like a contact manager app). Storing data in the cloud or on your own servers will require you to obtain a third-party security assessment (at your expense), and could also result in significant work to resolve any security issues found during the assessment.

Once you’ve decided on the scopes your app will need, make sure that they are registered with your project and reflected in your app’s code. We’ve seen many cases where a developer’s code calls a different set of scopes than those that have been registered in the Cloud Console. If your app does this, your users will see an unverified app error. Many developers request troubleshooting help because their users are unexpectedly seeing these errors even though their app was approved. Inevitably, it is because their code does not match what was verified. Similarly, if you need to add new scopes to your application, you’ll need to get those scopes approved before you launch the functionality into your production app (a test client is going to be essential here).

While you’re thinking about scopes, you should also consider how and when you are asking your users for consent. The best practice is to not request scopes at sign-in, but to use incremental authorization to allow a user to access a particular feature when they want it. This is a great way to build trust because the user interacts in a particular feature, can see the benefit of the feature, and understands why granting a particular permission will make the feature more useful.

Privacy Policy

Our goal in verifying apps is to ensure that any data users choose to share with third-parties is well-managed and meets users’ expectations about how it will be used. Your privacy policy is your public contract to your users and a critical proof to us that users’ expectations will be met.

You must include a link to your privacy policy on your website. If the domain where you host that policy isn’t verified, we won’t verify your app. If your app is purely mobile, with no server-side component, you will still need a privacy policy, but it may be very simple and describe that your app only stores data on a user’s device.

Google can not provide guidance on your privacy policy, but if your app requests restricted scopes, we will scrutinize your policy to understand how you plan to use that data and ensure that it conforms to our requirements. Make sure you understand the Limited Use requirements, and consult with your legal counsel to ensure that your privacy policy is consistent with the requirements. To ensure clarity in how your app handles email content, we also recommend adding the following statement to your application’s home page: “App’s use of information received from Gmail APIs will adhere to Google’s Limited Use Requirements.” This is needed when your privacy policy is not specific in how email content is used.

Submitting your app for verification

Once you have your project(s) configured with all the appropriate information, you can submit your app for verification. We have three different types of app verification depending on the scopes you request, each taking a different amount of time to complete. If you start your verification with one set of scopes and later decide you need different scopes, you usually need to finish your existing verification before you can start the process again. This could cause frustration and lengthen your overall verification process.

Brand Verification (2-3 days)

Brand Verification is our simplest process and validates that your brand name and logo belong to you. It is an optional step if your app is requesting non-sensitive scopes like Google Sign-In and typically takes just 2 to 3 business days. If your app doesn’t go through brand verification, users will only see your domain name listed on the consent page.

Sensitive Scope Verification (3-5 days)

Starting in June 2019, we greatly expanded the classification of sensitive scopes and started requiring more extensive verification for new apps that are accessing those scopes. Existing apps that are already accessing sensitive scopes need to go through this verification process in the latter half of 2019.

Sensitive scope verification involves brand and domain validation, checking that the privacy policy is prominently available from your application home page. We also review your app and privacy policy against our API Services: User Data Policy and check for deceptive practices. The privacy policy must disclose the manner in which your application accesses, uses, stores, or shares Google user data. Your use of Google user data must be limited to the practices disclosed in your published privacy policy.

A YouTube or accessible Drive video will also be required to understand how users will experience your request for scopes, showing specifically how they’ll benefit from granting you access. The identity of your app needs to be clear from the video (including the app’s client ID), and you’ll need to highlight the value proposition you communicate to the user before requesting the scopes.

Until verification is completed, users will see an unverified app page when your app requests a scope requiring verification. Up to 100 users may choose to grant access while your app is unverified. After that, users will be blocked from granting access to your app until verification is complete.

Unverified app screen on mobile

Sensitive scope verification usually takes 3 to 5 business days if there aren’t any issues with your app.

Restricted Scope Verification (4-6 weeks)

Restricted scope verification is a much more involved process. In addition to going through all the steps for a sensitive scope verification, your app will also have a much more rigorous privacy policy review to ensure that your use of Google user data conforms to our Limited Use requirements. Only permitted application types will be considered for access to restricted scopes. Finally, if your app stores data on a server, you will need to pass an annual security assessment.

We do error validation before allowing you to click the ‘Submit for Verification’ button. Here are some common reasons why the button is not clickable:

  • No verified domain
  • Privacy policy URL, authorized redirect URIs or origins for your client do not match an authorized domain
  • No new scopes added to the project that require verification

When you submit your app for verification, you will need to provide a written explanation for why your app needs the requested scopes. This explanation should include the nature of the feature and how the user will benefit from using it. It’s also best to include a link to your YouTube video in the original submission to save some back and forth with the review team.

You’ll also be asked again what email should receive questions and notifications about the verification process. Make sure you provide an address that you pay attention to and can receive emails from outside your domain. Questions will go to the person who initiated verification (not necessarily project owners) and the contact email address provided in the verification form. We’ve seen many requests delayed because the developer hasn’t responded to questions from the verification team.

Example form for a project requesting verification

Responding to verification questions

Apps with sensitive and restricted scopes often need to answer questions from the verification team. If you believe it has taken a long time to get a response from the verification team, you should search your inbox for messages from ‘api-oauth-dev-verification-reply’ to ensure that you haven’t missed anything.

By following these guidelines for submitting your app for verification, you can greatly streamline the process of getting your app approved and released to the Google user community. If you have any follow-up questions, be sure to scan the OAuth API Verification FAQ.