Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server

. Untuk mengetahui informasi selengkapnya, baca bagian Ringkasan Autentikasi di dokumentasi Google Cloud Platform.

Sistem Google OAuth 2.0 mendukung interaksi server ke server seperti interaksi antara aplikasi web dan layanan Google. Untuk skenario ini, Anda memerlukan akun layanan, yang merupakan akun milik aplikasi Anda, bukan milik pengguna akhir individu. Aplikasi Anda memanggil Google API atas nama akun layanan, sehingga pengguna tidak terlibat secara langsung. Skenario ini terkadang disebut "OAuth berkaki dua", atau "2LO". (Istilah terkait "OAuth berkaki tiga" mengacu pada skenario yang menunjukkan aplikasi Anda memanggil Google API atas nama pengguna akhir, dan terkadang izin pengguna diperlukan.)

Biasanya, aplikasi menggunakan akun layanan ketika aplikasi menggunakan Google API untuk bekerja dengan datanya sendiri dan bukan data pengguna. Misalnya, aplikasi yang menggunakan Google Cloud Datastore untuk persistensi data akan menggunakan akun layanan untuk mengautentikasi panggilannya ke Google Cloud Datastore API.

Administrator domain Google Workspace juga dapat memberikan otorisasi di seluruh akun layanan untuk mengakses data pengguna atas nama pengguna di domain.

Dokumen ini menjelaskan cara aplikasi menyelesaikan alur OAuth 2.0 server ke server dengan menggunakan library klien Google API (direkomendasikan) atau HTTP.

Dengan beberapa Google API, Anda dapat melakukan panggilan API yang diotorisasi menggunakan JWT yang ditandatangani, bukan menggunakan OAuth 2.0, yang dapat menyimpan permintaan jaringan. Lihat Adendum: Otorisasi akun layanan tanpa OAuth.

Ringkasan

Untuk mendukung interaksi server-ke-server, buat akun layanan untuk project Anda di terlebih dahulu. Jika Anda ingin mengakses data pengguna untuk pengguna di akun Google Workspace, delegasikan akses seluruh domain ke akun layanan.

Kemudian, aplikasi Anda bersiap untuk melakukan panggilan API yang diotorisasi menggunakan kredensial akun layanan untuk meminta token akses dari server autentikasi OAuth 2.0.

Terakhir, aplikasi Anda dapat menggunakan token akses untuk memanggil Google API.

Rekomendasi: Aplikasi Anda dapat menyelesaikan tugas ini baik menggunakan library klien Google API untuk bahasa Anda, atau dengan berinteraksi langsung dengan sistem OAuth 2.0 menggunakan HTTP. Namun, mekanisme interaksi autentikasi server ke server mengharuskan aplikasi membuat dan menandatangani Token Web JSON (JWT) secara kriptografis, dan sangat mudah untuk membuat error serius yang dapat berdampak serius pada keamanan aplikasi Anda.

Karena alasan ini, sebaiknya Anda menggunakan library, seperti library klien Google API, yang memisahkan kriptografi dari kode aplikasi Anda.

Membuat akun layanan

Kredensial akun layanan mencakup alamat email yang dibuat, yang unik dan minimal satu pasangan kunci publik/pribadi. Jika delegasi tingkat domain diaktifkan, client ID juga menjadi bagian dari kredensial akun layanan.

Jika aplikasi Anda berjalan pada Google App Engine, akun layanan akan disiapkan secara otomatis saat Anda membuat project.

Jika aplikasi Anda berjalan pada Google Compute Engine, akun layanan juga akan disiapkan secara otomatis saat Anda membuat project, tetapi Anda harus menentukan cakupan yang perlu diakses oleh aplikasi Anda saat membuat instance Google Compute Engine. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan instance untuk menggunakan akun layanan.

