Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server

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

Biasanya, aplikasi menggunakan akun layanan saat aplikasi menggunakan Google API untuk bekerja 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 memberikan akun layanan otoritas seluruh domain untuk mengakses data pengguna atas nama pengguna di domain.

Dokumen ini menjelaskan bagaimana aplikasi dapat menyelesaikan aliran OAuth 2.0 antar-server dengan menggunakan pustaka klien Google API (disarankan) atau HTTP.

Gambaran

Untuk mendukung interaksi server-ke-server, pertama-tama buat akun layanan untuk proyek Anda di API Console. 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 resmi dengan 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.

Membuat akun layanan

Kredensial akun layanan menyertakan alamat email yang dihasilkan yang unik dan setidaknya satu pasangan kunci publik / pribadi. Jika delegasi seluruh domain diaktifkan, ID klien juga merupakan bagian dari 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 yang perlu diakses aplikasi Anda saat membuat instance Google Compute Engine. Untuk informasi selengkapnya, lihat Mempersiapkan instance untuk menggunakan akun layanan .

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

  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 .
  5. Opsional: Di bawah Izin akun layanan , pilih peran IAM untuk diberikan ke akun layanan, lalu klik Lanjutkan .
  6. Opsional: Di bawah Berikan pengguna akses ke akun layanan ini , tambahkan pengguna atau grup yang diizinkan untuk menggunakan dan mengelola akun layanan.
  7. Klik tombol Buat , lalu klik Buat .

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

Jika Anda perlu memberikan otoritas seluruh domain G Suite ke akun layanan, klik alamat email akun layanan yang Anda buat, lalu salin nilainya dari kotak ID Unik .

Untuk mendelegasikan wewenang ke akun layanan, gunakan nilai yang Anda salin sebagai ID klien.

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 di file bantuan API Console.

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

Mendelegasikan otoritas seluruh domain ke akun layanan

Jika Anda memiliki akun Google Workspace, administrator organisasi dapat memberi otorisasi pada aplikasi untuk mengakses data pengguna 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 API Google Kalender atas nama pengguna. Memberi otorisasi 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, pertama-tama aktifkan delegasi seluruh domain untuk akun layanan yang ada di Service accounts page atau buat akun layanan baru dengan delegasi seluruh domain diaktifkan.

Kemudian, pengguna super domain Google Workspace harus menyelesaikan langkah-langkah berikut:

  1. Dari Google Workspace domain Anda konsol Admin , masuk ke menu utama > Keamanan> Kontrol API.
  2. Di panel Delegasi seluruh domain , pilih Kelola Delegasi Seluruh Domain .
  3. Klik Tambahkan baru .
  4. Di bidang ID Klien , masukkan ID Klien akun layanan. Anda dapat menemukan ID klien akun layanan Anda di Service accounts page.
  5. Di kolom Cakupan OAuth (dipisahkan koma) , masukkan daftar cakupan yang aksesnya harus diberikan kepada aplikasi Anda. Misalnya, jika aplikasi Anda memerlukan akses penuh di seluruh domain ke API Google Drive dan API Google Kalender, masukkan: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth / kalender .
  6. Klik Otorisasi .

Aplikasi Anda sekarang memiliki otoritas untuk melakukan panggilan API sebagai pengguna di domain Anda (untuk "meniru" pengguna). Saat Anda bersiap untuk melakukan panggilan API resmi, Anda menentukan pengguna yang akan ditiru.

Bersiap untuk melakukan panggilan API resmi

Jawa

Setelah Anda mendapatkan alamat email klien dan kunci pribadi dari API Console, gunakan Library Klien Google API untuk Java guna membuat objek GoogleCredential dari kredensial akun layanan dan cakupan yang perlu diakses aplikasi Anda. Sebagai 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.

Mendelegasikan otoritas di seluruh domain

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

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

Gunakan objek GoogleCredential untuk memanggil Google API di aplikasi Anda.

Python

