Autentikasi pengguna akhir

Contact Center AI Platform menggunakan autentikasi pengguna akhir untuk mengidentifikasi secara aman orang yang menggunakan aplikasi host Anda. Mekanisme ini memastikan bahwa hanya pengguna yang berwenang yang dapat mengakses API CCAI Platform dan sesi chat serta data mereka tetap terikat secara aman dengan identitas spesifik mereka.

Untuk mengidentifikasi pengguna akhir, aplikasi host Anda harus memberikan ID unik universal (UUID) yang mewakili orang tertentu tersebut.

Penting: Jangan gunakan alamat email sebagai ID. Alamat email dapat berubah dan mungkin tidak unik. Penggunaan UUID memastikan Platform CCAI melacak dan membedakan pengguna akhir secara akurat, meskipun informasi kontak mereka berubah seiring waktu.

Cara kerja autentikasi di CCAI Platform

Autentikasi di CCAI Platform mengandalkan handshake yang aman menggunakan Token Web JSON (JWT). JWT adalah standar terbuka yang digunakan untuk mentransmisikan informasi dengan aman sebagai objek JSON.

Berikut adalah alur autentikasi standar:

1. Permintaan: Saat pengguna akhir mulai menggunakan layanan pelanggan CCAI Platform, CCAI Platform SDK akan meminta JWT bertanda tangan dari aplikasi host Anda.

2. Tanda tangan: Aplikasi host Anda menandatangani JWT menggunakan secret perusahaan CCAI Platform bersama Anda (company_secret).

3. Penukaran: Aplikasi host meneruskan JWT yang ditandatangani kembali ke CCAI Platform SDK. Kemudian, SDK mengirimkan JWT ini ke server Platform CCAI.

4. Verifikasi: Server CCAI Platform memverifikasi tanda tangan. Jika valid, Platform CCAI akan mengeluarkan token autentikasi, memberikan akses API kepada pengguna, dan mengaitkannya dengan akunnya (atau membuat akun baru jika belum ada).

Jika aplikasi host Anda tidak memberikan ID dalam payload JWT, Platform CCAI akan membuat akun tamu anonim untuk pengguna.

Prasyarat

Sebelum menerapkan autentikasi, Anda memerlukan elemen autentikasi SDK unik. Kredensial ini mengidentifikasi perusahaan Anda dengan aman ke CCAI Platform API.

1. Login ke Platform CCAI dengan akun administrator.

2. Buka Settings > Developer Settings > API Credentials.

3. Temukan nama kunci SDK (sdk_key_name), kunci SDK (sdk_key), dan secret perusahaan (company_secret).

Jaga keamanan kredensial ini. Hanya bagikan kepada sistem dan developer yang berwenang.

Panduan penerapan developer

Bagian berikut menguraikan cara developer harus membuat payload JWT dan menginisialisasi CCAI Platform SDK di berbagai platform.

Persyaratan payload JWT

Untuk meneruskan informasi pengguna akhir ke Platform CCAI, aplikasi host Anda harus membuat payload JWT. Metode callback menyediakan payload default (yang dapat mencakup token push dan nama default), tetapi Anda dapat menambahkan detail pengguna tertentu menggunakan kunci yang dicadangkan berikut:

• identifier (UUID opsional, tetapi sangat direkomendasikan)

• name (opsional)

• email (opsional)

• phone (opsional, harus menggunakan format E.164)

• iss (opsional, nama perusahaan Anda)

• iat (wajib ada, diterbitkan saat stempel waktu)

• exp (wajib, stempel waktu habis masa berlaku)

Penandatanganan sisi server (direkomendasikan)

Penting: Sebaiknya tandatangani payload di server Anda. Tindakan ini menjaga company_secret Anda tetap tersembunyi dari sisi klien, sehingga mencegah akses yang tidak sah. Jika disusupi, Anda dapat mencabut rahasia tersebut. Di lingkungan produksi, Anda juga harus memastikan bahwa algoritma penandatanganan JWT yang digunakan sesuai dengan kebutuhan keamanan Anda.

Contoh API di server (Ruby on Rails)

Contoh ini menunjukkan cara menandatangani payload di sisi server menggunakan framework Ruby on Rails dengan JWT gem.

Kode menyiapkan endpoint API (/api/ujet/sign) menggunakan gem jwt untuk mengenkode payload dengan rahasia perusahaan dan menampilkan token yang dienkode ke klien.

Misalkan URL dasar aplikasi host Anda adalah https://company.com/api/. Untuk menandatangani payload untuk Platform CCAI, Anda dapat menambahkan endpoint API lain di https://company.com/api/ujet/sign.

