Endnutzerauthentifizierung mit dem SDK

Die Endnutzerauthentifizierung in Contact Center AI Platform (CCAI Platform) ist eine sichere Methode, um den Nutzer zu identifizieren, der die Hostanwendung verwendet. Der Endnutzer wird durch eine Universally Unique Identifier (UUID) identifiziert, die von der Hostanwendung bereitgestellt wird. Das CCAI Platform SDK fordert ein JSON Web Token (JWT) an, das mit dem gemeinsamen geheimen Schlüssel (company_secret) signiert und von der Hostanwendung bereitgestellt wird, wenn eine Authentifizierung erforderlich ist. Wenn die Host-App das JWT bereitstellt, startet das CCAI Platform SDK den Authentifizierungsprozess und ruft ein Authentifizierungstoken ab.

Endnutzer

Der Endnutzer in diesem Kontext bezieht sich auf den Nutzer der Hostanwendung.

Zur Identifizierung des Endnutzers verwendet die CCAI Platform eine Kennung, die von der Host-App bereitgestellt wird. Diese Kennung sollte eine universell eindeutige Kennung (UUID) sein, die für jeden einzelnen Nutzer eindeutig ist.

Die Verwendung einer UUID trägt dazu bei, dass der Endnutzer genau identifiziert und von anderen Nutzern unterschieden werden kann, auch wenn sich seine E-Mail-Adresse ändert.

Mit der CCAI Platform authentifizieren

Das JSON Web Token (JWT) wird verwendet, um einen Nutzer oder eine Anwendung, die eine Anfrage an die CCAI-Plattform sendet, sicher zu identifizieren. Die Hostanwendung ist dafür verantwortlich, das JWT über einen Callback an das CCAI Platform SDK zu übergeben. Das CCAI Platform SDK fordert die Hostanwendung auf, ein JWT mit dem gemeinsam genutzten SDK-Schlüssel (sdk_key) bereitzustellen, wenn eine Authentifizierung erforderlich ist.

Wenn die Hostanwendung dem CCAI Platform SDK über den Callback ein JWT bereitgestellt hat, beginnt das CCAI Platform SDK mit der Authentifizierung bei der CCAI Platform und ruft das Authentifizierungstoken ab.

Die Nutzlast des JWT kann Informationen wie die Nutzer-ID, die E-Mail-Adresse, den Namen und die Telefonnummer des Nutzers enthalten. Google Cloud empfiehlt, Telefonnummern im E.164-Format zu verwenden. Anhand dieser Informationen wird entweder ein neues Konto für den Nutzer erstellt oder der Nutzer wird einem bestehenden Konto auf der CCAI-Plattform zugeordnet.

Wenn die Hostanwendung eine Kennung in der JWT-Nutzlast bereitstellt, verwendet die CCAI-Plattform diese Kennung, um den Nutzer zu erstellen oder mit einem Konto zu verknüpfen. Wenn keine ID angegeben wird, erstellt CCAI Platform ein anonymes Konto für den Nutzer.

Weitere Informationen zur JWT-Signierung in der CCAI-Plattform finden Sie im Abschnitt zur JWT-Signierung.

SDK-Schlüssel verwalten

Die Felder sdk_key_name und sdk_key sind wichtige Authentifizierungselemente. Sie identifizieren Ihr Unternehmen eindeutig und werden für den sicheren Zugriff auf die CCAI Platform API verwendet.

So verwalten Sie Ihre SDK-Schlüssel:

  1. Melden Sie sich im CCAI Platform-Portal als Nutzer mit der Administratorrolle an.

  2. Klicken Sie im CCAI Platform-Portal auf Einstellungen > Entwicklereinstellungen. Wenn Sie das Menü Einstellungen nicht sehen, klicken Sie auf  Menü.

  3. Rufen Sie den Bereich Unternehmensschlüssel und geheimer Code auf, um Ihre SDK-Schlüssel zu verwalten, die zum Generieren von Autorisierungstokens verwendet werden.

