Integrasikan aplikasi untuk sinkronisasi akun - Identity as a Service

Identity as a Service (IDaaS) menggunakan mekanisme callback berbasis event untuk mendorong perubahan akun dan organisasi ke aplikasi Anda secara real time. Ketika suatu event yang telah Anda langganan terjadi—misalnya karyawan baru bergabung atau pengguna memperbarui nomor ponselnya—IDaaS mengirim permintaan HTTP POST ke titik akhir yang telah Anda konfigurasi, membawa data event dalam format JWT.

Ini merupakan dorongan asinkron: IDaaS mengirimkan event tersebut dan melanjutkan tanpa menunggu aplikasi Anda selesai memprosesnya. Segera kembalikan respons HTTP 200 setelah menerima permintaan, lalu proses event tersebut secara asinkron. Menunda respons hingga pemrosesan selesai merupakan penyebab paling umum timeout pengiriman dan upaya pengiriman ulang yang tidak perlu.

Untuk arah sebaliknya (menyinkronkan data dari aplikasi Anda ke IDaaS), lihat Operasi API untuk pengembangan aplikasi.

Cara kerja

Berlangganan satu atau beberapa event di Konsol IDaaS (misalnya, Create account, Update account, atau Delete account).
Ketika event yang telah dilanggankan terjadi, IDaaS mengirim permintaan HTTP POST ke URL for receiving synchronization requests yang telah Anda konfigurasi.
Aplikasi Anda mengurai muatan JWT, memverifikasi signature RS256, dan memproses data event tersebut.
Kembalikan respons HTTP 200 dalam waktu 10 detik. Jika IDaaS tidak menerima respons HTTP 200 dalam jangka waktu tersebut, sistem akan mencoba mengirim ulang hingga lima kali.

Berlangganan event

Masuk ke Konsol IDaaS, buka aplikasi Anda, lalu klik Provisioning untuk mengonfigurasi sinkronisasi akun.

Untuk detail konfigurasi, lihat Sinkronkan akun IDaaS pada aplikasi di Provisioning.

Pilih event yang ingin Anda lacak. Gambar berikut menunjukkan jenis event yang tersedia.

Menerima dan mengurai callback

Ketika event yang telah dilanggankan terjadi, IDaaS mengirim permintaan POST ke URL for receiving synchronization requests Anda. Semua data event dikodekan dalam bidang event sebagai JSON Web Token (JWT).

Contoh permintaan:

POST <your-endpoint-url>
Content-Type: application/json;charset=utf-8