Jika aplikasi Anda tidak berjalan di Google App Engine atau Google Compute Engine, Anda harus mendapatkan kredensial ini di . Untuk membuat kredensial akun layanan, atau melihat kredensial publik yang telah Anda buat, lakukan hal berikut:

Pertama, buat akun layanan:

1. Buka Service accounts page.
2. If prompted, select a project, or create a new one.
3. Klik Buat akun layanan .
4. Di bawah Detail akun layanan , ketik nama, ID, dan deskripsi untuk akun layanan, lalu klik Buat dan lanjutkan .
5. Opsional: Di bagian Berikan akses akun layanan ini ke project , pilih peran IAM untuk diberikan ke akun layanan.
6. Klik Lanjutkan .
7. Opsional: Di bawah Beri pengguna akses ke akun layanan ini , tambahkan pengguna atau grup yang diizinkan untuk menggunakan dan mengelola akun layanan.
8. Klik Selesai .

Selanjutnya, buat kunci akun layanan:

1. Klik alamat email untuk akun layanan yang Anda buat.
2. Klik tab Kunci .
3. Di daftar tarik-turun Tambahkan kunci , pilih Buat kunci baru .
4. Klik Buat .

Pasangan kunci publik/pribadi baru Anda dibuat dan diunduh ke mesin Anda; itu berfungsi sebagai satu-satunya salinan dari kunci privat. Anda bertanggung jawab untuk menyimpannya dengan aman. Jika Anda kehilangan pasangan kunci ini, Anda harus membuat yang baru.

Anda dapat kembali ke API Console kapan saja untuk melihat alamat email, sidik jari kunci publik, dan informasi lainnya, atau untuk membuat pasangan kunci publik/pribadi tambahan. Untuk detail selengkapnya tentang kredensial akun layanan di API Console, lihat Akun layanan dalam file bantuan API Console.

Catat alamat email akun layanan dan simpan file kunci pribadi akun layanan tersebut di lokasi yang dapat diakses oleh aplikasi Anda. Aplikasi Anda memerlukannya untuk melakukan panggilan API yang diotorisasi.

Catatan: Anda harus menyimpan dan mengelola kunci pribadi secara aman di lingkungan pengembangan dan produksi. Google tidak menyimpan salinan kunci pribadi Anda, hanya kunci publik Anda saja. Lihat bagian Menangani kredensial klien dengan aman dalam Kebijakan OAuth 2.0 untuk informasi selengkapnya.

Mendelegasikan otoritas seluruh domain ke akun layanan

Jika Anda memiliki akun Google Workspace, administrator organisasi dapat mengizinkan aplikasi untuk mengakses data pengguna atas nama pengguna di domain Google Workspace. Misalnya, aplikasi yang menggunakan Google Calendar API untuk menambahkan acara ke kalender semua pengguna di domain Google Workspace akan menggunakan akun layanan untuk mengakses Google Kalender API atas nama pengguna. Mengizinkan akun layanan untuk mengakses data atas nama pengguna di domain terkadang disebut sebagai "delegasikan otoritas seluruh domain" ke akun layanan.

Catatan: Saat Anda menggunakan Google Workspace Marketplace untuk menginstal aplikasi untuk domain Anda, izin yang diperlukan otomatis diberikan ke aplikasi selama penginstalan. Anda tidak perlu memberi otorisasi secara manual pada akun layanan yang digunakan aplikasi.

Catatan: Meskipun Anda dapat menggunakan akun layanan di aplikasi yang dijalankan dari domain Google Workspace, akun layanan bukan anggota akun Google Workspace Anda dan tidak tunduk pada kebijakan domain yang ditetapkan oleh administrator Google Workspace. Misalnya, kebijakan yang ditetapkan di konsol Admin Google Workspace untuk membatasi kemampuan pengguna akhir Google Workspace agar dapat berbagi dokumen di luar domain tidak akan berlaku untuk akun layanan.

Untuk mendelegasikan otoritas tingkat domain ke akun layanan, administrator super domain Google Workspace harus menyelesaikan langkah-langkah berikut:

