Gambaran Umum Alur Otentikasi Spotnana

Dibuat oleh Ashish Chaudhary, Diubah pada Sun, 5 Okt pada 4:44 AM oleh Ashish Chaudhary

Gambaran Umum Alur Autentikasi Spotnana

DAFTAR ISI

Gambaran Umum Alur Autentikasi Spotnana
- Komponen Utama
- Metode Autentikasi yang Didukung

Spotnana menyediakan beragam metode autentikasi yang memungkinkan mitra untuk melakukan integrasi yang aman dengan platform kami. Dokumen ini memberikan gambaran umum tentang berbagai metode autentikasi yang saat ini didukung oleh Spotnana, beserta penjelasan rinci mengenai alur prosesnya. Berbagai alur autentikasi yang dijelaskan di sini menunjukkan bagaimana Spotnana melakukan autentikasi dan otorisasi pengguna untuk mengakses sumber daya yang dilindungi di tingkat organisasi (yaitu, sumber daya milik perusahaan pengguna di platform Spotnana).

Komponen Utama

Sebelum memulai, silakan pelajari daftar berikut untuk mengetahui definisi komponen sistem utama yang disebutkan dalam dokumen ini.

Spotnana UI(Antarmuka Pengguna Spotnana) Mengacu pada aplikasi web antarmuka depan Spotnana (misal: Online Booking Tool) atau aplikasi mobile Spotnana. Secara khusus, ini merujuk pada halaman masuk (login) yang akan menjalankan proses autentikasi ketika pengguna masuk atau membuat akun baru.
Server Spotnana Mengacu pada server backend Spotnana yang digunakan untuk keperluan autentikasi (misalnya, mengotorisasi pengguna untuk mengakses sumber daya serta menyimpan dan mengelola data pengguna secara aman).
Partner UI (Antarmuka Pengguna Mitra) Antarmuka pengguna (yakni aplikasi antarmuka depan) yang digunakan oleh mitra untuk mengakses platform Spotnana. Contohnya, pada autentikasi berbasis iFrame, platform Spotnana ditanamkan di dalam antarmuka pengguna milik mitra, sehingga pengguna akan mengakses Spotnana melalui Partner UI.
Server Mitra Mengacu pada satu atau beberapa server backend milik mitra yang digunakan untuk integrasi dengan Spotnana.
Spotnana IdP (Penyedia Identitas Spotnana) Mengacu pada layanan internal Spotnana yang digunakan untuk pengelolaan identitas dan otorisasi pengguna.
IdP Mitra Penyedia Identitas (IdP) pihak ketiga yang digunakan oleh mitra. Beberapa IdP yang umum digunakan antara lain Google dan Azure.
OBT Online Booking Tool (OBT) dari Spotnana, yang dapat diakses melalui https://app.spotnana.com/
Subject token Pada autentikasi berbasis iFrame (atau pertukaran token), subject token adalah token yang mewakili identitas pengguna. Token ini digunakan untuk mengambil informasi pengguna dan mengotorisasi akses ke platform Spotnana.
Access token Merupakan kredensial (OAuth) yang digunakan oleh aplikasi mitra untuk mengakses sumber daya yang dilindungi atas nama pengguna. Token ini bersifat sementara dan memungkinkan aplikasi melakukan permintaan API tanpa harus membagikan kredensial pengguna.
Refresh token Kredensial dengan masa berlaku panjang yang digunakan untuk mendapatkan access token baru tanpa perlu pengguna melakukan autentikasi ulang. Biasanya, token ini diberikan bersamaan dengan access token saat sesi login pertama kali dibuat.
Client credentials Informasi yang diberikan kepada pengguna yang terhubung langsung ke API Spotnana (misal: sebuah clientId dan clientSecret).
PID (Personal identifier) Merupakan pengenal pribadi yang dibuat untuk pengguna. PID digunakan untuk mengambil data pengguna dari server Spotnana.
orgId Pengidentifikasi unik yang diberikan oleh Spotnana untuk organisasi pengguna.
tmcId Pengidentifikasi unik yang diberikan oleh Spotnana untuk TMC (Travel Management Company).

