Configuración de la autenticación SDK

La Autenticación del SDK te permite proporcionar una prueba criptográfica (generada en el servidor) a las solicitudes del SDK realizadas en nombre de usuarios que han iniciado sesión.

Cómo funciona

Después de habilitar esta característica en tu aplicación, puedes configurar el panel de Braze para que rechace cualquier solicitud con una firma JSON Web Token (JWT) no válida o que falte, lo que incluye:

• Envío de eventos personalizados, atributos, compras y datos de sesión
• Crear nuevos usuarios en tu espacio de trabajo Braze
• Actualización de los atributos estándar del perfil de usuario
• Recibir o desencadenar mensajes

Ahora puedes impedir que los usuarios no autentificados que hayan iniciado sesión utilicen la clave de API de SDK de tu aplicación para realizar acciones maliciosas, como suplantar la identidad de otros usuarios.

Configuración de la autenticación

Paso 1: Configura tu servidor

Paso 1.1: Generar un par de claves pública/privada

Genera un par de claves públicas/privadas RSA256. La clave pública se añadirá finalmente al panel de Braze, mientras que la clave privada debe almacenarse de forma segura en tu servidor.

Recomendamos usar una clave RSA con 2048 bits con el algoritmo RS256 JWT.

Paso 1.2: Crear un Token Web JSON para el usuario actual

Una vez que tengas tu clave privada, tu aplicación del lado del servidor debe utilizarla para devolver un JWT a tu aplicación o sitio web para el usuario conectado en ese momento.

Normalmente, esta lógica podría ir allí donde tu aplicación solicitaría normalmente el perfil del usuario actual; como un punto final de inicio de sesión o donde tu aplicación actualice el perfil del usuario actual.

Al generar el JWT, se esperan los siguientes campos:

Encabezado JWT

Carga útil JWT

Paso 2: Configura el SDK

Esta característica está disponible a partir de las siguientes versiones del SDK:

Paso 2.1: Habilita la autenticación en el SDK de Braze.

Cuando esta característica está habilitada, el SDK de Braze añadirá el último JWT conocido del usuario actual a las solicitudes de red realizadas a los servidores Braze.

• javascript
• java
• kotlin
• objective-c
• swift
• dart

1
2
3
4
5
import * as braze from"@braze/web-sdk";
braze.initialize("YOUR-API-KEY-HERE", {
  baseUrl: "YOUR-SDK-ENDPOINT-HERE",
  enableSdkAuthentication: true,
});

1
2
3
BrazeConfig.Builder brazeConfigBuilder = new BrazeConfig.Builder()
    .setIsSdkAuthenticationEnabled(true);
Braze.configure(this, brazeConfigBuilder.build());

1
2
3
BrazeConfig.Builder brazeConfigBuilder = BrazeConfig.Builder()
    .setIsSdkAuthenticationEnabled(true)
Braze.configure(this, brazeConfigBuilder.build())

1
2
3
4
5
6
BRZConfiguration *configuration =
    [[BRZConfiguration alloc] initWithApiKey:@"{BRAZE_API_KEY}"
                                    endpoint:@"{BRAZE_ENDPOINT}"];
configuration.api.sdkAuthentication = YES;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

1
2
3
4
5
let configuration = Braze.Configuration(apiKey: "{YOUR-BRAZE-API-KEY}",
                                        endpoint: "{YOUR-BRAZE-ENDPOINT}")
configuration.api.sdkAuthentication = true
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

Paso 2.2: Configura el token JWT del usuario actual

Siempre que tu aplicación llame al método Braze changeUser, proporciona también el token JWT que se generó en el servidor.

También puedes configurar el token para que se actualice a mitad de sesión para el usuario actual.

• javascript
• java
• kotlin
• objective-c
• swift
• dart

1
2
import * as braze from "@braze/web-sdk";
braze.changeUser("NEW-USER-ID", "JWT-TOKEN-FROM-SERVER");

1
2
import * as braze from"@braze/web-sdk";
braze.setSdkAuthenticationSignature("NEW-JWT-TOKEN-FROM-SERVER");

1
Braze.getInstance(this).changeUser("NEW-USER-ID", "JWT-TOKEN-FROM-SERVER");

1
Braze.getInstance(this).setSdkAuthenticationSignature("NEW-JWT-TOKEN-FROM-SERVER");

1
Braze.getInstance(this).changeUser("NEW-USER-ID", "JWT-TOKEN-FROM-SERVER")

1
Braze.getInstance(this).setSdkAuthenticationSignature("NEW-JWT-TOKEN-FROM-SERVER")

1
[AppDelegate.braze changeUser:@"userId" sdkAuthSignature:@"signature"];

1
[AppDelegate.braze setSDKAuthenticationSignature:@"signature"];

1
AppDelegate.braze?.changeUser(userId: "userId", sdkAuthSignature: "signature")

