Autentikasi pengguna akhir SDK

Proses autentikasi pengguna akhir di Contact Center AI Platform (CCAI Platform) adalah metode aman untuk mengidentifikasi pengguna yang menggunakan aplikasi host. Pengguna akhir diidentifikasi oleh ID Unik Universal (UUID) yang disediakan oleh aplikasi host. CCAI Platform SDK meminta Token Web JSON (JWT) yang ditandatangani oleh kunci rahasia bersama (company_secret) dan disediakan oleh aplikasi host setiap kali autentikasi diperlukan. Jika aplikasi host menyediakan JWT, CCAI Platform SDK akan memulai proses autentikasi dan mendapatkan token autentikasi.

Catatan: Untuk konteks, CCAI Platform SDK mencakup SDK web, seluler, dan tanpa UI.

Pengguna akhir

Pengguna akhir dalam konteks ini mengacu pada pengguna aplikasi host.

Untuk mengidentifikasi pengguna akhir, CCAI Platform menggunakan ID yang disediakan oleh aplikasi host. ID ini harus berupa ID Unik Universal (UUID) yang unik untuk setiap pengguna.

**Penting:** ID tidak boleh berupa alamat email, karena alamat email dapat berubah dan mungkin tidak unik untuk setiap pengguna.

Penggunaan UUID membantu memastikan bahwa pengguna akhir dapat diidentifikasi dan dibedakan secara akurat dari pengguna lain, meskipun alamat emailnya berubah.

Mengautentikasi dengan CCAI Platform

Token Web JSON (JWT) digunakan untuk mengidentifikasi pengguna atau aplikasi yang membuat permintaan ke CCAI Platform secara aman. Aplikasi host bertanggung jawab untuk menyediakan JWT ke CCAI Platform SDK melalui callback. CCAI Platform SDK meminta aplikasi host untuk menyediakan JWT menggunakan kunci SDK bersama (sdk_key) setiap kali autentikasi diperlukan.

Jika aplikasi host menyediakan JWT ke CCAI Platform SDK melalui callback, CCAI Platform SDK akan mulai mengautentikasi ke CCAI Platform dan mendapatkan token autentikasi.

Payload JWT dapat menyertakan informasi seperti ID pengguna, alamat email, nama, dan nomor telepon. Google Cloud merekomendasikan penggunaan format E.164untuk nomor telepon. Informasi ini digunakan untuk membuat akun baru bagi pengguna atau mengaitkan pengguna dengan akun yang ada di CCAI Platform.

Jika aplikasi host menyediakan ID dalam payload JWT, CCAI Platform akan menggunakan ID tersebut untuk membuat atau mengaitkan pengguna dengan akun. Jika ID tidak disediakan, CCAI Platform akan membuat akun anonim untuk pengguna.

Untuk mengetahui informasi selengkapnya tentang penandatanganan JWT ke CCAI Platform, lihat bagian Penandatanganan JWT.

Mengelola Kunci SDK

Kolom sdk_key_name dan sdk_key adalah elemen autentikasi penting. Kolom ini mengidentifikasi perusahaan Anda secara unik dan digunakan untuk mengakses CCAI Platform API secara aman.

Untuk mengelola kunci SDK, ikuti langkah-langkah berikut:

1. Login ke portal CCAI Platform sebagai pengguna dengan peran administrator.

2. Di portal CCAI Platform, klik Setelan > Setelan Developer. Jika Anda tidak melihat menu Setelan, klik Menu.

3. Buka panel Kunci Perusahaan &Kode Rahasia untuk mengelola kunci SDK, yang digunakan untuk membuat token autentikasi.

Anda harus menjaga keamanan kode ini dan hanya membagikannya kepada individu atau sistem yang berwenang yang memerlukan akses ke CCAI Platform API. Akses tidak sah ke kode ini dapat membahayakan keamanan data dan sistem Anda.

Alur kerja autentikasi

Berikut alur kerja autentikasi:

1. CCAI Platform menyediakan Nama Kunci SDK (sdk_key_name) dan Kunci SDK (sdk_key) ke aplikasi host. Keduanya dapat ditemukan di Setelan > Setelan Developer > Kunci SDK.

2. Saat pengguna akhir mulai menggunakan layanan pelanggan CCAI Platform, CCAI Platform SDK akan meminta penandatanganan JWT dari aplikasi host.

3. CCAI Platform memverifikasi JWT yang ditandatangani dan menerbitkan token autentikasi pengguna akhir. Proses ini memastikan autentikasi yang aman dan lancar antara aplikasi host dan layanan pelanggan CCAI Platform.

Penandatanganan JWT

Aplikasi host harus menerapkan metode callback untuk setiap platform. Bagian berikut memberikan petunjuk untuk setiap platform.

Untuk menangani informasi pengguna akhir, aplikasi host harus mengisi payload JWT. Payload default disediakan melalui metode callback dan mungkin sudah berisi beberapa nilai seperti token push dan nama default.

Aplikasi host dapat menambahkan informasi selengkapnya tentang pengguna dengan menggunakan nama kunci yang dicadangkan seperti berikut:

• identifier (opsional)

• name (opsional)

• email (opsional)

• phone number (opsional, format E.164)

Misalnya, untuk iOS SDK, penerapan metode dapat terlihat seperti berikut untuk tujuan pengujian (menggunakan JWT):

