## 1.1: OAuth Account Linking

### Introduction and Business Impact

*** ** * ** ***

To leverage the Google APIs, OAuth is required to grant your integration
the necessary merchant access to onboard them onto Free Listings and Paid Ads.

![alt-oauth](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth.png)

Your application must use [OAuth 2.0](https://developers.google.com/identity/protocols/oauth2) to authorize requests.
No other authorization protocols are supported.

### UX Guidance

*** ** * ** ***

**Goal**: Have merchants authorized to share
the use of their data for Google app.

**Design principle**: Ask for the right permission at the right time.
If merchants don't give the permission, fail gracefully.

The merchant is prompted to provide access permissions.
Find an example of how these instructions can be surfaced to the merchant:

![oauth_1](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_1.png)

![oauth_2](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_2.png)

Once the merchant goes through these initial steps,
there are three possible outcomes:

**Outcome #1: If the merchant agrees to all permissions:**

![oauth_3](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_3.png)

If the merchant provides full permissions, they check all of the boxes
and is prompted to continue the onboarding process.

**Outcome #2: If the merchant doesn't agree to Ads**

![oauth_4](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_4.png)

The merchant checks all of the boxes except the permission
related to Google Ads.
They continue the onboarding process and later,
when they are creating a new Google Ads account or connecting to
an existing account, they are prompted again to give permissions:

![oauth_5](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_5.png)
![oauth_6](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_6.png)

**Outcome #3: If product data or site verification is unchecked,
the merchant are blocked from continuing to onboard**

![oauth_7](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_7.png)

![oauth_8](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_8.png)

![oauth_9](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_9.png)

![oauth_10](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_10.png)

All of the preceding options result in the same error message:

![oauth_11](https://developers.google.com/static/merchant/storebuilder/images/blueprint/oauth_11.png)

### Tech Guidance

*** ** * ** ***

#### Choose the authorizing requests with OAuth 2.0

There are two methods to select a merchant [authentication method](https://cloud.google.com/docs/authentication/):

| OAuth 2.0 for non-service accounts (Highly Recommended) | OAuth 2.0 for service accounts |
|---|---|
| An OAuth 2.0 client identifies the application and lets end users grant your application limited access to their Google data. It allows your application to access Google Cloud APIs on behalf of the end user. The listed occurrences result in the access token being invalidated which should be accounted for in the code:  ● User has revoked access  ● User has changed password  ● Number of granted refresh tokens exceeded limit  ● Refresh token has not been used within 6 months | Service accounts are special Google accounts that can be used by applications to access Google APIs programmatically using OAuth 2.0.It uses an OAuth 2.0 flow that does not require human authorization. Instead, it uses a key file that only your application can access. **Note:** Applications using [service accounts](https://developers.google.com/shopping-content/guides/how-tos/service-accounts) for authentication can only access their own Merchant Center account. If you are writing a third-party application that needs access to your clients' Merchant Center accounts, see the Authorizing Requests guide instead. **Note:** a Cloud project is required and allows the creation of up to 100 service accounts. See [documentation](https://developers.google.com/identity/protocols/OAuth2ServiceAccount) |

> [!TIP]
> **Tip:** We highly recommend OAuth 2.0 to make API calls to your merchants' MC sub-accounts (reference preceding documentation for more info). There are other ways to make API calls to your merchants accounts.

> [!IMPORTANT]
> **Important:** Be aware that this authentication method requires a [cloud project](https://developers.google.com/adwords/shopping/feed-management/articles/t10). To learn more about setting this up, we recommend reviewing the [*Prerequisite and Essential Information Before Starting section*](https://developers.google.com/merchant/storebuilder/online/prerequisites).

#### Set up the OAuth flow

OAuth 2.0 authorization framework enables a third-party application to obtain
limited access to an HTTP service, either on behalf of a resource owner by
orchestrating an approval interaction between the resource owner and the HTTP
service, or by allowing the third-party application to obtain access on its own
behalf.

Because your app accesses protected (non-public) data, you need an OAuth 2.0
client ID. Google APIs use OAuth 2.0 protocol for authentication and
authorization. Google supports common OAuth 2.0 scenarios such as those for web
server, installed, and client-side applications.

**Learn More**

- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)
- [Setting up OAuth](https://support.google.com/googleapi/answer/6158849#zippy=%2Cpublic-and-internal-applications%2Cuser-consent)
- [OAuth for the content API](https://developers.google.com/shopping-content/guides/how-tos/authorizing)

#### Things to be aware about using OAuth for the content API for shopping:

1. **Ensure you have set the access_type to offline:** Access tokens
   periodically expire and become invalid credentials for a related API
   request.

2. **Refresh an access token:** You can do this without prompting the user
   for permission (including when the user is not present) if you requested
   offline access to the scopes. associated with the token ([learn more](https://developers.google.com/identity/protocols/oauth2/web-server#offline)).

3. **OAuth implementation in the Libraries:** We highly recommend you use
   [Google API Client Libraries](https://developers.google.com/api-client-library).

4. **Scope:** You need to request your merchant to grant you read and
   write access to its Google Account with the Google Merchant Center OAuth
   scope: https://www.googleapis.com/auth/content.

5. You can use **[OAuth to get key user profile info](https://developers.google.com/identity/protocols/oauth2/)**.

> [!TIP]
> **Tip:** For an interactive demonstration of using OAuth 2.0 with Google (including the option to use your own client credentials), experiment with the [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).

#### Scopes to use for your integration

Depending on which type of integrations you are planning to build for your
merchants, we recommend asking for all necessary scopes at this moment.

| Program | Scope | Which format is scope required |
|---|---|---|
| Content API | `https://www.googleapis.com/auth/content` | Free Listings |
| Site Verification | `https://www.googleapis.com/auth/siteverification` | Free Listing \& Paid Ads |
| Ads | `https://www.googleapis.com/auth/adwords` | Free Listing \& Paid Ads |

#### Verify if merchants have granted OAuth access

**Merchants have to tick boxes in the OAuth consent flow to grant you
access to specific scopes:** If the required scopes are missing, explain
to merchants why these are required and request the permission again
([more details](https://developers.google.com/identity/protocols/oauth2/policies#unbundled-consent)). Not having access to all of these permissions
prevent merchants from fully onboarding.

![access](https://developers.google.com/static/merchant/storebuilder/images/blueprint/1_1_access.png)

Call the following API endpoint to check the granted scopes:

    https://www.oauth2.googleapis.com/token

The URL returns the following information:

- access_token
- scopes granted to the user
- time before token expiration

![request](https://developers.google.com/static/merchant/storebuilder/images/blueprint/1_1_request.png)

#### Sensitive Scopes and OAuth Verification Process

Some scopes used by OAuth APIs are considered
[sensitive and require a verification process](https://support.google.com/cloud/answer/9110914#zippy=). Additional information
and examples can be found at [OAuth for the content API](https://developers.google.com/shopping-content/guides/how-tos/authorizing#requesting-app-verification).

1. Sensitive app scope to meet policy: Need to make sure that your app complies
   with [Google's API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy).
   You also need to agree to the [API terms of service](https://developers.google.com/terms/).

2. Confirm your app doesn't fall under any of the use cases listed in the
   [Exceptions to verification requirements](https://support.google.com/cloud/answer/9110914#exceptions-ver-reqts).

3. Verify ownership of your project's authorized domains: using the Search
   Console. Use an account that is either a Project Owner or a Project Editor
   of your Cloud Console project.

4. Make sure all branding information on the OAuth consent screen matches and is
   valid such as: the project name shown to users, support email, homepage URL, and
   privacy policy URL, accurately represents the app's identity.

5. Request your app for sensitive scope with the verification process:
   [Follow the process](https://support.google.com/cloud/answer/9110914#zippy=%2Csteps-for-apps-requesting-sensitive-scopes) which requires filling out a form,
   providing justification and sending a video.