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:
- Open the Service accounts page.
- If prompted, select a project, or create a new one.
- Click Create service account.
- Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
- Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
- Click Continue.
- Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
- Click Done.
Next, create a service account key:
- Click the email address for the service account you created.
- Click the Keys tab.
- In the Add key drop-down list, select Create new key.
- 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:
- Dari domain Google Workspace Anda Konsol Admin, buka Menu utama Keamanan > Kontrol data dan akses > Kontrol API.
- Di panel Delegasi tingkat domain, pilih Kelola Delegasi Tingkat Domain.
- Klik Tambahkan baru.
- Di kolom ID Klien, masukkan ID Klien akun layanan. Anda dapat menemukan client ID akun layanan Anda di Service accounts page.
- 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.
- 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:
- 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.
- 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 ObjekServiceAccountCredentials
. 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:
- Buat Token Web JSON (JWT, dibaca, "jot") yang mencakup header, kumpulan klaim, dan tanda tangan.
- Minta token akses dari Server Otorisasi Google OAuth 2.0.
- 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.
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:
- Buat objek layanan untuk API yang ingin Anda panggil menggunakan metode
Objek
GoogleCredential
. Contoh:SQLAdmin sqladmin = new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
- 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:
- Bangun objek layanan untuk API yang ingin Anda panggil. Anda membangun objek layanan
dengan memanggil fungsi
build
menggunakan nama dan versi API, serta objekCredentials
yang diberi otorisasi. Misalnya, untuk memanggil versi 1beta3 Cloud SQL Administration API:import googleapiclient.discovery sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
- 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 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 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 |
|
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 Perlu diketahui bahwa daftar cakupan dalam klaim |
disabled_client |
The OAuth client was disabled. |
Kunci yang digunakan untuk menandatangani pernyataan JWT dinonaktifkan. |
Buka Google API Console, dan di bagian IAM & Admin > 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:
- Buat akun layanan seperti yang dijelaskan di atas. Pastikan untuk menyimpan file JSON yang Anda dapatkan ketika membuat akun.
- 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 kolomprivate_key_id
pada akun layanan Anda file JSON Anda. - Untuk kolom
iss
dansub
, tentukan email akun layanan Anda alamat IPv6 Anda dapat menemukan nilai ini di kolomclient_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 untukexp
, 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')
- 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.