Kode ini menambahkan rute baru ke file rute aplikasi untuk menangani permintaan POST ke URL /api/ujet/sign.

File ujet_controller.rb menentukan class UjetController, yang memiliki satu endpoint, sign, yang digunakan untuk menandatangani payload untuk Platform CCAI.

Dalam kode, COMPANY_SECRET ditentukan sebagai secret yang digunakan untuk menandatangani payload. Payload diekstrak dari isi permintaan, lalu berbagai nilai ditambahkan ke dalamnya, misalnya, UNIQUE-IDENTIFIER, nama pengguna, email, telepon.

Metode JWT.encode digunakan untuk mengenkode payload dan ujet_secret ke dalam Token Web JSON (JWT), yang kemudian ditampilkan dalam respons sebagai objek JSON dengan kunci token.

# routes.rb
post 'ujet/sign' => "ujet#sign"

# ujet_controller.rb
class UjetController
  def sign
    # In production, securely store and call your secret (e.g., via environment variables)
    ujet_secret = "COMPANY_SECRET"

    payload = body["payload"]
    payload["identifier"] = "UNIQUE-IDENTIFIER"
    payload["name"] = "user name"
    payload["email"] = "[e-mail]"
    payload["phone"] = ""                     # E.164 format
    payload["iss"] = "YOUR_COMPANY_NAME"
    payload["iat"] = Time.now.to_i
    payload["exp"] = Time.now.to_i + 10.minutes # Valid for 10 minutes

    token = JWT.encode(payload, ujet_secret)

    render json: {token: token}
  end
end

Inisialisasi sisi klien

Ikuti panduan ini untuk melakukan inisialisasi SDK seluler Platform CCAI.

Penandatanganan dari iOS SDK

Contoh penandatanganan payload dari iOS SDK ini membuat permintaan POST ke server di URL https://your.company.com/api/ujet/sign dengan payload sebagai isi permintaan.

Server diharapkan menampilkan token bertanda tangan sebagai respons, yang kemudian diteruskan ke callback keberhasilan dalam bentuk kunci "token" dalam objek JSON.

Jika terjadi error selama permintaan, error tersebut akan diteruskan ke callback kegagalan.

-   (void)signPayload:(NSDictionary *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success failure:(void (^)(NSError *))failure
{
  if (payloadType == UjetPayloadAuthToken) {
    NSURLSessionConfiguration *sessionConfiguration = [NSURLSessionConfiguration defaultSessionConfiguration];
    NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfiguration];

    NSMutableURLRequest *mutableRequest = [[NSMutableURLRequest alloc] init];
    mutableRequest.URL = [NSURL URLWithString:@"https://your.company.com/api/ujet/sign"];
    mutableRequest.HTTPMethod = @"POST";
    NSError *error;
    NSDictionary *data = @{@"payload": payload};
    mutableRequest.HTTPBody = [NSJSONSerialization dataWithJSONObject:data options:0 error:&error];

    NSURLSessionDataTask *task = [session dataTaskWithRequest:mutableRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if(error) {
            failure(error);
        }
        else {
            NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
            success(json[@"token"]);
        }
    }];

    [task resume];
  }
}

Penandatanganan dari Android SDK

Berikut adalah contoh penandatanganan payload dari Android SDK.

Contoh ini menggunakan Retrofit, klien HTTP untuk Android, untuk meminta payload bertanda tangan dari server Anda. Fungsi ini menggunakan payload, jenis payload, dan callback token sebagai input.

Jika jenis payload adalah UjetPayloadType.AuthToken, payload akan membuat instance Retrofit, menggunakannya untuk membuat permintaan ke endpoint API https://company.com/api guna menandatangani payload, dan menampilkan token yang ditandatangani dalam metode onToken instance tokenCallback.

Jika gagal, pesan toast "Authentication failed" akan ditampilkan.