{
  "event": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

JWT tersebut ditandatangani menggunakan RS256 dan disusun sesuai dengan RFC 7515 (JSON Web Signature). Uraikan token tersebut menggunakan pustaka JWT standar untuk bahasa pemrograman Anda. Untuk inspeksi cepat selama pengembangan, tempel nilai tersebut di jwt.io.

Format event

JWT terdiri dari header dan payload.

Contoh header:

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

Contoh payload:

{
  "iss": "urn:alibaba:idaas:app:event",
  "sub": "idaas-121313",
  "aud": "app_12131313",
  "exp": 1640966400,
  "iat": 1640966400,
  "jti": "cNetm9OD5bXqfVfdvqGMYw",
  "dataEncrypted": false,
  "cipherData": "",
  "plainData": {
    "aliUid": 1231313,
    "instanceId": "instance ID",
    "eventVersion": "V1.0",
    "eventData": [
      {
        "eventId": "",
        "eventType": "",
        "eventTime": 121313,
        "bizId": "business ID",
        "bizData": {}
      }
    ]
  }
}

Bidang header JWT

Field	Position	Type	Description
`alg`	header	String	Nilai tetap: `RS256`. Algoritma signature RSA SHA-256.
`kid`	header	String	ID pasangan kunci yang dikeluarkan oleh IDaaS. Gunakan kunci publik yang sesuai untuk memverifikasi signature. Pasangan kunci dapat diputar; pasangan kunci yang telah disinkronkan tetap tidak berubah.

Bidang payload JWT

Field	Position	Type	Description
`iss`	payload	String	Nilai tetap: `urn:alibaba:idaas:app:event`. Mengidentifikasi bahwa event berasal dari IDaaS.
`sub`	payload	String	ID instans IDaaS.
`aud`	payload	String	ID aplikasi IDaaS.
`exp`	payload	Long	Waktu kedaluwarsa event, dalam milidetik. Nilai default: 30 menit setelah `iat`. Jika waktu saat ini telah melewati `exp`, event dianggap kedaluwarsa.
`iat`	payload	Long	Waktu pembuatan event, dalam milidetik. Jika waktu saat ini sebelum `iat`, event dianggap tidak valid.
`data_encrypted`	payload	Boolean	Menentukan apakah data event dienkripsi.
`cipher_data`	payload	String	Teks sandi terenkripsi dari data event. Hanya tidak kosong jika `data_encrypted` bernilai `true`.
`plain_data`	payload	Object	Semua data event dalam teks biasa. Hanya tidak kosong jika `data_encrypted` bernilai `false`.

Bidang `plain_data`

Field	Description
`aliUid`	ID Akun Alibaba Cloud.
`instanceId`	ID instans IDaaS.
`eventVersion`	Nomor versi event.
`eventId`	ID event di IDaaS. Jika bidang ini tidak dikirim atau ID event yang tidak valid ditransmisikan, sistem akan memicu pengiriman ulang.
`eventType`	Jenis event.
`eventTime`	Waktu terjadinya event.
`bizId`	ID bisnis. Jika bisnis tersebut adalah organisasi, maka ini adalah ID organisasi.
`bizData`	Data spesifik event. Struktur berbeda-beda tergantung jenis event. Untuk detailnya, lihat event buku alamat.

Verifikasi signature

Verifikasi signature JWT untuk memastikan bahwa event tersebut berasal dari IDaaS. Hal ini mencegah pemalsuan permintaan.

Dapatkan public key endpoint dari halaman sinkronisasi di Konsol IDaaS.

Gunakan toolkit JWT open-source untuk bahasa pemrograman Anda guna memverifikasi signature RS256 terhadap kunci publik tersebut.

Dekripsi data event (opsional)

Jika Anda mengaktifkan enkripsi, IDaaS mengenkripsi data event menggunakan enkripsi simetris AES-256 dalam format JSON Web Encryption (JWE) sebelum mengirimkannya. Data terenkripsi tersebut berada di bidang cipher_data dalam payload.

{
    "cipher_data": "ZePq7ckODWnL54vqZc3kTw0vF7tjvIRZjqqy/gZm9oTEt71WMufD9swlmHzZkniSqyDGQpkmMRLCXz9gzRJ4BY2RroLUPQW8ZDPSfmJKEf2m2w6wY1twoRlnHLoFCVhravsvN0afBqmxd3eK5tHd05Ze6MLOXS3fqxqH61dGAm2mwecvAFPRrKVeg6JXBYUvA2Uu6dmCOP3y938kFdhodD13O05MBIqWghq569wYvVjKMFMcnsZqmGGKXN0vRFhg+SR16sr24b1X/gQDbNqyMDICB9k3QMe09dOodwNEwvgxbf1v4PbyCRX1P9UO74nDQaWROWZFplE7qP/JMy3pBr0pxW+hJS9u/Zpvj/hvLlhBTAZkmhAKDKxlrYztqrgJbr4VOUv8mlqxWjDK4I7VZugODJMSwi1HdjXL+wlMzPMOeH8rkDFU+b5VH3dsxg3hZ64Ukd7exB62QyyeIJpfk0d57xw8UACiSsXadexQYpJPDycVdmJ7FAmIhxbJ8I6w9Kcv9U5sKybUz1YA8tONAw=="
}

Untuk mengaktifkan enkripsi, buka halaman sinkronisasi di Konsol IDaaS. Masukkan kunci enkripsi atau hasilkan kunci baru.

Gunakan kunci yang sama untuk mendekripsi bidang cipher_data dan mengambil data event tersebut.

Untuk contoh implementasi lengkap, lihat Integrasikan aplikasi untuk mengimplementasikan sinkronisasi pengguna menggunakan Java.

Respons terhadap callback

Segera kembalikan respons HTTP 200 setelah menerima permintaan—jangan menunggu logika bisnis internal Anda selesai. Proses event tersebut secara asinkron setelah memberikan respons. Hal ini mencegah timeout dan menghindari pemicuan pengiriman ulang yang tidak perlu.

Penting

Jika IDaaS tidak menerima respons HTTP 200 dalam waktu 10 detik, IDaaS menganggap pengiriman gagal dan melakukan percobaan ulang hingga lima kali dengan interval masing-masing 1 detik, 5 detik, 10 detik, 10 detik, dan 10 detik.

Respons sukses

Kembalikan hasil pemrosesan untuk setiap event dalam format berikut:

Field	Type	Description
`successEvents`	Array	Event yang berhasil diproses.
`skippedEvents`	Array	Event yang sengaja dilewati. Misalnya, event `Delete account` untuk pengguna yang tidak ada di sistem Anda.
`failedEvents`	Array	Event yang gagal diproses.
`retriedEvents`	Array	Event yang akan dicoba ulang (hingga lima kali).
`eventId`	String	ID event IDaaS. Jika bidang ini tidak ada atau tidak valid, IDaaS akan memicu pengiriman ulang.
`eventCode`	String	Kode kesalahan kustom. IDaaS mencatat kode ini untuk troubleshooting.
`eventMessage`	String	Pesan kesalahan kustom. IDaaS mencatat pesan ini untuk troubleshooting.

Contoh respons sukses:

{
    "successEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ],
    "failedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ]
}

Respons gagal

Jika pemrosesan gagal, kembalikan respons HTTP 403, 429, atau 500 dengan isi badan berikut:

Field	Type	Description
`error`	String	Kode kesalahan.
`error_description`	String	Pesan kesalahan.

Error code	HTTP status	Description
`invalid_token`	403	Token JWS tidak valid.
`too_many_request`	429	Layanan sedang sibuk. IDaaS menerapkan pembatasan kecepatan.
`internal_error`	500	Terjadi kesalahan internal. IDaaS secara otomatis mencoba mengirim ulang.

Contoh respons gagal:

{
    "error": "invalid_token",
    "error_description": "The JWS token is invalid."
}

Langkah selanjutnya

Sinkronkan akun IDaaS pada aplikasi di Provisioning — Konfigurasikan event mana yang memicu callback dan atur URL titik akhir Anda.
Integrasikan aplikasi untuk mengimplementasikan sinkronisasi pengguna menggunakan Java — Implementasi lengkap dalam Java yang mencakup verifikasi signature, dekripsi, dan penanganan respons.
Operasi API untuk pengembangan aplikasi — Sinkronkan data dari aplikasi Anda ke IDaaS.