Configurer l’authentification SDK

L’authentification SDK vous permet de fournir des preuves cryptographiques (générées côté serveur) aux requêtes SDK effectuées au nom des utilisateurs connectés.

Fonctionnement

Après avoir activé cette fonctionnalité dans votre application, vous pouvez configurer le tableau de bord de Braze pour qu’il rejette toute requête avec un jeton Web JSON (JWT) invalide ou manquant, ce qui inclut :

• L’envoi d’événements personnalisés, d’attributs, d’achats et de données de session
• La création de nouveaux utilisateurs dans votre espace de travail Braze
• La mise à jour des attributs de profil utilisateur standard
• La réception ou le déclenchement de messages

Vous pouvez désormais empêcher les utilisateurs connectés non authentifiés d’utiliser la clé API SDK de votre application pour effectuer des actions malveillantes, telles que l’usurpation d’identité d’autres utilisateurs.

Mise en place de l’authentification

Étape 1 : Configurez votre serveur

Étape 1.1 : Générer une paire de clés publiques/privées

Générez une paire de clés publiques/privées RSA256. La clé publique sera ajoutée au tableau de bord de Braze, tandis que la clé privée devra être stockée en toute sécurité sur votre serveur.

Nous recommandons une clé RSA de 2048 bits pour une utilisation avec l’algorithme JWT RS256.

Étape 1.2 : Créer un jeton Web JSON pour l’utilisateur actuel

Une fois que vous disposez de votre clé privée, votre application côté serveur doit l’utiliser pour renvoyer un JWT à votre application ou site web pour l’utilisateur actuellement connecté.

En général, cette logique peut être placée partout où votre application demande normalement le profil de l’utilisateur actuel, comme un endpoint de connexion ou partout où votre application actualise le profil de l’utilisateur actuel.

Lors de la génération du JWT, les champs suivants sont attendus :

En-tête JWT

PAYLOAD JWT

Étape 2 : Configurer le SDK

Cette fonctionnalité est disponible à partir des versions SDK suivantes :

Étape 2.1 : Activer l’authentification dans le SDK Braze.

Lorsque cette fonctionnalité est activée, le SDK Braze ajoutera le dernier JWT connu de l’utilisateur actuel aux requêtes réseau effectuées vers les serveurs 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
        }
      ]
    ]
  }
}

Étape 2.2 : Définir le JWT de l’utilisateur actuel

Lorsque votre application appelle la méthode Braze changeUser, fournissez également le JWT qui a été généré côté serveur.

Vous pouvez également configurer le jeton pour qu’il s’actualise en cours de session pour l’utilisateur actuel.

• 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");

Étape 2.3 : Enregistrer une fonction de rappel pour les jetons invalides

Lorsque cette fonctionnalité est définie comme Requise, les scénarios suivants entraîneront le rejet des requêtes SDK par Braze :

• Le JWT avait expiré au moment où il a été reçu par l’API Braze
• Le JWT était vide ou manquant
• Le JWT n’a pas pu être vérifié avec les clés publiques que vous avez téléchargées sur le tableau de bord de Braze

Vous pouvez utiliser subscribeToSdkAuthenticationFailures pour vous abonner aux notifications lorsque les requêtes SDK échouent pour l’une de ces raisons. Une fonction de rappel contient un objet avec le errorCode correspondant, la reason de l’erreur, le userId de la requête (l’utilisateur ne peut pas être anonyme) et le jeton d’authentification (JWT) à l’origine de l’erreur.

Les requêtes échouées seront périodiquement relancées jusqu’à ce que votre application fournisse un nouveau JWT valide. Si cet utilisateur est toujours connecté, vous pouvez profiter de ce rappel pour demander un nouveau JWT à votre serveur et fournir au SDK Braze ce nouveau jeton valide.

Lorsque vous recevez une erreur d’authentification, vérifiez que le userId dans l’erreur correspond à celui de l’utilisateur actuellement connecté, puis récupérez une nouvelle signature depuis votre serveur et fournissez-la au SDK Braze. Vous pouvez également enregistrer ces erreurs dans votre service de surveillance ou de signalement des erreurs.

