Mempersiapkan permintaan terautentikasi ke API

Setelah membuat dan mengonfigurasi akun layanan, aplikasi Anda perlu menyelesaikan langkah-langkah berikut:

1. Membuat JSON Web Token (JWT), yang mencakup header, payload, dan signature;
2. Meminta token akses (AccessToken) dari platform autentikasi OAuth2;
3. Menangani respons JSON yang akan dikembalikan oleh platform autentikasi.

Jika respons menyertakan token akses, Anda dapat menggunakannya untuk membuat permintaan ke API produk Unico yang memiliki izin akses untuk akun layanan tersebut. (Jika respons tidak menyertakan token akses, JWT dan permintaan token Anda mungkin salah, atau akun layanan mungkin tidak memiliki izin yang diperlukan untuk mengakses sumber daya yang diminta.)

Token akses yang dihasilkan dalam permintaan yang disebutkan di atas memiliki masa berlaku default 3600 detik, tetapi ini dapat bervariasi tergantung pada konfigurasi keamanan yang ditetapkan untuk perusahaan Anda. Ketika token akses kedaluwarsa, aplikasi Anda harus membuat JWT baru, menandatanganinya, dan meminta token akses baru dari platform autentikasi.

1 — Membuat JWT

JWT terdiri dari tiga bagian: sebuah header, sebuah payload, dan sebuah signature. Header dan payload adalah objek JSON. Objek JSON ini diserialisasi dalam UTF-8 dan kemudian dikodekan menggunakan pengkodean Base64url¹. Pengkodean ini memberikan ketahanan terhadap perubahan pengkodean dalam kasus operasi pengkodean berulang. Header, payload, dan signature digabungkan dengan karakter titik (.).

JWT disusun sebagai berikut:

{Header dalam Base64url}.{Payload dalam Base64url}.{Signature dalam Base64url}

Teks dasar untuk signature disusun sebagai berikut:

{Header dalam Base64url}.{Payload dalam Base64url}

1.1 — Membentuk Header JWT

Header terdiri dari dua bidang yang menentukan algoritma penandatanganan dan format token. Kedua bidang bersifat wajib, dan setiap bidang hanya memiliki satu nilai. Akun layanan mengandalkan algoritma RSA SHA-256 dan format token JWT. Akibatnya, representasi JSON dari header adalah sebagai berikut:

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

Representasi Base64url adalah sebagai berikut:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 — Membentuk Payload JWT

Payload JWT berisi informasi tentang JWT, termasuk izin yang diminta (scope), akun yang meminta akses, penerbit, waktu ketika token diterbitkan, dan masa berlaku token. Sebagian besar bidang bersifat wajib. Sama seperti header JWT, payload adalah objek JSON dan digunakan dalam penyusunan signature.

1.3 — Bidang Wajib

Bidang wajib dalam JWT ditunjukkan pada tabel di bawah ini. Bidang tersebut dapat muncul dalam urutan apa pun di dalam payload.

Nama	Deskripsi
iss	Pengenal akun layanan di dalam perusahaan.
scope	Daftar izin yang diminta aplikasi, dipisahkan oleh spasi atau tanda plus (+). Jika semua izin akun diperlukan, gunakan simbol tanda bintang (*) untuk ini.
aud	Alamat platform autentikasi yang menerbitkan token akses. Nilai ini harus selalu tepat https://identityhomolog.acesso.io. Masalah umum yang tidak berfungsi: menambahkan garis miring di akhir (https://identityhomolog.acesso.io/), atau menggunakan HTTP alih-alih HTTPS.
exp	Waktu kedaluwarsa token, ditentukan dalam detik sejak 00:00:00 UTC, 1 Januari 1970. Nilai ini memiliki durasi maksimum 1 jam setelah waktu penerbitan JWT. Nilai ini harus numerik — nilai yang dikutip seperti "1524161193" adalah string dan tidak akan berfungsi; 1524161193 adalah angka dan akan berfungsi.
iat	Waktu penerbitan JWT, ditentukan dalam detik sejak 00:00:00 UTC, 1 Januari 1970. Nilai ini harus numerik, dengan aturan yang sama seperti exp.

Bidang iat harus merepresentasikan waktu saat ini dalam format yang diperlukan, dan bidang exp harus mengikuti perhitungan berikut:

