Latar Belakang

Anda dapat mengintegrasikan aplikasi yang dikembangkan sendiri dengan Identity as a Service (IDaaS) untuk menyinkronkan organisasi dan akun IDaaS ke dalam aplikasi tersebut.

Untuk informasi lebih lanjut tentang cara menyinkronkan akun aplikasi ke IDaaS, lihat Operasi API untuk pengembangan aplikasi.

Untuk informasi lebih lanjut tentang cara mengonfigurasi sinkronisasi aplikasi, lihat Sinkronkan akun IDaaS pada aplikasi dalam Provisioning. Topik ini menjelaskan cara mengintegrasikan aplikasi dengan IDaaS untuk menerapkan sinkronisasi akun.

• Konsistensi dependensi: Pihak terkait mungkin bergantung pada data identitas di aplikasi Anda untuk pemasaran atau verifikasi. Oleh karena itu, Anda harus segera menyinkronkan perubahan akun IDaaS. Sebagai contoh, ketika seorang karyawan baru masuk, akun dibuat di IDaaS. Untuk tetap sesuai jadwal, akun harus dibuat di aplikasi HR pada saat yang sama. Dalam hal ini, Anda dapat berlangganan ke acara Buat akun.

• Persyaratan real-time: Aplikasi Anda harus segera merespons operasi pengguna. Sebagai contoh, setelah pengguna masuk ke sistem dan mengubah nomor ponsel mereka, nomor ponsel pengguna harus diperbarui di aplikasi Anda menggunakan acara Perbarui akun.

Mekanisme Callback Acara

Contoh-contoh di atas adalah dua skenario sederhana. Berdasarkan persyaratan yang berbeda, pengembang dapat berlangganan berbagai acara untuk memproses data sesuai kebutuhan.

IDaaS menyediakan metode yang nyaman dan aman untuk menyinkronkan perubahan IDaaS ke aplikasi. Anda dapat dengan cepat mengintegrasikan aplikasi dengan IDaaS untuk memungkinkan aplikasi menerima permintaan sinkronisasi.

Metode ini diimplementasikan dengan menggunakan mekanisme callback acara.

Di IDaaS, Anda dapat mengonfigurasi acara yang ingin Anda ikuti (seperti acara Buat akun). Ketika acara terjadi, permintaan sinkronisasi secara otomatis dikirim ke pelanggan acara menggunakan HTTP POST.

Mekanisme acara terdiri dari dua bagian berikut:

• Berlangganan ke acara: Masuk ke Konsol IDaaS dan konfigurasikan acara IDaaS yang ingin Anda ikuti.

• Menerima callback acara: Pengembang harus mengintegrasikan aplikasi dengan IDaaS untuk menerapkan sinkronisasi akun sesuai kebutuhan.

Berlangganan ke Acara

Setelah Anda membuat aplikasi di IDaaS, klik Provisioning untuk mengonfigurasi sinkronisasi akun.

Untuk informasi lebih lanjut, lihat Sinkronkan akun IDaaS pada aplikasi dalam Provisioning.

Anda dapat berlangganan aplikasi ke satu atau lebih acara. Gambar berikut menunjukkan acara yang dapat Anda ikuti.

Ketika acara yang dipilih terjadi, IDaaS mengirim permintaan ke aplikasi.

Menerima Callback

Ketika acara yang dipilih terjadi, IDaaS mengirim permintaan POST ke URL untuk menerima permintaan sinkronisasi yang telah dikonfigurasi.

Kode berikut memberikan contoh tentang cara mengonfigurasi parameter permintaan:

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

// Contoh body dari permintaan POST dari IDaaS. Setelah aplikasi mendapatkan parameter, ia memverifikasi tanda tangan.
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Semua parameter dilewatkan dalam bidang event dalam format JSON Web Token (JWT), yang berisi tanda tangan. Untuk informasi lebih lanjut, lihat RFC 7515: JSON Web Signature (JWS).

Format Acara

Anda harus menggunakan alat open-source universal untuk berbagai bahasa untuk mengurai informasi JWT.

Untuk tujuan pengujian, Anda juga dapat menempelkan nilai dalam format JWT di bidang di https://jwt.io/ untuk melihat isi kontennya.

Nilai event terdiri dari dua bagian: 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":"ID instance",  // ID instance.
    "eventVersion":"V1.0",  // Nomor versi acara.
    "eventData":[
      {
        "eventId":"",     // ID acara.
        "eventType":"",   // Jenis acara.
        "eventTime":121313,  // Waktu terjadinya acara.
        "bizId":"ID bisnis",  // ID bisnis. Jika bisnis adalah organisasi, nilainya adalah ID organisasi.
        "bizData":{}       // Detail data spesifik. Nilai bidang ini bervariasi menurut jenis acara. Untuk informasi lebih lanjut, lihat acara buku alamat.
      }
    ]   
  }
}

Tabel berikut menjelaskan bidang yang terkandung.

Verifikasi Tanda Tangan

Tanda tangan JWT harus diverifikasi untuk memastikan bahwa informasi acara dikeluarkan oleh IDaaS. Verifikasi tanda tangan mencegah pemalsuan permintaan.

Di halaman sinkronisasi, Anda dapat memperoleh titik akhir kunci publik untuk memverifikasi tanda tangan JWT dan sumber acara yang dikirim ke aplikasi. Kami merekomendasikan Anda menggunakan toolkit JWT open-source dari bahasa pemrograman untuk verifikasi tanda tangan.

Dekripsi Data (opsional)

Transmisi data sinkronisasi acara yang dienkripsi didukung. Bidang yang dienkripsi dilewatkan dalam bidang cipher_data di payload.

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

Setelah Anda mengaktifkan fitur ini, Anda dapat memasukkan kunci enkripsi atau menghasilkan kunci enkripsi. Sebelum IDaaS mengirim permintaan callback acara, IDaaS menggunakan kunci ini untuk mengenkripsi semua data permintaan sebelum transmisi.

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

Aplikasi harus menggunakan kunci yang sama untuk dekripsi guna memperoleh data sinkronisasi.

Untuk informasi lebih lanjut, lihat Integrasi aplikasi untuk menerapkan sinkronisasi pengguna menggunakan Java.

Respons

Aplikasi harus mengembalikan hasil pemrosesan acara sesuai dengan spesifikasi IDaaS. IDaaS mencatat hasilnya dan memproses data berdasarkan informasi yang dikembalikan.

Respons sukses

Jika permintaan diproses, aplikasi harus mengembalikan eventId dan hasil dalam format berikut.

Contoh respons sukses

{
    "successEvents": [
        {
            "eventId": "ID acara",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "ID acara",
            "eventCode": "Kode kesalahan yang dikembalikan",
            "eventMessage": "Pesan kesalahan yang dikembalikan"
        }
    ],
    "failedEvents": [
        {
            "eventId": "ID acara",
            "eventCode": "Kode kesalahan yang dikembalikan",
            "eventMessage": "Pesan kesalahan yang dikembalikan"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "ID acara",
            "eventCode": "Kode kesalahan yang dikembalikan",
            "eventMessage": "Pesan kesalahan yang dikembalikan"
        }
    ]
}

Respons gagal

Jika pemrosesan gagal, aplikasi harus mengembalikan kode status HTTP 403, 429, atau 500.

Parameter berikut dikembalikan jika pemrosesan gagal.

Secara umum, kode kesalahan berikut dikembalikan.

Contoh respons kesalahan

{
     "error": "invalid_token",
     "error_description": "Token JWS tidak valid."
}