Autentikasi pengguna akhir SDK

Proses autentikasi pengguna akhir di Contact Center AI Platform (CCAI Platform) adalah metode yang 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: Sebagai konteks, CCAI Platform SDK mencakup SDK web, seluler, dan tanpa antarmuka.

Pengguna akhir

Pengguna akhir dalam konteks ini mengacu pada pengguna aplikasi host.

Untuk mengidentifikasi pengguna akhir, Platform CCAI 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 secara akurat dan dibedakan dari pengguna lain, meskipun alamat emailnya berubah.

Melakukan autentikasi dengan CCAI Platform

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

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

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

Jika aplikasi host memberikan ID di payload JWT, Platform CCAI menggunakan ID tersebut untuk membuat atau mengaitkan pengguna dengan akun. Jika ID tidak diberikan, Platform CCAI akan membuat akun anonim untuk pengguna.

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

Mengelola Kunci SDK Anda

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

Untuk mengelola kunci SDK Anda, ikuti langkah-langkah berikut:

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

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

3. Buka panel Kunci Perusahaan & Kode Rahasia untuk mengelola kunci SDK Anda, 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. Kunci ini dapat ditemukan di Setelan > Setelan Developer > Kunci SDK.

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

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

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 perlu mengisi payload JWT. Payload default disediakan melalui metode callback dan dapat sudah berisi beberapa nilai seperti token push dan nama default.

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

• ID (opsional)

• nama (opsional)

• email (opsional)

• nomor telepon (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 keamanan tambahan. Dengan begitu, secret perusahaan tidak diekspos di sisi klien dan dapat dibatalkan 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 mengimplementasikan handler autentikasi yang membuat permintaan AJAX ke API dan meneruskan token dan informasi pengguna yang diambil ke fungsi inisialisasi Platform CCAI.

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 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 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, dan telepon.

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 secret perusahaan Anda dan memastikan bahwa algoritma penandatanganan JWT yang digunakan sesuai untuk 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.

Fungsi ini membuat permintaan POST ke server di URL https://your.company.com/api/ccaip/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/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, kode ini akan membuat instance Retrofit dan menggunakannya untuk membuat permintaan ke endpoint API https://company.com/api untuk menandatangani payload. Metode ini mengembalikan token yang ditandatangani dalam metode onToken instance tokenCallback. Jika gagal, pesan toast "Autentikasi gagal" 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) {
        // 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 Auth

Di CCAI Platform, aplikasi host menggunakan JWT (JSON Web Token) untuk menandatangani token autentikasi pengguna akhir, yang kemudian ditukar dengan token autentikasi pengguna akhir. JWT adalah standar terbuka untuk mentransmisikan informasi dengan 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 berwenang yang memiliki akses ke API.