Contact Center AI Platform utilise l'authentification des utilisateurs finaux pour identifier de manière sécurisée les personnes qui utilisent votre application hôte. Ce mécanisme garantit que seuls les utilisateurs autorisés peuvent accéder à l'API CCAI Platform et que leurs sessions de chat et leurs données restent associées de manière sécurisée à leur identité spécifique.
Pour identifier un utilisateur final, votre application hôte doit fournir un identifiant unique universel (UUID) qui représente cette personne spécifique.
Fonctionnement de l'authentification dans CCAI Platform
L'authentification dans CCAI Platform repose sur une négociation sécurisée à l'aide d'un jeton Web JSON (JWT). Un JWT est une norme ouverte utilisée pour transmettre des informations de manière sécurisée sous forme d'objet JSON.
Voici le flux d'authentification standard :
La requête : lorsqu'un utilisateur final commence à utiliser le service client CCAI Platform, le SDK CCAI Platform demande un jeton JWT signé à votre application hôte.
La signature : votre application hôte signe le jeton JWT à l'aide de votre secret d'entreprise partagé sur la plate-forme CCAI (
company_secret).L'échange : l'application hôte renvoie le jeton JWT signé au SDK CCAI Platform. Le SDK envoie ensuite ce JWT au serveur CCAI Platform.
La validation : le serveur CCAI Platform valide la signature. Si la demande est valide, la plate-forme CCAI émet un jeton d'authentification, accordant à l'utilisateur l'accès à l'API et l'associant à son compte (ou en créant un s'il n'existe pas).
Si votre application hôte ne fournit pas d'identifiant dans la charge utile JWT, CCAI Platform créera un compte invité anonyme pour l'utilisateur.
Prérequis
Avant d'implémenter l'authentification, vous devez disposer de vos éléments d'authentification SDK uniques. Ils permettent d'identifier votre entreprise de manière sécurisée auprès de l'API CCAI Platform.
Connectez-vous à la plate-forme CCAI avec un compte administrateur.
Accédez à Paramètres > Paramètres pour les développeurs > Identifiants API.
Localisez le nom de votre clé SDK (
sdk_key_name), votre clé SDK (sdk_key) et le code secret de votre entreprise (company_secret).
Conservez ces identifiants en lieu sûr. Ne les partagez qu'avec les systèmes et les développeurs autorisés.
Guide d'implémentation pour les développeurs
La section suivante explique comment les développeurs doivent construire la charge utile JWT et initialiser le SDK CCAI Platform sur différentes plates-formes.
Exigences concernant la charge utile JWT
Pour transmettre les informations de l'utilisateur final à CCAI Platform, votre application hôte doit créer une charge utile JWT. La méthode de rappel fournit une charge utile par défaut (qui peut inclure un jeton push et un nom par défaut), mais vous pouvez ajouter des informations utilisateur spécifiques à l'aide des clés réservées suivantes :
identifier(UUID facultatif, mais vivement recommandé)name(facultatif)email(facultatif)phone(facultatif, doit être au format E.164)iss(facultatif, nom de l'entreprise)iat(obligatoire, horodatage d'émission)exp(obligatoire, code temporel de l'expiration)
Signature côté serveur (recommandée)
Exemple d'API sur le serveur (Ruby on Rails)
Cet exemple montre comment signer la charge utile côté serveur à l'aide du framework Ruby on Rails avec la gem JWT.
Le code configure un point de terminaison d'API (/api/ujet/sign) à l'aide du gem jwt pour encoder la charge utile avec un secret d'entreprise et renvoyer le jeton encodé au client.
Supposons que l'URL de base de votre application hôte soit https://company.com/api/. Pour signer la charge utile pour la plate-forme CCAI, vous pouvez ajouter un autre point de terminaison d'API à l'adresse https://company.com/api/ujet/sign.
Le code ajoute une route au fichier de routes de l'application pour gérer les requêtes POST vers l'URL /api/ujet/sign.
Le fichier ujet_controller.rb définit la classe UjetController, qui comporte un seul point de terminaison, sign, utilisé pour signer une charge utile pour CCAI Platform.
Dans le code, COMPANY_SECRET est défini comme le secret utilisé pour signer la charge utile. La charge utile est extraite du corps de la requête, puis différentes valeurs y sont ajoutées, par exemple UNIQUE-IDENTIFIER, nom d'utilisateur, adresse e-mail et numéro de téléphone.
La méthode JWT.encode est utilisée pour encoder la charge utile et ujet_secret dans un jeton Web JSON (JWT), qui est ensuite renvoyé dans la réponse sous la forme d'un objet JSON avec la clé de jeton.
# 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
Initialisation côté client
Suivez ces consignes pour initialiser votre SDK mobile CCAI Platform.
Signature depuis le SDK iOS
Cet exemple de signature d'une charge utile à partir du SDK iOS envoie une requête POST au serveur à l'URL https://your.company.com/api/ujet/sign avec la charge utile comme corps de la requête.
Le serveur est censé renvoyer un jeton signé en réponse, qui est ensuite transmis au rappel de réussite sous la forme de la clé "token" dans un objet JSON.
En cas d'erreur lors de la requête, celle-ci est transmise au rappel d'échec.
- (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];
}
}
Signer à partir du SDK Android
Voici un exemple de signature d'une charge utile à partir d'un SDK Android.
Cet exemple utilise Retrofit, un client HTTP pour Android, afin de demander la charge utile signée à votre serveur. La fonction utilise une charge utile, un type de charge utile et un rappel de jeton en tant qu'entrées.
Si le type de charge utile est UjetPayloadType.AuthToken, il crée une instance Retrofit, l'utilise pour envoyer une requête au point de terminaison de l'API https://company.com/api afin de signer la charge utile, puis renvoie le jeton signé dans la méthode onToken de l'instance tokenCallback.
En cas d'échec, un message toast "Authentication failed" s'affiche.
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();
}
});
}
}
Signer depuis le SDK Web
L'exemple suivant montre comment signer la charge utile dans le SDK Web en envoyant une requête API au serveur avec la charge utile.
Le serveur doit être configuré pour gérer la requête API et signer la charge utile à l'aide d'une méthode sécurisée. Le résultat est ensuite renvoyé à la page Web, qui transmet le jeton signé à la plate-forme CCAI à l'aide de la fonction de rappel.
$(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
});
});
Authentification en cours de session et réinitialisation du SDK
Dans certains cas, un utilisateur final peut démarrer une session de chat en tant qu'invité (non authentifié) et valider son identité en cours de session (par exemple, via un assistant virtuel ou un écran de connexion en cours de flux). Pour vous assurer que la session active est mise à jour de manière sécurisée et associée à l'utilisateur nouvellement authentifié, procédez comme suit :
Étapes de l'authentification en cours de session
Initialisez le SDK avec un identifiant temporaire : lorsque l'utilisateur n'est pas authentifié, initialisez le SDK CCAI Platform à l'aide d'un identifiant invité ou aléatoire.
Invitez l'utilisateur à s'authentifier : guidez l'utilisateur dans votre flux d'authentification, par exemple un assistant virtuel (AV) de la plate-forme CCAI ou l'écran de connexion intégré à votre application.
Mettre à jour l'utilisateur final via l'API : une fois l'utilisateur authentifié (et tant qu'il est encore dans l'agent virtuel ou le flux d'authentification), votre backend doit appeler l'API CCAI Platform Apps pour mettre à jour la session de chat de l'utilisateur final avec son véritable identifiant.
Réinitialisez le SDK avec un nouveau jeton JWT : une fois la mise à jour du backend effectuée, générez un nouveau jeton JWT pour l'utilisateur authentifié. Réinitialisez le SDK CCAI Platform en appelant à nouveau la méthode d'initialisation avec ce nouveau JWT.
Transférez la session (si vous utilisez un assistant virtuel) : si l'utilisateur s'authentifiait à l'aide d'un assistant virtuel, celui-ci doit maintenant le transférer vers la file d'attente finale.
Exemple (SDK Web)
Pour réinitialiser, appelez à nouveau la fonction UJET.initialize. Cela déclenchera le gestionnaire d'authentification pour récupérer le nouveau jeton.
// 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
});
Pourquoi est-ce nécessaire ?
Cela garantit que toutes les actions, le routage et l'historique ultérieurs sont associés de manière sécurisée à l'utilisateur authentifié, plutôt qu'à une session invité anonyme.
Il empêche les fuites de données et permet de conserver des enregistrements CRM et utilisateur précis.
tableau récapitulatif
| Scénario | Action requise |
|---|---|
| L'utilisateur est authentifié au début | Initialisez le SDK avec le véritable UUID et le JWT de l'utilisateur. |
| L'utilisateur commence sans être authentifié | Initialisez le SDK avec un identifiant invité/aléatoire. |
| L'utilisateur s'authentifie en cours de session | Mettez à jour la plate-forme CCAI avec l'API, générez un jeton JWT et réinitialisez le SDK. |