Alur kerja autentikasi pengguna tunggal

Catatan: Panduan ini mengasumsikan bahwa Anda sudah memahami model akses Google Ads. Jika belum, sebaiknya baca panduan model akses Google Ads untuk memahami konsepnya. Anda juga harus mengonfigurasi kredensial OAuth menggunakan project Google Cloud yang sama tempat Anda mengaktifkan Google Ads API dan meminta tingkat akses API yang sesuai agar Google Ads API berfungsi dengan benar.

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

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

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

Karena hanya ada satu pengguna yang terlibat, Anda dapat mengandalkan alat seperti gcloud CLI atau contoh kode GenerateUserCredential, alih-alih membangun 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 hingga 4 pengguna), sehingga upaya pengembangan untuk membangun alur kerja autentikasi multi-pengguna OAuth yang lengkap tidak dapat dibenarkan jika dibandingkan dengan upaya untuk mendapatkan otorisasi bagi 3 hingga 4 pengguna menggunakan alat command line seperti gcloud CLI.

Kekurangan

Ada beberapa kelemahan pada alur ini jika dibandingkan dengan alur kerja akun layanan:

• Alur kerja autentikasi pengguna mengharuskan Anda membuat client ID dan rahasia OAuth 2.0 di Konsol API Google, yang memerlukan lebih banyak langkah konfigurasi daripada membuat akun dan kunci layanan.
• Jika pengguna yang diberi otorisasi keluar dari tim atau perusahaan, aplikasi Anda mungkin berhenti berfungsi jika Anda menghapus pengguna dari akun atau menonaktifkan akun pengguna. Akun layanan tidak terkait dengan pengguna individu, sehingga risiko ini dapat dihindari.
• Untuk melindungi dari penyusupan akun akibat malware atau phishing, pengguna yang mengizinkan akun Google Ads harus melakukan autentikasi dengan kunci sandi saat membuat token refresh OAuth 2.0. Akun layanan tidak memerlukan kunci sandi dan tidak terlalu rentan terhadap serangan yang ditargetkan kepada pengguna, seperti phishing.

Membuat kredensial

Catatan: Panduan ini menggunakan Aplikasi desktop sebagai jenis aplikasi OAuth saat membuat kredensial OAuth, karena 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 bangun. Jika Anda memilih Aplikasi web, Anda harus menggunakan OAuth 2.0 Playground untuk membuat token refresh.

1. Konfigurasikan 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 Anda membuat klien OAuth 2.0, download file JSON klien dengan mengklik tombol Download JSON pada dialog konfirmasi. 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, berikan akses akun kepada pengguna tersebut. Pastikan akun pengguna ini telah menyiapkan kunci sandi (waktu tunggu selama 7 hari mungkin berlaku sebelum kunci sandi yang baru dibuat menjadi tepercaya).

4. Download dan instal gcloud CLI. Setelah diinstal, pastikan alat berfungsi dengan benar dengan menjalankan perintah gcloud version dari prompt command line. Outputnya akan terlihat mirip 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
   

5. Buat token refresh OAuth 2.0 dengan menjalankan alat gcloud CLI dengan file credentials.json dari langkah sebelumnya. Meneruskan parameter --client-id-file diperlukan agar token refresh dikeluarkan di bawah project Konsol API Google Anda, bukan project default 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

6. Perintah gcloud akan membuka jendela login Akun Google di jendela browser baru dan memandu Anda melalui langkah-langkah autentikasi OAuth 2.0. Login sebagai pengguna yang Anda pilih di langkah sebelumnya dan verifikasi identitas Anda menggunakan kunci sandi. Jika aplikasi Anda tidak diverifikasi, Anda mungkin melihat layar peringatan. Dalam kasus seperti ini, Anda dapat mengklik link Advanced dan mengklik opsi Go to PROJECT_NAME (unsafe) dengan aman.

7. Setelah Anda 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]
   

   Buka file application_default_credentials.json. Isinya mirip dengan berikut ini:

   {
     "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. Jika pengguna yang diberi otorisasi mengakses akun klien melalui akun pengelola Google Ads, tetapkan login-customer-id (atau loginCustomerId) ke ID pelanggan 10 digit akun pengelola tersebut tanpa tanda hubung.

Java

Konfigurasikan kunci berikut dalam file ads.properties Anda.

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

Lihat panduan konfigurasi untuk opsi tambahan.

.NET

Tetapkan kredensial OAuth 2.0 pada instance GoogleAdsConfig dan gunakan untuk menginisialisasi objek GoogleAdsClient.

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

Lihat panduan konfigurasi untuk opsi tambahan.

Python

Konfigurasikan 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_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

Lihat panduan konfigurasi untuk opsi tambahan.

PHP

Konfigurasikan kunci berikut dalam file 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

Konfigurasikan kunci berikut dalam file google_ads_config.rb Anda.

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

Lihat panduan konfigurasi untuk opsi tambahan.

Perl

Konfigurasikan 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

Mulailah 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://oauth2.googleapis.com/token

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/v26/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"

Isi query.json adalah sebagai berikut:

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