Gambaran keseluruhan aliran pengesahan Spotnana

Dicipta oleh Ashish Chaudhary, Diubah suai pada Sun, 5 Okt pada 9:11 PG ikut Ashish Chaudhary

Gambaran Umum Aliran Pengesahan Spotnana

KANDUNGAN

Gambaran Umum Aliran Pengesahan Spotnana
- Komponen Utama
- Kaedah Pengesahan yang Disokong

Spotnana menyediakan beberapa kaedah pengesahan untuk membolehkan rakan kongsi mengintegrasikan sistem mereka dengan platform kami secara selamat. Dokumen ini menerangkan secara ringkas kaedah-kaedah pengesahan yang disokong oleh Spotnana, lengkap dengan penjelasan terperinci tentang aliran proses setiap kaedah. Aliran pengesahan yang diterangkan di sini menunjukkan bagaimana Spotnana mengesahkan dan memberi kebenaran kepada pengguna untuk mengakses sumber yang dilindungi di peringkat organisasi (iaitu sumber yang dimiliki oleh syarikat pengguna di platform Spotnana).

Komponen Utama

Sebelum anda bermula, sila semak senarai ini untuk memahami maksud setiap komponen sistem utama yang disebut dalam dokumen ini.

Antara Muka Pengguna Spotnana (Spotnana UI)(Antara Muka Pengguna Spotnana) Merujuk kepada aplikasi web hadapan Spotnana (iaitu Alat Tempahan Dalam Talian) atau aplikasi mudah alih Spotnana. Secara khusus, ia merujuk kepada halaman log masuk yang akan memulakan aliran pengesahan apabila pengguna log masuk atau mencipta akaun baharu.
Pelayan Spotnana Merujuk kepada pelayan belakang Spotnana yang digunakan untuk tujuan pengesahan (contohnya, memberi kebenaran kepada pengguna untuk mengakses sesuatu sumber serta menyimpan dan memproses maklumat pengguna dengan selamat).
Antara Muka Pengguna Rakan Kongsi (Partner UI) (Antara Muka Pengguna Rakan Kongsi) Antara muka pengguna (iaitu aplikasi hadapan) yang digunakan oleh rakan kongsi untuk mengakses platform Spotnana. Sebagai contoh, dalam pengesahan berasaskan iFrame, platform Spotnana akan dimasukkan ke dalam antara muka pengguna rakan kongsi dan pengguna mereka akan mengakses Spotnana melalui Partner UI.
Pelayan Rakan Kongsi Merujuk kepada satu atau lebih pelayan belakang yang digunakan oleh rakan kongsi kami untuk berintegrasi dengan Spotnana.
Spotnana IdP (Penyedia Identiti Spotnana) Merujuk kepada perkhidmatan dalaman Spotnana yang digunakan untuk pengurusan identiti dan kebenaran pengguna.
IdP Rakan Kongsi Penyedia Identiti pihak ketiga (IdP) yang digunakan oleh rakan kongsi, seperti Google dan Azure.
OBT Alat Tempahan Dalam Talian Spotnana (OBT), yang boleh diakses di https://app.spotnana.com/
Token subjek Dalam pengesahan berasaskan iFrame (atau pertukaran token), token subjek mewakili identiti pengguna. Token ini digunakan untuk mendapatkan maklumat pengguna dan memberi kebenaran akses ke platform Spotnana.
Token akses Sijil (OAuth) yang digunakan oleh aplikasi rakan kongsi untuk mengakses sumber terlindung bagi pihak pengguna. Ia merupakan kunci kebenaran sementara yang membolehkan aplikasi membuat permintaan API tanpa mendedahkan maklumat log masuk pengguna.
Token segar semula (refresh token) Sijil jangka panjang yang digunakan untuk mendapatkan token akses baharu tanpa memerlukan pengguna log masuk semula. Biasanya dikeluarkan bersama token akses semasa sesi log masuk pertama.
Kelayakan klien (client credentials) Maklumat yang diberikan kepada pengguna yang berhubung terus dengan API Spotnana (iaitu, clientId dan clientSecret).
PID (Pengecam Peribadi) Pengecam peribadi yang dicipta untuk pengguna. PID ini digunakan untuk mendapatkan maklumat pengguna daripada pelayan Spotnana.
orgId Pengecam unik yang diberikan oleh Spotnana untuk organisasi pengguna.
tmcId Pengecam unik yang diberikan oleh Spotnana untuk TMC (Syarikat Pengurusan Perjalanan).

