Single User Authentication Workflow

AI-generated Key Takeaways

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 accountsthat 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 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 (e.g. 3-4 users), so the development effort to build a full-blown OAuth user authentication workflow isn't justified when compared to the effort for obtaining authorization for 3-4 users using a command line tool such as gcloud CLI.

Drawbacks

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

1. 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. Your app may have to go through an additional Google Cloud App verification process .
3. 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.
4. The user authorizing the Google Ads account should take extra precautions such as enabling 2 factor authentication to defend against their Google Account getting compromised due to getting compromised due to poor security, malware, or phishing. Service accounts are less vulnerable to this issue since some of these modes of attack don't directly apply to them.

Generate credentials

1. Follow the instructions to configure an OAuth consent screen for your application and add https://www.googleapis.com/auth/adwords as an OAuth 2.0 scope.

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 first clicking its Download OAuth client icon and then the DOWNLOAD JSON button on the following screen. 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, then follow the instructions to grant the necessary access.

4. Download and install gcloud CLI. Once installed, verify that the tool works correctly by running the gcloud version command from a command line prompt. The output may look as follows.

    :~$  
   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
   gsutil  
    5 
   .30 
   

5. Generate an OAuth 2.0 refresh token by running the gcloud CLI tool:

   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>

   The credentials.json file is from the previous step.

6. The gcloud command opens a Google Account login 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 from the previous steps. If your app is unverified, you might see a warning screen. In such cases, it's safe to click the Show Advancedlink and click the Go to PROJECT_NAME (unverified)option.

   

7. After you verify the scopes, click the Continuebutton to grant the 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]

   Now open the application_default_credentials.json file. Its contents should be similar to follows:

     { 
    "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.

 api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE 

  GoogleAdsConfig 
  
 config 
  
 = 
  
 new 
  
 GoogleAdsConfig 
 () 
 { 
  
 OAuth2Mode 
  
 = 
  
 OAuth2Flow 
 . 
 APPLICATION 
 , 
  
 OAuth2ClientId 
  
 = 
  
 "INSERT_OAUTH2_CLIENT_ID" 
 , 
  
 OAuth2ClientSecret 
  
 = 
  
 "INSERT_OAUTH2_CLIENT_SECRET" 
 , 
  
 OAuth2RefreshToken 
  
 = 
  
 "INSERT_OAUTH2_REFRESH_TOKEN" 
 , 
  
 ... 
 }; 
 GoogleAdsClient 
  
 client 
  
 = 
  
 new 
  
 GoogleAdsClient 
 ( 
 config 
 ); 
 

 client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE 

  [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_CLIENT_ID_HERE' 
  
 c 
 . 
 client_secret 
  
 = 
  
 'INSERT_CLIENT_SECRET_HERE' 
  
 c 
 . 
 refresh_token 
  
 = 
  
 'INSERT_REFRESH_TOKEN_HERE' 
  
 c 
 . 
 developer_token 
  
 = 
  
 'INSERT_DEVELOPER_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://www.googleapis.com/oauth2/v3/token 

 curl  
-i  
-X  
POST  
https://googleads.googleapis.com/v22/customers/ CUSTOMER_ID 
/googleAds:searchStream  
 \ 
  
-H  
 "Content-Type: application/json" 
  
 \ 
  
-H  
 "Authorization: Bearer ACCESS_TOKEN 
" 
  
 \ 
  
-H  
 "developer-token: DEVELOPER_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" 
 }