1. Dari konsol Admin domain Google Workspace Anda, buka Menu utama > Keamanan > Kontrol data dan akses > Kontrol API.
2. Di panel Delegasi tingkat domain, pilih Kelola Delegasi Tingkat Domain.
3. Klik Tambahkan baru.
4. Di kolom Client-ID, masukkan Client-ID akun layanan. Anda dapat menemukan client ID akun layanan di Service accounts page.
5. Pada kolom OAuth scopes (comma delimited), masukkan daftar cakupan yang dapat diakses oleh aplikasi Anda. Misalnya, jika aplikasi Anda memerlukan akses penuh di seluruh domain ke Google Drive API dan Google Calendar API, masukkan: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Klik Otorisasi.

Aplikasi Anda kini memiliki otorisasi untuk melakukan panggilan API sebagai pengguna di domain Anda (untuk meniru identitas pengguna). Saat bersiap untuk melakukan panggilan API yang diotorisasi, Anda menentukan pengguna yang akan ditiru.

Catatan: Biasanya diperlukan waktu beberapa menit hingga akses peniruan identitas diberikan setelah client ID ditambahkan, tetapi dalam beberapa kasus, mungkin diperlukan waktu hingga 24 jam agar perubahan diterapkan ke semua pengguna Akun Google Anda.

Bersiap untuk melakukan panggilan API yang diotorisasi

Java

Setelah Anda mendapatkan alamat email klien dan kunci pribadi dari API Console, gunakan Library Klien Google API untuk Java untuk membuat objek GoogleCredential dari kredensial akun layanan dan cakupan yang perlu diakses oleh aplikasi Anda. Contoh:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Jika Anda mengembangkan aplikasi di Google Cloud Platform, Anda dapat menggunakan kredensial default aplikasi, yang dapat menyederhanakan prosesnya.

Delegasikan otoritas seluruh domain

Jika Anda telah mendelegasikan akses seluruh domain ke akun layanan dan ingin menirukan akun pengguna, tentukan alamat email akun pengguna dengan metode createDelegated dari objek GoogleCredential. Contoh:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

Gunakan objek GoogleCredential untuk memanggil Google API di aplikasi Anda.

Python

Setelah Anda mendapatkan alamat email klien dan kunci pribadi dari API Console, gunakan Library Klien Google API untuk Python untuk menyelesaikan langkah-langkah berikut:

1. Buat objek Credentials dari kredensial akun layanan dan cakupan yang perlu diakses oleh aplikasi Anda. Contoh:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Jika Anda mengembangkan aplikasi di Google Cloud Platform, Anda dapat menggunakan kredensial default aplikasi, yang dapat menyederhanakan prosesnya.

2. Delegasikan otoritas seluruh domain

   Jika Anda telah mendelegasikan akses seluruh domain ke akun layanan dan ingin meniru akun pengguna, gunakan metode with_subject dari objek ServiceAccountCredentials yang ada. Contoh:

   delegated_credentials = credentials.with_subject('[e-mail]')

Gunakan objek Credentials untuk memanggil Google API di aplikasi Anda.

HTTP/REST

Rekomendasi: Meskipun aplikasi Anda dapat menyelesaikan tugas ini dengan berinteraksi langsung dengan sistem OAuth 2.0 menggunakan HTTP, mekanisme interaksi autentikasi server-ke-server mengharuskan aplikasi untuk membuat dan menandatangani Token Web JSON (JWT) secara mudah, dan mudah untuk membuat error serius yang dapat berdampak serius pada keamanan aplikasi Anda.

Karena alasan ini, sebaiknya Anda menggunakan library, seperti library klien Google API, yang memisahkan kriptografi dari kode aplikasi Anda.

Setelah Anda mendapatkan client ID dan kunci pribadi dari API Console, aplikasi Anda harus menyelesaikan langkah-langkah berikut:

