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.

Après avoir activé cette fonctionnalité dans votre app, vous pouvez configurer le tableau de bord de Braze pour qu’il rejette toute demande dont la signature de jeton Web JSON (JWT) est invalide ou manquante, 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 de l’identité d’autres utilisateurs.

Démarrage

Il existe quatre étapes de haut niveau pour commencer :

1. Intégration côté serveur - Générez une paire de clés publique et privée et utilisez votre clé privée pour créer un JWT pour l’utilisateur connecté actuel.
   
   
2. Intégration SDK - Activez cette fonctionnalité dans le SDK Braze et demandez le JWT généré à partir de votre serveur.
   
   
3. Ajout de clés publiques - Ajoutez votre clé publique au tableau de bord de Braze dans la page Gérer les paramètres.
   
   
4. Basculer l’application dans le tableau de bord de Braze - Basculez l’application de cette fonctionnalité dans le tableau de bord de Braze, application par application.

Intégration côté serveur

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.

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

Bibliothèques JWT

Pour en savoir plus sur les jetons Web JSON ou pour parcourir les nombreuses bibliothèques open source qui simplifient ce processus de signature, consultez https://jwt.io.

Intégration SDK

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

Activez cette fonction dans le SDK 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.

• javascript
• java
• kotlin
• objectif-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

Définir le jeton JWT de l’utilisateur actuel

Lorsque votre application appelle la méthode changeUser Braze, fournissez également le jeton 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.

• javascript
• java
• kotlin
• objectif-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")

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 informations suivantes errorCode, reason pour l’erreur, le userId de la demande (si l’utilisateur n’est pas anonyme) et le signature d’authentification qui a causé 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.

• javascript
• java
• kotlin
• objectif-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);
});

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.

Activation dans le tableau de bord de Braze

Une fois l’intégration côte à côte avec le serveur et l’intégration SDK terminées, vous pouvez commencer à activer cette fonctionnalité pour ces applications spécifiques.

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.

Les signatures JWT non valides seront signalées à la fois dans l’état facultatif et dans l’état obligatoire, mais seul l’état obligatoire rejettera les demandes de SDK, ce qui obligera les applications à réessayer et à demander de nouvelles signatures.

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

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 de jetons 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 a une fonction de rappel. Celle-ci permet d’indiquer à votre application qu’un nouveau jeton 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 des jetons JWT ou si vous remarquez un problème d’intégration, vous pouvez toujours désactiver la fonction 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, les SDK invoqueront votre fonction de rappel utilisé pour actualiser la signature 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.