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 bei Bedarf ein JSON Web Token (JWT) an, das mit dem gemeinsamen geheimen Schlüssel (company_secret) signiert und von der Hostanwendung bereitgestellt wird. Wenn die Hostanwendung das JWT bereitstellt, startet das CCAI Platform SDK den Authentifizierungsprozess und ruft ein Authentifizierungstoken ab.
Endnutzer
Der Endnutzer bezieht sich in diesem Zusammenhang auf den Nutzer der Hostanwendung.
Zur Identifizierung des Endnutzers verwendet die CCAI Platform eine ID, die von der Hostanwendung bereitgestellt wird. Diese ID sollte eine Universally Unique Identifier (UUID) sein, die für jeden einzelnen Nutzer eindeutig ist.
Durch die Verwendung einer UUID kann der Endnutzer genau identifiziert und von anderen Nutzern unterschieden werden, auch wenn sich seine E-Mail-Adresse ändert.
Authentifizierung mit der CCAI Platform
Das JSON Web Token (JWT) wird verwendet, um einen Nutzer oder eine Anwendung, die eine Anfrage an die CCAI Platform sendet, sicher zu identifizieren. Die Hostanwendung ist dafür verantwortlich, das JWT über einen Callback an das CCAI Platform SDK zu senden. Das CCAI Platform SDK fordert die Hostanwendung auf, bei Bedarf ein JWT mit dem gemeinsamen SDK-Schlüssel (sdk_key) bereitzustellen.
Wenn die Hostanwendung dem CCAI Platform SDK über den Callback ein JWT bereitgestellt hat, authentifiziert sich das CCAI Platform SDK bei der CCAI Platform und ruft das Authentifizierungstoken ab.
Die Nutzlast des JWT kann Informationen wie die ID des Nutzers,
die E-Mail-Adresse, den Namen und die Telefonnummer enthalten. Google Cloud empfiehlt, für Telefonnummern das Format E.164 zu verwenden. Diese Informationen werden verwendet, um entweder ein neues Konto für den Nutzer zu erstellen oder den Nutzer einem bestehenden Konto in der CCAI Platform zuzuordnen.
Wenn die Hostanwendung eine ID in der JWT-Nutzlast bereitstellt, verwendet die CCAI Platform diese ID, um den Nutzer zu erstellen oder ihm ein Konto zuzuordnen. Wenn keine ID angegeben wird, erstellt die CCAI Platform ein anonymes Konto für den Nutzer.
Weitere Informationen zum Signieren von JWTs in der CCAI Platform finden Sie im Abschnitt JWT-Signierung.
SDK-Schlüssel verwalten
Die Felder sdk_key_name und sdk_key sind wichtige Authentifizierung
elemente. Sie identifizieren Ihr Unternehmen eindeutig und werden verwendet, um sicher auf die CCAI Platform API zuzugreifen.
So verwalten Sie Ihre SDK-Schlüssel:
Melden Sie sich im CCAI Platform-Portal als Nutzer mit der Rolle „Administrator“ an.
Klicken Sie im CCAI Platform-Portal auf Einstellungen > Entwicklereinstellungen. Wenn das Menü Einstellungen nicht angezeigt wird, klicken Sie auf Menü.
Im Bereich Unternehmensschlüssel und geheimer Code können Sie Ihre SDK-Schlüssel verwalten, die zum Generieren von Authentifizierungstokens verwendet werden.
Sie müssen diese Codes sicher aufbewahren und nur für autorisierte Personen oder Systeme freigeben, die Zugriff auf die CCAI Platform API benötigen. Unbefugter Zugriff auf diese Codes kann die Sicherheit Ihrer Daten und Systeme gefährden.
Authentifizierungsworkflow
So sieht der Authentifizierungsworkflow aus:
Die CCAI Platform stellt der Hostanwendung einen SDK-Schlüsselnamen
(sdk_key_name)und einen SDK-Schlüssel (sdk_key) zur Verfügung. Sie finden diese unter Einstellungen > Entwicklereinstellungen > SDK-Schlüssel.Wenn der Endnutzer den Kundenservice der CCAI Platform verwendet, fordert das CCAI Platform SDK die Hostanwendung auf, das JWT zu signieren.
Die CCAI Platform überprüft das signierte JWT und stellt ein Authentifizierungstoken für den Endnutzer aus. Dieser Prozess sorgt für eine sichere und nahtlose Authentifizierung zwischen der Hostanwendung und dem Kundenservice der CCAI Platform.
JWT-Signierung
Die Hostanwendung muss für jede Plattform eine Callback-Methode implementieren. In den folgenden Abschnitten finden Sie Anleitungen für jede Plattform.
Um die Informationen des Endnutzers zu verarbeiten, muss die Hostanwendung 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:
ID (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. So 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 das Signieren der Nutzlast auf der Clientseite.
Die folgenden Code-Snippets enthalten Beispiele für das Signieren der Nutzlast auf der Serverseite mit dem Ruby on Rails-Framework und dem JWT-Gem sowie auf der Clientseite mit dem iOS SDK, Android SDK und Web SDK.
Auf der Serverseite richtet der Code einen API-Endpunkt zum Signieren der Nutzlast ein. Dabei wird das JWT-Gem verwendet, um die Nutzlast mit einem Unternehmens-Secret zu codieren und das codierte Token an den Client zurückzugeben.
Auf der Clientseite enthält der Code Beispiele für das Senden einer Anfrage an die Server-API über das iOS SDK, Android SDK und Web SDK, um das signierte Token abzurufen.
Im iOS SDK und Android SDK sendet der Code eine HTTP POST-Anfrage an die API und ruft das Token aus der Antwort ab. Im Web SDK implementiert der Code einen Authentifizierungshandler, der eine AJAX-Anfrage an die API sendet und das abgerufene Token sowie die Nutzerinformationen an die Initialisierungsfunktion der CCAI Platform ü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 ist https://company.com/api/. Um die Nutzlast für die CCAI Platform zu signieren, können Sie einen weiteren API-Endpunkt unter https://company.com/api/ccaip/sign hinzufügen.
Der Code fügt der Routendatei der Anwendung eine neue Route hinzu, um POST-Anfragen an die URL /api/ccaip/sign zu verarbeiten.
Die Datei ccaip_controller.rb definiert die Klasse CCAIPController mit einem einzigen Endpunkt namens sign. Dieser Endpunkt wird verwendet, um eine Nutzlast für die
CCAI Platform zu signieren.
Im Code ist 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 Web Token (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
Signierung über das iOS SDK
Im Folgenden sehen Sie ein Beispiel für das Signieren einer Nutzlast über das iOS SDK.
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 bei 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];
}
}
Signierung ü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 verwendet eine Nutzlast, einen Nutzlasttyp und einen Token-Callback als Eingabe. Wenn der Nutzlasttyp UjetPayloadType.AuthToken ist, wird eine Retrofit-Instanz erstellt und verwendet, um eine Anfrage an den API-Endpunkt https://company.com/api zu senden, um die Nutzlast zu signieren. Das signierte Token wird in der Methode onToken der tokenCallback-Instanz zurückgegeben. Im Fehlerfall wird die Toast-Nachricht „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();
}
});
}
}
Signierung ü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 muss 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 Platform 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 Platform verwendet die Hostanwendung JWT (JSON Web Token), um das Authentifizierungstoken des Endnutzers zu signieren, das dann gegen ein Authentifizierungstoken für den Endnutzer ausgetauscht wird. JWT ist ein offener Standard für die sichere Übertragung von Informationen als JSON-Objekt.
Das Authentifizierungstoken des Endnutzers wird verwendet, um auf die CCAI Platform API zuzugreifen. Dieser Mechanismus trägt dazu bei, den Authentifizierungsprozess zu sichern und sicherzustellen, dass nur autorisierte Nutzer Zugriff auf die API haben.