JSON Web Token

Prologue

JSON Web Token (JWT) adalah standar terbuka (RFC 7519) yang mendefinisikan cara ringkas dan mandiri untuk mentransmisikan informasi secara aman antara pihak-pihak sebagai objek JSON (Sumber).

Setiap komunikasi antar service gateway (GW) dan backend (BE) maupun antar backend diproteksi dengan token JWT.

How It Works?

Dalam implementasi sesungguhnya, yang berhak membuat token JWT hanya service gateway (sa-gw-admin (GWA) dan sa-gw-customer (GWC)) dan service backend hanya memvalidasi apakah token tersebut valid atau tidak.

Namun untuk memudahkan proses development, kami membuak kemampuan agar service backend dapat memproduksi token JWT sendiri, namun ini hanya berlaku di local environment. Ketika Laravel diatur ke mode production, endpoint JWT dari service tersebut tidak dapat diakses.

Claim JWT

Sejatinya, payload dalam JWT terdiri atas 7 claim berikut:

iss (Issuer)

Nama service yang membuat token. Terdiri atas 2 kode: nomor service dan codename service. Contoh: 01-gwa.

aud (Audience)

Nama service dimana token akan digunakan. Terdiri atas codename dari service saja. Contoh: srf.

iat (Issued at)

Datetime kapan token dibuat oleh issuer dalam bentuk epoch.

exp (Expired at)

Datetime kapan token expired dalam bentuk epoch.

sid (Subject's ID)

User id dari user yang memiliki token. Diambil dari tabel users dari setiap gw.

snm (Subject's Name)

Nama user dari user yang memiliki token. Diambil dari tabel users dari setiap gw.

fet (Features)

Daftar fitur yang bisa diakses. Berbentuk list dari permission code.

Apabila token berasal dari GWA, maka ada 2 kemungkinan isi dari fet

1. Single string dari nama kunci permission yang dimiliki.
2. Array of string. Setiap string mewakili kunci permission untuk mengakses fitur.

Apabila token berasal dari GWC, maka isi dari fet pasti diantara 3 string sesuai dengan jenis pengguna:

1. psn: Personal
2. cpy: Company
3. mit: Mitra/Provider

Implementation

Untuk bisa menggunakan token JWT, anda perlu menyiapkan asymmetric key (key pair) dan mengenalkan token tersebut ke Laravel. Untuk metode enkripsi yang digunakan kami tidak membatasi karena kunci ini hanya akan dipakai di local anda sendiri.

1. Silahkan buat key pair: public key dan private key (Anda bisa menggunakan website berikut untuk membuat asymmetric key).
2. Letakkan 2 file key tersebut di dalam folder /storage di service generator (GWA dan GWC, ataupun service BE untuk local development).
3. Kenalkan 2 file tersebut ke Laravel dengan cara membuat key baru di dalam file .env bernama KEY_PRI untuk nama file dari private key, dan KEY_PUB untuk nama file dari public key.
   • Contoh: Anda memberi nama key pair dengan nama myPrivate.key dan myPublic.key. Maka di dalam .env tuliskan seperti berikut:

KEY_PRI=myPrivate.key
KEY_PUB=myPublic.key

4. Apabila anda bekerja menggunakan lebih dari 1 service, anda perlu copy file public key tersebut ke project lain agar service tersebut bisa memvalidasi token yang dibuat benar dari anda. Lakukan step 2 dan 3 namun hanya untuk public key.

BpmJWT.php

Class ini membantu anda bekerja dengan token JWT. Anda tidak perlu memahami semuanya karena semua akan berjalan secara otomatis.

Namun mungkin anda perlu menggunakan method getUserName() dan getUserId() untuk membaca token tersebut milik dari siapa. Sehingga anda perlu perlu membuat object untuk class BpmJWT untuk bisa menggunakan 2 method tersebut karena bukan static. Berikut adalah contoh penggunaannya untuk membaca user id dari request

use App\Extension\Helpers\BpmJWT;
use Illuminate\Http\Request

public function myRequest(Request $req) {
    $bearer = $req->bearerToken();
    $jwt = new BpmJWT();
    $userId = $jwt->getUserId($bearer);
    $userName = $jwt->getUserName($bearer);
}

Authorization Middleware

Dalam mengecek apakah request memiliki token jwt yang valid atau tidak, anda bisa menggunakan middleware jwt yang diimplementasi di class JwtMiddleware.php. Berikut adalah opsi penggunaan JWT:

Implementasi Middleware di Route	Deskripsi
Route::middleware('jwt')	Pengecekkan JWT secara minimal, hanya mengecek apakah token yang dikirim valid dan masih aktif.
Route::middleware('jwt:doc')	Selain mengecek secara minimal, token JWT harus memiliki permission doc (di salah satu item array maupun exact string) di dalam claim fet untuk bisa mengakses endpoint tersebut.
Route::middleware('jwt:doc,ptn')	Endpoint yang diproteksi menerima lebih dari 1 permission yang bisa mengakses. Jadi setidaknya ketika user memiliki doc dan/atau ptn (minimal 1 kondisi terpenuhi), maka user bisa mengakses endpoint tersebut.