Melakukan autentikasi sebagai project Apps Script menggunakan akun layanan

Panduan ini menjelaskan cara melakukan autentikasi dengan akun layanan saat memanggil API di Apps Script.

Akun layanan adalah jenis akun khusus yang digunakan oleh aplikasi, bukan oleh pengguna. Anda dapat menggunakan akun layanan untuk mengakses data atau melakukan tindakan oleh akun robot, atau untuk mengakses data atas nama pengguna Google Workspace atau Cloud Identity. Untuk mengetahui informasi selengkapnya, lihat Memahami akun layanan.

Untuk ringkasan tentang autentikasi untuk Google Workspace API, lihat Membuat kredensial akses.

Kapan menggunakan akun layanan di Apps Script

Berikut beberapa alasan mengapa Anda dapat mempertimbangkan untuk menggunakan autentikasi akun layanan, bukan metode autentikasi lain seperti ScriptApp.getOAuthToken():

• Performa yang lebih baik dengan API dan layanan Google Cloud: Banyak Google Cloud API didesain untuk autentikasi akun layanan. Akun layanan juga dapat memberikan cara yang lebih terintegrasi, andal, dan aman untuk berinteraksi dengan sebagian besar API.
• Izin yang tidak terkait: Akun layanan memiliki izinnya sendiri, terpisah dari pengguna mana pun. Metode autentikasi ScriptApp.getOAuthToken() dapat gagal saat Anda membagikan project Apps Script kepada pengguna lain. Dengan menggunakan akun layanan, Anda dapat membagikan skrip dan memublikasikannya sebagai add-on Google Workspace.
• Skrip otomatis dan tugas yang berjalan lama: Akun layanan memungkinkan Anda menjalankan skrip otomatis, proses batch, atau tugas latar belakang tanpa input pengguna.
• Keamanan yang ditingkatkan dan prinsip hak istimewa terendah: Anda dapat memberikan izin tertentu kepada akun layanan, sehingga hanya memberikan akses ke resource yang dibutuhkan. Tindakan ini mengikuti prinsip hak istimewa terendah, yang menurunkan risiko keamanan. Penggunaan ScriptApp.getOAuthToken() sering kali memberikan semua izin pengguna ke skrip, yang bisa terlalu luas.
• Pengelolaan akses terpusat: Akun layanan dikelola menggunakan Identity and Access Management (IAM) Google Cloud. IAM dapat membantu organisasi Google Workspace mengelola akses ke layanan yang diautentikasi dalam project Apps Script.

Prasyarat

• Project Google Cloud.
• Di project Cloud Anda, aktifkan API apa pun yang ingin Anda autentikasi menggunakan kredensial akun layanan.
• Untuk menetapkan peran ke akun layanan, Anda harus memiliki hak istimewa administrator super.

Membuat akun layanan

Di project Cloud Anda, buat akun layanan:

Konsol Google Cloud

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Klik Create service account.
3. Isi detail akun layanan, lalu klik Buat dan lanjutkan.
   Catatan: Secara default, Google membuat ID akun layanan yang unik. Jika Anda ingin mengubah ID, ubah ID di kolom ID akun layanan.
4. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.
5. Klik Lanjutkan.
6. Opsional: Masukkan pengguna atau grup yang dapat mengelola dan melakukan tindakan dengan akun layanan ini. Untuk mengetahui detail selengkapnya, lihat Mengelola peniruan identitas akun layanan.
7. Klik Selesai. Catat alamat email untuk akun layanan.

gcloud CLI

1. Buat akun layanan:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.

Menetapkan peran ke akun layanan

Anda harus menetapkan peran standar atau khusus ke akun layanan oleh akun administrator super.

1. Di konsol Google Admin, buka Menu > Akun > Peran admin.

   Buka Peran admin

2. Arahkan kursor ke peran yang ingin Anda tetapkan, lalu klik Tetapkan admin.

3. Klik Tetapkan akun layanan.

4. Masukkan alamat email akun layanan.

5. Klik Tambahkan > Tetapkan peran.

Membuat kredensial untuk akun layanan

Anda harus mendapatkan kredensial dalam bentuk pasangan kunci publik/pribadi. Kredensial ini digunakan oleh kode Anda untuk mengizinkan tindakan akun layanan dalam aplikasi Anda.

Untuk mendapatkan kredensial akun layanan Anda:

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Pilih akun layanan Anda.
3. Klik Keys > Add key > Create new key.
4. Pilih JSON, lalu klik Buat.

   Pasangan kunci umum/pribadi baru Anda dibuat dan didownload ke komputer Anda sebagai file baru. Simpan file JSON yang didownload sebagai credentials.json di direktori kerja Anda. File ini adalah satu-satunya salinan kunci ini. Untuk mengetahui informasi tentang cara menyimpan kunci Anda dengan aman, lihat Mengelola kunci akun layanan.

5. Klik Tutup.

Menyalin nomor project Cloud

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Settings.

   Buka Setelan IAM & Admin

2. Di kolom Project number, salin nilai.

Menyiapkan autentikasi akun layanan di project Apps Script Anda

Bagian ini menjelaskan cara menambahkan kredensial akun layanan dari project Cloud ke project Apps Script.

Menetapkan project Cloud di Apps Script

1. Buka Apps Script untuk membuka atau membuat project:

   
   Membuka Apps Script

2. Di project Apps Script Anda, klik Project Settings .

3. Pada Google Cloud Platform (GCP) Project, klik Change project.

4. Di GCP project number, tempelkan nomor project Google Cloud.

5. Klik Set project.

Simpan kredensial sebagai properti skrip

Simpan kredensial akun layanan Anda dengan aman dengan menyimpannya sebagai properti skrip di setelan project Apps Script Anda:

1. Salin konten file JSON akun layanan (credentials.json) yang Anda buat di bagian sebelumnya.
2. Di project Apps Script Anda, buka Project Settings .
3. Dari halaman Project Settings, buka Script Properties, lalu klik Add script property dan masukkan informasi berikut:
   • Di kolom Properti, masukkan SERVICE_ACCOUNT_KEY.
   • Di kolom Value, tempelkan konten file kunci JSON Anda.
4. Klik Simpan properti skrip.

Tambahkan library OAuth2

Untuk menangani alur autentikasi OAuth2, Anda dapat menggunakan library Apps Script apps-script-oauth2.

Untuk menambahkan library ke project Apps Script Anda:

1. Di editor Apps Script, di sebelah kiri, di samping Libraries, klik Add a library .
2. Di kolom Script ID, masukkan 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Klik Cari.
4. Pilih versi terbaru, lalu klik Tambahkan.

Memanggil API menggunakan kredensial akun layanan

Untuk menggunakan kredensial akun layanan dari project Apps Script, Anda dapat menggunakan fungsi getServiceAccountService() berikut:

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Ganti SCOPE dengan cakupan otorisasi yang Anda perlukan untuk memanggil API. Skrip menggunakan kredensial akun layanan yang Anda simpan sebagai properti skrip SERVICE_ACCOUNT_KEY di langkah sebelumnya.

Anda kemudian dapat menggunakan kredensial ini untuk memanggil API, seperti yang ditunjukkan dalam contoh berikut dengan layanan UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Ganti API_URL dengan endpoint HTTP yang Anda panggil.

Topik terkait

• Buat kredensial akses
• Melakukan autentikasi sebagai aplikasi Google Chat