Setelah Anda mendapatkan alamat email klien dan kunci pribadi dari API Console, gunakan Perpustakaan 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. Misalnya:
    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 Anda ingin meniru akun pengguna, gunakan metode with_subject dari objek ServiceAccountCredentials ada. Sebagai contoh:

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

Gunakan objek Credentials untuk memanggil Google API di aplikasi Anda.

HTTP / REST

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

  1. Buat Token Web JSON (JWT, diucapkan, "jot") yang mencakup tajuk, kumpulan klaim, dan tanda tangan.
  2. Minta token akses dari Server Otorisasi Google OAuth 2.0.
  3. Tangani respons JSON yang dikembalikan oleh Server Otorisasi.

Bagian berikutnya menjelaskan cara menyelesaikan langkah-langkah ini.

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

Saat token akses kedaluwarsa , aplikasi Anda menghasilkan JWT lain, menandatanganinya, dan meminta token akses lain.

Aplikasi server Anda menggunakan JWT untuk meminta token dari Server Otorisasi Google, kemudian menggunakan token tersebut untuk memanggil titik akhir API Google. Tidak ada pengguna akhir yang terlibat.

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

Membuat JWT

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

JWT terdiri 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

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

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

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

Representasi Base64url ini 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 diterbitkan, dan masa pakai token. Sebagian besar bidang wajib diisi. Seperti header JWT, set klaim JWT adalah objek JSON dan digunakan dalam penghitungan tanda tangan.

Klaim yang dibutuhkan

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

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

Representasi JSON dari bidang wajib dalam kumpulan klaim JWT ditunjukkan 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 seluruh domain untuk bertindak atas nama pengguna tertentu dalam organisasi. Izin untuk melakukan jenis peniruan ini harus diberikan sebelum aplikasi dapat meniru pengguna, dan biasanya ditangani oleh administrator super. Untuk informasi selengkapnya, lihat Mengontrol akses API dengan delegasi seluruh domain .

Untuk mendapatkan token akses yang memberi aplikasi akses yang didelegasikan ke sumber daya, sertakan alamat email pengguna di klaim JWT yang ditetapkan sebagai nilai sub bidang.

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

Jika aplikasi tidak memiliki izin untuk menyamar sebagai pengguna, respons terhadap permintaan token akses yang menyertakan sub bidang tersebut akan menjadi kesalahan .

Contoh kumpulan klaim JWT yang mencakup sub bidang ditunjukkan 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 diserialkan ke UTF-8 dan encoded Base64url-safe. 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

JSON Web Signature (JWS) adalah spesifikasi yang memandu mekanisme pembuatan tanda tangan untuk JWT. Input untuk tanda tangan adalah larik 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 Server Otorisasi Google OAuth 2.0 adalah RSA yang menggunakan algoritme pencirian SHA-256. Ini diekspresikan sebagai RS256 di bidang 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 menjadi array byte.

Tanda tangan kemudian harus dienkode Base64url. Header, set klaim, dan tanda tangan digabungkan bersama dengan karakter titik ( . ). Hasilnya adalah JWT. Ini harus sebagai berikut (jeda baris ditambahkan untuk kejelasan):

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

Di bawah ini adalah contoh JWT sebelum pengkodean 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]

Di bawah ini adalah contoh JWT yang telah ditandatangani dan siap untuk transmisi:

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 HTTPS POST , dan isi kode URL. URL ditampilkan di bawah ini:

https://oauth2.googleapis.com/token

Parameter berikut diperlukan dalam permintaan HTTPS POST :

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

Di bawah ini adalah dump mentah dari permintaan HTTPS POST 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 JWT dan permintaan token akses dibuat dengan benar dan akun layanan memiliki izin untuk melakukan operasi, maka respons JSON dari Server Otorisasi menyertakan token akses. Berikut contoh responnya:

