Single-user authentication workflow

Page Summary

outlined_flag

• The single user authentication flow allows an app to manage all Google Ads accounts associated with a single authorized user.

• This workflow involves granting a user access to all relevant accounts and then having that user authorize your app.

• While simpler for a few users, this workflow has drawbacks compared to service accounts, including more complex setup, potential app verification, and risks if the authorized user leaves.

• You can generate the necessary credentials, such as a refresh token, using tools like gcloud CLI after configuring an OAuth consent screen and creating OAuth credentials in the Google Cloud Console.

• Once credentials are obtained, you can configure your Google Ads API client library to use them for API calls.

Similar to the service account workflow, the single-user authentication flow makes use of the authorization and user management features offered by the Google Ads UI to grant the app access to all the necessary accounts. This authentication workflow has two steps:

• You grant a single user access to all the Google Ads accounts that should be managed by the app.
• The user authorizes your app to manage their Google Ads accounts on their behalf, thus granting the app access to all the Google Ads accounts.

Since there is only one user involved, you can rely on tools such as the gcloud CLI or the GenerateUserCredential code example instead of building your own OAuth 2.0 user authentication flow.

A related use case for this workflow is when your accounts can be accessed through a handful of user logins (for example, 3 to 4 users), so the development effort to build a full-blown OAuth multi-user authentication workflow isn't justified when compared to the effort for obtaining authorization for 3 to 4 users using a command-line tool such as the gcloud CLI.

Drawbacks

There are a few disadvantages to this flow when compared to the service account workflow:

1. The user authentication workflow requires you to create an OAuth 2.0 client ID and secret in the Google Cloud Console, which requires more configuration steps than creating a service account and key.
2. If the authorized user leaves the team or company, then your app may stop working if you remove the user from your accounts or disable the user account. Service accounts are not tied to individual users, so this risk is avoided.
3. The user authorizing the Google Ads account should enable passkeys in their Google Account to defend against their Google Account getting compromised due to poor security, malware, or phishing. Service accounts are not required to enable passkeys, and are less vulnerable to this issue since some of these modes of attack don't directly apply to them.

Generate credentials

1. Configure an OAuth consent screen for your application and add https://www.googleapis.com/auth/adwords as an OAuth 2.0 scope. See Setting up your OAuth consent screen for details.

2. Create a client ID and client secret by following the instructions. Once you create the OAuth 2.0 client, download the client's JSON file by clicking the Download JSON button on the confirmation dialog. Save the file as credentials.json.

3. Identify a user account that has access to all the Google Ads accounts you want to manage using your app. If there are accounts with missing access, grant account access to that user.

4. Download and install the gcloud CLI. Once installed, verify that the tool works correctly by running the gcloud version command from a command-line prompt. The output looks similar to the following:

   gcloud version

   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   

5. Generate an OAuth 2.0 refresh token by running the gcloud CLI tool with the credentials.json file from the previous step. Passing --client-id-file is required so the refresh token is issued under your Google API Console project rather than the gcloud CLI's default project:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CREDENTIALS_JSON

6. The gcloud command opens a Google Account sign-in window in a new browser window and takes you through the OAuth 2.0 authentication steps. Make sure you sign in as the user you selected in the previous steps. If your app is unverified, you might see a warning screen. In such cases, it's safe to click the Advanced link and click the Go to PROJECT_NAME (unsafe) option.

7. After you verify the scopes, click the Continue button to grant permission. The browser navigates to https://cloud.google.com/sdk/auth_success, indicating that the authentication was successful. The page displays the following message:

   Authorization code granted. Close this tab.

   The gcloud command prints the following message:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
   

   Open the application_default_credentials.json file. Its contents are similar to the following:

   {
     "account": "",
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "refresh_token": "******",
     "type": "authorized_user",
     "universe_domain": "googleapis.com"
   }
   

Client library configuration

Select the tab corresponding to your programming language for instructions on how to configure your client library. If your authorized user accesses client accounts through a Google Ads manager account (MCC), set login-customer-id (or loginCustomerId) to the 10-digit customer ID of that manager account without hyphens.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://oauth2.googleapis.com/token

curl -i -X POST \
  https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}