SDK 使用者驗證

Contact Center AI Platform (CCAI Platform) 的使用者驗證程序是一種安全方法，可識別使用主機應用程式的使用者。主機應用程式提供的通用唯一識別碼 (UUID) 可識別使用者。每當需要驗證時，CCAI Platform SDK 會要求由共用私密金鑰 (company_secret) 簽署，並由主機應用程式提供的 JSON Web Token (JWT)。如果主機應用程式提供 JWT，CCAI Platform SDK 會開始驗證程序並取得驗證權杖。

使用者

在此情況下，使用者是指主機應用程式的使用者。

為識別使用者，CCAI Platform 會使用主機應用程式提供的 ID。這個 ID 應為通用專屬 ID (UUID)，且每個使用者都應有專屬的 UUID。

使用 UUID 可確保系統能準確識別使用者，並與其他使用者區分，即使電子郵件地址變更也一樣。

使用 CCAI 平台進行驗證

JSON Web Token (JWT) 用於安全地識別向 CCAI Platform 提出要求的使用者或應用程式。主機應用程式負責透過回呼將 JWT 提供給 CCAI Platform SDK。每當需要驗證時，CCAI Platform SDK 會要求主機應用程式使用共用 SDK 金鑰 (sdk_key) 提供 JWT。

如果主機應用程式透過回呼向 CCAI Platform SDK 提供 JWT，CCAI Platform SDK 就會開始向 CCAI Platform 驗證，並取得驗證權杖。

JWT 的酬載可能包含使用者 ID、電子郵件地址、姓名和電話號碼等資訊。 Google Cloud 建議使用 E.164 格式的電話號碼。這項資訊可用於為使用者建立新帳戶，或將使用者與 CCAI Platform 上的現有帳戶建立關聯。

如果主機應用程式在 JWT 酬載中提供 ID，CCAI Platform 會使用該 ID 建立帳戶或將使用者與帳戶建立關聯。如果未提供 ID，CCAI Platform 會為使用者建立匿名帳戶。

如要進一步瞭解如何登入 CCAI Platform 並簽署 JWT，請參閱「JWT 簽署」一節。

管理 SDK 金鑰

sdk_key_name 和 sdk_key 欄位是重要的驗證元素。這些 ID 可專門識別貴公司，並用於安全存取 CCAI Platform API。

如要管理 SDK 金鑰，請按照下列步驟操作：

以具備管理員角色的使用者身分登入 CCAI Platform 入口網站。
在 CCAI Platform 入口網站中，依序點選「Settings」>「Developer Settings」。如果沒有看到「設定」選單，請按一下「選單」圖示。
前往「公司金鑰和密碼」窗格管理 SDK 金鑰，這些金鑰用於產生驗證權杖。

請務必妥善保管這些代碼，只分享給需要存取 CCAI Platform API 的授權人員或系統。如果未經授權存取這些代碼，可能會導致資料和系統安全受到威脅。

驗證工作流程

驗證工作流程如下：

CCAI Platform 會提供 SDK 金鑰名稱 (sdk_key_name) 和 SDK 金鑰 (sdk_key) 給主機應用程式。如要查看這些設定，請依序前往「設定」>「開發人員設定」>「SDK 鍵」。
當使用者開始使用 CCAI Platform 客服時，CCAI Platform SDK 會向主機應用程式要求簽署 JWT。
CCAI Platform 會驗證已簽署的 JWT，並核發使用者授權權杖。這個程序可確保主機應用程式與 CCAI Platform 客服之間的驗證安全無虞。

JWT 簽署

主機應用程式必須為每個平台實作回呼方法。下列各節提供各平台的操作說明。

如要處理使用者的資訊，主機應用程式必須填寫 JWT 酬載。系統會透過回呼方法提供預設酬載，且可能已包含某些值，例如推送權杖和預設名稱。

主機應用程式可以使用保留的金鑰名稱 (例如下列名稱)，新增更多使用者資訊：

識別碼 (選填)
名稱 (選填)
電子郵件地址 (選填)
電話號碼 (選填，格式為 E.164)

舉例來說，如果是 iOS SDK，為了進行測試 (使用 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"]  @"test@email.com";      // 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);
    }
  }
}

