Mise en place de l’authentification SDK

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

Fonctionnement

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

• Envoi d’événements personnalisés, d’attributs, d’achats et de données de session
• Créer de nouveaux utilisateurs dans votre espace de travail Braze
• Mise à jour des attributs de profil utilisateur standard
• Réception ou 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é de vos 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 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 avez votre clé privée, votre application côté serveur doit l’utiliser pour renvoyer un JWT à votre application ou site Internet pour l’utilisateur actuellement connecté.

En général, cette logique peut aller partout où votre application demande normalement le profil de l’utilisateur actuel, comme un endpoint de connexion ou partout où votre application a rafraîchi le profil de l’utilisateur actuel.

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

En-tête JWT

Charge utile JWT

Étape 2 : Configurer le SDK Braze

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

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

Lorsque cette fonctionnalité est activée, le SDK Braze ajoutera le dernier JWT connu de l’utilisateur actuel aux demandes réseau effectuées sur 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 actualiser la mi-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înent le rejet des demandes de SDK par Braze :

• Le JWT a expiré au moment où l’API Braze a été reçue
• JWT était vide ou manquant
• JWT n’a pas vérifié 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 à être averti lorsque les demandes SDK échouent pour l’une de ces raisons. Une fonction de rappel contient un objet avec les éléments suivants . errorCode, reason pour l’erreur, le userId de la demande (l’utilisateur ne peut pas être anonyme) et le jeton d’authentification (JWT) à l’origine de l’erreur.

Les demandes échouées seront périodiquement récupéré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 de Braze ce nouveau jeton valide.

Lorsque vous recevez une erreur d’authentification, vérifiez que l’adresse userId indiquée dans l’erreur correspond à l’utilisateur actuellement connecté, puis récupérez une nouvelle signature sur votre serveur et fournissez-la au SDK de 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 apps que vous avez configurées précédemment.

Gardez à l’esprit que les requêtes SDK continueront à circuler comme d’habitude sans authentification, sauf si le paramètre d’authentification SDK de l’app 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 comme d’habitude 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 obligatoire, mais seul l’état obligatoire rejettera les demandes de 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.

Attribuer une nouvelle clé primaire

Pour attribuer 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 > Faire une clé primaire.

Supprimer une clé

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

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 primaire et sélectionnez Gérer > Supprimer la clé publique.

Analyses

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

Les données sont disponibles en temps réel, et vous pouvez déplacer le curseur sur 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 sont toujours sur les versions antérieures de mon application ?

Lorsque vous commencez à faire appliquer cette fonctionnalité, les demandes effectuées par les versions anciennes d’applications seront rejetées par Braze et récupérées par les SDK. Une fois que les utilisateurs auront mis à jour leur application vers une version prise en charge, les demandes en file d’attente seront à nouveau acceptées.

Dans la mesure du possible, il convient de faire en sorte que les utilisateurs effectuent la mise à niveau comme pour toute autre mise à niveau obligatoire. Vous pouvez également laisser la fonctionnalité en option jusqu’à ce que vous constatiez qu’un pourcentage acceptable d’utilisateurs a effectué la mise à niveau.

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

Nous vous recommandons d’utiliser la valeur la plus élevée parmi : la durée moyenne de la session, l’expiration du cookie/jeton de la session, ou la fréquence à laquelle votre application rafraîchirait autrement le profil 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 à mi-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 un 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 demandes de SDK échouées en attente seront finalement récupérées par le SDK et acceptées par Braze.

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

Lors de l’utilisation de secrets partagés, toute personne ayant accès à ce secret partagé, 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 pour que ni même les employés de Braze (seuls les utilisateurs de votre tableau de bord) aient accès à vos clés privées.

Comment les demandes rejetées seront-elles récupérées ?

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

Les demandes réessaieront périodiquement en utilisant une approche de délais exponentielle. Après 50 tentatives consécutives échouées, les nouvelles tentatives seront interrompues jusqu’à la prochaine session. Chaque SDK dispose également d’une méthode qui permet de demander manuellement un rafraîchissement des données.

Pouvez-vous utiliser l’authentification SDK pour les utilisateurs anonymes ?

Non. L’authentification par le SDK ne fonctionne pas pour les utilisateurs anonymes.