La procedura di autenticazione dell'utente finale in Contact Center AI Platform (CCAI Platform) è un metodo sicuro per identificare l'utente che utilizza l'applicazione host. L'utente finale viene identificato da un UUID (Universally Unique Identifier) fornito dall'applicazione host. L'SDK CCAI Platform richiede un JWT (JSON Web Token) firmato dalla chiave segreta condivisa (company_secret) e fornito dall'applicazione host ogni volta che è richiesta l'autenticazione. Se l'app host fornisce il JWT, l'SDK CCAI Platform avvia la procedura di autenticazione e ottiene un token di autenticazione.
Utente finale
In questo contesto, l'utente finale si riferisce all'utente dell'applicazione host.
Per identificare l'utente finale, CCAI Platform utilizza un identificatore fornito dall'app host. Questo identificatore deve essere un UUID (Universally Unique Identifier) univoco per ogni singolo utente.
L'utilizzo di un UUID contribuisce a garantire che l'utente finale possa essere identificato e distinto con precisione dagli altri utenti, anche se il suo indirizzo email cambia.
Autenticarsi con CCAI Platform
Il JWT (JSON Web Token) viene utilizzato per identificare in modo sicuro un utente o un'applicazione che effettua una richiesta a CCAI Platform. L'applicazione host è responsabile della fornitura del JWT all'SDK CCAI Platform tramite un callback. L'SDK CCAI Platform chiede all'applicazione host di fornire un JWT utilizzando la chiave SDK condivisa (sdk_key) ogni volta che è necessaria l'autenticazione.
Se l'applicazione host ha fornito un JWT all'SDK CCAI Platform tramite il callback, l'SDK CCAI Platform inizia l'autenticazione a CCAI Platform e ottiene il token di autenticazione.
Il payload del JWT potrebbe includere informazioni come l'identificatore dell'utente,
l'indirizzo email, il nome e il numero di telefono. Google Cloud Ti consigliamo di utilizzare il formato E.164per i numeri di telefono. Queste informazioni vengono utilizzate per creare un nuovo account per l'utente o per associare l'utente a un account esistente su CCAI Platform.
Se l'applicazione host fornisce un identificatore nel payload JWT, CCAI Platform lo utilizza per creare o associare l'utente a un account. Se non viene fornito un identificatore, CCAI Platform crea un account anonimo per l'utente.
Per ulteriori informazioni sull'accesso con firma JWT a CCAI Platform, consulta la sezione Firma JWT.
Gestire le chiavi SDK
I campi sdk_key_name e sdk_key sono elementi di autenticazione
importanti. Identificano in modo univoco la tua azienda e vengono utilizzati per accedere in modo sicuro all'API CCAI Platform.
Per gestire le chiavi SDK:
Accedi al portale CCAI Platform come utente con il ruolo di amministratore.
Nel portale CCAI Platform, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
Vai al riquadro Chiave e codice segreto dell'azienda per gestire le chiavi SDK, che vengono utilizzate per generare i token di autenticazione.
Devi proteggere questi codici e condividerli solo con persone o sistemi autorizzati che devono accedere all'API CCAI Platform. L'accesso non autorizzato a questi codici può compromettere la sicurezza dei tuoi dati e sistemi.
Flusso di lavoro per l'autenticazione
Di seguito è riportato il flusso di lavoro per l'autenticazione:
CCAI Platform fornisce un nome chiave SDK
(sdk_key_name)e una chiave SDK (sdk_key) all'applicazione host. Questi sono disponibili in Impostazioni > Impostazioni sviluppatore > Chiavi SDK.Quando l'utente finale inizia a utilizzare il servizio clienti di CCAI Platform, l'SDK CCAI Platform richiede la firma JWT all'applicazione host.
CCAI Platform verifica il JWT firmato ed emette un token di autenticazione dell'utente finale. Questa procedura garantisce un'autenticazione sicura e senza interruzioni tra l'applicazione host e il servizio clienti di CCAI Platform.
Firma JWT
L'applicazione host deve implementare un metodo di callback per ogni piattaforma. Le sezioni seguenti forniscono istruzioni per ogni piattaforma.
Per gestire le informazioni dell'utente finale, l'app host deve compilare il payload JWT. Un payload predefinito viene fornito tramite il metodo di callback e può già contenere alcuni valori come il token push e il nome predefinito.
L'applicazione host può aggiungere ulteriori informazioni sull'utente utilizzando nomi di chiavi riservate come le seguenti:
identificatore (facoltativo)
nome (facoltativo)
email (facoltativo)
numero di telefono (facoltativo, formato
E.164)
Ad esempio, per l'SDK iOS, l'implementazione del metodo può avere il seguente aspetto a scopo di test (utilizzando 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);
}
}
}
Esempio per la produzione
Google Cloud Ti consigliamo di firmare il payload sul lato server per una maggiore sicurezza. In questo modo, il segreto dell'azienda non viene esposto sul lato client e può essere revocato in qualsiasi momento se ritenuto a rischio. Questo approccio offre una maggiore sicurezza rispetto alla firma del payload sul lato client.
I seguenti snippet di codice forniscono esempi di firma del payload sul lato server utilizzando il framework Ruby on Rails con la gemma JWT e sul lato client utilizzando l'SDK iOS, l'SDK Android e l'SDK web.
Sul lato server, il codice configura un endpoint API per la firma del payload, utilizzando la gemma JWT per codificare il payload con un segreto aziendale e restituire il token codificato al client.
Sul lato client, il codice fornisce esempi di invio di una richiesta all'API server dall'SDK iOS, dall'SDK Android e dall'SDK web per recuperare il token firmato.
Nell'SDK iOS e nell'SDK Android, il codice effettua una richiesta HTTP POST all'API e recupera il token dalla risposta. Nell'SDK web, il codice implementa un gestore di autenticazione che effettua una richiesta AJAX all'API e passa il token recuperato e le informazioni utente alla funzione di inizializzazione di CCAI Platform.
Esempio di API sul server
Il codice in questa sezione è scritto in Ruby e utilizza il framework Rails.
Supponiamo che l'URL di base dell'applicazione host sia https://company.com/api/. Per firmare il payload per CCAI Platform, puoi aggiungere un altro endpoint API all'indirizzo https://company.com/api/ccaip/sign.
Il codice aggiunge una nuova route al file delle route dell'applicazione per gestire le richieste POST all'URL /api/ccaip/sign.
Il file ccaip_controller.rb definisce la classe CCAIPController, che ha un singolo endpoint chiamato sign. Questo endpoint viene utilizzato per firmare un payload per
CCAI Platform.
Nel codice, COMPANY_SECRET è definito come il segreto utilizzato per firmare il payload. Il payload viene estratto dal corpo della richiesta e vengono aggiunti vari valori, ad esempio UNIQUE-IDENTIFIER, nome utente, email e telefono.
Il metodo JWT.encode viene utilizzato per codificare il payload e il ccaip_secret in un JWT (JSON Web Token), che viene poi restituito nella risposta come oggetto JSON con la chiave token.
# 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
Firma dall'SDK iOS
Di seguito è riportato un esempio di firma di un payload dall'SDK iOS.
Effettua una richiesta POST al server all'URL https://your.company.com/api/ccaip/sign con il payload come corpo della richiesta. Il server dovrebbe restituire un token firmato in risposta, che viene poi passato al callback di successo sotto forma di chiave "token" in un oggetto JSON.
Se si verifica un errore durante la richiesta, viene passato al callback di errore.
- (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];
}
}
Firma dall'SDK Android
Di seguito è riportato un esempio di firma di un payload da un SDK Android.
Si tratta di un'implementazione di una funzione SDK Android per la firma di un payload utilizzando Retrofit, un client HTTP per Android. La funzione accetta come input un payload, un tipo di payload e un callback del token. Se il tipo di payload è UjetPayloadType.AuthToken, crea un'istanza Retrofit e la utilizza per effettuare una richiesta all'endpoint API https://company.com/api per firmare il payload. Restituisce il token firmato nel metodo onToken dell'istanza tokenCallback. In caso di errore, viene visualizzato un messaggio popup "Autenticazione non riuscita".
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();
}
});
}
}
Firma dall'SDK web
L'esempio seguente mostra come firmare il payload nell'SDK web effettuando una richiesta API al server con il payload.
Il server deve essere configurato per gestire la richiesta API e firmare il payload utilizzando un metodo sicuro. Il risultato viene poi restituito alla pagina web, che passa il token firmato a CCAI Platform utilizzando la funzione di callback.
$(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
});
});
Scambio di token di autenticazione
In CCAI Platform, l'applicazione host utilizza JWT (JSON Web Token) per firmare il token di autenticazione dell'utente finale, che viene poi scambiato con un token di autenticazione dell'utente finale. JWT è uno standard aperto per la trasmissione sicura di informazioni come oggetto JSON.
Il token di autenticazione dell'utente finale viene utilizzato per accedere all'API CCAI Platform. Questo meccanismo contribuisce a proteggere la procedura di autenticazione e a garantire che solo gli utenti autorizzati abbiano accesso all'API.