Le processus d'authentification des utilisateurs finaux dans Contact Center AI Platform (CCAI Platform) est une méthode sécurisée permettant d'identifier l'utilisateur qui utilise l'application hôte. L'utilisateur final est identifié par un identifiant unique universel (UUID) fourni par l'application hôte. Le SDK CCAI Platform demande un jeton Web JSON (JWT) signé par la clé secrète partagée (company_secret) et fourni par l'application hôte chaque fois qu'une authentification est requise. Si l'application hôte fournit le JWT, le SDK CCAI Platform lance le processus d'authentification et obtient un jeton d'authentification.
Utilisateur final
Dans ce contexte, l'utilisateur final désigne l'utilisateur de l'application hôte.
Pour identifier l'utilisateur final, CCAI Platform utilise un identifiant fourni par l'application hôte. Cet identifiant doit être un identifiant unique universel (UUID) propre à chaque utilisateur.
L'utilisation d'un UUID permet de s'assurer que l'utilisateur final peut être identifié avec précision et distingué des autres utilisateurs, même si son adresse e-mail change.
S'authentifier avec CCAI Platform
Le jeton Web JSON (JWT) permet d'identifier de manière sécurisée un utilisateur ou une application qui envoie une requête à la plate-forme CCAI. L'application hôte est chargée de fournir le JWT au SDK CCAI Platform via un rappel. Le SDK de la plate-forme CCAI demande à l'application hôte de fournir un jeton JWT à l'aide de la clé SDK partagée (sdk_key) chaque fois qu'une authentification est nécessaire.
Si l'application hôte a fourni un jeton JWT au SDK CCAI Platform via le rappel, le SDK CCAI Platform commence à s'authentifier auprès de CCAI Platform et obtient le jeton d'authentification.
La charge utile du JWT peut inclure des informations telles que l'identifiant, l'adresse e-mail, le nom et le numéro de téléphone de l'utilisateur. Google Cloud recommande d'utiliser le format E.164 pour les numéros de téléphone. Ces informations sont utilisées pour créer un compte pour l'utilisateur ou pour l'associer à un compte existant sur la plate-forme CCAI.
Si l'application hôte fournit un identifiant dans la charge utile JWT, la plate-forme CCAI l'utilise pour créer ou associer l'utilisateur à un compte. Si aucun identifiant n'est fourni, CCAI Platform crée un compte anonyme pour l'utilisateur.
Pour en savoir plus sur la connexion avec signature JWT à CCAI Platform, consultez la section Signature JWT.
Gérer vos clés SDK
Les champs sdk_key_name et sdk_key sont des éléments d'authentification importants. Elles permettent d'identifier de manière unique votre entreprise et d'accéder de manière sécurisée à l'API de la plate-forme CCAI.
Pour gérer vos clés SDK, procédez comme suit :
Connectez-vous au portail de la plate-forme CCAI en tant qu'utilisateur disposant du rôle d'administrateur.
Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
Accédez au volet Clé et code secret de l'entreprise pour gérer vos clés SDK, qui sont utilisées pour générer des jetons d'authentification.
Vous devez protéger ces codes et ne les partager qu'avec les personnes ou systèmes autorisés qui ont besoin d'accéder à l'API CCAI Platform. Un accès non autorisé à ces codes peut compromettre la sécurité de vos données et de vos systèmes.
Workflow d'authentification
Voici le workflow d'authentification :
CCAI Platform fournit un nom de clé SDK (
(sdk_key_name)) et une clé SDK (sdk_key) à l'application hôte. Pour cela, accédez à Paramètres > Paramètres pour les développeurs > Clés SDK.Lorsque l'utilisateur final commence à utiliser le service client CCAI Platform, le SDK CCAI Platform demande la signature JWT à l'application hôte.
La plate-forme CCAI vérifie le jeton JWT signé et émet un jeton d'authentification de l'utilisateur final. Ce processus garantit une authentification sécurisée et fluide entre l'application hôte et le service client de la plate-forme CCAI.
Signature JWT
L'application hôte doit implémenter une méthode de rappel pour chaque plate-forme. Les sections suivantes fournissent des instructions pour chaque plate-forme.
Pour gérer les informations de l'utilisateur final, l'application hôte doit remplir la charge utile JWT. Une charge utile par défaut est fournie par le biais de la méthode de rappel et peut déjà contenir certaines valeurs, telles que le jeton push et le nom par défaut.
L'application hôte peut ajouter des informations sur l'utilisateur à l'aide de noms de clés réservés, tels que les suivants :
identifiant (facultatif)
name (facultatif)
adresse e-mail (facultatif)
Numéro de téléphone (facultatif, au format
E.164)
Par exemple, pour le SDK iOS, l'implémentation de la méthode peut se présenter comme suit à des fins de test (à l'aide de 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);
}
}
}
Exemple pour la production
Google Cloud recommande de signer la charge utile côté serveur pour renforcer la sécurité. De cette façon, le secret de l'entreprise n'est pas exposé côté client et peut être révoqué à tout moment s'il est considéré comme à risque. Cette approche offre une sécurité renforcée par rapport à la signature de la charge utile côté client.
Les extraits de code suivants fournissent des exemples de signature de la charge utile côté serveur à l'aide du framework Ruby on Rails avec le gem JWT, et côté client à l'aide des SDK iOS, Android et Web.
Côté serveur, le code configure un point de terminaison d'API pour signer la charge utile, en utilisant le gem JWT pour encoder la charge utile avec un code secret d'entreprise et renvoyer le jeton encodé au client.
Côté client, le code fournit des exemples de requête à l'API du serveur à partir des SDK iOS, Android et Web pour récupérer le jeton signé.
Dans les SDK iOS et Android, le code envoie une requête HTTP POST à l'API et récupère le jeton à partir de la réponse. Dans le SDK Web, le code implémente un gestionnaire d'authentification qui envoie une requête AJAX à l'API et transmet le jeton et les informations utilisateur récupérés à la fonction d'initialisation de la plate-forme CCAI.
Exemple d'API sur le serveur
Le code de cette section est écrit en Ruby et utilise le framework Rails.
Supposons que l'URL de base de votre application hôte soit https://company.com/api/. Pour signer la charge utile pour CCAI Platform, vous pouvez ajouter un autre point de terminaison d'API à l'adresse https://company.com/api/ccaip/sign.
Le code ajoute une route au fichier de routes de l'application pour gérer les requêtes POST vers l'URL /api/ccaip/sign.
Le fichier ccaip_controller.rb définit la classe CCAIPController, qui comporte un seul point de terminaison appelé sign. Ce point de terminaison permet de 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 le ccaip_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é du jeton.
# 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
Signature depuis le SDK iOS
Voici un exemple de signature d'une charge utile à partir du SDK iOS.
Il envoie une requête POST au serveur à l'URL https://your.company.com/api/ccaip/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/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];
}
}
Signature depuis le SDK Android
Voici un exemple de signature d'une charge utile à partir d'un SDK Android.
Il s'agit d'une implémentation d'une fonction du SDK Android permettant de signer une charge utile à l'aide de Retrofit, un client HTTP pour Android. 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 et l'utilise pour envoyer une requête au point de terminaison de l'API https://company.com/api afin de signer la charge utile. Il renvoie le jeton signé dans la méthode onToken de l'instance tokenCallback. En cas d'échec, un message toast "Échec de l'authentification" 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();
}
});
}
}
Signature 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) {
// 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
});
});
Échange de jetons d'authentification
Dans CCAI Platform, l'application hôte utilise JWT (JSON Web Token) pour signer le jeton d'authentification de l'utilisateur final, qui est ensuite échangé contre un jeton d'authentification de l'utilisateur final. JWT est une norme ouverte permettant de transmettre des informations de manière sécurisée sous forme d'objet JSON.
Le jeton d'authentification de l'utilisateur final permet d'accéder à l'API de la plate-forme CCAI. Ce mécanisme permet de sécuriser le processus d'authentification et de s'assurer que seuls les utilisateurs autorisés ont accès à l'API.