{
  "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

Jawa

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 . Misalnya:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Membuat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan . Misalnya, untuk membuat daftar instance database Cloud SQL dalam proyek exciting-example-123:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

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

  1. Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan memanggil fungsi build dengan nama dan versi API dan objek Credentials resmi. Misalnya, untuk memanggil versi 1beta3 dari Cloud SQL Administration API:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Membuat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan . Misalnya, untuk membuat daftar instance database Cloud SQL dalam proyek exciting-example-123:
    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 memasukkan parameter kueri access_token atau nilai Bearer header HTTP Authorization . Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam kebanyakan kasus, Anda dapat menggunakan pustaka klien untuk menyiapkan panggilan Anda ke Google API (misalnya, saat memanggil API File Drive ).

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) 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 yang diautentikasi 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 baris perintah 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

Saat token akses kedaluwarsa

Token akses yang dikeluarkan oleh Server Otorisasi Google OAuth 2.0 akan kedaluwarsa setelah durasi yang diberikan oleh nilai expires_in . Saat token akses kedaluwarsa, aplikasi harus membuat JWT lain, menandatanganinya, dan meminta token akses lain.

Kode kesalahan JWT

bidang error error_description Berarti Bagaimana mengatasinya
unauthorized_client Unauthorized client or scope in request. Jika Anda mencoba menggunakan delegasi seluruh domain, akun layanan tidak diberi otorisasi di konsol Admin domain pengguna.

Pastikan akun layanan diotorisasi di halaman delegasi seluruh Domain di konsol Admin untuk pengguna di sub klaim (kolom).

Meskipun biasanya membutuhkan waktu beberapa menit, mungkin diperlukan waktu hingga 24 jam untuk otorisasi menyebar 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 ID klien (numerik) di konsol Admin. Di halaman Delegasi seluruh domain di konsol Admin, hapus klien, dan tambahkan kembali dengan ID numerik.
access_denied (nilai apapun) Jika Anda menggunakan Delegasi seluruh domain, satu atau beberapa cakupan yang diminta tidak diizinkan di konsol Admin.

Pastikan akun layanan diotorisasi di halaman delegasi seluruh Domain di konsol Admin untuk pengguna di sub klaim (kolom), dan itu mencakup semua cakupan yang Anda minta dalam klaim scope JWT Anda.

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

invalid_grant Not a valid email. Pengguna tidak ada. Periksa apakah alamat email di sub klaim (bidang) 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 tidak tepat. Ini juga bisa terjadi jika nilai exp lebih dari 65 menit di masa depan dari nilai iat , atau nilai exp lebih rendah dari nilai iat .

Pastikan jam pada sistem tempat JWT dibuat 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, pernyataan JWT mungkin dienkode dengan tidak benar - harus dienkode Base64, tanpa baris baru atau padding dengan tanda yang sama.

Dekode kumpulan klaim JWT dan verifikasi kunci yang menandatangani pernyataan terkait dengan akun layanan.

Coba gunakan pustaka 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 (artinya tidak valid).

Pastikan klaim scope (bidang) JWT diisi, dan bandingkan cakupan yang ada di dalamnya dengan cakupan terdokumentasi untuk API yang ingin Anda gunakan, untuk memastikan tidak ada kesalahan 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 bawah IAM & Admin> Akun Layanan , aktifkan akun layanan yang berisi "ID Kunci" yang digunakan untuk menandatangani pernyataan.

Tambahan: Otorisasi akun layanan tanpa OAuth

Dengan beberapa Google API, Anda dapat melakukan panggilan API resmi menggunakan JWT yang ditandatangani secara langsung sebagai token pembawa, daripada token akses OAuth 2.0. Jika memungkinkan, Anda tidak perlu membuat 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 resmi 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 pustaka JWT standar apa pun, seperti yang ditemukan 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 ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di bidang private_key_id dari file JSON akun layanan Anda.
    • Untuk iss dan sub field, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di bidang client_email dari file JSON akun layanan Anda.
    • Untuk bidang aud , tentukan titik akhir API. Misalnya: https:// SERVICE .googleapis.com/ .
    • Untuk bidang iat , tentukan waktu Unix saat ini, dan untuk bidang exp , tentukan waktu tepat 3600 detik kemudian, saat JWT akan kedaluwarsa.

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

Sebagai contoh:

Jawa

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