Metode Autentikasi yang Didukung

Berikut adalah berbagai metode autentikasi yang didukung oleh Spotnana:

Autentikasi Berbasis Kata Sandi
- Pengguna Lama
- Pengguna Baru
Autentikasi Berbasis IdP
Autentikasi Berbasis API
Autentikasi Berbasis iFrame
Autentikasi Berbasis Kode Otorisasi
Autentikasi Antar Mesin (M2M)

Autentikasi Berbasis Kata Sandi

Pada autentikasi berbasis kata sandi, Spotnana UI (misal: halaman login atau daftar akun di OBT) akan memulai dan mengelola proses autentikasi dengan server backend Spotnana. Pendekatan ini memiliki dua alur berbeda, tergantung apakah pengguna masuk dengan profil yang sudah ada atau mendaftar sebagai pengguna baru. Penjelasan rinci untuk masing-masing alur dapat dilihat di bagian berikut, lengkap dengan diagram urutan proses.

Pengguna Lama

Diagram urutan beserta langkah-langkah berikut menjelaskan bagaimana Spotnana UI berinteraksi dengan layanan backend untuk melakukan autentikasi bagi pengguna yang sudah terdaftar.

Gambar: Diagram urutan yang menjelaskan autentikasi berbasis kata sandi untuk pengguna lama.

Langkah	Alur
Pengguna lama masuk ke OBT atau aplikasi mobile Spotnana menggunakan email mereka.
1	Spotnana UI mengirimkan permintaan API ke server Spotnana untuk mengambil informasi konfigurasi autentikasi pengguna. Permintaan ini berisi kredensial login pengguna sebagai parameter. Respons yang diterima berisi `tmcId`, `orgId`, dan `authProviderType`.
2	Spotnana UI mengirimkan permintaan API ke Spotnana IdP dengan menyertakan `clientId`, email, dan kata sandi. Spotnana IdP akan membuat bearer token baru dan mengembalikannya ke Spotnana UI. Langkah ini menandakan pengguna telah berhasil diautentikasi.
3	Setelah pengguna berhasil diautentikasi pada langkah 2, seluruh permintaan API berikutnya harus menyertakan bearer token, `orgId`, dan `tmcId` pada header permintaan. Bearer token akan diverifikasi pada setiap permintaan API yang masuk, lalu respons dikirimkan kembali ke Spotnana UI.

Pengguna Baru

Diagram urutan beserta langkah-langkah berikut menjelaskan bagaimana Spotnana UI berinteraksi dengan layanan backend untuk melakukan autentikasi bagi pengguna baru (atau pengguna lama yang ingin mengatur ulang kata sandi).

Gambar: Diagram urutan yang menjelaskan autentikasi berbasis kata sandi untuk pengguna baru.

Langkah	Alur
Pengguna baru memasukkan email pada halaman login OBT Spotnana lalu klik Next.
1	Spotnana UI mengirimkan permintaan API ke server Spotnana untuk mengambil informasi konfigurasi autentikasi pengguna. Permintaan ini berisi kredensial login pengguna sebagai parameter. Respons yang diterima berisi `tmcId`, `orgId`, dan `authProviderType`.
1 a	Pengguna memasukkan kata sandi baru lalu klik Next.
2	Spotnana UI mengirimkan permintaan API ke Spotnana IdP untuk mendaftarkan pengguna beserta `clientId`, email, dan kata sandi baru. Setelah data berhasil didaftarkan, kode OTP (One-Time Password) akan dikirimkan ke email pengguna.
3	Pengguna memasukkan OTP di Spotnana UI lalu klik Verify. Spotnana UI mengirimkan permintaan ke Spotnana IdP untuk memverifikasi OTP dan menghasilkan bearer token untuk login. Bearer token dihasilkan dan dikirimkan ke Spotnana UI. Ini menandakan autentikasi pengguna berhasil dan pengguna dapat mengakses platform Spotnana dengan bearer token tersebut.
4	Setelah pengguna berhasil diautentikasi pada langkah 3, seluruh permintaan API berikutnya harus menyertakan bearer token, `orgId`, dan `tmcId` pada header permintaan. Bearer token akan diverifikasi pada setiap permintaan API yang masuk, lalu respons dikirimkan kembali ke Spotnana UI.