1. Membuat Token Web JSON (JWT, diucapkan, "jot") yang menyertakan header, kumpulan klaim, dan tanda tangan.
2. Minta token akses dari Server Otorisasi Google OAuth 2.0.
3. Tangani respons JSON yang ditampilkan Server Otorisasi.

Bagian berikut menjelaskan cara menyelesaikan langkah-langkah ini.

Jika responsnya menyertakan token akses, Anda dapat menggunakan token akses tersebut untuk memanggil Google API. (Jika respons tidak menyertakan token akses, JWT dan permintaan token Anda mungkin tidak diformat dengan benar, atau akun layanan mungkin tidak memiliki izin untuk mengakses cakupan yang diminta.)

Saat masa berlaku token akses berakhir, aplikasi Anda membuat JWT lain, menandatanganinya, dan meminta token akses lainnya.

Bagian selanjutnya menjelaskan cara membuat JWT, menandatangani JWT, membentuk permintaan token akses, dan menangani respons.

Membuat JWT

JWT terdiri dari tiga bagian: header, kumpulan klaim, dan tanda tangan. Header dan kumpulan klaim adalah objek JSON. Objek JSON ini diserialisasi ke byte UTF-8, lalu dienkode menggunakan encoding Base64url. Encoding ini memberikan ketahanan terhadap perubahan encoding karena operasi encoding yang berulang. Header, kumpulan klaim, dan tanda tangan digabungkan dengan karakter titik (.).

JWT terdiri dari berikut ini:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

String dasar untuk tanda tangan adalah sebagai berikut:

{Base64url encoded header}.{Base64url encoded claim set}

Membentuk header JWT

Header terdiri dari dua kolom yang menunjukkan algoritme penandatanganan dan format pernyataan. Kedua kolom wajib diisi, dan setiap kolom hanya memiliki satu nilai. Saat algoritme dan format tambahan diperkenalkan, header ini juga akan berubah.

Akun layanan mengandalkan algoritme RSA SHA-256 dan format token JWT. Akibatnya, representasi JSON dari header adalah sebagai berikut:

{"alg":"RS256","typ":"JWT"}

Representasi Base64url adalah sebagai berikut:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Membentuk kumpulan klaim JWT

Kumpulan klaim JWT berisi informasi tentang JWT, termasuk izin yang diminta (cakupan), target token, penerbit, waktu token dikeluarkan, dan masa aktif token. Sebagian besar kolom bersifat wajib. Seperti header JWT, kumpulan klaim JWT adalah objek JSON dan digunakan dalam penghitungan tanda tangan.

Klaim yang diperlukan

Klaim yang diperlukan dalam kumpulan klaim JWT ditunjukkan di bawah ini. Klaim tersebut dapat muncul dalam urutan apa pun di kumpulan klaim.

Nama	Deskripsi
iss	Alamat email akun layanan.
scope	Daftar izin yang dipisahkan spasi yang diminta aplikasi.
aud	Deskripsi target yang dimaksud dari pernyataan. Saat membuat permintaan token akses, nilai ini selalu https://oauth2.googleapis.com/token.
exp	Waktu habis masa berlaku pernyataan, ditetapkan sebagai detik sejak 00.00.00 UTC, 1 Januari 1970. Nilai ini memiliki batas waktu maksimum 1 jam setelah waktu yang ditentukan.
iat	Waktu dikeluarkannya pernyataan, yang ditentukan sebagai detik sejak 00.00.00 UTC, 1 Januari 1970.

Representasi JSON dari kolom wajib diisi dalam rangkaian klaim JWT ditunjukkan di bawah ini:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Klaim tambahan

Dalam beberapa kasus perusahaan, aplikasi dapat menggunakan delegasi di seluruh domain untuk bertindak atas nama pengguna tertentu dalam organisasi. Izin untuk melakukan jenis peniruan identitas ini harus diberikan sebelum aplikasi dapat meniru identitas pengguna, dan biasanya ditangani oleh administrator super. Untuk mengetahui informasi selengkapnya, lihat Mengontrol akses API dengan delegasi tingkat domain.

