Like other Google APIs, the Google Ads API uses the OAuth 2.0 protocol for
authentication and authorization. OAuth 2.0 enables your Google Ads API .NET client
app to access a user's Google Ads account without having to handle or store the
user's login info.

## Understand the Google Ads access model

To work effectively with the Google Ads API, understand how the Google Ads access model
works. Refer to the [Google Ads access model guide](https://developers.google.com/google-ads/api/docs/oauth/access-model).

## OAuth workflows

There are three common workflows used when working with the Google Ads API.

### Service account flow

This is the recommended workflow if your application doesn't require any human
interaction. This workflow requires a configuration step, where the user adds a
[service account](https://developers.google.com/identity/protocols/oauth2#serviceaccount) to their Google Ads account. The app can then use
the service account's credentials to manage the user's Google Ads account.

Configure the library as follows:

    // Initialize a GoogleAdsConfig instance.
    GoogleAdsConfig config = new GoogleAdsConfig()
    {
        OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
        OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
        LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
    };

    // Initialize a GoogleAdsClient instance.
    GoogleAdsClient client = new GoogleAdsClient(config);

Refer to the [service account workflow guide](https://developers.google.com/google-ads/api/docs/oauth/service-accounts) to learn
more.

### Single-user authentication flow

This workflow may be used if you cannot use service accounts. This workflow
requires two configuration steps:

1. Give a single user access to all the accounts to be managed using the Google Ads API. A common approach is to give the user access to a Google Ads API manager account, and link all the Google Ads accounts under that manager account.
2. The user runs a command-line tool such as [`gcloud`](https://cloud.google.com/sdk/gcloud) or the [`GenerateUserCredentials` code example](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples/Authentication/GenerateUserCredentials) to authorize your app to manage all their Google Ads accounts on their behalf.

Initialize the library using the user's OAuth 2.0 credentials as follows:

    GoogleAdsConfig config = new GoogleAdsConfig()
    {
        LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
        OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
        OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
        OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
    };

    GoogleAdsClient client = new GoogleAdsClient(config);

Refer to the [single-user authentication workflow guide](https://developers.google.com/google-ads/api/docs/oauth/single-user-authentication) to
learn more.

### Multi-user authentication flow

This is the recommended workflow if your app allows users to sign in and
authorize your app to manage their Google Ads accounts on their behalf. Your app
builds and manages the OAuth 2.0 user credentials dynamically per user session
or request, and then initializes a `GoogleAdsClient` with the active user's
refresh token:

    GoogleAdsConfig config = new GoogleAdsConfig()
    {
        LoginCustomerId = userSession.LoginCustomerId,
        OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
        OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
        OAuth2RefreshToken = userSession.RefreshToken
    };

    GoogleAdsClient client = new GoogleAdsClient(config);

Starting in `Google.Ads.GoogleAds` **`v27.0.0`** , you can also inject a
pre-configured `ICredential` or `GoogleCredential` object directly on
`GoogleAdsConfig` using the `Credentials` property.

Refer to the [multi-user authentication workflow guide](https://developers.google.com/google-ads/api/docs/oauth/multi-user-authentication) to
learn more. The .NET client library includes two code examples for reference:

1. The [`AuthenticateInAspNetCoreApplication`](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples/Authentication/AuthenticateInAspNetCoreApplication) code example illustrates how to build a web app that obtains user authentication at runtime to manage their Google Ads accounts on their behalf. The app uses the user's OAuth 2.0 credentials to retrieve the campaigns in their Google Ads account.
2. The [`GenerateUserCredentials`](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples/Authentication/GenerateUserCredentials) command-line code example illustrates how to obtain user authentication at runtime to manage their Google Ads accounts on their behalf. You can use this code example as a reference to build desktop apps that require user authentication.

## What if my user manages multiple accounts?

It is common for a user to manage more than one Google Ads account, either through
direct access to accounts, or through a Google Ads manager account. The .NET client
library provides the following code examples that illustrate how to handle such
cases:

1. The [`GetAccountHierarchy`](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples/AccountManagement/GetAccountHierarchy.cs) code example shows how to retrieve the list of all accounts under a Google Ads manager account.
2. The [`ListAccessibleCustomers`](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples/AccountManagement/ListAccessibleCustomers.cs) code example shows how to retrieve the list of all accounts that a user has direct access to. These accounts can then be used as valid values for the `LoginCustomerId` setting.

## Application Default Credentials

The .NET client library (`v24.1.0` and later) also supports authenticating with
[Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials).

This is particularly useful for local development or for development against
different Google APIs, as you can reuse the same credentials, provided that they
can access the required OAuth 2.0 scopes.

For the Google Ads API, make sure your Application Default Credentials can access the
`https://www.googleapis.com/auth/adwords` OAuth 2.0 scope.

To use Application Default Credentials, set the
`UseApplicationDefaultCredentials` option to `true` in your `GoogleAdsConfig`
(or set the `USE_APPLICATION_DEFAULT_CREDENTIALS=true` environment variable when
loading configuration with `config.LoadFromEnvironmentVariables()`):

    GoogleAdsConfig config = new GoogleAdsConfig()
    {
        UseApplicationDefaultCredentials = true,
        LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
    };
    GoogleAdsClient client = new GoogleAdsClient(config);

Refer to the [configuration](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/configuration) page for further details about
the available options to configure the .NET client library.