Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server

Sistem Google OAuth 2.0 mendukung interaksi server-ke-server seperti interaksi antara web aplikasi dan layanan Google. Untuk skenario ini, Anda memerlukan akun layanan, yang adalah akun milik aplikasi Anda, bukan milik pengguna akhir individu. Nama aplikasi memanggil Google API atas nama akun layanan, sehingga pengguna tidak yang terlibat. Skenario ini kadang disebut sebagai "{i>two-legged OAuth<i}," atau "2LO". (Istilah terkait "OAuth bercabang tiga" merujuk pada skenario saat aplikasi Anda memanggil Google API atas nama pengguna akhir, dan yang terkadang memerlukan izin pengguna.)

Biasanya, aplikasi menggunakan akun layanan saat aplikasi menggunakan Google API untuk berfungsi dengan datanya sendiri, bukan dengan 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 otorisasi seluruh domain ke akun layanan untuk mengakses pengguna data atas nama pengguna di domain.

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

Ringkasan

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

Kemudian, aplikasi Anda bersiap untuk melakukan panggilan API yang diotorisasi dengan menggunakan atribut kredensial untuk meminta token akses dari server otentikasi OAuth 2.0.

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

Membuat akun layanan

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

Jika aplikasi Anda berjalan di Google App Engine, akun layanan disiapkan secara otomatis saat Anda membuat proyek.

Jika aplikasi Anda berjalan di Google Compute Engine, akun layanan juga disiapkan secara otomatis saat Anda membuat proyek, tetapi Anda harus menentukan cakupan aplikasi perlu diakses saat Anda membuat instance Google Compute Engine. Untuk selengkapnya informasi, lihat Menyiapkan instance untuk menggunakan akun layanan.

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

First, create a service account:

  1. Open the Service accounts page.
  2. If prompted, select a project, or create a new one.
  3. Click  Create service account.
  4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
  5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
  6. Click Continue.
  7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
  8. Click Done.

Next, create a service account key:

  1. Click the email address for the service account you created.
  2. Click the Keys tab.
  3. In the Add key drop-down list, select Create new key.
  4. Click Create.

Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.

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

Catat alamat email akun layanan dan simpan kunci pribadi akun layanan di lokasi yang dapat diakses oleh aplikasi Anda. Aplikasi Anda membutuhkan mereka untuk melakukan panggilan API yang diizinkan.

Mendelegasikan otoritas seluruh domain ke akun layanan

Dengan akun Google Workspace, administrator Workspace organisasi dapat mengizinkan aplikasi Google untuk mengakses data pengguna Workspace atas nama pengguna di domain Google Workspace. Misalnya, aplikasi yang menggunakan API Google Kalender untuk menambahkan acara ke kalender semua pengguna di domain Google Workspace akan menggunakan akun layanan untuk mengakses Google Calendar API di nama pengguna. Memberikan otorisasi pada akun layanan untuk mengakses data atas nama pengguna di domain terkadang disebut sebagai "mendelegasikan otoritas seluruh domain" ke akun layanan.

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

  1. Dari domain Google Workspace Anda Konsol Admin, 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 ID Klien, masukkan ID Klien akun layanan. Anda dapat menemukan client ID akun layanan Anda di Service accounts page.
  5. Di kolom Cakupan OAuth (yang dipisahkan koma), masukkan daftar cakupan yang ingin yang boleh diberikan akses. Misalnya, jika aplikasi Anda membutuhkan seluruh akses penuh ke Google Drive API dan Google Calendar API, masukkan: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
  6. Klik Authorize.

Aplikasi Anda sekarang memiliki wewenang untuk melakukan panggilan API sebagai pengguna di domain Workspace Anda (untuk "tiru identitas" pengguna). Saat mempersiapkan untuk melakukan panggilan API yang didelegasikan ini, Anda akan secara eksplisit menentukan pengguna meniru identitasnya.

Bersiap untuk melakukan panggilan API yang didelegasikan

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 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 sebagai gantinya, yang dapat menyederhanakan prosesnya.

Mendelegasikan otoritas di seluruh domain

Jika Anda telah mendelegasikan akses seluruh domain ke akun layanan dan ingin meniru identitas akun pengguna, tentukan alamat email dari 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("workspace-user@example.com");