實際運作範例

Google Cloud 建議在伺服器端簽署酬載，以提升安全性。這樣一來，公司密鑰就不會暴露在用戶端，而且如果認為有風險，隨時可以撤銷。相較於在用戶端簽署酬載，這種做法可提供更高的安全性。

下列程式碼片段提供範例，說明如何使用 JWT Gem，透過 Ruby on Rails 架構在伺服器端簽署酬載，以及如何使用 iOS SDK、Android SDK 和 Web SDK 在用戶端簽署酬載。

在伺服器端，程式碼會設定 API 端點來簽署酬載，並使用 JWT Gem 以公司機密資訊編碼酬載，然後將編碼的權杖傳回給用戶端。

在用戶端，程式碼提供範例，說明如何從 iOS SDK、Android SDK 和 Web SDK 向伺服器 API 發出要求，以擷取已簽署的權杖。

在 iOS SDK 和 Android SDK 中，程式碼會向 API 發出 HTTP POST 要求，並從回應中擷取權杖。在 Web SDK 中，程式碼會實作驗證處理常式，向 API 提出 AJAX 要求，並將擷取的權杖和使用者資訊傳遞至 CCAI Platform 初始化函式。

伺服器上的 API 範例

本節中的程式碼是以 Ruby 編寫，並使用 Rails 架構。

假設主機應用程式的基本網址是 https://company.com/api/。如要簽署 CCAI 平台的酬載，您可以在 https://company.com/api/ccaip/sign 新增另一個 API 端點。

這段程式碼會在應用程式的路徑檔案中新增路徑，以處理對 /api/ccaip/sign 網址的 POST 要求。

ccaip_controller.rb 檔案會定義 CCAIPController 類別，其中包含名為 sign 的單一端點。該端點用於簽署 CCAI 平台的酬載。

在程式碼中，COMPANY_SECRET 定義為用於簽署酬載的密鑰。酬載會從要求主體中擷取，然後加入各種值，例如 UNIQUE-IDENTIFIER、使用者名稱、電子郵件和電話。

JWT.encode 方法會將酬載和 ccaip_secret 編碼為 JSON Web Token (JWT)，然後在回應中以 JSON 物件形式傳回，並包含權杖金鑰。

 # 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"] = "test@email.com"       # 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

從 iOS SDK 簽署

以下範例說明如何從 iOS SDK 簽署酬載。

這會向 https://your.company.com/api/ccaip/sign 網址的伺服器發出 POST 要求，並將酬載做為要求本體。伺服器應在回應中傳回已簽署的權杖，然後以 JSON 物件中「token」鍵的形式，傳遞至成功回呼。如果要求期間發生錯誤，系統會將錯誤傳遞至失敗回呼。

- (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];
  }
}

透過 Android SDK 簽署

以下範例說明如何從 Android SDK 簽署酬載。

這是 Android SDK 函式的實作項目，可使用 Android 的 HTTP 用戶端 Retrofit 簽署酬載。這個函式會將酬載、酬載類型和權杖回呼做為輸入內容。如果酬載類型為 UjetPayloadType.AuthToken，系統會建立 Retrofit 執行個體，並使用該執行個體向 https://company.com/api API 端點提出要求，以簽署酬載。這個方法會在 tokenCallback 例項的 onToken 方法中傳回已簽署的權杖。如果驗證失敗，系統會顯示「驗證失敗」浮動式訊息。

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();
                }
            });
        }
    }

透過 Web SDK 簽署

以下範例說明如何透過向伺服器發出含有酬載的 API 要求，在 Web SDK 中簽署酬載。

伺服器應設定為處理 API 要求，並使用安全方法簽署酬載。結果隨後會傳回網頁，並使用回呼函式將簽署的權杖傳回 CCAI Platform。

$(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
  });
});

交換驗證權杖

在 CCAI Platform 中，主機應用程式會使用 JWT (JSON Web Token) 簽署使用者的驗證權杖，然後換取使用者驗證權杖。JWT 是一種開放標準，可將資訊以 JSON 物件的形式安全傳輸。

使用者驗證權杖可用於存取 CCAI Platform API。這項機制有助於確保身分驗證程序安全無虞，並確保只有授權使用者能存取 API。