Configure OAuth

When you publish your app, there are 4 main tasks to complete for authentication and authorization:

  1. Fill out the OAuth consent screen.
  2. Create your OAuth 2.0 credential.
  3. Configure all scopes that the app needs to run in the Google Workspace Marketplace SDK
  4. Submit your app for OAuth verification.

The scopes you add to each place must match and are used in the following ways:

  • The scopes added to the OAuth consent screen are used for OAuth verification.
  • The scopes added to the Google Workspace Marketplace SDK are used for domain-wide and individual installs to authorize your app when its installed from the Google Workspace Marketplace.
  • The scopes added to the manifest are necessary for your app to function properly.

For example, if you publish an app that includes a Google Sheets add-on and a Google Docs add-on, each add-on's Apps Script manifest only includes the scopes specific to the add-on. In your Google Cloud project, the OAuth consent screen and Google Workspace Marketplace SDK include the scopes for both add-ons.

Prerequisites

The OAuth consent screen is a prompt that tells users who's requesting access to their data and what kind of data users are allowing your app to access.

  1. In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.

    Go to OAuth consent screen

  2. Select the user type for your app, then click Create.
  3. Complete the app registration form, then click Save and Continue.

  4. If you're creating an app for use outside of your Google Workspace organization, click Add or Remove Scopes. We recommend the following best practices when selecting scopes:

    • Select the scopes that provide the minimum level of access required by your app. For a list of available scopes, see OAuth 2.0 Scopes for Google APIs.
    • Review the scopes listed in each of the three sections: non-sensitive scopes, sensitive scopes, and restricted scopes. For any scopes listed in the "Your sensitive scopes" or "Your restricted scopes" sections, try to identify alternative non-sensitive scopes to avoid unnecessary additional reviews.
    • Some scopes require additional reviews by Google. For apps used only internally by your Google Workspace organization, scopes aren't listed on the consent screen and use of restricted or sensitive scopes doesn't require further review by Google. For more information, see Scope categories.
  5. After selecting the scopes required by your app, click Save and Continue.
  6. If you selected External for user type, add test users:
    1. Under Test users, click Add users.
    2. Enter your email address and any other authorized test users, then click Save and Continue.
  7. Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.

2. Create your OAuth 2.0 credential

Depending on how you built your app, there are two different ways to create your OAuth 2.0 credentials.

If you built your app in Apps Script

Switch your Apps Script project from its default Google Cloud project to your new, standard project. See Switching to a different standard project.

After you associate your Apps Script project with the Google Cloud project, your OAuth 2.0 credential is automatically created.

If you didn't use Apps Script to build your app

To create your OAuth 2.0 credential, see OAuth client ID credentials.

3. Configure scopes

Provide a complete list of the OAuth scopes that your app requires. Always use the narrowest scopes possible.

To define the level of access granted to your app, you need to identify and declare authorization scopes. An authorization scope is an OAuth 2.0 URI string that contains the Google Workspace app name, what kind of data it accesses, and the level of access. Scopes are your app's requests to work with Google Workspace data, including users' Google Account data.

When your app is installed, a user is asked to validate the scopes used by the app. Generally, you should choose the most narrowly focused scope possible and avoid requesting scopes that your app doesn't require. Users more readily grant access to limited, clearly described scopes.

4. Submit for OAuth verification (Public apps only)

If a public app uses sensitive or restricted scopes, it must undergo an OAuth verification review process.

  • For OAuth verification, you must submit a demo video demonstrating the journey or flow that explains the usage of the requested scopes or data to users.
  • If your app uses restricted scopes, it might also need to go through a security assessment. See Why is the security assessment needed.

To submit for verification, follow these steps:

  1. In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.

    Go to OAuth consent screen

  2. Click Project selector, and select your project.
  3. Click Edit app
  4. Enter the required information, and then click Submit for verification.
  5. In the Verification required dialog, enter the appropriate justifications, and then click Submit to start the verification process.

If you update your app to use different scopes that are sensitive or restrictive, you must submit your app for OAuth verification again. You don't need to send it for app review again.

How OAuth verification differs from app review

OAuth verification is a separate process from app review. It focuses on making sure that your consent screen accurately represents your app's identity and intent, and makes sure your app doesn't misuse user data. Your app listing cannot be approved until your app's OAuth verification is complete. For more information about OAuth verification, see OAuth API verification FAQ.

App review focuses on the information that you provide in the Google Workspace Marketplace API, and the functionality and usability of your app. To learn more about the app review criteria, see About app review.