Kode di atas menggunakan objek GoogleCredential untuk memanggil createDelegated()-nya . Argumen untuk metode createDelegated() harus berupa pengguna yang termasuk Google Workspace. Kode Anda yang membuat permintaan akan menggunakan kredensial ini untuk memanggil Google Google Cloud API menggunakan akun layanan 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 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 sebagai gantinya, yang dapat menyederhanakan prosesnya.

  2. Mendelegasikan otoritas di seluruh domain

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

    delegated_credentials = credentials.with_subject('user@example.org')

Gunakan objek Credentials untuk memanggil Google API di aplikasi Anda.

HTTP/REST

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

  1. Buat Token Web JSON (JWT, dibaca, "jot") yang mencakup header, kumpulan klaim, dan tanda tangan.
  2. Minta token akses dari Server Otorisasi Google OAuth 2.0.
  3. Menangani respons JSON yang ditampilkan Server Otorisasi.

Bagian berikut ini menjelaskan cara menyelesaikan langkah-langkah ini.

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

Saat token akses berakhir, aplikasi Anda akan membuat token JWT, menandatanganinya, dan meminta token akses lain.

Aplikasi server Anda menggunakan JWT untuk meminta token dari
                  Server Otorisasi, kemudian menggunakan token untuk memanggil endpoint Google API. Lain kali
                  pengguna akhir dilibatkan.

Sisa dari bagian ini menjelaskan secara spesifik cara membuat JWT, menandatangani JWT, membentuk permintaan token akses, dan menangani respons.

Membuat JWT

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

JWT disusun sebagai berikut:

{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

{i>Header<i} terdiri dari tiga isian yang menunjukkan algoritma penandatanganan, format dari pernyataan, dan [ID kunci akun layanan key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) yang digunakan untuk menandatangani JWT. Algoritma dan format bersifat wajib, dan setiap {i>field<i} hanya memiliki satu nilai. Saat algoritma dan format tambahan diperkenalkan, {i>header<i} ini akan berubah sebagaimana mestinya. ID kunci bersifat opsional dan jika ID Kunci yang ditentukan salah, GCP akan mencoba semua kunci yang terkait dengan akun layanan untuk memverifikasi token dan menolak token jika kunci yang valid tidak ditemukan. Google berhak menolak token dengan ID kunci yang salah di masa mendatang.

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

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

Representasi Base64url ini adalah sebagai berikut:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
Pembentukan kumpulan klaim JWT

Kumpulan klaim JWT berisi informasi tentang JWT, termasuk izin yang diminta (cakupan), target token, penerbit, waktu token diterbitkan, dan masa berlaku token. Sebagian besar kolom bersifat wajib. Seperti {i>header<i} JWT, Kumpulan klaim JWT adalah objek JSON dan digunakan dalam penghitungan tanda tangan.

Klaim yang diperlukan

Klaim yang diperlukan dalam kumpulan klaim JWT ditampilkan di bawah ini. Mereka dapat muncul dalam urutan apa pun di klaim ditetapkan.

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

Representasi JSON dari kolom yang wajib diisi dalam kumpulan klaim JWT ditampilkan di bawah ini:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "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 tingkat domain untuk bertindak atas nama pengguna tertentu dalam sebuah organisasi. Izin untuk melakukan jenis peniruan identitas ini harus diberikan sebelum aplikasi bisa meniru identitas pengguna, dan biasanya ditangani oleh administrator super. Untuk informasi selengkapnya, lihat Kontrol akses API dengan delegasi tingkat domain.

Untuk mendapatkan token akses yang memberikan akses delegasi aplikasi ke sumber daya, sertakan alamat email pengguna dalam klaim JWT yang ditetapkan sebagai nilai Kolom sub.

Nama Deskripsi
sub Alamat email pengguna yang menerima delegasi dari aplikasi akses.

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 ditampilkan di bawah ini:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "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 UTF-8 dan Base64url-safe dienkode. Di bawah ini adalah contoh representasi JSON dari kumpulan Klaim JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Menghitung tanda tangan

Tanda Tangan Web JSON (JWS) adalah spesifikasi yang memandu mekanisme menghasilkan tanda tangan untuk JWT. Input untuk tanda tangan adalah array byte konten berikut:

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

Algoritma penandatanganan di {i>header<i} JWT harus digunakan saat menghitung tanda tangan. Tujuan satu-satunya algoritma penandatanganan yang didukung oleh Server Otorisasi Google OAuth 2.0 yang menggunakan Algoritma hashing SHA-256. Hal ini dinyatakan sebagai RS256 dalam alg di header JWT.

Menandatangani representasi input UTF-8 menggunakan SHA256withRSA (juga dikenal sebagai RSASSA-PKCS1-V1_5-SIGN dengan fungsi {i>hash<i} SHA-256) dengan kunci pribadi yang diperoleh dari Google API Console. Output-nya akan berupa array byte.

Tanda tangan tersebut kemudian harus dienkode dengan Base64url. {i>Header<i}, kumpulan klaim, dan tanda tangan adalah yang digabungkan dengan karakter titik (.). Hasilnya adalah JWT. Ini harus sebagai berikut (jeda baris ditambahkan agar lebih jelas):

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

Di bawah ini adalah contoh JWT sebelum encoding Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"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 untuk ditransmisikan:

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 adalah URL dienkode. URL-nya ditampilkan di bawah ini:

https://oauth2.googleapis.com/token

Parameter berikut wajib ada dalam permintaan POST HTTPS:

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

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

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

Berikut 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 JWT dan permintaan token akses diformat dengan benar dan akun layanan telah izin untuk melakukan operasi, lalu respons JSON dari Server Otorisasi memiliki 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 jendela 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 metode 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 dalammenarik-example-123 proyek:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

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

  1. Bangun objek layanan untuk API yang ingin Anda panggil. Anda membangun objek layanan dengan memanggil fungsi build menggunakan nama dan versi API, serta objek Credentials yang diberi otorisasi. 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 dalammenarik-example-123 proyek:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Setelah aplikasi Anda mendapatkan token akses, Anda bisa menggunakan token tersebut untuk melakukan panggilan ke API atas nama akun layanan tertentu atau jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam sebagian besar 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 GET HTTP

Panggilan ke drive.files endpoint (Drive Files API) menggunakan HTTP Authorization: Bearer {i>header<i} akan 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 access_token parameter string kueri:

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 adalah 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

Waktu masa berlaku token akses habis

Masa berlaku token akses yang dikeluarkan oleh Server Otorisasi Google OAuth 2.0 akan habis setelah durasinya yang disediakan oleh nilai expires_in. Ketika token akses kedaluwarsa, maka aplikasi harus menghasilkan JWT lain, menandatanganinya, dan meminta token akses lain.

Kode error JWT

Kolom error Kolom error_description Arti Cara mengatasi
unauthorized_client Unauthorized client or scope in request. Jika Anda mencoba menggunakan delegasi seluruh domain, akun layanan tidak diizinkan di konsol Admin domain pengguna.

Pastikan akun layanan diberi otorisasi di Halaman delegasi seluruh domain konsol Admin untuk pengguna di Klaim sub (kolom).

Meskipun biasanya diperlukan waktu beberapa menit, diperlukan waktu hingga 24 jam untuk otorisasi 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 diberi otorisasi menggunakan alamat email klien, bukan client ID (numerik) di konsol Admin. Di Halaman delegasi seluruh domain di konsol Admin, menghapus klien, dan menambahkannya kembali dengan ID numerik.
access_denied (semua nilai) Jika Anda menggunakan delegasi seluruh Domain, satu atau beberapa cakupan yang diminta tidak diberi otorisasi di konsol Admin.

Pastikan akun layanan diberi otorisasi di Halaman delegasi seluruh domain konsol Admin untuk pengguna di Klaim sub (kolom), dan bahwa kolom tersebut mencakup semua cakupan yang Anda minta dalam klaim scope pada JWT Anda.

Meskipun biasanya diperlukan waktu beberapa menit, diperlukan waktu hingga 24 jam untuk otorisasi diterapkan ke semua pengguna di Akun Google Anda.

admin_policy_enforced (semua nilai) Akun Google tidak dapat memberikan otorisasi ke satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace mereka.

Lihat artikel bantuan Admin Google Workspace Mengontrol layanan pihak ketiga & aplikasi internal mengakses data Google Workspace untuk mendapatkan informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan yang dibatasi sampai akses secara eksplisit diberikan ke client ID OAuth Anda.

invalid_client (semua nilai)

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.

Periksa apakah klien dan akun layanan OAuth telah dikonfigurasi dengan benar dan bahwa Anda menggunakan alamat email yang benar.

Periksa apakah token JWT sudah benar dan diterbitkan untuk client ID di bagian permintaan.

invalid_grant Not a valid email. Pengguna tidak ada. Periksa apakah alamat email di 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, itu berarti bahwa waktu sistem lokal tidak benar. Hal itu 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 dibuat sudah benar. Jika yang diperlukan, sinkronkan waktu Anda dengan NTP Google.

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 masa berlakunya telah berakhir.

Atau, pernyataan JWT mungkin salah dienkode - harus Berenkode Base64, tanpa newline atau padding tanda sama dengan.

Mendekode kumpulan klaim JWT dan memverifikasi 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 kosong), atau salah satu cakupan yang diminta tidak ada (yaitu tidak valid).

