Configurar la autenticación del 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 un token web JSON (JWT) no válido 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 de Braze
• Actualización de los atributos estándar del perfil de usuario
• Recibir o desencadenar mensajes

Ahora puedes evitar que los usuarios que hayan iniciado sesión sin autenticarse utilicen la clave de API de SDK de tu aplicación para realizar acciones maliciosas, como la suplantación de identidad.

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 de conexión 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 en 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 de Braze.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

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
4
5
6
7
8
9
10
11
12
import BrazeKit
import braze_react_native_sdk

let configuration = Braze.Configuration(
  apiKey: "{YOUR-BRAZE-API-KEY}",
  endpoint: "{YOUR-BRAZE-ENDPOINT}"
)
configuration.api.sdkAuthentication = true
let braze = BrazeReactBridge.perform(
  #selector(BrazeReactBridge.initBraze(_:)),
  with: configuration
).takeUnretainedValue() as! Braze

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

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

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

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
<key>SDKAuthenticationEnabled</key>
<true/>

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
<preference name="com.braze.ios_enable_sdk_authentication" value="true" />

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
3
var configuration = new BRZConfiguration("YOUR-API-KEY", "YOUR-ENDPOINT");
configuration.Api.SdkAuthentication = true;
var braze = new Braze(configuration);

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
3
4
5
6
7
8
9
10
11
12
{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          "enableSdkAuthentication": true
        }
      ]
    ]
  }
}

Paso 2.2: Establece el JWT del usuario actual

Cada vez que tu aplicación llame al método changeUser de Braze, proporciona también el 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.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

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

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

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

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

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

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

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

1
[AppDelegate.braze changeUser:@"userId" sdkAuthSignature:@"JWT-FROM-SERVER"];

1
[AppDelegate.braze setSDKAuthenticationSignature:@"NEW-JWT-FROM-SERVER"];

1
AppDelegate.braze?.changeUser(userId: "userId", sdkAuthSignature: "JWT-FROM-SERVER")

1
AppDelegate.braze?.set(sdkAuthenticationSignature: "NEW-JWT-FROM-SERVER")

1
braze.changeUser("userId", sdkAuthSignature: "JWT-FROM-SERVER")

1
braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER")

1
2
3
4
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();
braze.changeUser("NEW-USER-ID", sdkAuthSignature: "JWT-FROM-SERVER");

1
2
3
4
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();
braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
BrazeBinding.ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
BrazeBinding.SetSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
BrazePlugin.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
BrazePlugin.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.SharedInstance?.ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
Braze.SharedInstance?.SetSDKAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.GetInstance(this).ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
Braze.GetInstance(this).SetSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

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

Cuando esta característica se establece como Obligatoria, los siguientes escenarios harán que las solicitudes del 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 el JWT para las claves públicas que cargaste 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 el errorCode relevante, el motivo (reason) del error, el userId de la solicitud (el usuario no puede ser anónimo) y el token de autenticación (JWT) 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.

Cuando recibas un error de autenticación, comprueba que el userId del error coincide con tu usuario actualmente conectado, luego obtén una nueva firma de tu servidor y proporciónala al SDK de Braze. También puedes registrar estos errores en tu servicio de supervisión o de notificación de errores.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import * as braze from "@braze/web-sdk";

braze.subscribeToSdkAuthenticationFailures((error) => {
  console.error("SDK authentication failed:", error);
  console.log("Error code:", error.errorCode);
  console.log("User ID:", error.userId);
  // Note: Do not log error.signature as it contains sensitive authentication credentials
  
  // Verify the error.userId matches the currently logged-in user
  // Fetch a new token from your server and set it
  fetchNewSignature(error.userId).then((newSignature) => {
    braze.setSdkAuthenticationSignature(newSignature);
  });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import Braze from '@braze/react-native-sdk';

const sdkAuthErrorSubscription = Braze.addListener(
  Braze.Events.SDK_AUTHENTICATION_ERROR,
  (error) => {
    console.log(`SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.`);
    
    const updated_jwt = getNewTokenSomehow(error);
    Braze.setSdkAuthenticationSignature(updated_jwt);
  }
);

// Don't forget to remove the listener when done
// sdkAuthErrorSubscription.remove();

1
2
3
4
Braze.getInstance(this).subscribeToSdkAuthenticationFailures(error -> {
    String newToken = getNewTokenSomehow(error);
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken);
});

1
2
3
4
Braze.getInstance(this).subscribeToSdkAuthenticationFailures({ error: BrazeSdkAuthenticationErrorEvent ->
    val newToken: String = getNewTokenSomehow(error)
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken)
})

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

// Method to implement in delegate
- (void)braze:(Braze *)braze sdkAuthenticationFailedWithError:(BRZSDKAuthenticationError *)error {
  NSLog(@"Invalid SDK Authentication Token.");
  NSString *newSignature = getNewTokenSomehow(error);
  [AppDelegate.braze setSDKAuthenticationSignature:newSignature];
}

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

// Method to implement in delegate
func braze(_ braze: Braze, sdkAuthenticationFailedWithError error: Braze.SDKAuthenticationError) {
  print("Invalid SDK Authentication Token.")
  let newSignature = getNewTokenSomehow(error)
  AppDelegate.braze?.set(sdkAuthenticationSignature: newSignature)
}