public void onSignPayloadRequest(Map<String, Object> payload, UjetPayloadType ujetPayloadType, final UjetTokenCallback tokenCallback) {
    if (ujetPayloadType == UjetPayloadType.AuthToken) {
        Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("https://company.com/api/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();

        AuthService authService = retrofit.create(AuthService.class);
        Call<AuthToken> authenticate = authService.authenticate(new AuthRequest(payload));
        authenticate.enqueue(new Callback<AuthToken>() {
            @Override
            public void onResponse(Call<AuthToken> call, Response<AuthToken> response) {
                if (response.isSuccessful()) {
                    AuthToken authToken = response.body();
                    tokenCallback.onToken(authToken.getToken());
                } else {
                    Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
                }
            }

            @Override
            public void onFailure(Call<AuthToken> call, Throwable t) {
                Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
            }
        });
    }
}

Penandatanganan dari Web SDK

Contoh berikut menunjukkan cara menandatangani payload di Web SDK dengan membuat permintaan API ke server dengan payload.

Server harus disiapkan untuk menangani permintaan API dan menandatangani payload menggunakan metode yang aman. Hasilnya kemudian ditampilkan ke halaman web, yang meneruskan token yang ditandatangani kembali ke Platform CCAI menggunakan fungsi callback.

$(function() {
  UJET.initialize({
    // ... other parameters
    handlers: {
      authentication(callback) {
        $.ajax({
          type: 'POST',
          url: 'https://company.com/api/ujet/sign',
          data: JSON.stringify({
            payload: {
              identifier: 'UNIQUE-Identifier',
              name: 'Test user'
            }
          }),
          success: function(result) {
            callback({
              token: result.token,
              user: {
                identifier: 'UNIQUE-IDENTIFIER',
                name: 'Test user'
              }
            });
          }
        });
      }
    }
  }).then(function() {
    // successfully initialized
  }).catch(function(error) {
    // Handle initialization error
  });
});

Autentikasi di tengah sesi dan inisialisasi ulang SDK

Dalam beberapa kasus, pengguna akhir dapat memulai sesi chat sebagai tamu (tidak diautentikasi) dan memverifikasi identitasnya di tengah sesi (misalnya, melalui asisten virtual atau layar login di tengah alur). Untuk memastikan sesi aktif diperbarui dan dikaitkan dengan pengguna yang baru diautentikasi secara aman, ikuti langkah-langkah berikut:

Langkah-langkah untuk autentikasi di tengah sesi

1. Menginisialisasi SDK dengan ID sementara: Saat pengguna tidak diautentikasi, inisialisasi CCAI Platform SDK menggunakan ID tamu atau acak.

2. Mengarahkan pengguna untuk melakukan autentikasi: Pandu pengguna ke alur autentikasi Anda, seperti asisten virtual (VA) Platform CCAI atau layar login bawaan aplikasi Anda.

3. Memperbarui pengguna akhir melalui API: Setelah pengguna berhasil diautentikasi (dan saat mereka masih berada dalam alur autentikasi atau agen virtual), backend Anda harus memanggil CCAI Platform Apps API untuk memperbarui sesi chat pengguna akhir dengan ID sebenarnya.

4. Menginisialisasi ulang SDK dengan JWT baru: Setelah pembaruan backend berhasil, buat JWT baru untuk pengguna terautentikasi. Lakukan inisialisasi ulang CCAI Platform SDK dengan memanggil metode inisialisasi lagi dengan JWT baru ini.

5. Mengirimkan sesi ke tingkat yang lebih tinggi (jika menggunakan VA): Jika pengguna melakukan autentikasi menggunakan asisten virtual, agen virtual kini harus mengirimkan konsumen ke antrean tujuan akhir mereka.

Contoh (Web SDK)

Untuk melakukan inisialisasi ulang, panggil fungsi UJET.initialize lagi. Tindakan ini akan memicu pengendali autentikasi untuk mengambil token baru.

// Call this after successful authentication and the CCAI Platform Apps API update
UJET.initialize({
  // ...include your existing parameters
  handlers: {
    authentication(callback) {
      // Fetch the new JWT for the newly authenticated user
      $.ajax({
        type: 'POST',
        url: 'https://your.company.com/api/ujet/sign',
        data: JSON.stringify({
          payload: {
            identifier: 'AUTHENTICATED-USER-UUID',
            name: 'Authenticated User Name'
          }
        }),
        success: function(result) {
          callback({
            token: result.token,
            user: {
              identifier: 'AUTHENTICATED-USER-UUID',
              name: 'Authenticated User Name'
            }
          });
        }
      });
    }
  }
}).then(function() {
  // SDK successfully reinitialized with the authenticated user
}).catch(function(error) {
  // Handle reinitialization errors
});

Mengapa ini perlu?

• Hal ini memastikan semua tindakan, perutean, dan histori berikutnya dikaitkan dengan aman ke pengguna terautentikasi, bukan sesi tamu anonim.

• Fitur ini mencegah kebocoran data dan mempertahankan catatan CRM dan pengguna yang akurat.

Tabel ringkasan

Skenario	Tindakan diperlukan
Pengguna memulai autentikasi	Lakukan inisialisasi SDK dengan JWT dan UUID sebenarnya pengguna.
Pengguna memulai tanpa autentikasi	Menginisialisasi SDK dengan ID tamu/acak.
Pengguna melakukan autentikasi di tengah sesi	Perbarui Platform CCAI dengan API, buat JWT baru, dan inisialisasi ulang SDK.