• 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();

Étape 3 : Activer l’authentification dans le tableau de bord

Ensuite, vous pouvez activer l’authentification dans le tableau de bord de Braze pour les applications que vous avez configurées précédemment.

Gardez à l’esprit que les requêtes SDK continueront à circuler normalement sans authentification, sauf si le paramètre d’authentification SDK de l’application est défini sur Requis dans le tableau de bord de Braze.

En cas de problème avec votre intégration (par exemple, votre application transmet incorrectement des jetons au SDK ou votre serveur génère des jetons invalides), désactivez cette fonctionnalité dans le tableau de bord de Braze, et les données recommenceront à circuler normalement sans vérification.

Options d’application

Dans la page Gérer les paramètres du tableau de bord, chaque application dispose de trois états d’authentification SDK qui contrôlent la manière dont Braze vérifie les requêtes.

Le paramètre Facultatif est un moyen utile de surveiller l’impact potentiel de cette fonctionnalité sur le trafic SDK de votre application.

Un JWT invalide sera signalé dans les deux états Facultatif et Requis, mais seul l’état Requis rejettera les requêtes SDK, obligeant les applications à réessayer et à demander un nouveau JWT.

Gérer les clés publiques

Ajouter une clé publique

Vous pouvez ajouter jusqu’à trois clés publiques pour chaque application : une clé principale, une clé secondaire et une clé tertiaire. Si nécessaire, vous pouvez également ajouter la même clé à plusieurs applications. Pour ajouter une clé publique :

1. Rendez-vous sur le tableau de bord de Braze et sélectionnez Paramètres > Paramètres de l’application.
2. Choisissez une application dans votre liste d’applications disponibles.
3. Sous Authentification SDK, sélectionnez Ajouter une clé publique.
4. Saisissez une description facultative, collez votre clé publique, puis sélectionnez Ajouter une clé publique.

Affecter une nouvelle clé principale

Pour affecter une clé secondaire ou tertiaire comme nouvelle clé principale :

1. Rendez-vous sur le tableau de bord de Braze et sélectionnez Paramètres > Paramètres de l’application.
2. Choisissez une application dans votre liste d’applications disponibles.
3. Sous Authentification SDK, choisissez une clé et sélectionnez Gérer > Définir comme clé principale.

Supprimer une clé

Pour supprimer une clé principale, affectez d’abord une nouvelle clé principale, puis supprimez votre clé. Pour supprimer une clé non principale :

1. Rendez-vous sur le tableau de bord de Braze et sélectionnez Paramètres > Paramètres de l’application.
2. Choisissez une application dans votre liste d’applications disponibles.
3. Sous Authentification SDK, choisissez une clé non principale et sélectionnez Gérer > Supprimer la clé publique.

Analyses

Chaque application affiche une ventilation des erreurs d’authentification SDK collectées lorsque cette fonctionnalité est dans l’état Facultatif ou Requis.

Les données sont disponibles en temps réel, et vous pouvez survoler les points du graphique pour voir la répartition des erreurs pour une date donnée.

Codes d’erreur

Foire aux questions (FAQ)

Cette fonctionnalité doit-elle être activée sur toutes mes applications en même temps ?

Non, cette fonctionnalité peut être activée pour des applications spécifiques et n’a pas besoin d’être utilisée sur toutes vos applications en même temps.

Que se passe-t-il pour les utilisateurs qui utilisent encore des versions antérieures de mon application ?

Lorsque vous commencez à appliquer cette fonctionnalité, les requêtes effectuées par les versions antérieures de l’application seront rejetées par Braze et relancées par le SDK. Une fois que les utilisateurs auront mis à jour leur application vers une version prise en charge, les requêtes en file d’attente seront à nouveau acceptées.