Autentikasi Berbasis IdP

Spotnana mendukung autentikasi melalui IdP seperti Google, Azure, maupun IdP khusus menggunakan OpenID Connect serta protokol SAML. Diagram urutan beserta langkah-langkah berikut menjelaskan alur autentikasi berbasis IdP.

Gambar: Diagram urutan yang menjelaskan alur autentikasi berbasis IdP.

Langkah	Alur
Pengguna masuk ke OBT atau aplikasi mobile Spotnana menggunakan email mereka.
1	Spotnana UI mengirimkan permintaan API ke server Spotnana untuk mengambil informasi konfigurasi autentikasi pengguna. Permintaan ini berisi kredensial login pengguna sebagai parameter. Respons yang diterima berisi `tmcId`, `orgId`, dan `authProviderType`.
2	Spotnana UI mengalihkan permintaan ke Spotnana IdP.
3	Spotnana IdP meneruskan permintaan ke IdP milik mitra. Hal ini memulai proses autentikasi IdP untuk pengguna. Catatan: Pada setiap pengalihan, status kode 302 akan dikembalikan untuk menunjukkan bahwa permintaan dialihkan ke URL lain.
4	Koneksi antara Spotnana IdP dan IdP mitra dibuat untuk memastikan pengguna telah diautentikasi oleh IdP mitra. Catatan: Selama proses ini, Spotnana IdP mengirimkan `clientId` dan `clientSecret` dalam bentuk data URL-encoded melalui API ke IdP Mitra. Jika server IdP tidak dapat memproses format data ini, server Spotnana dapat bertindak sebagai perantara untuk mengubah data ke format yang dikenali oleh IdP mitra.
5	IdP mitra berhasil melakukan autentikasi terhadap pengguna. Catatan: Setelah langkah ini, profil pengguna tetap harus melalui proses verifikasi bearer token.
5 a	Setelah autentikasi berhasil, respons dari IdP mitra dikirimkan ke Spotnana IdP.
5 b	Spotnana IdP menghasilkan kode unik untuk profil pengguna dan mengirimkannya ke Spotnana UI.
6	Spotnana UI mengirimkan permintaan API ke Spotnana IdP dengan menggunakan `clientID` dan kode yang diterima pada langkah 5(b). Spotnana IdP akan membuat bearer token baru dan mengirimkannya ke Spotnana UI. Catatan: Pembuatan bearer token yang berhasil menandakan pengguna telah diautentikasi dan dapat mengakses Spotnana.
7	Setelah pengguna berhasil diautentikasi pada langkah 6, seluruh permintaan API berikutnya harus menyertakan bearer token, `orgId`, dan `tmcId` pada header permintaan. Bearer token akan diverifikasi pada setiap permintaan API yang masuk, lalu respons dikirimkan kembali ke Spotnana UI.

Autentikasi Berbasis API

Mitra yang menggunakan API Spotnana untuk terhubung ke platform Spotnana dapat menggunakan endpoint autentikasi kami untuk menghasilkan bearer token bagi pengguna mereka. Diagram urutan berikut menggambarkan alur autentikasi untuk mitra yang menggunakan autentikasi berbasis API.

Gambar: Diagram urutan yang menjelaskan autentikasi berbasis API.

Langkah Alur

Langkah	Alur
1	Pengguna API melakukan pemanggilan POST pada `get-auth-token(clientId,clientSecret)` endpoint API di server Spotnana untuk menghasilkan dan mengambil bearer token sementara. Berikut contoh permintaan cUrl yang dapat digunakan untuk memanggil endpoint `get-auth-token` : curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Catatan: Ganti nilai `clientId` dan `clientSecret` dengan kredensial yang Anda terima dari Spotnana.
2	Server Spotnana akan memanggil metode `getToken(clientId,clientSecret)` pada Spotnana IdP untuk menghasilkan `bearerToken` dan mengirimkannya kembali ke server Spotnana. Server Spotnana kemudian mengirimkan bearer token ini sebagai respons JSON ke pengguna API.