Untuk mendapatkan token akses yang memberi aplikasi akses yang didelegasikan ke resource, sertakan alamat email pengguna dalam klaim JWT yang ditetapkan sebagai nilai kolom sub.

Nama	Deskripsi
sub	Alamat email pengguna tempat aplikasi meminta akses yang didelegasikan.

Jika aplikasi tidak memiliki izin untuk meniru identitas pengguna, respons terhadap permintaan token akses yang menyertakan kolom sub akan menjadi error.

Contoh kumpulan klaim JWT yang menyertakan kolom sub ditunjukkan di bawah ini:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Mengenkode kumpulan klaim JWT

Seperti header JWT, kumpulan klaim JWT harus diserialisasi ke berenkode UTF-8 dan Base64url-safe. Berikut adalah contoh representasi JSON dari kumpulan Klaim JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Menghitung tanda tangan

JSON Web Signature (JWS) adalah spesifikasi yang memandu mekanisme dalam membuat tanda tangan untuk JWT. Input untuk tanda tangan adalah array byte dari konten berikut:

{Base64url encoded header}.{Base64url encoded claim set}

Algoritme penandatanganan di header JWT harus digunakan saat menghitung tanda tangan. Satu-satunya algoritme penandatanganan yang didukung oleh Google 2.0 Authorization Server adalah RSA yang menggunakan algoritme hashing SHA-256. Hal ini dinyatakan sebagai RS256 dalam kolom alg di header JWT.

Tanda tangani representasi UTF-8 dari input menggunakan SHA256withRSA (juga dikenal sebagai RSASSA-PKCS1-V1_5-SIGN dengan fungsi hash SHA-256) dengan kunci pribadi yang diperoleh dari Google API Console. Outputnya akan berupa array byte.

Tanda tangan kemudian harus dienkode dengan Base64url. Header, kumpulan klaim, dan tanda tangan digabungkan dengan karakter titik (.). Hasilnya adalah JWT. Berikut ini harus berupa (baris baru ditambahkan agar lebih jelas):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Berikut adalah contoh JWT sebelum encoding Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Berikut adalah contoh JWT yang telah ditandatangani dan siap dikirim:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Membuat permintaan token akses

Setelah membuat JWT yang ditandatangani, aplikasi dapat menggunakannya untuk meminta token akses. Permintaan token akses ini adalah permintaan POST HTTPS, dan isinya dienkode URL. URL-nya ditampilkan di bawah ini:

https://oauth2.googleapis.com/token

Parameter berikut diperlukan dalam permintaan POST HTTPS:

Nama	Deskripsi
grant_type	Gunakan string berikut, yang dienkode URL jika diperlukan: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	JWT, termasuk tanda tangan.

Di bawah ini adalah dump mentah dari permintaan POST HTTPS yang digunakan dalam permintaan token akses:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Di bawah ini adalah permintaan yang sama, menggunakan curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Menangani respons

Jika permintaan token akses dan JWT dibentuk dengan benar dan akun layanan memiliki izin untuk melakukan operasi, respons JSON dari Server Otorisasi akan menyertakan token akses. Berikut adalah contoh respons:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Token akses dapat digunakan kembali selama periode durasi yang ditentukan oleh nilai expires_in.

Memanggil Google API

Java

Gunakan objek GoogleCredential untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:

1. Buat objek layanan untuk API yang ingin Anda panggil menggunakan objek GoogleCredential. Contoh:

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();

2. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk membuat daftar instance database Cloud SQL dalam project contoh-123 yang menarik:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Gunakan objek Credentials yang diotorisasi untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:

1. Buat objek layanan untuk API yang ingin Anda panggil. Buat objek layanan dengan memanggil fungsi build dengan nama dan versi API serta objek Credentials yang diotorisasi. Misalnya, untuk memanggil versi 1beta3 Cloud SQL Administration API:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk membuat daftar instance database Cloud SQL dalam project contoh-123 yang menarik:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Setelah aplikasi Anda mendapatkan token akses, Anda dapat menggunakan token tersebut untuk melakukan panggilan ke Google API atas nama akun layanan atau akun pengguna tertentu jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan parameter kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih direkomendasikan, karena string kueri cenderung terlihat di log server. Dalam sebagian besar kasus, Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil Drive Files API).

Anda dapat mencoba semua Google API dan melihat cakupannya di OAuth 2.0 Playground.

Contoh HTTP GET

Panggilan ke endpoint drive.files (Drive Files API) yang menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Berikut adalah panggilan ke API yang sama untuk pengguna terautentikasi menggunakan parameter string kueri access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Contoh curl

Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut ini contoh yang menggunakan opsi header HTTP (lebih disukai):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Atau, sebagai alternatif, opsi parameter string kueri:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Saat masa berlaku token akses berakhir

Masa berlaku token akses yang dikeluarkan oleh Server Otorisasi Google OAuth 2.0 berakhir setelah durasi yang diberikan oleh nilai expires_in. Setelah masa berlaku token akses berakhir, aplikasi harus membuat JWT lain, menandatanganinya, dan meminta token akses lainnya.

Kode error JWT

Kolom error	Kolom error_description	Arti	Cara mengatasi
unauthorized_client	Unauthorized client or scope in request.	Jika Anda mencoba menggunakan delegasi tingkat domain, akun layanan tidak diizinkan di konsol Admin domain pengguna.	Pastikan akun layanan telah diotorisasi di halaman Delegasi tingkat domain pada konsol Admin untuk pengguna dalam klaim (kolom) sub. Meskipun biasanya diperlukan waktu beberapa menit, otorisasi mungkin memerlukan waktu hingga 24 jam untuk diterapkan ke semua pengguna di Akun Google Anda.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Akun layanan diotorisasi menggunakan alamat email klien, bukan client ID (numerik) di konsol Admin.	Di halaman Delegasi tingkat domain di konsol Admin, hapus klien, lalu tambahkan kembali dengan ID numerik.
access_denied	(nilai apa pun)	Jika Anda menggunakan delegasi tingkat Domain, satu atau beberapa cakupan yang diminta tidak diotorisasi di konsol Admin.	Pastikan bahwa akun layanan telah diberi otorisasi di halaman Delegasi seluruh domain di konsol Admin untuk pengguna dalam klaim (kolom) sub, dan akun tersebut menyertakan semua cakupan yang Anda minta dalam klaim scope dari JWT. Meskipun biasanya diperlukan waktu beberapa menit, otorisasi mungkin memerlukan waktu hingga 24 jam untuk diterapkan ke semua pengguna di Akun Google Anda.
admin_policy_enforced	(nilai apa pun)	Akun Google tidak dapat mengizinkan satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace miliknya.	Lihat artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal yang mengakses data Google Workspace untuk mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan yang dibatasi hingga akses diberikan secara eksplisit ke client ID OAuth Anda.
invalid_client	(nilai apa pun)	Klien OAuth atau token JWT tidak valid atau tidak dikonfigurasi dengan benar. Lihat deskripsi error untuk mengetahui detailnya.	Pastikan token JWT valid dan berisi klaim yang benar. Pastikan klien dan akun layanan OAuth dikonfigurasi dengan benar dan Anda menggunakan alamat email yang benar. Pastikan token JWT sudah benar dan diterbitkan untuk client ID dalam permintaan.
invalid_grant	Not a valid email.	Pengguna tidak ada.	Pastikan alamat email dalam klaim sub (kolom) sudah benar.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Biasanya, ini berarti waktu sistem lokal salah. Hal ini juga bisa terjadi jika nilai exp lebih dari 65 menit di masa mendatang dari nilai iat, atau nilai exp lebih rendah dari nilai iat.	Pastikan jam pada sistem tempat JWT dihasilkan sudah benar. Jika perlu, sinkronkan waktu Anda dengan Google NTP.
invalid_grant	Invalid JWT Signature.	Pernyataan JWT ditandatangani dengan kunci pribadi yang tidak terkait dengan akun layanan yang diidentifikasi oleh email klien, atau kunci yang digunakan telah dihapus, dinonaktifkan, atau habis masa berlakunya. Atau, pernyataan JWT mungkin dienkode dengan tidak benar - pernyataan tersebut harus dienkode dengan Base64, tanpa tanda baris baru atau padding yang sama.	Dekode kumpulan klaim JWT dan verifikasi bahwa kunci yang menandatangani pernyataan terkait dengan akun layanan. Coba gunakan library OAuth yang disediakan Google untuk memastikan JWT dibuat dengan benar.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Tidak ada cakupan yang diminta (daftar cakupan yang kosong), atau salah satu cakupan yang diminta tidak ada (yaitu tidak valid).	Pastikan klaim scope (kolom) JWT diisi, dan bandingkan cakupan yang ada dengan cakupan yang didokumentasikan untuk API yang ingin digunakan, untuk memastikan tidak ada error atau kesalahan ketik. Perhatikan bahwa daftar cakupan dalam klaim scope harus dipisahkan dengan spasi, bukan koma.
disabled_client	The OAuth client was disabled.	Kunci yang digunakan untuk menandatangani pernyataan JWT dinonaktifkan.	Buka Google API Console, dan di bagian IAM & Admin > Service Accounts, aktifkan akun layanan yang berisi "Key ID" yang digunakan untuk menandatangani pernyataan.
org_internal	This client is restricted to users within its organization.	Client ID OAuth dalam permintaan adalah bagian dari project yang membatasi akses ke Akun Google di Organisasi Google Cloud tertentu.	Gunakan akun layanan dari organisasi untuk mengautentikasi. Konfirmasi konfigurasi jenis pengguna untuk aplikasi OAuth Anda.

