El proceso de autenticación del usuario final en Contact Center AI Platform (CCAI Platform) es un método seguro para identificar al usuario que está utilizando la aplicación host. El usuario final se identifica con un identificador único universal (UUID) que proporciona la aplicación host. El SDK de la plataforma de la CCAI solicita un token web JSON (JWT) firmado por la clave secreta compartida (company_secret) y proporcionado por la aplicación host cada vez que se requiere autenticación. Si la app host proporciona el JWT, el SDK de la Plataforma de CCAI comienza el proceso de autenticación y obtiene un token de autorización.
Usuario final
En este contexto, el usuario final se refiere al usuario de la aplicación host.
Para identificar al usuario final, CCAI Platform usa un identificador que proporciona la app host. Este identificador debe ser un identificador único universal (UUID) que sea único para cada usuario individual.
El uso de un UUID ayuda a garantizar que se pueda identificar con precisión al usuario final y diferenciarlo de otros usuarios, incluso si cambia su dirección de correo electrónico.
Autentícate con CCAI Platform
El token web JSON (JWT) se usa para identificar de forma segura a un usuario o una aplicación que realiza una solicitud a la plataforma de la CCAI. La aplicación host es responsable de proporcionar el JWT al SDK de la plataforma de CCAI a través de una devolución de llamada. El SDK de la plataforma de CCAI le solicita a la aplicación host que proporcione un JWT con la clave del SDK compartido (sdk_key) cada vez que se necesite autenticación.
Si la aplicación host proporcionó un JWT al SDK de CCAI Platform a través de la devolución de llamada, el SDK de CCAI Platform comienza a autenticarse en CCAI Platform y obtiene el token de autenticación.
La carga útil del JWT puede incluir información como el identificador, la dirección de correo electrónico, el nombre y el número de teléfono del usuario. Google Cloud recomienda usar el formato E.164 para los números de teléfono. Esta información se usa para crear una cuenta nueva para el usuario o para asociarlo con una cuenta existente en la plataforma de la CCAI.
Si la aplicación host proporciona un identificador en la carga útil del JWT, la Plataforma de la CCAI usa ese identificador para crear o asociar al usuario con una cuenta. Si no se proporciona un identificador, CCAI Platform crea una cuenta anónima para el usuario.
Para obtener más información sobre el acceso con firma de JWT a la CCAI Platform, consulta la sección sobre la firma de JWT.
Administra tus claves del SDK
Los campos sdk_key_name y sdk_key son elementos de autenticación importantes. Identifican de forma única a tu empresa y se usan para acceder de forma segura a la API de CCAI Platform.
Para administrar tus claves del SDK, sigue estos pasos:
Accede al portal de CCAI Platform como un usuario con el rol de administrador.
En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador. Si no ves el menú Configuración, haz clic en Menú.
Ve al panel Clave y código secreto de la empresa para administrar las claves del SDK, que se usan para generar tokens de autorización.
Debes mantener estos códigos seguros y solo compartirlos con personas o sistemas autorizados que necesiten acceder a la API de la Plataforma de CCAI. El acceso no autorizado a estos códigos puede comprometer la seguridad de tus datos y sistemas.
Flujo de trabajo de autenticación
Este es el flujo de trabajo de autenticación:
La plataforma de CCAI proporciona un nombre de clave del SDK
(sdk_key_name)y una clave del SDK (sdk_key) a la aplicación host. Puedes encontrarlas en Configuración > Configuración para desarrolladores > Claves del SDK.Cuando el usuario final comienza a usar el servicio de atención al cliente de CCAI Platform, el SDK de CCAI Platform solicita la firma de JWT a la aplicación host.
La plataforma de la CCAI verifica el JWT firmado y emite un token de autorización del usuario final. Este proceso garantiza una autenticación segura y sin problemas entre la aplicación host y el servicio de atención al cliente de la Plataforma de CCAI.
Firma de JWT
La aplicación host debe implementar un método de devolución de llamada para cada plataforma. En las siguientes secciones, se proporcionan instrucciones para cada plataforma.
Para controlar la información del usuario final, la app host debe completar la carga útil del JWT. Se proporciona una carga útil predeterminada a través del método de devolución de llamada y ya puede contener algunos valores, como el token de envío y el nombre predeterminado.
La aplicación host puede agregar más información sobre el usuario con nombres de clave reservados, como los siguientes:
Identificador (opcional)
Nombre (opcional)
Correo electrónico (opcional)
Número de teléfono (opcional, formato
E.164)
Por ejemplo, para el SDK de iOS, la implementación del método puede verse de la siguiente manera para fines de prueba (con 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);
}
}
}
Ejemplo para producción
Google Cloud recomienda firmar la carga útil en el servidor para mayor seguridad. De esta manera, el secreto de la empresa no se expone en el cliente y se puede revocar en cualquier momento si se considera que está en riesgo. Este enfoque ofrece mayor seguridad en comparación con la firma de la carga útil en el cliente.
Los siguientes fragmentos de código proporcionan ejemplos para firmar la carga útil en el servidor con el framework de Ruby on Rails y la gema JWT, y en el cliente con el SDK de iOS, el SDK de Android y el SDK web.
En el servidor, el código configura un extremo de API para firmar la carga útil, usando la gema JWT para codificar la carga útil con un secreto de la empresa y devolver el token codificado al cliente.
En el cliente, el código proporciona ejemplos para realizar una solicitud a la API del servidor desde el SDK para iOS, el SDK de Android y el SDK web para recuperar el token firmado.
En los SDKs para iOS y Android, el código realiza una solicitud HTTP POST a la API y recupera el token de la respuesta. En el SDK web, el código implementa un controlador de autenticación que realiza una solicitud AJAX a la API y pasa el token recuperado y la información del usuario a la función de inicialización de la Plataforma de CCAI.
Ejemplo de API en el servidor
El código de esta sección está escrito en Ruby y usa el framework de Rails.
Supongamos que la URL base de tu aplicación host es https://company.com/api/. Para firmar la carga útil de CCAI Platform, puedes agregar otro extremo de API en https://company.com/api/ccaip/sign.
El código agrega una nueva ruta al archivo de rutas de la aplicación para controlar las solicitudes POST a la URL /api/ccaip/sign.
El archivo ccaip_controller.rb define la clase CCAIPController, que tiene un solo extremo llamado sign. Ese extremo se usa para firmar una carga útil para CCAI Platform.
En el código, COMPANY_SECRET se define como el secreto que se usa para firmar la carga útil. La carga útil se extrae del cuerpo de la solicitud y, luego, se le agregan varios valores, por ejemplo, UNIQUE-IDENTIFIER, nombre de usuario, correo electrónico y teléfono.
El método JWT.encode se usa para codificar la carga útil y ccaip_secret en un token web JSON (JWT), que luego se devuelve en la respuesta como un objeto JSON con la clave del 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 desde el SDK de iOS
A continuación, se muestra un ejemplo de cómo firmar una carga útil desde el SDK para iOS.
Realiza una solicitud POST al servidor en la URL https://your.company.com/api/ccaip/sign con la carga útil como cuerpo de la solicitud. Se espera que el servidor devuelva un token firmado en la respuesta, que luego se pasa a la devolución de llamada de éxito en forma de la clave "token" en un objeto JSON.
Si se produce un error durante la solicitud, se pasa a la devolución de llamada de error.
- (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 desde el SDK de Android
A continuación, se muestra un ejemplo de cómo firmar una carga útil desde un SDK de Android.
Es una implementación de una función del SDK de Android para firmar una carga útil con Retrofit, un cliente HTTP para Android. La función toma una carga útil, un tipo de carga útil y una devolución de llamada de token como entrada. Si el tipo de carga útil es UjetPayloadType.AuthToken, se crea una instancia de Retrofit y se usa para realizar una solicitud al extremo de API de https://company.com/api para firmar la carga útil. Devuelve el token firmado en el método onToken de la instancia tokenCallback. En caso de falla, se muestra el mensaje de aviso "Authentication failed".
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 desde el SDK web
En el siguiente ejemplo, se muestra cómo firmar la carga útil en el SDK web realizando una solicitud de API al servidor con la carga útil.
El servidor debe configurarse para controlar la solicitud a la API y firmar la carga útil con un método seguro. Luego, el resultado se devuelve a la página web, que pasa el token firmado a la plataforma de CCAI a través de la función de devolución de llamada.
$(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
});
});
Intercambio de tokens de Auth
En la plataforma de CCAI, la aplicación host usa JWT (token web JSON) para firmar el token de autenticación del usuario final, que luego se intercambia por un token de autenticación del usuario final. JWT es un estándar abierto para transmitir información de forma segura como un objeto JSON.
El token de autenticación del usuario final se usa para acceder a la API de CCAI Platform. Este mecanismo ayuda a proteger el proceso de autenticación y garantiza que solo los usuarios autorizados tengan acceso a la API.