exp = iat + 3600

Representasi bidang JSON wajib dalam payload JWT adalah sebagai berikut:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

1.4 — Menghitung Signature

Spesifikasi **JSON Web Signature (JWS)**² adalah mekanisme yang memandu perhitungan signature untuk JWT. Konten input untuk perhitungan signature adalah array byte dari konten berikut:

{Header dalam Base64url}.{Payload dalam Base64url}

Algoritma yang sama seperti yang ditentukan dalam header JWT harus digunakan untuk menghitung signature. Satu-satunya algoritma signature yang didukung oleh platform autentikasi OAuth2 adalah RSA menggunakan SHA-256, dinyatakan sebagai RS256 pada bidang alg di header JWT.

Tandatangani representasi UTF-8 dari konten input menggunakan SHA256withRSA (juga dikenal sebagai RSASSA-PKCS1-V1_5-SIGN dengan hash SHA-256) dengan kunci privat yang telah dibuat dan diasosiasikan dengan akun layanan (file .key.pem yang dihasilkan dari permintaan yang diterima melalui email). Konten output akan berupa array byte.

Signature kemudian perlu dikodekan dalam Base64url. Header, payload, dan signature harus digabungkan dengan karakter titik. Hasilnya adalah JWT.

Anda juga dapat menggunakan pustaka yang telah ditetapkan sebelumnya untuk membuat JWT. Sebagai referensi, Anda dapat menemukan daftar pustaka di situs jwt.io.

2 — Membuat permintaan token akses

Setelah membuat JWT yang telah ditandatangani, aplikasi dapat menggunakannya untuk meminta token akses. Permintaan token akses adalah permintaan POST HTTPS, dan body harus dikodekan dalam URL. URL-nya ditunjukkan di bawah ini:

https://identityhomolog.acesso.io/oauth2/token

Parameter berikut wajib ada dalam permintaan POST HTTPS:

Nama	Deskripsi
grant_type	Gunakan teks berikut, dikodekan URL jika diperlukan: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	JWT, termasuk signature.

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>

3 — Menangani Respons Platform Autentikasi

Jika JWT dan permintaan token akses dibentuk dengan benar, dan akun layanan memiliki izin yang diperlukan, platform autentikasi akan mengembalikan objek JSON yang berisi token akses:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

Token akses yang dikembalikan dalam bidang access_token dari objek JSON juga merupakan token JWT yang harus digunakan pada API Produk Unico. Jika terjadi kesalahan dalam permintaan, periksa jenis kesalahan di Kesalahan Autentikasi.

4 — Durasi Token Akses

Durasi token akses bervariasi. Durasinya ditentukan dalam bidang expires_in, yang dikembalikan bersama dengan token akses. Token akses yang sama harus digunakan selama masa berlakunya untuk semua panggilan API ke produk.

Jangan meminta token akses baru sampai masa berlaku token saat ini mendekati akhir. Kami merekomendasikan margin 600 detik (10 menit):

new Date((token.exp - 600) * 1000)

Di mana token.exp adalah timestamp waktu kedaluwarsa token.

catatan

Secara default, token yang dikirim ke perusahaan berlaku selama 1 jam, tetapi dapat diubah. Rekomendasinya adalah selalu menggunakan expires_in sebagai basis dan mengurangi 600 detik darinya untuk meminta token baru.

Contoh:

Skenario standar:
expires_in: 3600 (1j) - Token dibuat pada 14:42
Minta token baru hanya pada 15:32, yaitu 14:42 + (3600 - 600)

Skenario dengan durasi yang dimodifikasi:
expires_in: 7200 (2j) - Token dibuat pada 14:42
Minta token baru hanya pada 16:32, yaitu 14:42 + (7200 - 600)

peringatan

Jangan gunakan waktu tetap untuk mendapatkan token baru, karena durasi token yang diterima mungkin lebih pendek dari waktu yang ditetapkan, yang dapat menyebabkan kegagalan saat menggunakan layanan.

---

¹ Menurut RFC 4648 untuk pengkodean BaseN, format Base64url mirip dengan Base64, kecuali bahwa karakter = dihilangkan, dan karakter + serta / digantikan oleh - dan _. ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.