Adendum: Otorisasi akun layanan tanpa OAuth

Dengan beberapa Google API, Anda dapat melakukan panggilan API yang diotorisasi menggunakan JWT yang ditandatangani secara langsung sebagai token pemilik, bukan token akses OAuth 2.0. Jika memungkinkan, Anda dapat menghindari permintaan jaringan ke server otorisasi Google sebelum melakukan panggilan API.

Jika API yang ingin Anda panggil memiliki definisi layanan yang dipublikasikan di repositori GitHub Google API, Anda dapat melakukan panggilan API yang diotorisasi menggunakan JWT, bukan token akses. Untuk melakukannya:

1. Buat akun layanan seperti yang dijelaskan di atas. Pastikan untuk menyimpan file JSON yang Anda dapatkan saat membuat akun.
2. Menggunakan library JWT standar, seperti yang ditemukan di jwt.io, buat JWT dengan header dan payload seperti contoh berikut:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• Untuk kolom kid di header, tentukan ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom private_key_id pada file JSON akun layanan Anda.
• Untuk kolom iss dan sub, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di kolom client_email pada file JSON akun layanan Anda.
• Untuk kolom aud, tentukan endpoint API. Misalnya: https://SERVICE.googleapis.com/.
• Untuk kolom iat, tentukan waktu Unix saat ini, dan untuk kolom exp, tentukan waktu persis 3600 detik setelahnya, saat JWT akan berakhir.

Tanda tangani JWT dengan RSA-256 menggunakan kunci pribadi yang ditemukan dalam file JSON akun layanan Anda.

Contoh:

Java

Menggunakan google-api-java-client dan java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Menggunakan PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. Panggil API ini menggunakan JWT yang ditandatangani sebagai token pemilik:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com