1
2
3
4
5
braze.setBrazeSdkAuthenticationErrorCallback((BrazeSdkAuthenticationError error) async {
  print("Invalid SDK Authentication Token.");
  final newSignature = getNewTokenSomehow(error);
  braze.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
10
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();

braze.setBrazeSdkAuthenticationErrorCallback((BrazeSdkAuthenticationError error) async {
  print("SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.");
  
  String newSignature = getNewTokenSomehow(error);
  braze.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
public class SdkAuthDelegate : BRZSdkAuthDelegate
{
  public void Braze(Braze braze, BRZSDKAuthenticationError error)
  {
    Debug.Log("Invalid SDK Authentication Token.");
    string newSignature = GetNewTokenSomehow(error);
    BrazeBinding.SetSdkAuthenticationSignature(newSignature);
  }
}

1
2
3
4
Braze.GetInstance(this).SubscribeToSdkAuthenticationFailures((error) => {
  string newToken = GetNewTokenSomehow(error);
  Braze.GetInstance(this).SetSdkAuthenticationSignature(newToken);
});

1
2
3
4
5
6
BrazePlugin.subscribeToSdkAuthenticationFailures((error) => {
  console.log(`SDK Authentication for ${error.user_id} failed with error code ${error.error_code}.`);
  
  const newSignature = getNewTokenSomehow(error);
  BrazePlugin.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class SdkAuthDelegate : BRZSdkAuthDelegate
{
  public override void Braze(Braze braze, BRZSDKAuthenticationError error)
  {
    Console.WriteLine("Invalid SDK Authentication Token.");
    string newSignature = GetNewTokenSomehow(error);
    Braze.SharedInstance?.SetSDKAuthenticationSignature(newSignature);
  }
}

// Set the delegate during initialization
var configuration = new BRZConfiguration("YOUR-API-KEY", "YOUR-ENDPOINT");
configuration.Api.SdkAuthentication = true;
var braze = new Braze(configuration);
braze.SdkAuthDelegate = new SdkAuthDelegate();

1
2
3
4
Braze.GetInstance(this).SubscribeToSdkAuthenticationFailures((error) => {
  string newToken = GetNewTokenSomehow(error);
  Braze.GetInstance(this).SetSdkAuthenticationSignature(newToken);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import Braze from '@braze/react-native-sdk';

const sdkAuthErrorSubscription = Braze.addListener(
  Braze.Events.SDK_AUTHENTICATION_ERROR,
  (error) => {
    console.log(`SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.`);
    
    const updated_jwt = getNewTokenSomehow(error);
    Braze.setSdkAuthenticationSignature(updated_jwt);
  }
);

// Don't forget to remove the listener when done
// sdkAuthErrorSubscription.remove();

Paso 3: Habilita la autenticación en el dashboard

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

Ten en cuenta que las solicitudes del SDK seguirán fluyendo como de costumbre sin autenticación, a menos que la configuración de autenticación del SDK de la aplicación se establezca en Obligatoria 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 dashboard, cada aplicación tiene tres estados de autenticación del 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 del SDK de tu aplicación.

Se notificará un JWT no válido tanto en estado Opcional como Obligatoria, sin embargo, solo el estado Obligatoria rechazará las solicitudes del SDK, lo que provocará que las aplicaciones vuelvan a intentarlo y soliciten un nuevo JWT.

Administración 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 del 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 del SDK, elige una clave y selecciona Gestionar > Convertir en clave principal.

Eliminar una clave

Para eliminar una clave primaria, asigna primero una nueva primaria y luego elimina tu clave. Para eliminar 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 del 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 del SDK recopilados mientras esta característica está en estado Opcional y Obligatoria.

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 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 animar a los usuarios a actualizarse como harías con cualquier otra actualización obligatoria. Alternativamente, puedes mantener la característica como Opcional hasta que veas que un porcentaje aceptable de usuarios se ha actualizado.

¿Qué caducidad debo usar al generar un 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 durante la 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 JWT para continuar 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 un JWT o detectas algún problema de integración, siempre puedes desactivar la característica en el panel de Braze.

Una vez desactivada, 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 empresa) tengan acceso a tus claves privadas.

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

Cuando una solicitud es rechazada debido a un error de autenticación, el SDK invocará tu devolución de llamada utilizada para actualizar el JWT del usuario.

Las solicitudes se reintentarán periódicamente utilizando un backoff 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 un vaciado de datos.

¿Se puede utilizar la autenticación del SDK para usuarios anónimos?

No. La autenticación del SDK funciona cuando tu sitio web confirma la identidad de alguien, por lo que solo se aplica a usuarios identificados. Como usuario anónimo, no hay identidad que confirmar.

La aplicación comienza después de llamar a changeUser. Antes de que un usuario sea identificado (por ejemplo, mientras navega de forma anónima antes de registrarse), el SDK puede seguir enviando datos a Braze sin un JWT. Después de llamar a changeUser, las solicitudes para ese perfil identificado requieren un JWT válido.

Esto significa que un recorrido típico de usuario podría verse así:

1. Un usuario visita tu sitio o abre tu aplicación de forma anónima. Braze recopila esta actividad sin un JWT.
2. El usuario se registra o inicia sesión, y tu aplicación llama a changeUser con un external_id.
3. Braze continúa recopilando la actividad de ese usuario, y la autenticación del SDK se aplica a las solicitudes de ese perfil identificado.

¿Funciona la autenticación del SDK con alias de usuario?

No. La autenticación del SDK requiere un external_id. No puedes configurarla cuando solo hay un braze_id o alias_id disponible, por lo que los perfiles que solo tienen alias no pueden usar la autenticación del SDK.

¿Habilitar la autenticación del SDK bloquea la recopilación de actividad no autenticada?

No. La autenticación del SDK no bloquea la recopilación legítima de actividad anónima. Solo se aplica después de que un perfil es identificado con changeUser.