Autenticazione degli utenti finali dell'SDK

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 è identificato da un UUID (Universally Unique Identifier) fornito dall'applicazione host. L'SDK della piattaforma CCAI richiede un token 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 della piattaforma CCAI avvia la procedura di autenticazione e ottiene un token di autenticazione.

Nota :per contesto, l'SDK della piattaforma CCAI include l'SDK web, mobile e headless.

Utente finale

L'utente finale in questo contesto 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 identificatore univoco universale (UUID) univoco per ogni singolo utente.

Importante: l'identificatore non deve essere un indirizzo email, in quanto gli indirizzi email possono cambiare e potrebbero non essere univoci per ogni utente.

L'utilizzo di un UUID contribuisce a garantire che l'utente finale possa essere identificato con precisione e differenziato dagli altri utenti, anche se il suo indirizzo email cambia.

Autenticarsi con CCAI Platform

Il token web JSON (JWT) viene utilizzato per identificare in modo sicuro un utente o un'applicazione che effettua una richiesta alla piattaforma CCAI. L'applicazione host è responsabile di fornire il JWT all'SDK di CCAI Platform tramite un callback. L'SDK della piattaforma CCAI 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, indirizzo email, nome e numero di telefono. Google Cloud Consigliamo di utilizzare il formato E.164 per i numeri di telefono. Queste informazioni vengono utilizzate per creare un nuovo account per l'utente o per associarlo a un account esistente sulla piattaforma CCAI.

Se l'applicazione host fornisce un identificatore nel payload JWT, la piattaforma CCAI 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.

Gestisci le chiavi SDK

I campi sdk_key_name e sdk_key sono importanti elementi di autenticazione. Identificano in modo univoco la tua azienda e vengono utilizzati per accedere in modo sicuro all'API CCAI Platform.

Per gestire le chiavi SDK:

1. Accedi al portale CCAI Platform come utente con il ruolo di amministratore.

2. Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.

3. Vai al riquadro Chiave e codice segreto dell'azienda per gestire le chiavi SDK, che vengono utilizzate per generare token di autenticazione.

Devi mantenere questi codici al sicuro 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 di autenticazione

Ecco il flusso di lavoro di autenticazione:

1. CCAI Platform fornisce un nome della chiave SDK (sdk_key_name) e una chiave SDK (sdk_key) all'applicazione host. Queste informazioni sono disponibili in Impostazioni > Impostazioni sviluppatore > Chiavi SDK.

2. Quando l'utente finale inizia a utilizzare il servizio clienti della piattaforma CCAI, l'SDK della piattaforma CCAI richiede la firma JWT dall'applicazione host.

3. La piattaforma CCAI 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 della piattaforma CCAI.

Firma JWT

L'applicazione host deve implementare un metodo di callback per ogni piattaforma. Le sezioni seguenti forniscono le istruzioni per ciascuna 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 riservati come i seguenti:

• (Facoltativo) Identificatore

• (facoltativo) nome

• Email (facoltativo)

• Numero di telefono (facoltativo, formato E.164)

Ad esempio, per l'SDK per 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"]  @"[e-mail]";      // 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 consiglia di firmare il payload lato server per una maggiore sicurezza. In questo modo, il segreto aziendale 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 lato client.

I seguenti snippet di codice forniscono esempi per la firma del payload sul lato server utilizzando il framework Ruby on Rails con il gem JWT e sul lato client utilizzando l'SDK per iOS, l'SDK per Android e l'SDK web.

Sul lato server, il codice configura un endpoint API per firmare il payload, utilizzando il gem JWT per codificare il payload con un segreto aziendale e restituire il token codificato al client.

Lato client, il codice fornisce esempi di richiesta all'API server dagli SDK iOS, Android e web per recuperare il token firmato.

Nell'SDK per iOS e nell'SDK per Android, il codice invia una richiesta POST HTTP 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 e le informazioni utente recuperati alla funzione di inizializzazione della piattaforma CCAI.

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 poi vengono aggiunti vari valori, ad esempio UNIQUE-IDENTIFIER, nome utente, email e telefono.

Il metodo JWT.encode viene utilizzato per codificare il payload e ccaip_secret in un token web JSON (JWT), che viene poi restituito nella risposta come oggetto JSON con la chiave del token.

Nota :in un ambiente di produzione, devi adottare misure per proteggere il segreto della tua azienda e assicurarti che l'algoritmo di firma JWT utilizzato sia appropriato per le tue esigenze di sicurezza.

 # 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"] = "[e-mail]"       # 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 per iOS.

Invia 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 trasmesso al callback di successo sotto forma di chiave "token" in un oggetto JSON. Se si verifica un errore durante la richiesta, questo 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.

È un'implementazione di una funzione dell'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 inviare 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 di notifica "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 alla piattaforma CCAI 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

Nella piattaforma CCAI, 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 il processo di autenticazione e a garantire che solo gli utenti autorizzati abbiano accesso all'API.