Skip to main content
Gunakan kredensial klien OAuth saat integrasi backend Anda membutuhkan token akses berumur pendek atau saat kebijakan keamanan Anda mewajibkannya. Setiap klien milik satu akun layanan dan satu organisasi. OAuth bersifat opsional: kunci API dengan cakupan terbatas sudah memadai untuk integrasi server privat yang dapat menyimpan dan merotasi kunci dengan aman. Lihat Autentikasi untuk memilih di antara kedua metode tersebut dan memahami peran akun layanan.
Akses OAuth harus diaktifkan untuk organisasi Anda. Proses penyiapan Anda menyediakan endpoint token regional, issuer, audience, dan metode autentikasi klien. Jika Anda memerlukan pengaturan ini atau tidak dapat mengakses pengelolaan klien, hubungi Dukungan Living Security.
Grant kredensial klien mewakili akun layanan Anda. Grant ini tidak memasukkan seseorang ke sistem atau meminta pelanggan untuk mengotorisasi suatu aplikasi. Otorisasi terdelegasi melalui browser merupakan kemampuan OAuth yang terpisah dan tidak disediakan oleh operasi-operasi ini.

Sebelum Anda memulai

  • Buat akun layanan dengan hanya izin yang dibutuhkan oleh integrasi.
  • Gunakan kredensial manajemen dengan service_account:manage dan setiap izin yang ingin Anda berikan kepada klien baru. Akun target juga harus memiliki izin tersebut. Klien tidak dapat memperluas kewenangan akun mana pun.
  • Pilih wilayah organisasi. Kredensial API dan token akses OAuth harus digunakan pada host API regional yang sesuai.
  • Simpan secret klien dan token di penyimpanan secret sisi server Anda. Jangan pernah menaruhnya dalam kode browser, aplikasi seluler, kontrol sumber, atau log permintaan.

Membuat klien

POST /v1/oauth_clients memerlukan service_account_id, daftar tidak kosong berisi scopes eksplisit, dan Idempotency-Key. Wildcard tidak diterima. Satu klien mendukung hingga 100 cakupan, dengan total panjang maksimal 4.096 karakter. Setiap akun layanan dapat memiliki paling banyak 20 klien atau operasi pembuatan/pembersihan yang belum selesai. Pencabutan langsung menolak akses API. Klien atau pembuatan yang tidak pasti di sisi penyedia tetap dihitung terhadap batas hingga pembersihan jarak jauh dikonfirmasi. Reservasi yang ditinggalkan atau pembuatan yang terbukti gagal sebelum pekerjaan penyedia dimulai dapat melepaskan slotnya dengan aman. Kunci percobaan ulangnya tetap milik upaya awal; pulihkan tanda terima tersebut sebelum memutuskan untuk membuat pengganti. Pilih satu kunci percobaan ulang untuk upaya pembuatan ini dan simpan sebelum mengirim permintaan. Gunakan 1–255 karakter ASCII yang terlihat, tanpa spasi. Gunakan kembali kunci tersebut dengan akun, cakupan, prinsipal manajemen, wilayah, dan versi API yang sama setelah respons hilang. Merotasi kredensial manajemen pada akun layanan yang sama tidak membuat identitas percobaan ulang yang baru. Instal paket requests Python. Muat nilai lingkungan berikut melalui pengelolaan secret dan konfigurasi Anda yang biasa:
Python
Contoh ini membuat satu permintaan dan menyimpan hasilnya di memori. Tambahkan operasi tulis pengelola secret Anda pada titik yang ditandai sebelum menjalankannya di produksi. Contoh ini sengaja mengharuskan adanya keputusan setelah hasil yang tidak pasti, alih-alih diam-diam membuat klien lain. Pengecualian jaringan juga memerlukan langkah pemulihan di bawah ini. Respons pembuatan dan tanda terima menggunakan 201 dan berisi resource oauth_client dengan id, service_account_id, client_id, scopes, status, created_at, dan client_secret. Respons ditandai Cache-Control: no-store.
  • id mengidentifikasi resource platform. Simpan untuk pengambilan dan pencabutan.
  • client_id mengidentifikasi klien selama pertukaran token. Ini bukan ID resource platform. Nilainya dapat berupa null saat pembuatan masih tertunda.
  • client_secret hanya dikembalikan kepada permintaan yang menyelesaikan pembuatan. Setiap permintaan pembuatan berulang mengembalikan null, termasuk percobaan ulang setelah respons keberhasilan hilang. Pengambilan tidak pernah mengembalikan secret.

Memulihkan respons yang hilang atau terputus

Ulangi permintaan pembuatan yang sama dengan kunci percobaan ulang yang tersimpan untuk memulihkan tanda terima resource. Tanda terima mencerminkan status terkini, sehingga klien yang telah dicabut tetap berstatus dicabut. Operasi ini tidak menggunakan kontrak pemutaran ulang respons tersimpan selama 24 jam yang umum dan tidak mengembalikan header Idempotent-Replayed. Lihat kesalahan untuk ID permintaan dan detail pemulihan. Jangan pernah mengirim secret klien atau token akses bersama permintaan dukungan.

Memeriksa dan mencabut

Gunakan kredensial manajemen Anda dan id resource platform: Pencabutan memblokir permintaan API berikutnya dari klien, termasuk permintaan dengan token yang sudah diterbitkan. Pencabutan tidak membatalkan pekerjaan yang sudah diterima oleh API. Pembersihan kredensial jarak jauh dapat selesai kemudian. Mengulangi pencabutan aman dilakukan dan tidak memerlukan kunci percobaan ulang. Lanjutkan menggunakan kredensial manajemen jika klien yang dicabut itu sendiri merupakan pemanggil API.

Rotasi tanpa kehilangan akses

Buat klien kedua dengan batas atas cakupan yang diperlukan. Simpan secret-nya, peroleh token menggunakan endpoint token regional Anda, dan verifikasi bahwa integrasi berfungsi dengannya. Alihkan integrasi ke klien pengganti, lalu cabut resource yang lama. Pertahankan kredensial manajemen independen agar Anda dapat pulih dari peluncuran yang gagal. Token akses tidak dapat memberikan lebih dari cakupan klien dan izin akun layanan saat ini. Penghapusan izin akun atau pencabutan klien lebih diutamakan daripada sisa masa berlaku token. Jangan menganggap token yang di-cache sebagai bukti bahwa otorisasi masih valid. Peroleh token akses baru sebelum kedaluwarsa dengan mengautentikasi klien kembali; grant ini tidak menggunakan refresh token.