Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server

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.

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.

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:

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.

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.