Alur Kerja Autentikasi Pengguna Tunggal

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

Perhatian: Google merekomendasikan penggunaan alur kerja akun layanan, bukan 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 memberikan akses pengguna tunggal ke semua akun Google Ads yang harus dikelola oleh aplikasi.
• Pengguna mengotorisasi aplikasi Anda untuk 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 membuat 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 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 konfigurasi lebih banyak daripada membuat akun layanan dan kunci.
2. Aplikasi Anda mungkin harus menjalani proses verifikasi Aplikasi Google Cloud tambahan.
3. Jika pengguna yang diberi otorisasi keluar dari tim atau perusahaan, aplikasi Anda mungkin berhenti berfungsi jika Anda menghapus pengguna dari akun Anda atau menonaktifkan akun pengguna. Akun layanan tidak terikat ke pengguna perorangan, sehingga risiko ini dapat dihindari.
4. Pengguna yang mengotorisasi akun Google Ads harus mengambil tindakan pencegahan tambahan seperti mengaktifkan autentikasi 2 faktor untuk melindungi Akun Google mereka agar tidak disusupi karena keamanan yang buruk, malware, atau phishing. Akun layanan lebih rentan terhadap masalah ini karena beberapa mode serangan ini tidak berlaku langsung untuk akun layanan.

Membuat kredensial

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

1. Ikuti petunjuk untuk mengonfigurasi layar izin OAuth untuk aplikasi Anda dan tambahkan https://www.googleapis.com/auth/adwords sebagai cakupan OAuth 2.0. Lihat Menyiapkan layar izin OAuth untuk mengetahui detailnya.

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 tidak memiliki akses, maka ikuti petunjuk untuk memberikan akses yang diperlukan.

4. Download dan instal gcloud CLI. Setelah diinstal, pastikan alat berfungsi dengan benar dengan menjalankan perintah gcloud version dari perintah command line. Outputnya 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-langkah sebelumnya. Jika aplikasi Anda belum diverifikasi, Anda mungkin akan melihat layar peringatan. Dalam kasus tersebut, Anda dapat mengklik link Tampilkan Lanjutan dan mengklik opsi Buka PROJECT_NAME (belum diverifikasi).

   

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

   Authorization code granted. Close this tab.

   Perintah gcloud akan mencetak pesan berikut:

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

   Sekarang buka file application_default_credentials.json. Isinya akan 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 mengetahui petunjuk cara mengonfigurasi library klien.

Java

Konfigurasi kunci berikut dalam 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 melakukan inisialisasi instance GoogleAdsClient saat runtime, menggunakan kredensial yang Anda peroleh dari pengguna yang akunnya Anda gunakan untuk melakukan panggilan API.

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 dalam 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 dalam 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 dalam file Anda. google_ads_config.rb

  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 dalam 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 Anda. 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/v24/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"
}