Bei der Contact Center AI Platform wird die Endnutzerauthentifizierung verwendet, um die Nutzer Ihrer Host-App sicher zu identifizieren. Dieser Mechanismus sorgt dafür, dass nur autorisierte Nutzer auf die CCAI Platform API zugreifen können und dass ihre Chatsitzungen und Daten sicher mit ihrer jeweiligen Identität verknüpft bleiben.
Um einen Endnutzer zu identifizieren, muss Ihre Host-App eine Universally Unique Identifier (UUID) bereitstellen, die diese bestimmte Person repräsentiert.
So funktioniert die Authentifizierung in CCAI Platform
Die Authentifizierung in der CCAI-Plattform basiert auf einem sicheren Handshake mit einem JSON Web Token (JWT). Ein JWT ist ein offener Standard, der verwendet wird, um Informationen sicher als JSON-Objekt zu übertragen.
So sieht der Standardauthentifizierungsablauf aus:
Die Anfrage: Wenn ein Endnutzer den Kundenservice der CCAI Platform nutzt, fordert das CCAI Platform SDK ein signiertes JWT von Ihrer Host-App an.
Die Signatur: Ihre Host-App signiert das JWT mit Ihrem gemeinsamen Unternehmensgeheimnis der CCAI-Plattform (
company_secret).Der Austausch: Die Host-App übergibt das signierte JWT zurück an das CCAI Platform SDK. Das SDK sendet dieses JWT dann an den CCAI Platform-Server.
Die Überprüfung: Der CCAI Platform-Server überprüft die Signatur. Wenn die Anmeldedaten gültig sind, gibt die CCAI-Plattform ein Autorisierungstoken aus, das dem Nutzer Zugriff auf die API gewährt und ihn mit seinem Konto verknüpft (oder ein neues Konto erstellt, falls noch keines vorhanden ist).
Wenn Ihre Host-App keinen Bezeichner in der JWT-Nutzlast bereitstellt, erstellt die CCAI Platform ein anonymes Gastkonto für den Nutzer.
Vorbereitung
Bevor Sie die Authentifizierung implementieren können, benötigen Sie Ihre eindeutigen SDK-Authentifizierungselemente. Damit wird Ihr Unternehmen sicher gegenüber der CCAI Platform API identifiziert.
Melden Sie sich mit einem Administratorkonto in der CCAI-Plattform an.
Gehen Sie zu Einstellungen > Entwicklereinstellungen > API-Anmeldedaten.
Suchen Sie nach dem Namen des SDK-Schlüssels (
sdk_key_name), dem SDK-Schlüssel (sdk_key) und dem Unternehmensgeheimnis (company_secret).
Bewahren Sie diese Anmeldedaten an einem sicheren Ort auf. Geben Sie sie nur an autorisierte Systeme und Entwickler weiter.
Implementierungsleitfaden für Entwickler
Im folgenden Abschnitt wird beschrieben, wie Entwickler die JWT-Nutzlast erstellen und das CCAI Platform SDK auf verschiedenen Plattformen initialisieren sollten.
Anforderungen an die JWT-Nutzlast
Damit die Informationen des Endnutzers an die CCAI Platform übergeben werden können, muss Ihre Host-App eine JWT-Nutzlast erstellen. Die Callback-Methode stellt eine Standardnutzlast bereit, die ein Push-Token und einen Standardnamen enthalten kann. Sie können jedoch bestimmte Nutzerdetails mit den folgenden reservierten Schlüsseln hinzufügen:
identifier(optionale, aber dringend empfohlene UUID)name(optional)email(optional)phone(optional, muss im E.164-Format angegeben werden)iss(optional, Ihr Unternehmensname)iat(erforderlich, Zeitstempel für „ausgestellt am“)exp(erforderlich, Zeitstempel des Ablaufs)
Serverseitige Signierung (empfohlen)
API-Beispiel auf dem Server (Ruby on Rails)
In diesem Beispiel wird gezeigt, wie die Nutzlast serverseitig mit dem Ruby on Rails-Framework und dem JWT-Gem signiert wird.
Im Code wird ein API-Endpunkt (/api/ujet/sign) mit dem jwt-Gem eingerichtet, um die Nutzlast mit einem Unternehmensgeheimnis zu codieren und das codierte Token an den Client zurückzugeben.
Angenommen, die Basis-URL Ihrer Hostanwendung lautet https://company.com/api/. Wenn Sie die Nutzlast für die CCAI-Plattform signieren möchten, können Sie einen weiteren API-Endpunkt unter https://company.com/api/ujet/sign hinzufügen.
Mit dem Code wird der Routendatei der Anwendung eine neue Route hinzugefügt, um POST-Anfragen an die URL /api/ujet/sign zu verarbeiten.
In der Datei ujet_controller.rb wird die Klasse UjetController definiert, die einen einzelnen Endpunkt (sign) hat, der zum Signieren einer Nutzlast für die CCAI-Plattform verwendet wird.
Im Code wird COMPANY_SECRET als das Geheimnis 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 ujet_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 '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"] = "test@email.com"
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
Clientseitige Initialisierung
Halten Sie sich an diese Richtlinien, um das mobile SDK für CCAI Platform zu initialisieren.
Signieren über das iOS SDK
In diesem Beispiel für das Signieren einer Nutzlast über das iOS SDK wird eine POST-Anfrage an den Server unter der URL https://your.company.com/api/ujet/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/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];
}
}
Signieren über das Android SDK
Im Folgenden sehen Sie ein Beispiel für das Signieren einer Nutzlast über ein Android SDK.
In diesem Beispiel wird Retrofit verwendet, ein HTTP-Client für Android, um die signierte Nutzlast von Ihrem Server anzufordern. Die Funktion verwendet eine Nutzlast, einen Nutzlasttyp und einen Token-Callback als Eingabe.
Wenn der Nutzlasttyp UjetPayloadType.AuthToken ist, wird eine Retrofit-Instanz erstellt, mit der eine Anfrage an den API-Endpunkt https://company.com/api gesendet wird, um die Nutzlast zu signieren. Das signierte Token wird in der Methode onToken der tokenCallback-Instanz zurückgegeben.
Bei einem Fehler wird die Kurzmitteilung "Authentication failed" 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) {
$.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
});
});
Authentifizierung während der Sitzung und Reinitialisierung des SDK
In einigen Fällen kann ein Endnutzer eine Chatsitzung als Gast (nicht authentifiziert) starten und seine Identität während der Sitzung bestätigen, z.B. über einen virtuellen Assistenten oder einen Anmeldebildschirm während des Ablaufs. So stellen Sie sicher, dass die aktive Sitzung sicher aktualisiert und dem neu authentifizierten Nutzer zugeordnet wird:
Schritte für die Authentifizierung während der Sitzung
SDK mit einer temporären Kennung initialisieren: Wenn der Nutzer nicht authentifiziert ist, initialisieren Sie das CCAI Platform SDK mit einer zufälligen oder Gast-Kennung.
Nutzer zur Authentifizierung weiterleiten: Leiten Sie den Nutzer zu Ihrem Authentifizierungsablauf weiter, z. B. zu einem virtuellen Assistenten (VA) der CCAI-Plattform oder zum integrierten Anmeldebildschirm Ihrer App.
Endnutzer über API aktualisieren: Nachdem sich der Nutzer erfolgreich authentifiziert hat (und während er sich noch im virtuellen Kundenservicemitarbeiter oder Authentifizierungsablauf befindet), muss Ihr Backend die CCAI Platform Apps API aufrufen, um die Chatsitzung des Endnutzers mit seiner tatsächlichen Kennung zu aktualisieren.
SDK mit einem neuen JWT neu initialisieren: Generieren Sie nach einer erfolgreichen Backend-Aktualisierung ein neues JWT für den authentifizierten Nutzer. Initialisieren Sie das CCAI Platform SDK neu, indem Sie die Initialisierungsmethode noch einmal mit diesem neuen JWT aufrufen.
Sitzung eskalieren (bei Verwendung eines virtuellen Kundenservicemitarbeiters): Wenn sich der Nutzer über einen virtuellen Kundenservicemitarbeiter authentifiziert hat, sollte der virtuelle Kundenservicemitarbeiter den Nutzer jetzt an die endgültige Zielwarteschlange weiterleiten.
Beispiel (Web-SDK)
Rufen Sie die Funktion UJET.initialize noch einmal auf, um die Initialisierung zu wiederholen. Dadurch wird der Authentifizierungs-Handler ausgelöst, um das neue Token abzurufen.
// 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
});
Warum ist das notwendig?
So wird sichergestellt, dass alle nachfolgenden Aktionen, das Routing und der Verlauf sicher dem authentifizierten Nutzer und nicht einer anonymen Gast-Sitzung zugeordnet werden.
So werden Datenlecks verhindert und genaue CRM- und Nutzerdatensätze geführt.
Übersichtstabelle
| Szenario | Maßnahme erforderlich |
|---|---|
| Nutzer startet authentifiziert | Initialisieren Sie das SDK mit der tatsächlichen UUID und dem JWT des Nutzers. |
| Nutzer startet nicht authentifiziert | SDK mit einer Gast- oder zufälligen ID initialisieren |
| Nutzer authentifiziert sich während der Sitzung | Aktualisieren Sie die CCAI-Plattform mit der API, generieren Sie ein neues JWT und initialisieren Sie das SDK neu. |