Pengguna API melakukan pemanggilan POST pada get-auth-token(clientId,clientSecret) endpoint API di server Spotnana untuk menghasilkan dan mengambil bearer token sementara.

Berikut contoh permintaan cUrl yang dapat digunakan untuk memanggil endpoint get-auth-token :

curl -i -X POST \
https://api.spotnana.com/get-auth-token \
-H 'Content-Type: application/json' \
-d '{
  "clientId": "sample-apiuser@tmcorg.com",
  "clientSecret": "<password>"
}'

Catatan: Ganti nilai clientId dan clientSecret dengan kredensial yang Anda terima dari Spotnana.

Server Spotnana akan memanggil metode getToken(clientId,clientSecret) pada Spotnana IdP untuk menghasilkan bearerToken dan mengirimkannya kembali ke server Spotnana.
Server Spotnana kemudian mengirimkan bearer token ini sebagai respons JSON ke pengguna API.

Setelah pengguna API menerima bearer token, seluruh permintaan berikutnya ke API Spotnana (misal: Trip APIs) wajib menyertakan bearer token pada header untuk keperluan otorisasi.

Catatan: Endpoint get-auth-token(clientId, clientSecret) mempunyai batasan 100 kali pemanggilan API per 5 menit.

Autentikasi Berbasis iFrame

iFrame atau solusi tertanam adalah ketika mitra menanamkan Spotnana UI ke dalam Partner UI, sehingga pengguna mengakses Spotnana melalui antarmuka milik mitra. Pada skenario ini, autentikasi pengguna dilakukan melalui pertukaran token antara sistem mitra dan Spotnana.

Catatan: Untuk autentikasi berbasis iFrame, pengguna yang masuk akan disebut sebagai caller. Hal ini untuk mengakomodasi skenario khusus di mana pengguna API/Mesin masuk dan meminta access token atas nama pengguna lain. Pengguna API/Mesin ini dapat menggunakan kredensial admin TMC (Travel Management Company) untuk terhubung langsung ke server Spotnana. Oleh karena itu, istilah caller digunakan secara umum, baik untuk pengguna yang masuk ke profilnya sendiri maupun pengguna API/Mesin yang meminta access token untuk pengguna lain.

Diagram urutan berikut menggambarkan bagaimana alur autentikasi dilakukan melalui pertukaran token antara Spotnana dan server mitra.

Gambar: Diagram urutan yang menjelaskan autentikasi berbasis iFrame dengan pertukaran token.

Langkah	Alur
Caller masuk melalui Partner UI.
1	Partner UI menampilkan Spotnana UI melalui iFrame.
2	Spotnana UI mengirimkan permintaan ke Partner UI melalui post message untuk mengambil token. Permintaan dikirim dengan `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI mengirimkan permintaan API ke server mitra untuk mengambil OAuth token, yang selanjutnya akan memulai proses autentikasi berikutnya.
3 a	Server mitra memanggil server Spotnana menggunakan kredensial pengguna dan subject token sebagai parameter. Server Spotnana akan memeriksa apakah permintaan tersebut dikirim oleh pengguna API/Mesin.
3 b	Server Spotnana memanggil server mitra untuk mengambil email subject (yaitu caller). Email tersebut diambil dan dikirimkan ke server Spotnana untuk mengidentifikasi pengguna.
3 c	Respons permintaan API dari langkah 1 dikirimkan oleh server Spotnana ke server mitra, berisi access token dan refresh token. Informasi ini kemudian diteruskan ke Partner UI.
4	Partner UI mengirimkan token ke Spotnana UI melalui post message dengan `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI mengirimkan permintaan API ke server Spotnana untuk menghasilkan dan mengambil bearer token baru. Bearer token akan dibuat oleh server Spotnana dan dikirimkan ke Spotnana UI. Catatan: Pembuatan bearer token yang berhasil menandakan pengguna telah diautentikasi dan dapat mengakses Spotnana.
6	Setelah pengguna berhasil diautentikasi pada langkah 3, seluruh permintaan API berikutnya harus menyertakan bearer token, `orgId`, dan `tmcId` pada header permintaan. Bearer token akan diverifikasi pada setiap permintaan API yang masuk, lalu respons dikirimkan kembali ke Spotnana UI.