Sie müssen diese Codes sicher aufbewahren und dürfen sie nur an autorisierte Personen oder Systeme weitergeben, die Zugriff auf die CCAI Platform API benötigen. Unbefugter Zugriff auf diese Codes kann die Sicherheit Ihrer Daten und Systeme beeinträchtigen.

Authentifizierungsworkflow

So funktioniert die Authentifizierung:

  1. Die CCAI-Plattform stellt der Hostanwendung einen SDK-Schlüsselnamen (sdk_key_name) und einen SDK-Schlüssel sdk_key zur Verfügung. Sie finden sie unter Einstellungen > Entwicklereinstellungen > SDK-Schlüssel.

  2. Wenn der Endnutzer den CCAI Platform-Kundenservice nutzt, fordert das CCAI Platform SDK die JWT-Signierung von der Hostanwendung an.

  3. CCAI Platform überprüft das signierte JWT und stellt ein Endnutzer-Autorisierungstoken aus. Dieser Prozess sorgt für eine sichere und nahtlose Authentifizierung zwischen der Hostanwendung und dem Kundenservice der CCAI-Plattform.

JWT-Signierung

Die Hostanwendung muss für jede Plattform eine Callback-Methode implementieren. In den folgenden Abschnitten finden Sie Anleitungen für die einzelnen Plattformen.

Zum Verarbeiten der Informationen des Endnutzers muss die Host-App die JWT-Nutzlast ausfüllen. Eine Standardnutzlast wird über die Callback-Methode bereitgestellt und kann bereits einige Werte wie das Push-Token und den Standardnamen enthalten.

Die Hostanwendung kann weitere Informationen zum Nutzer hinzufügen, indem sie reservierte Schlüsselnamen wie die folgenden verwendet:

  • identifier (optional)

  • name (optional)

  • E‑Mail-Adresse (optional)

  • Telefonnummer (optional, Format E.164)

Für das iOS SDK kann die Methodenimplementierung für Testzwecke beispielsweise so aussehen (mit 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);
    }
  }
}

Beispiel für die Produktion

Google Cloud empfiehlt, die Nutzlast zur Erhöhung der Sicherheit serverseitig zu signieren. Dadurch wird das Unternehmens-Secret nicht auf der Clientseite offengelegt und kann jederzeit widerrufen werden, wenn es als gefährdet gilt. Dieser Ansatz bietet mehr Sicherheit als die Signierung der Nutzlast auf Clientseite.

Die folgenden Code-Snippets enthalten Beispiele für das Signieren der Nutzlast auf der Serverseite mit dem Ruby on Rails-Framework mit dem JWT-Gem und auf der Clientseite mit dem iOS SDK, Android SDK und Web SDK.

Auf der Serverseite wird mit dem JWT-Gem ein API-Endpunkt zum Signieren der Nutzlast eingerichtet. Die Nutzlast wird mit einem Unternehmens-Secret codiert und das codierte Token wird an den Client zurückgegeben.

Auf der Clientseite enthält der Code Beispiele für das Senden einer Anfrage an die Server-API über das iOS SDK, das Android SDK und das Web-SDK, um das signierte Token abzurufen.

Im iOS SDK und Android SDK wird mit dem Code eine HTTP POST-Anfrage an die API gesendet und das Token aus der Antwort abgerufen. Im Web-SDK wird ein Authentifizierungshandler implementiert, der eine AJAX-Anfrage an die API sendet und das abgerufene Token und die Nutzerinformationen an die Initialisierungsfunktion der CCAI-Plattform übergibt.

API-Beispiel auf dem Server

Der Code in diesem Abschnitt ist in Ruby geschrieben und verwendet das Rails-Framework.