Kaedah Pengesahan yang Disokong

Berikut ialah kaedah pengesahan yang disokong oleh Spotnana:

Pengesahan Berasaskan Kata Laluan
- Pengguna Sedia Ada
- Pengguna Baharu
Pengesahan Berasaskan IdP
Pengesahan Berasaskan API
Pengesahan Berasaskan iFrame
Pengesahan Berasaskan Kod Kebenaran
Pengesahan Mesin ke Mesin (M2M)

Pengesahan Berasaskan Kata Laluan

Untuk pengesahan berasaskan kata laluan, Spotnana UI (iaitu halaman log masuk atau daftar di OBT) akan memulakan dan mengurus proses pengesahan bersama pelayan belakang Spotnana. Terdapat dua aliran berbeza bergantung sama ada pengguna log masuk menggunakan profil sedia ada atau mendaftar untuk akaun baharu. Setiap aliran pengesahan ini akan diterangkan di bawah bersama rajah urutan.

Pengguna Sedia Ada

Rajah urutan dan langkah-langkah berikut menerangkan bagaimana Spotnana UI berinteraksi dengan perkhidmatan belakang untuk mengesahkan pengguna sedia ada.

Rajah: Rajah urutan yang menerangkan pengesahan berasaskan kata laluan untuk pengguna sedia ada.

Langkah	Aliran
Pengguna sedia ada log masuk melalui OBT atau aplikasi mudah alih Spotnana menggunakan emel mereka.
1	Spotnana UI menghantar permintaan API ke pelayan Spotnana untuk mendapatkan maklumat konfigurasi pengesahan pengguna. Permintaan ini mengandungi maklumat log masuk pengguna sebagai parameter. Maklum balas yang diterima akan mengandungi `tmcId`, `orgId`, dan `authProviderType`.
2	Spotnana UI menghantar permintaan API ke Spotnana IdP menggunakan `clientId`, emel, dan kata laluan. Satu token bearer baharu akan dijana oleh Spotnana IdP dan dikembalikan kepada Spotnana UI. Langkah ini akan mengesahkan pengguna.
3	Sebaik sahaja pengguna disahkan pada langkah 2, semua permintaan API seterusnya perlu mengandungi token bearer, `orgId`, dan `tmcId` dalam pengepala permintaan. Token bearer akan disemak dalam setiap permintaan API yang diterima dan maklum balas akan dihantar semula ke Spotnana UI.

Pengguna Baharu

Rajah urutan dan langkah-langkah berikut menerangkan bagaimana Spotnana UI berinteraksi dengan perkhidmatan belakang untuk mengesahkan pengguna baharu (atau pengguna sedia ada yang ingin menetapkan semula kata laluan).

Rajah: Rajah urutan yang menerangkan pengesahan berasaskan kata laluan untuk pengguna baharu.

Langkah	Aliran
Pengguna baharu memasukkan emel mereka di halaman log masuk OBT Spotnana dan klik Next.
1	Spotnana UI menghantar permintaan API ke pelayan Spotnana untuk mendapatkan maklumat konfigurasi pengesahan pengguna. Permintaan ini mengandungi maklumat log masuk pengguna sebagai parameter. Maklum balas yang diterima akan mengandungi `tmcId`, `orgId`, dan `authProviderType`.
1 a	Pengguna memasukkan kata laluan baharu dan klik Next.
2	Spotnana UI menghantar permintaan API ke Spotnana IdP untuk mendaftar pengguna bersama `clientId`, emel, dan kata laluan baharu. Sebaik sahaja maklumat didaftarkan, Kata Laluan Sekali Guna (OTP) akan dihantar ke emel pengguna.
3	Pengguna memasukkan OTP dalam Spotnana UI dan klik Verify. Spotnana UI menghantar permintaan ke Spotnana IdP untuk mengesahkan OTP dan menjana token bearer untuk log masuk. Token bearer dijana dan dikembalikan ke Spotnana UI. Ini menandakan pengesahan pengguna telah berjaya dan pengguna boleh mengakses platform Spotnana menggunakan token tersebut.
4	Sebaik sahaja pengguna disahkan pada langkah 3, semua permintaan API seterusnya perlu mengandungi token bearer, `orgId`, dan `tmcId` dalam pengepala permintaan. Token bearer akan disemak dalam setiap permintaan API yang diterima dan maklum balas akan dihantar semula ke Spotnana UI.

