Identity as a Service:Ikhtisar integrasi sinkronisasi akun

Latar Belakang

Identity as a Service (IDaaS) mendukung integrasi dengan aplikasi kustom untuk menyinkronkan organisasi dan akun dari IDaaS ke aplikasi Anda. Untuk menyinkronkan akun dari aplikasi Anda ke IDaaS, lihat Referensi API untuk pengembangan aplikasi.

Untuk informasi tentang konfigurasi sinkronisasi aplikasi, lihat Sinkronisasi Akun – Sinkronkan dari IDaaS ke Aplikasi. Topik ini menjelaskan cara mengintegrasikan aplikasi untuk sinkronisasi akun sesuai spesifikasi IDaaS.

• Perubahan akun harus disinkronkan dari IDaaS secara tepat waktu. Misalnya, saat onboarding karyawan, akun dibuat di IDaaS. Aplikasi HR harus membuat akun yang sesuai hampir secara bersamaan untuk mencegah penundaan dalam proses onboarding. Untuk mencapai hal ini, berlangganan event Create account.

• Aplikasi Anda perlu merespons tindakan pengguna secara cepat. Misalnya, jika pengguna memperbarui nomor ponselnya setelah login, aplikasi Anda harus segera mencerminkan perubahan tersebut. Untuk melakukannya, berlangganan event Update account.

Mekanisme callback event

Contoh sebelumnya merupakan dua kasus penggunaan sederhana. Anda dapat berlangganan berbagai event dan menanganinya sesuai kebutuhan spesifik Anda.

IDaaS menyediakan metode standar, aman, dan praktis untuk menyinkronkan data ke aplikasi Anda. Metode ini memungkinkan aplikasi Anda menerima permintaan sinkronisasi dengan konfigurasi minimal.

Sistem ini dibangun di atas mekanisme callback event.

Di IDaaS, Anda mengonfigurasi event yang ingin dipantau, seperti pembuatan akun. Ketika event tertentu terjadi, IDaaS secara otomatis mengirim permintaan HTTP POST ke subscriber event.

Proses ini terdiri dari dua bagian utama:

• Berlangganan event: Konfigurasikan event yang ingin Anda pantau di Konsol IDaaS.

• Menerima event: Kembangkan aplikasi Anda untuk menangani data event masuk sesuai spesifikasi.

Berlangganan event

Setelah membuat aplikasi di IDaaS, buka menu Provisioning untuk mengonfigurasi sinkronisasi akun untuk aplikasi tersebut.

Untuk langkah-langkah konfigurasi detail, lihat Sinkronkan dari IDaaS ke aplikasi – SCIM.

Dalam konfigurasi event callback, Anda dapat memilih event yang ingin diikuti oleh aplikasi Anda. Ketika event yang diikuti terjadi, IDaaS mengirim permintaan ke aplikasi Anda.

Menerima callback

Saat suatu event terjadi, IDaaS mengirimkan permintaan POST ke URL for receiving synchronization requests yang telah dikonfigurasi.

Kode berikut menunjukkan contoh permintaan:

Content-Type: application/json;charset=utf-8

// Contoh isi badan permintaan POST dari IDaaS. Aplikasi Anda memverifikasi signature setelah menerima parameter.
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Semua parameter dikirimkan dalam bidang event. Nilai bidang ini adalah JSON Web Token (JWT) yang ditandatangani, sebagaimana ditentukan dalam RFC 7515 JWS.

Format event

Anda harus menggunakan library open-source standar untuk bahasa pemrograman Anda guna mengurai JWT.

Untuk tujuan pengujian, Anda dapat menempelkan nilai JWT ke alat seperti https://jwt.io/ untuk memeriksa isinya.

Nilai event 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,  // ID Akun Alibaba Cloud.
    "instanceId":"Instance ID",  // ID instans.
    "eventVersion":"V1.0",  // Versi event.
    "eventData":[
      {
        "eventId":"",     // ID event.
        "eventType":"",   // Jenis event.
        "eventTime":121313,  // Waktu terjadinya event.
        "bizId":"Business data ID",  // ID data bisnis. Untuk organisasi, ini adalah ID organisasi.
        "bizData":{}       // Data detail. Bidang ini bervariasi tergantung jenis event. Untuk informasi lebih lanjut, lihat referensi event Buku alamat.
      }
    ]   
  }
}

Tabel berikut menjelaskan bidang-bidang dalam event.

Verifikasi signature

Pertama, verifikasi signature JWT untuk memastikan bahwa event dikeluarkan oleh IDaaS. Jika Anda melewatkan verifikasi ini, pihak jahat dapat memalsukan permintaan tersebut.

Anda dapat memperoleh informasi kunci publik yang digunakan untuk memverifikasi signature JWT dari Public Key Endpoint di menu sinkronisasi, dan menggunakannya untuk memverifikasi bahwa konten event yang dikirim ke aplikasi Anda berasal dari sumber yang valid. Kami menyarankan Anda menggunakan toolkit JWT open-source untuk bahasa pengembangan Anda guna melakukan verifikasi signature.

Dekripsi data (opsional)

IDaaS mendukung transmisi data event yang dienkripsi. Saat diaktifkan, data terenkripsi dikirimkan dalam bidang cipherData pada payload.

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

Setelah mengaktifkan fitur ini, Anda dapat menyediakan kunci enkripsi sendiri atau meminta IDaaS menghasilkannya untuk Anda. Sebelum mengirim callback event, IDaaS menggunakan kunci ini untuk mengenkripsi seluruh data permintaan.

IDaaS menggunakan algoritma enkripsi simetris AES-256 dan format JSON Web Encryption (JWE) untuk mengenkripsi event.

Aplikasi Anda harus menggunakan kunci yang sama untuk mendekripsi data tersebut.

Untuk contoh pengembangan, lihat Contoh integrasi aplikasi Java untuk sinkronisasi akun.

Format respons

Aplikasi Anda harus mengembalikan hasil pemrosesan event sesuai spesifikasi IDaaS. IDaaS mencatat hasil ini dan bertindak berdasarkan informasi yang dikembalikan.

Respons sukses

Jika permintaan diproses berhasil, Anda harus mengembalikan kode status HTTP 200 dan badan respons yang mencakup eventId serta hasil pemrosesan. Formatnya sebagai berikut:

Contoh respons sukses:

{
    "successEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "A skip code",
            "eventMessage": "A skip message"
        }
    ],
    "failedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ]
}

Respons gagal

Jika pemrosesan gagal, Anda harus mengembalikan kode status HTTP dalam rentang 4xx atau 5xx.

Parameter yang harus dikembalikan dalam badan respons untuk kegagalan adalah sebagai berikut:

Kami menyarankan Anda menggunakan kode kesalahan berikut untuk skenario kegagalan umum:

Contoh respons gagal:

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