1
AppDelegate.braze?.set(sdkAuthenticationSignature: "signature")

1
braze.changeUser("userId", sdkAuthSignature: "signature")

1
braze.setSdkAuthenticationSignature("signature")

Paso 2.3: Registra una función de devolución de llamada para tokens no válidos

Cuando esta característica se establece como Requerido, los siguientes escenarios harán que las solicitudes SDK sean rechazadas por Braze:

• El JWT había caducado en el momento en que lo recibió la API de Braze
• El JWT estaba vacío o faltaba
• No se ha podido verificar JWT para las claves públicas que has cargado en el panel de Braze

Puedes utilizar subscribeToSdkAuthenticationFailures para suscribirte y recibir una notificación cuando las solicitudes del SDK fallen por uno de estos motivos. Una función de devolución de llamada contiene un objeto con la información relevante errorCode, reason para el error, el userId de la solicitud (si el usuario no es anónimo), y la autenticación signature que causó el error.

Las solicitudes fallidas se reintentarán periódicamente hasta que tu aplicación proporcione un nuevo JWT válido. Si ese usuario sigue conectado, puedes utilizar esta devolución de llamada como una oportunidad para solicitar un nuevo JWT a tu servidor y suministrar al SDK de Braze este nuevo token válido.

• javascript
• java
• kotlin
• objective-c
• swift
• dart

1
2
3
4
5
6
7
import * as braze from"@braze/web-sdk";
braze.subscribeToSdkAuthenticationFailures((error) => {
  // TODO: Optionally log to your error-reporting service
  // TODO: Check if the `user_id` within the `error` matches the currently logged-in user
  const updated_jwt = await getNewTokenSomehow(error);
  braze.setSdkAuthenticationSignature(updated_jwt);
});

1
2
3
4
5
6
Braze.getInstance(this).subscribeToSdkAuthenticationFailures(error -> {
    // TODO: Optionally log to your error-reporting service
    // TODO: Check if the error user matches the currently logged-in user
    String newToken = getNewTokenSomehow(error);
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken);
});

1
2
3
4
5
6
Braze.getInstance(this).subscribeToSdkAuthenticationFailures({ error: BrazeSdkAuthenticationErrorEvent ->
    // TODO: Optionally log to your error-reporting service
    // TODO: Check if the `user_id` within the `error` matches the currently logged-in user
    val newToken: String = getNewTokenSomehow(error)
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken)
})

1
2
3
4
5
6
7
8
9
10
11
12
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
braze.sdkAuthDelegate = delegate;
AppDelegate.braze = braze;

// Method to implement in delegate
- (void)braze:(Braze *)braze sdkAuthenticationFailedWithError:(BRZSDKAuthenticationError *)error {
  // TODO: Optionally log to your error-reporting service
  // TODO: Check if the `user_id` within the `error` matches the currently logged-in user
  NSLog(@"Invalid SDK Authentication signature.");
  NSString *newSignature = getNewSignatureSomehow(error);
  [AppDelegate.braze setSDKAuthenticationSignature:newSignature];
}

1
2
3
4
5
6
7
8
9
10
11
12
let braze = Braze(configuration: configuration)
braze.sdkAuthDelegate = delegate
AppDelegate.braze = braze

// Method to implement in delegate
func braze(_ braze: Braze, sdkAuthenticationFailedWithError error: Braze.SDKAuthenticationError) {
  // TODO: Optionally log to your error-reporting service
  // TODO: Check if the `user_id` within the `error` matches the currently logged-in user
  print("Invalid SDK Authentication signature.")
  let newSignature = getNewSignatureSomehow(error)
  AppDelegate.braze?.set(sdkAuthenticationSignature: newSignature)
}

1
2
3
4
5
6
7
braze.setBrazeSdkAuthenticationErrorCallback((BrazeSdkAuthenticationError error) async {
  // TODO: Optionally log to your error-reporting service
  // TODO: Check if the `user_id` within the `error` matches the currently logged-in user
  print("Invalid SDK Authentication signature.")
  let newSignature = getNewSignatureSomehow(error)
  braze.setSdkAuthenticationSignature(newSignature);
});

Paso 3: Habilitar la autenticación en el panel de control

A continuación, puedes habilitar la autenticación en el panel de Braze para las aplicaciones que configuraste anteriormente.

Ten en cuenta que las solicitudes de SDK seguirán fluyendo como de costumbre sin autenticación, a menos que la configuración de Autenticación de SDK de la aplicación se establezca en Obligatorio en el panel de Braze.

Si algo va mal con tu integración (por ejemplo, tu aplicación está pasando tokens incorrectamente al SDK, o tu servidor está generando tokens no válidos), desactiva esta característica en el panel de Braze, y los datos volverán a fluir como de costumbre sin verificación.

Opciones de aplicación