Pengesahan Berasaskan IdP

Spotnana menyokong pengesahan melalui IdP seperti Google, Azure dan IdP tersuai menggunakan OpenID connect serta protokol SAML. Rajah urutan dan langkah-langkah berikut menerangkan aliran pengesahan berasaskan IdP.

Rajah: Rajah urutan yang menerangkan aliran pengesahan berasaskan IdP.

Langkah	Aliran
Pengguna log masuk melalui OBT atau aplikasi mudah alih Spotnana menggunakan emel mereka.
1	Spotnana UI menghantar permintaan API ke pelayan Spotnana untuk mendapatkan maklumat konfigurasi pengesahan pengguna. Permintaan ini mengandungi maklumat log masuk pengguna sebagai parameter. Maklum balas yang diterima akan mengandungi `tmcId`, `orgId`, dan `authProviderType`.
2	Spotnana UI mengalihkan permintaan ke Spotnana IdP.
3	Spotnana IdP mengalihkan permintaan ke IdP rakan kongsi. Ini akan memulakan proses pengesahan IdP untuk pengguna. Nota: Bagi setiap pengalihan, kod status 302 akan dipulangkan untuk menandakan permintaan telah dialihkan ke URL lain.
4	Satu sambungan diwujudkan antara Spotnana IdP dan IdP rakan kongsi. Sambungan ini memastikan pengguna benar-benar disahkan oleh IdP rakan kongsi. Nota: Semasa sambungan ini, Spotnana IdP akan menghantar `clientId` dan `clientSecret` dalam bentuk data URL-encoded melalui panggilan API ke IdP rakan kongsi. Jika pelayan IdP tidak dapat memproses format data ini, pelayan Spotnana boleh bertindak sebagai proksi untuk menukarkan data ke format yang diterima oleh IdP rakan kongsi.
5	IdP rakan kongsi berjaya mengesahkan pengguna. Nota: Selepas langkah ini, profil pengguna masih perlu melalui pengesahan token bearer.
5 a	Selepas pengesahan berjaya, maklum balas daripada IdP rakan kongsi dihantar ke Spotnana IdP.
5 b	Spotnana IdP menjana kod unik untuk profil pengguna dan menghantarnya ke Spotnana UI.
6	Spotnana UI menghantar permintaan API ke Spotnana IdP menggunakan `clientID` dan kod yang diterima pada langkah 5(b). Spotnana IdP akan menjana token bearer baharu dan menghantarnya ke Spotnana UI. Nota: Kejayaan penciptaan token bearer menandakan pengguna telah disahkan dan dibenarkan mengakses Spotnana.
7	Sebaik sahaja pengguna disahkan pada langkah 6, semua permintaan API seterusnya perlu mengandungi token bearer, `orgId`, dan `tmcId` dalam pengepala permintaan. Token bearer akan disemak dalam setiap permintaan API yang diterima dan maklum balas akan dihantar semula ke Spotnana UI.

Pengesahan Berasaskan API

Rakan kongsi yang menggunakan API Spotnana untuk berhubung dengan platform Spotnana boleh menggunakan titik akhir pengesahan kami untuk menjana token bearer bagi pengguna mereka. Rajah urutan berikut menunjukkan aliran pengesahan untuk mana-mana rakan kongsi yang menggunakan pengesahan berasaskan API.

Rajah: Rajah urutan yang menerangkan pengesahan berasaskan API.

Langkah Aliran