Dans la mesure du possible, vous devriez inciter les utilisateurs à effectuer la mise à jour comme pour toute autre mise à niveau obligatoire. Vous pouvez également laisser la fonctionnalité en mode Facultatif jusqu’à ce qu’un pourcentage acceptable d’utilisateurs ait effectué la mise à jour.

Quelle expiration dois-je utiliser lors de la génération d’un JWT ?

Nous recommandons d’utiliser la valeur la plus élevée parmi : la durée moyenne de session, l’expiration du cookie/jeton de session, ou la fréquence à laquelle votre application actualise normalement le profil de l’utilisateur actuel.

Que se passe-t-il si un JWT expire au milieu de la session d’un utilisateur ?

Si le jeton d’un utilisateur expire en cours de session, le SDK dispose d’une fonction de rappel qu’il invoquera pour indiquer à votre application qu’un nouveau JWT est nécessaire pour continuer à envoyer des données à Braze.

Que se passe-t-il si mon intégration côté serveur est interrompue et que je ne peux plus créer de JWT ?

Si votre serveur n’est pas en mesure de fournir un JWT ou si vous remarquez un problème d’intégration, vous pouvez toujours désactiver la fonctionnalité dans le tableau de bord de Braze.

Une fois désactivée, toutes les requêtes SDK échouées en attente seront finalement relancées par le SDK et acceptées par Braze.

Pourquoi cette fonctionnalité utilise-t-elle des clés publiques/privées plutôt que des secrets partagés ?

Avec des secrets partagés, toute personne ayant accès à ce secret, comme la page du tableau de bord de Braze, serait en mesure de générer des jetons et d’usurper l’identité de vos utilisateurs finaux.

Nous utilisons plutôt des clés publiques/privées afin que même les employés de Braze (et a fortiori les utilisateurs de votre entreprise) n’aient pas accès à vos clés privées.

Comment les requêtes rejetées seront-elles relancées ?

Lorsqu’une requête est rejetée en raison d’une erreur d’authentification, le SDK invoque votre rappel utilisé pour actualiser le JWT de l’utilisateur.

Les requêtes seront relancées périodiquement selon une approche de délais exponentiels. Après 50 tentatives consécutives échouées, les nouvelles tentatives seront suspendues jusqu’au début de la prochaine session. Chaque SDK dispose également d’une méthode permettant de demander manuellement un envoi des données.

Est-il possible d’utiliser l’authentification SDK pour les utilisateurs anonymes ?

Non. L’authentification SDK fonctionne en faisant valider l’identité d’une personne par votre site web, elle ne s’applique donc qu’aux utilisateurs identifiés. En tant qu’utilisateur anonyme, il n’y a pas d’identité à valider.

L’application de l’authentification commence après l’appel à changeUser. Avant qu’un utilisateur ne soit identifié (par exemple, lorsqu’il navigue de manière anonyme avant de s’inscrire), le SDK peut toujours envoyer des données à Braze sans JWT. Après l’appel à changeUser, les requêtes pour ce profil identifié nécessitent un JWT valide.

Cela signifie qu’un parcours utilisateur typique pourrait ressembler à ceci :

1. Un utilisateur visite votre site ou ouvre votre application de manière anonyme. Braze collecte cette activité sans JWT.
2. L’utilisateur s’inscrit ou se connecte, et votre application appelle changeUser avec un external_id.
3. Braze continue de collecter l’activité pour cet utilisateur, et l’authentification SDK est appliquée pour les requêtes concernant ce profil identifié.

L’authentification SDK fonctionne-t-elle avec les alias d’utilisateur ?

Non. L’authentification SDK nécessite un external_id. Vous ne pouvez pas la configurer lorsque seul un braze_id ou un alias_id est disponible, les profils avec alias uniquement ne peuvent donc pas utiliser l’authentification SDK.

L’activation de l’authentification SDK bloque-t-elle la collecte d’activité non authentifiée ?

Non. L’authentification SDK ne bloque pas la collecte légitime d’activité anonyme. Elle ne s’applique qu’après l’identification d’un profil avec changeUser.