En la página Administrar configuración del panel, cada aplicación tiene tres estados de Autenticación SDK que controlan cómo verifica Braze las solicitudes.

La configuración Opcional es una forma útil de controlar el impacto potencial que esta característica tendrá en el tráfico SDK de tu aplicación.

Las firmas JWT no válidas se notificarán tanto en el estado Opcional como en el Requerido, aunque sólo el estado Requerido rechazará las solicitudes SDK haciendo que las aplicaciones vuelvan a intentarlo y soliciten nuevas firmas.

Administrador de claves públicas

Añadir una clave pública

Puedes añadir hasta tres claves públicas para cada aplicación: una principal, una secundaria y una terciaria. También puedes añadir la misma clave a más de una aplicación si es necesario. Para añadir una clave pública:

1. Ve al panel de Braze y selecciona Configuración > Configuración de la aplicación .
2. Elige una aplicación de tu lista de aplicaciones disponibles.
3. En Autenticación SDK, selecciona Añadir clave pública.
4. Introduce una descripción opcional, pega tu clave pública y selecciona Añadir clave pública.

Asignar una nueva clave primaria

Para asignar una clave secundaria o terciaria como nueva clave primaria:

1. Ve al panel de Braze y selecciona Configuración > Configuración de la aplicación .
2. Elige una aplicación de tu lista de aplicaciones disponibles.
3. En Autenticación SDK, elige una clave y selecciona Gestionar > Convertir en clave principal.

Borrar una clave

Para eliminar una clave primaria, asigna primero una nueva primaria y luego elimina tu clave. Para borrar una clave no primaria:

1. Ve al panel de Braze y selecciona Configuración > Configuración de la aplicación .
2. Elige una aplicación de tu lista de aplicaciones disponibles.
3. En Autenticación SDK, elige una clave no primaria y selecciona Gestionar > Eliminar clave pública.

Análisis

Cada aplicación mostrará un desglose de los errores de Autenticación SDK recopilados mientras esta característica está en estado Opcional y Obligatorio.

Los datos están disponibles en tiempo real, y puedes pasar el ratón por encima de los puntos del gráfico para ver un desglose de los errores de una fecha determinada.

Códigos de error

Preguntas más frecuentes (FAQ)

¿Es necesario habilitar esta característica en todas mis aplicaciones al mismo tiempo?

No, esta característica puede habilitarse para aplicaciones concretas y no es necesario utilizarla en todas tus aplicaciones a la vez.

¿Qué ocurre con los usuarios que siguen utilizando versiones anteriores de mi aplicación?

Cuando empieces a aplicar esta característica, las solicitudes realizadas por versiones anteriores de la aplicación serán rechazadas por Braze y reintentadas por el SDK. Después de que los usuarios actualicen su aplicación a una versión compatible, esas solicitudes en cola empezarán a aceptarse de nuevo.

Si es posible, debes empujar a los usuarios a actualizarse como harías con cualquier otra actualización obligatoria. Alternativamente, puedes mantener la característica Opcional hasta que veas que un porcentaje aceptable de usuarios se ha actualizado.

¿Qué caducidad debo utilizar al generar tokens JWT?

Te recomendamos que utilices el valor más alto de la duración media de la sesión, la caducidad de la cookie/token de sesión o la frecuencia con la que tu aplicación actualizaría el perfil del usuario actual.

¿Qué ocurre si un JWT caduca en mitad de la sesión de un usuario?

Si el token de un usuario caduca a mitad de sesión, el SDK tiene una función de devolución de llamada que invocará para informar a tu aplicación de que se necesita un nuevo token JWT para seguir enviando datos a Braze.

¿Qué ocurre si mi integración en servidor se rompe y ya no puedo crear un JWT?

Si tu servidor no puede proporcionar tokens JWT o detectas algún problema de integración, siempre puedes desactivar la característica en el panel de Braze.

Una vez desactivado, el SDK reintentará cualquier solicitud fallida pendiente, y Braze la aceptará.

¿Por qué esta característica utiliza claves públicas/privadas en lugar de secretos compartidos?

Al utilizar secretos compartidos, cualquiera con acceso a ese secreto compartido, como la página del panel de Braze, podría generar tokens y suplantar la identidad de tus usuarios finales.

En su lugar, utilizamos claves públicas/privadas para que ni siquiera los Empleados de Braze (y mucho menos los usuarios de tu panel) tengan acceso a tus claves privadas.

¿Cómo se reintentarán las solicitudes rechazadas?

Cuando se rechaza una solicitud debido a un error de autenticación, el SDK invocará su devolución de llamada utilizada para actualizar la firma JWT del usuario.

Las solicitudes se reintentarán periódicamente utilizando un método de retirada exponencial. Después de 50 intentos fallidos consecutivos, los reintentos se pausarán hasta el siguiente inicio de sesión. Cada SDK también tiene un método para solicitar manualmente una descarga de datos.