Langkah	Aliran
1	Pengguna API membuat panggilan POST ke `get-auth-token(clientId,clientSecret)` titik akhir API di pelayan Spotnana untuk menjana dan mendapatkan token bearer sementara. Berikut contoh permintaan cUrl yang boleh digunakan untuk memanggil `get-auth-token` titik akhir: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Nota: Gantikan nilai `clientId` dan `clientSecret` dengan kelayakan yang anda terima daripada Spotnana.
2	Pelayan Spotnana akan memanggil kaedah `getToken(clientId,clientSecret)` di Spotnana IdP, yang akan menjana `bearerToken` sementara dan menghantarnya semula ke pelayan Spotnana. Pelayan Spotnana akan menghantar token bearer ini sebagai maklum balas JSON kepada pengguna API.

Pengguna API membuat panggilan POST ke get-auth-token(clientId,clientSecret) titik akhir API di pelayan Spotnana untuk menjana dan mendapatkan token bearer sementara.

Berikut contoh permintaan cUrl yang boleh digunakan untuk memanggil get-auth-token titik akhir:

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

Nota: Gantikan nilai clientId dan clientSecret dengan kelayakan yang anda terima daripada Spotnana.

Pelayan Spotnana akan memanggil kaedah getToken(clientId,clientSecret) di Spotnana IdP, yang akan menjana bearerToken sementara dan menghantarnya semula ke pelayan Spotnana.
Pelayan Spotnana akan menghantar token bearer ini sebagai maklum balas JSON kepada pengguna API.

Sebaik sahaja pengguna API menerima token bearer, semua permintaan seterusnya ke API Spotnana (contohnya, Trip APIs) perlu menyertakan token bearer dalam pengepala untuk tujuan kebenaran.

Nota: Titik akhir get-auth-token(clientId, clientSecret) mempunyai had kadar 100 panggilan API setiap 5 minit.

Pengesahan Berasaskan iFrame

iFrame atau penyelesaian terbenam ialah apabila rakan kongsi memasukkan Spotnana UI ke dalam Partner UI, bermakna pengguna mengakses Spotnana melalui Partner UI. Dalam situasi ini, pengesahan pengguna dikendalikan melalui pertukaran token antara sistem rakan kongsi dan Spotnana.

Nota: Untuk pengesahan berasaskan iFrame, pengguna yang log masuk akan dirujuk sebagai caller. Ini bagi membolehkan senario khusus di mana pengguna API/Mesin log masuk dan memohon token akses bagi pihak pengguna lain. Pengguna API/Mesin ini boleh menggunakan kelayakan pentadbir TMC (Syarikat Pengurusan Perjalanan) untuk berhubung terus dengan pelayan Spotnana. Oleh itu, istilah caller akan digunakan sebagai istilah umum, sama ada untuk pengguna yang log masuk ke profil sendiri atau pengguna API/Mesin yang memohon token akses bagi pihak pengguna lain.

Rajah urutan berikut menerangkan bagaimana aliran pengesahan dikendalikan melalui pertukaran token antara pelayan Spotnana dan pelayan rakan kongsi.

Rajah: Rajah urutan yang menerangkan pengesahan berasaskan iFrame menggunakan pertukaran token.

Langkah	Aliran
Caller log masuk menggunakan Partner UI.
1	Partner UI memaparkan Spotnana UI melalui iFrame.
2	Spotnana UI menghantar permintaan kepada Partner UI melalui post message untuk mendapatkan token. Permintaan ini dihantar dengan `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI menghantar permintaan API ke pelayan rakan kongsi untuk mendapatkan token OAuth, lalu memulakan langkah seterusnya dalam aliran pengesahan.
3 a	Pelayan rakan kongsi memanggil pelayan Spotnana menggunakan kelayakan pengguna dan token subjek sebagai parameter. Pelayan Spotnana akan menyemak sama ada permintaan ini dihantar oleh pengguna API/Mesin.
3 b	Pelayan Spotnana memanggil pelayan rakan kongsi untuk mendapatkan emel subjek (iaitu, caller). Emel ini diambil dan dihantar semula ke pelayan Spotnana untuk mengenal pasti pengguna.
3 c	Maklum balas kepada permintaan API dari langkah 1 dihantar oleh pelayan Spotnana ke pelayan rakan kongsi yang mengandungi token akses dan token segar semula. Maklumat ini kemudiannya dihantar ke Partner UI.
4	Partner UI menghantar token kepada Spotnana UI melalui post message dengan `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI menghantar permintaan API ke pelayan Spotnana untuk menjana dan mendapatkan token bearer baharu. Token bearer dijana oleh pelayan Spotnana dan dikembalikan ke Spotnana UI. Nota: Kejayaan penciptaan token bearer menandakan pengguna telah disahkan dan boleh mengakses Spotnana.
6	Sebaik sahaja pengguna disahkan pada langkah 3, semua permintaan API seterusnya perlu mengandungi token bearer, `orgId`, dan `tmcId` dalam pengepala permintaan. Token bearer akan disemak dalam setiap permintaan API yang diterima dan maklum balas akan dihantar semula ke Spotnana UI.

