Alur Kerja Autentikasi Pengguna Tunggal

Catatan: Panduan ini mengasumsikan bahwa Anda telah memahami model akses Google Ads. Jika Anda belum melakukannya, sebaiknya baca panduan model akses Google Ads untuk memahami konsepnya.

Perhatian: Google merekomendasikan penggunaan alur kerja akun layanan daripada alur kerja autentikasi pengguna tunggal. Alur kerja autentikasi pengguna tunggal hanya boleh digunakan jika akun layanan tidak dapat digunakan.

Mirip dengan alur kerja akun layanan, alur autentikasi pengguna tunggal menggunakan fitur otorisasi dan pengelolaan pengguna yang ditawarkan oleh UI Google Ads untuk memberikan akses aplikasi ke semua akun yang diperlukan. Alur kerja autentikasi ini memiliki dua langkah:

• Anda memberi satu pengguna akses ke semua akun Google Ads yang harus dikelola oleh aplikasi.
• Pengguna mengizinkan aplikasi Anda mengelola akun Google Ads mereka atas nama mereka, sehingga memberikan akses aplikasi ke semua akun Google Ads.

Karena hanya ada satu pengguna yang terlibat, Anda dapat mengandalkan alat seperti gcloud CLI atau contoh kode GenerateUserCredential, bukan membuat alur autentikasi pengguna OAuth 2.0 Anda sendiri.

Kasus penggunaan terkait untuk alur kerja ini adalah saat akun Anda dapat diakses melalui beberapa login pengguna (misalnya, 3-4 pengguna), sehingga upaya pengembangan untuk membangun alur kerja autentikasi pengguna OAuth lengkap tidak dapat dibenarkan jika dibandingkan dengan upaya untuk mendapatkan otorisasi bagi 3-4 pengguna menggunakan alat command line seperti gcloud CLI.

Kekurangan

Ada beberapa kekurangan dalam alur ini jika dibandingkan dengan alur kerja akun layanan:

1. Alur kerja autentikasi pengguna mengharuskan Anda membuat client ID dan rahasia OAuth 2.0 di Konsol Google Cloud, yang memerlukan langkah-langkah konfigurasi lebih banyak daripada membuat akun layanan dan kunci.
2. Aplikasi Anda mungkin harus melalui proses verifikasi Aplikasi Google Cloud tambahan.
3. Jika pengguna yang diberi otorisasi keluar dari tim atau perusahaan, aplikasi Anda dapat berhenti berfungsi jika Anda menghapus pengguna dari akun Anda atau menonaktifkan akun pengguna. Akun layanan tidak terikat dengan pengguna individual, sehingga risiko ini dapat dihindari.
4. Pengguna yang mengizinkan akun Google Ads harus mengambil tindakan pencegahan tambahan seperti mengaktifkan autentikasi 2 faktor untuk melindungi Akun Google mereka dari pembajakan akibat keamanan yang buruk, malware, atau phishing. Akun layanan kurang rentan terhadap masalah ini karena beberapa mode serangan ini tidak berlaku secara langsung untuk akun layanan.

Membuat kredensial

Catatan: Panduan ini menggunakan Aplikasi Desktop sebagai jenis aplikasi OAuth saat membuat kredensial OAuth, karena jenis ini paling cocok dengan gcloud CLI. Saat menggunakan alur kerja autentikasi pengguna tunggal, jenis aplikasi OAuth ini dapat digunakan terlepas dari jenis aplikasi yang Anda bangun. Jika memilih Aplikasi Web, Anda harus menggunakan OAuth playground untuk membuat token refresh. Lihat video untuk mendapatkan petunjuk.

1. Ikuti petunjuk untuk mengonfigurasi layar izin OAuth bagi aplikasi Anda dan menambahkan https://www.googleapis.com/auth/adwords sebagai cakupan OAuth 2.0.

2. Buat client ID dan rahasia klien dengan mengikuti petunjuk. Setelah membuat klien OAuth 2.0, download file JSON klien dengan mengklik ikon Download klien OAuth terlebih dahulu, lalu tombol DOWNLOAD JSON di layar berikutnya. Simpan file sebagai credentials.json.

3. Identifikasi akun pengguna yang memiliki akses ke semua akun Google Ads yang ingin Anda kelola menggunakan aplikasi Anda. Jika ada akun yang aksesnya tidak ada, maka ikuti petunjuk untuk memberikan akses yang diperlukan.

4. Download dan instal gcloud CLI. Setelah diinstal, verifikasi bahwa alat berfungsi dengan benar dengan menjalankan perintah gcloud version dari prompt command line. Output-nya mungkin terlihat seperti berikut.

   :~$ 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. Buat token refresh OAuth 2.0 dengan menjalankan alat gcloud CLI:

   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>

   File credentials.json berasal dari langkah sebelumnya.

6. Perintah gcloud akan membuka jendela login Akun Google di jendela browser baru dan memandu Anda melalui langkah-langkah autentikasi OAuth 2.0. Pastikan Anda login sebagai pengguna yang Anda pilih dari langkah sebelumnya. Jika aplikasi Anda tidak terverifikasi, Anda mungkin melihat layar peringatan. Dalam kasus seperti itu, Anda dapat mengklik link Tampilkan Lanjutan dan mengklik opsi Buka PROJECT_NAME (belum diverifikasi) dengan aman.

   

7. Setelah Anda memverifikasi cakupan, klik tombol Lanjutkan untuk memberikan izin. Browser membuka https://cloud.google.com/sdk/auth_success, yang menunjukkan bahwa autentikasi berhasil. Halaman menampilkan pesan berikut:

   Authorization code granted. Close this tab.

   Perintah gcloud menampilkan pesan berikut:

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

   Sekarang, buka file application_default_credentials.json. Kontennya harus mirip dengan berikut:

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

Konfigurasi library klien

Pilih tab yang sesuai dengan bahasa pemrograman Anda untuk mendapatkan petunjuk tentang cara mengonfigurasi library klien.

Java

Konfigurasi kunci berikut di file ads.properties Anda.

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

Lihat panduan konfigurasi untuk opsi tambahan.

.NET

Anda dapat menginisialisasi instance GoogleAdsClient saat runtime, menggunakan kredensial yang telah Anda peroleh dari pengguna yang akunnya Anda panggil API-nya.

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);

Lihat panduan konfigurasi untuk opsi tambahan.

Python

Konfigurasi kunci berikut di file google-ads.yaml Anda.

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

Lihat panduan konfigurasi untuk opsi tambahan.

PHP

Konfigurasi kunci berikut di google_ads_php.ini Anda.

[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"

Lihat panduan konfigurasi untuk opsi tambahan.

Ruby

Konfigurasi kunci berikut di file google_ads_config.rb Anda.

  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

Lihat panduan konfigurasi untuk opsi tambahan.

Perl

Konfigurasi kunci berikut di file googleads.properties Anda.

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

Lihat panduan konfigurasi untuk opsi tambahan.

curl

Mulai dengan menggunakan klien HTTP untuk mengambil token akses OAuth 2.0. Panduan ini menggunakan perintah curl.

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

Sekarang Anda dapat menggunakan token akses dalam panggilan API. Contoh berikut menunjukkan cara menjalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda. Panduan ini tidak membahas detail pelaporan.

curl -i -X POST https://googleads.googleapis.com/v21/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"

Isi query.json adalah sebagai berikut:

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