Autentikasi Berbasis Kode Otorisasi

Diagram urutan berikut menggambarkan bagaimana alur autentikasi dilakukan menggunakan kode otorisasi.

Gambar: Diagram urutan yang menjelaskan autentikasi berbasis kode otorisasi.

Langkah	Alur
1	Partner UI memanggil server mitra untuk mengambil auth code bagi caller yang akan masuk. Auth code diambil dan dikirimkan kembali ke Partner UI.
2	Partner UI mengirimkan permintaan ke Spotnana UI menggunakan custom redirect URL yang berisi `tmcId` dan `authCode` sebagai parameter.
3	Spotnana UI melakukan pemanggilan POST API ke server Spotnana menggunakan `v2/auth/token/companies/<tmcId>(authCode)` endpoint API.
3 a	Server Spotnana mengirimkan permintaan ke server mitra untuk mengambil `pid` pengguna menggunakan auth code. PID pengguna `akan diambil dan dikirimkan ke server Spotnana.` 3 b
Access token dan refresh token dihasilkan oleh server Spotnana dan dikirimkan ke Spotnana UI.	4
Spotnana UI mengirimkan permintaan ke server Spotnana menggunakan access token dan refresh token untuk menghasilkan serta mengambil bearer token untuk akses.	Bearer token dihasilkan dan dikirimkan ke Spotnana UI. Catatan: Pembuatan bearer token yang berhasil menandakan pengguna telah diautentikasi dan dapat mengakses Spotnana. 5
Setelah pengguna berhasil diautentikasi pada langkah 4, seluruh permintaan API berikutnya harus menyertakan bearer token,	orgId `, dan`tmcId `pada header permintaan.` Bearer token akan diverifikasi pada setiap permintaan API yang masuk, lalu respons dikirimkan kembali ke Spotnana UI. Catatan:

Alur autentikasi ini tidak dapat digunakan jika admin TMC mengizinkan lebih dari satu pengguna menggunakan email yang sama saat masuk. Autentikasi Antar Mesin (M2M)

Metode autentikasi M2M ini cocok digunakan ketika alur autentikasi melibatkan aplikasi klien yang mengakses callback URL pihak ketiga untuk menghasilkan

accessToken bagi pengguna. Diagram urutan berikut menggambarkan alur autentikasi M2M. Gambar:

Diagram urutan yang menjelaskan alur autentikasi M2M. Langkah

Alur	Kunci publik untuk seluruh aplikasi yang digunakan dalam proses autentikasi disinkronkan antara server Spotnana dan Spotnana IdP. Nantinya, kunci ini akan digunakan untuk memverifikasi access token dalam alur autentikasi.
1
Server mitra mengirimkan permintaan API ke	/oauth2/token(clientId,clientSecret) `pada Spotnana IdP untuk menghasilkan bearer token. Bearer token baru kemudian dikirimkan kembali ke server mitra.` 2
Server mitra mengirimkan permintaan API ke callback URL pihak ketiga untuk menghasilkan access token bagi pengguna.	Access token ini dibuat dan dikirimkan ke server Spotnana. 3
Server Spotnana memverifikasi tanda tangan access token menggunakan kunci publik yang telah disinkronkan sebelumnya. Selain itu,	claim_id `juga divalidasi untuk memastikan identitas mitra.` Access token kemudian dikirimkan ke server mitra untuk melakukan autentikasi pengguna. ...