Pengesahan Berasaskan Kod Kebenaran

Rajah urutan berikut menerangkan bagaimana aliran pengesahan dikendalikan menggunakan kod kebenaran.

Rajah: Rajah urutan yang menerangkan pengesahan berasaskan kod kebenaran.

Langkah	Aliran
1	Partner UI memanggil pelayan rakan kongsi untuk mendapatkan kod kebenaran bagi caller yang log masuk. Kod kebenaran ini diambil dan dihantar semula ke Partner UI.
2	Partner UI menghantar permintaan ke Spotnana UI menggunakan URL pengalihan khas yang mengandungi `tmcId` dan `authCode` sebagai parameter.
3	Spotnana UI membuat panggilan POST API ke pelayan Spotnana menggunakan `v2/auth/token/companies/<tmcId>(authCode)` titik akhir API.
3 a	Pelayan Spotnana menghantar permintaan ke pelayan rakan kongsi untuk mendapatkan `pid` pengguna menggunakan kod kebenaran. pid `pengguna diambil dan dihantar ke pelayan Spotnana.` 3 b
Token akses dan token segar semula dijana oleh pelayan Spotnana dan dihantar ke Spotnana UI.	4
Spotnana UI menghantar permintaan ke pelayan Spotnana menggunakan token akses dan token segar semula untuk menjana dan mendapatkan token bearer bagi akses.	Token bearer dijana dan dihantar ke Spotnana UI. Nota: Kejayaan penciptaan token bearer menandakan pengguna telah disahkan dan boleh mengakses Spotnana. 5
Sebaik sahaja pengguna disahkan pada langkah 4, semua permintaan API seterusnya perlu mengandungi token bearer,	orgId `, dan`tmcId `dalam pengepala permintaan.` Token bearer akan disemak dalam setiap permintaan API yang diterima dan maklum balas akan dihantar semula ke Spotnana UI. Nota:

Aliran pengesahan ini tidak boleh digunakan jika pentadbir TMC membenarkan lebih daripada satu pengguna menggunakan emel yang sama untuk log masuk. Pengesahan Mesin ke Mesin (M2M)

Kaedah pengesahan M2M sesuai digunakan apabila aliran pengesahan melibatkan aplikasi klien mengakses URL callback pihak ketiga untuk menjana

accessToken bagi pengguna. Rajah urutan berikut menerangkan aliran pengesahan M2M. Rajah:

Rajah urutan yang menerangkan aliran pengesahan M2M. Langkah

Aliran	Kunci awam untuk semua aplikasi yang digunakan dalam pengesahan akan diselaraskan antara pelayan Spotnana dan Spotnana IdP. Kunci ini akan digunakan kemudian untuk mengesahkan token akses dalam aliran pengesahan.
1
Pelayan rakan kongsi menghantar permintaan API ke	/oauth2/token(clientId,clientSecret) `di Spotnana IdP untuk menjana token bearer. Token bearer baharu ini akan dihantar semula ke pelayan rakan kongsi.` 2
Pelayan rakan kongsi menghantar permintaan API ke URL callback pihak ketiga untuk menjana token akses bagi pengguna.	Token akses ini dijana dan dihantar ke pelayan Spotnana. 3
Pelayan Spotnana menyemak tandatangan token akses menggunakan kunci awam yang telah diselaraskan sebelum ini. Ia juga menyemak	claim_id `untuk mengesahkan identiti rakan kongsi.` Token akses kemudiannya dihantar ke pelayan rakan kongsi untuk mengesahkan pengguna. ...