Pastikan bahwa klaim scope (kolom) JWT terisi, dan bandingkan cakupan yang ada di dalamnya dengan cakupan terdokumentasi untuk API yang ingin Anda gunakan, untuk memastikan tidak ada kesalahan atau salah ketik.

Perlu diketahui 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 &gt; Akun Layanan, aktifkan akun layanan yang berisi "ID Kunci" 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 Google Akun di Organisasi Google Cloud.

Gunakan akun layanan dari organisasi untuk melakukan autentikasi. Konfirmasi jenis pengguna untuk aplikasi OAuth Anda.

Adendum: Otorisasi akun layanan tanpa OAuth

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

Jika API yang ingin Anda panggil memiliki definisi layanan yang diterbitkan di Repositori GitHub Google API, Anda dapat melakukan panggilan API yang diotorisasi menggunakan JWT sebagai ganti token akses. Untuk melakukannya:

  1. Buat akun layanan seperti yang dijelaskan di atas. Pastikan untuk menyimpan file JSON yang Anda dapatkan ketika membuat akun.
  2. Menggunakan pustaka JWT standar, seperti yang ada di jwt.io, buat JWT dengan header dan payload seperti contoh berikut:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • Untuk kolom kid di header, tentukan kunci pribadi akun layanan Anda ke ID. Anda dapat menemukan nilai ini di kolom private_key_id pada akun layanan Anda file JSON Anda.
    • Untuk kolom iss dan sub, tentukan email akun layanan Anda alamat IPv6 Anda dapat menemukan nilai ini di kolom client_email layanan Anda file JSON akun Anda.
    • Untuk kolom aud, tentukan endpoint API. Contoh: https://SERVICE.googleapis.com/.
    • Untuk kolom iat, tentukan waktu Unix saat ini, dan untuk exp, tentukan waktu tepat 3600 detik kemudian, saat JWT akan berakhir.

Tanda tangani JWT dengan RSA-256 menggunakan kunci pribadi yang ada di 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("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .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': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           '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 menggunakan JWT yang ditandatangani sebagai token pembawa:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com

Menerapkan Perlindungan Lintas Akun

Langkah tambahan yang harus Anda ambil untuk melindungi akun menerapkan Lintas Akun Perlindungan dengan menggunakan Layanan Perlindungan Lintas Akun Google. Layanan ini memungkinkan Anda berlangganan pemberitahuan peristiwa keamanan yang memberikan informasi ke aplikasi Anda tentang perubahan besar pada akun pengguna. Selanjutnya, Anda dapat menggunakan informasi tersebut untuk mengambil tindakan, bergantung pada bagaimana Anda memutuskan untuk menanggapi peristiwa.

Beberapa contoh jenis peristiwa yang dikirim ke aplikasi Anda oleh Cross-Account Protection Service Google adalah:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Lihat Melindungi akun pengguna dengan halaman Perlindungan Lintas Akun untuk mengetahui informasi selengkapnya tentang cara menerapkan Perlindungan Lintas Akun dan daftar lengkap peristiwa yang tersedia.