- (void)signPayload:(NSDictionry *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success ailure:(void (^)(NSError *))failure
{
  if (payloadType == UjetPayloadAuthToken) {
    @try {
        NSString *companySecre = @"COMPANY_SECRET";
        NSMutableDictionary *pyloadData = [payload mutableCopy];
        payloadData[@"identifir"] = @"UNIQUE-IDENTIFIER"; // optional
        payloadData[@"name"] =@"user name";            // optional
        payloadData[@"email"]  @"[e-mail]";      // optional
        payloadData[@"phone"]  @"";                    // optional, E.164 format 
        payloadData[@"iss"] = "YOUR_COMPANY_NAME";     // optional
        payloadData[@"iat"] = NSNumber numberWithDouble:[[NSDate date] timeIntervalSince1970]; // required
        payloadData[@"exp"] = NSNumber numberWithDouble:([[NSDate date] timeIntervalSince1970]+ 600)]; // required

        id<JWTAlgorithm> algorthm = [JWTAlgorithmFactory algorithmByName:@"HS256"];
        NSString *signedToken  [JWTBuilder encodePayload:payload].secret(companySecret).algorithm(algorithm).ecode;
        success(signedToken);
    }
    @catch (NSError *error) {
        failure(error);
    }
  }
}

Contoh untuk produksi

Google Cloud merekomendasikan penandatanganan payload di sisi server untuk meningkatkan keamanan. Dengan demikian, rahasia perusahaan tidak diekspos di sisi klien dan dapat dicabut kapan saja jika dianggap berisiko. Pendekatan ini menawarkan keamanan yang lebih baik dibandingkan dengan menandatangani payload di sisi klien.

Cuplikan kode berikut memberikan contoh untuk menandatangani payload di sisi server menggunakan framework Ruby on Rails dengan gem JWT dan di sisi klien menggunakan iOS SDK, Android SDK, dan Web SDK.

Di sisi server, kode menyiapkan endpoint API untuk menandatangani payload, menggunakan gem JWT untuk mengenkode payload dengan rahasia perusahaan dan menampilkan token yang dienkode ke klien.

Di sisi klien, kode memberikan contoh untuk membuat permintaan ke API server dari iOS SDK, Android SDK, dan Web SDK untuk mengambil token yang ditandatangani.

Di iOS SDK dan Android SDK, kode membuat permintaan POST HTTP ke API dan mengambil token dari respons. Di Web SDK, kode menerapkan pengendali autentikasi yang membuat permintaan AJAX ke API dan meneruskan token yang diambil serta informasi pengguna ke fungsi inisialisasi CCAI Platform.

Contoh API di server

Kode di bagian ini ditulis dalam Ruby dan menggunakan framework Rails.

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

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

File ccaip_controller.rb menentukan class CCAIPController, yang memiliki satu endpoint bernama sign. Endpoint tersebut digunakan untuk menandatangani payload untuk CCAI Platform.

Dalam kode, COMPANY_SECRET ditentukan sebagai rahasia yang digunakan untuk menandatangani payload. Payload diekstrak dari isi permintaan, lalu berbagai nilai ditambahkan ke payload, misalnya, UNIQUE-IDENTIFIER, username, email, dan phone.

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

Catatan: Dalam lingkungan produksi, Anda harus mengambil langkah-langkah untuk mengamankan rahasia perusahaan dan memastikan bahwa algoritma penandatanganan JWT yang digunakan sesuai dengan kebutuhan keamanan Anda.

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

# ccaip_controller.rb
class CCAIPController
  def sign
    ccaip_secret = "COMPANY_SECRET"

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

    token = JWT.encode(payload, ccaip_secret)

    render json: {token: token}
  end
end

Penandatanganan dari iOS SDK

Berikut adalah contoh penandatanganan payload dari iOS SDK.

Kode ini membuat permintaan POST ke server di URL https://your.company.com/api/ccaip/sign dengan payload sebagai isi permintaan. Server diharapkan menampilkan token yang ditandatangani 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/ccaip/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.

Ini adalah penerapan fungsi Android SDK untuk menandatangani payload menggunakan Retrofit, klien HTTP untuk Android. Fungsi ini menggunakan payload, jenis payload, dan callback token sebagai input. Jika jenis payload adalah UjetPayloadType.AuthToken, fungsi ini akan membuat instance Retrofit dan menggunakannya untuk membuat permintaan ke endpoint API https://company.com/api untuk menandatangani payload. Fungsi ini menampilkan token yang ditandatangani dalam metode onToken dari instance tokenCallback. Jika terjadi kegagalan, fungsi ini akan menampilkan pesan toast "Authentication failed".

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 CCAI Platform menggunakan fungsi callback.

$(function() {
  UJET.initialize({
    ... // other parameters
    handlers: {
      authentication(callback) {
        // YOU SHOULD HAVE THIS KIND OF API ON YOUR SERVER
        $.ajax({
          type: 'POST',
          url: 'http://company.com/api/ccaip/sign',
          data: JSON.stringify({
            payload: {
              identifier: 'UNIQUE-Identifier',
              name: 'Test user'
            }
          }),
          success: function(result) {
            // YOU SHOULD CALL `callback` FUNCTION TO RESPONSE THE AUTHENTICATION REQUEST
            callback({
              token: result.token,
              user: {
                identifier: 'UNIQUE-IDENTIFIER',
                name: 'Test user'
              }
            });
          }
        });
      }
    }
  }).then(function() {
    // successfully initialized
  }).catch(function(error) {
    // HANDLE INITIALIZATION ERROR
    // you can handle an error occurred during initialization
  });
});

Pertukaran token autentikasi

Di CCAI Platform, aplikasi host menggunakan JWT (Token Web JSON) untuk menandatangani token autentikasi pengguna akhir, yang kemudian ditukar dengan token autentikasi pengguna akhir. JWT adalah standar terbuka untuk mengirimkan informasi secara aman sebagai objek JSON.

Token autentikasi pengguna akhir digunakan untuk mengakses CCAI Platform API. Mekanisme ini membantu mengamankan proses autentikasi dan memastikan bahwa hanya pengguna yang diizinkan yang memiliki akses ke API.