Angenommen, die Basis-URL Ihrer Hostanwendung lautet https://company.com/api/. Wenn Sie die Nutzlast für die CCAI Platform signieren möchten, können Sie einen weiteren API-Endpunkt unter https://company.com/api/ccaip/sign hinzufügen.

Mit dem Code wird der Routendatei der Anwendung eine neue Route hinzugefügt, um POST-Anfragen an die URL /api/ccaip/sign zu verarbeiten.

In der Datei ccaip_controller.rb wird die Klasse CCAIPController definiert, die einen einzelnen Endpunkt namens sign hat. Dieser Endpunkt wird verwendet, um eine Nutzlast für die CCAI-Plattform zu signieren.

Im Code wird COMPANY_SECRET als das Secret definiert, das zum Signieren der Nutzlast verwendet wird. Die Nutzlast wird aus dem Text der Anfrage extrahiert und dann werden verschiedene Werte hinzugefügt, z. B. UNIQUE-IDENTIFIER, Nutzername, E-Mail-Adresse und Telefonnummer.

Die Methode JWT.encode wird verwendet, um die Nutzlast und das ccaip_secret in ein JSON-Webtoken (JWT) zu codieren, das dann in der Antwort als JSON-Objekt mit dem Schlüssel „token“ zurückgegeben wird.

 # 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

Signieren über das iOS SDK

Das folgende Beispiel zeigt, wie eine Nutzlast mit dem iOS SDK signiert wird.

Es wird eine POST-Anfrage an den Server unter der URL https://your.company.com/api/ccaip/sign gesendet, wobei die Nutzlast als Anfragetext verwendet wird. Der Server sollte als Antwort ein signiertes Token zurückgeben, das dann in Form des Schlüssels „token“ in einem JSON-Objekt an den Erfolgs-Callback übergeben wird. Wenn während der Anfrage ein Fehler auftritt, wird er an den Fehler-Callback übergeben.

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

Signieren über das Android SDK

Im Folgenden sehen Sie ein Beispiel für das Signieren einer Nutzlast über ein Android SDK.

Es handelt sich um eine Implementierung einer Android SDK-Funktion zum Signieren einer Nutzlast mit Retrofit, einem HTTP-Client für Android. Die Funktion nimmt eine Nutzlast, einen Nutzlasttyp und einen Token-Callback als Eingabe entgegen. Wenn der Nutzlasttyp UjetPayloadType.AuthToken ist, wird eine Retrofit-Instanz erstellt und damit eine Anfrage an den https://company.com/api-API-Endpunkt gesendet, um die Nutzlast zu signieren. Das signierte Token wird in der Methode onToken der tokenCallback-Instanz zurückgegeben. Im Fehlerfall wird die Toast-Meldung „Authentifizierung fehlgeschlagen“ angezeigt.

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

Signieren über das Web-SDK

Im folgenden Beispiel wird gezeigt, wie die Nutzlast im Web-SDK signiert wird, indem eine API-Anfrage mit der Nutzlast an den Server gesendet wird.

Der Server sollte so eingerichtet sein, dass er die API-Anfrage verarbeiten und die Nutzlast mit einer sicheren Methode signieren kann. Das Ergebnis wird dann an die Webseite zurückgegeben, die das signierte Token über die Callback-Funktion an die CCAI-Plattform zurückgibt.

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

Austausch von Authentifizierungstokens

In der CCAI-Plattform verwendet die Hostanwendung JWT (JSON Web Token), um das Authentifizierungstoken des Endnutzers zu signieren, das dann gegen ein Authentifizierungstoken des Endnutzers eingetauscht wird. JWT ist ein offener Standard für die sichere Übertragung von Informationen als JSON-Objekt.

Das Endnutzer-Authentifizierungstoken wird für den Zugriff auf die CCAI Platform API verwendet. Dieser Mechanismus trägt dazu bei, den Authentifizierungsprozess zu schützen und dafür zu sorgen, dass nur autorisierte Nutzer Zugriff auf die API haben.