Configurar autenticação do SDK

A autenticação do SDK permite fornecer prova criptográfica (gerada no lado do servidor) para solicitações do SDK feitas em nome de usuários registrados.

Como funciona

Depois de ativar esse recurso em seu app, você pode configurar o dashboard da Braze para rejeitar quaisquer solicitações com um JSON Web Token (JWT) inválido ou ausente, o que inclui:

• Envio de eventos personalizados, atributos, compras e dados de sessão
• Criação de novos usuários em seu espaço de trabalho da Braze
• Atualização de atributos padrão do perfil de usuário
• Receber ou disparar mensagens

Agora você pode impedir que usuários conectados não autenticados usem a chave de API do SDK do seu app para realizar ações maliciosas, como simular a identidade de outros usuários.

Configurando a autenticação

Etapa 1: Configure seu servidor

Etapa 1.1: Gerar um par de chaves pública/privada

Gere um par de chaves pública/privada RSA256. A chave pública será eventualmente adicionada ao dashboard da Braze, enquanto a chave privada deverá ser armazenada com segurança em seu servidor.

Recomendamos usar uma chave RSA com 2048 bits para uso com o algoritmo RS256 JWT.

Etapa 1.2: Crie um JSON Web Token para o usuário atual

Depois de obter a chave privada, o aplicativo no lado do servidor deve usá-la para retornar um JWT ao seu app ou site para o usuário atualmente registrado.

Normalmente, essa lógica pode ser acessada em qualquer lugar em que o aplicativo normalmente solicite o perfil do usuário atual, como um endpoint de login ou em qualquer lugar em que o aplicativo atualize o perfil do usuário atual.

Ao gerar o JWT, os seguintes campos são esperados:

Cabeçalho JWT

Carga útil do JWT

Etapa 2: Configurar o SDK

Este recurso está disponível nas seguintes versões do SDK:

Etapa 2.1: Ative a autenticação no SDK da Braze.

Quando esse recurso for ativado, o SDK da Braze anexará o último JWT conhecido do usuário atual às solicitações de rede feitas aos servidores da 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
        }
      ]
    ]
  }
}

Etapa 2.2: Definir o JWT do usuário atual

Sempre que seu app chamar o método changeUser da Braze, forneça também o JWT que foi gerado no lado do servidor.

Também é possível configurar o token para ser atualizado no meio da sessão para o usuário atual.

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

Etapa 2.3: Registre uma função de retorno de chamada para tokens inválidos

Quando esse recurso for definido como Obrigatório, os cenários a seguir farão com que as solicitações do SDK sejam rejeitadas pela Braze:

• O JWT expirou no momento em que foi recebido pela API da Braze
• O JWT estava vazio ou ausente
• Falha na verificação do JWT para as chaves públicas cujo upload foi feito para o dashboard da Braze

Você pode usar subscribeToSdkAuthenticationFailures para se inscrever e ser notificado quando as solicitações do SDK falharem por um desses motivos. Uma função de retorno de chamada contém um objeto com o errorCode relevante, o reason do erro, o userId da solicitação (o usuário não pode ser anônimo) e o token de autenticação (JWT) que causou o erro.

As solicitações com falha serão repetidas periodicamente até que seu app forneça um novo JWT válido. Se o usuário ainda estiver registrado, você poderá usar esse retorno de chamada como uma oportunidade para solicitar um novo JWT do seu servidor e fornecer ao SDK da Braze esse novo token válido.

Quando você receber um erro de autenticação, verifique se o userId no erro corresponde ao usuário atualmente conectado, em seguida, obtenha uma nova assinatura do seu servidor e forneça-a ao SDK da Braze. Você também pode registrar esses erros em seu serviço de monitoramento ou relatório de erros.

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

Etapa 3: Ative a autenticação no dashboard

Em seguida, você pode ativar a autenticação no dashboard da Braze para os apps que você configurou anteriormente.

Lembre-se de que as solicitações do SDK continuarão a fluir normalmente sem autenticação, a menos que a configuração de autenticação do SDK do app esteja definida como Obrigatória no dashboard da Braze.

Se algo der errado com sua integração (por exemplo, seu app está passando tokens incorretamente para o SDK ou seu servidor está gerando tokens inválidos), desative esse recurso no dashboard da Braze e os dados voltarão a fluir normalmente sem verificação.

Opções de aplicação

Na página Gerenciar configurações do dashboard, cada app tem três estados de autenticação do SDK que controlam como a Braze verifica as solicitações.

A configuração Opcional é uma maneira útil de monitorar o impacto potencial que esse recurso terá no tráfego do SDK do seu app.

Um JWT inválido será relatado nos estados Opcional e Obrigatório, porém apenas o estado Obrigatório rejeitará as solicitações do SDK, fazendo com que os apps tentem novamente e solicitem um novo JWT.

Gerenciamento de chaves públicas

Adição de uma chave pública

Você pode adicionar até três chaves públicas para cada app: uma primária, uma secundária e uma terciária. Você também pode adicionar a mesma chave a mais de um app, se necessário. Para adicionar uma chave pública:

1. Acesse o dashboard da Braze e selecione Configurações > Configurações do app.
2. Escolha um app da sua lista de apps disponíveis.
3. Em Autenticação do SDK, selecione Adicionar chave pública.
4. Insira uma descrição opcional, cole sua chave pública e selecione Adicionar chave pública.

Atribuir uma nova chave primária

Para atribuir uma chave secundária ou terciária como sua nova chave primária:

1. Acesse o dashboard da Braze e selecione Configurações > Configurações do app.
2. Escolha um app da sua lista de apps disponíveis.
3. Em Autenticação do SDK, escolha uma chave e selecione Gerenciar > Tornar chave primária.

Exclusão de uma chave

Para excluir uma chave primária, primeiro atribua uma nova primária e, em seguida, exclua sua chave. Para excluir uma chave não primária:

1. Acesse o dashboard da Braze e selecione Configurações > Configurações do app.
2. Escolha um app da sua lista de apps disponíveis.
3. Em Autenticação do SDK, escolha uma chave não primária e selecione Gerenciar > Excluir chave pública.

Análise de dados

Cada app mostrará um detalhamento dos erros de autenticação do SDK coletados enquanto esse recurso estiver no estado Opcional e Obrigatório.

Os dados estão disponíveis em tempo real, e você pode passar o mouse sobre os pontos do gráfico para ver um detalhamento dos erros de uma determinada data.

Códigos de erro

Perguntas frequentes (FAQ)

Esse recurso precisa ser ativado em todos os meus apps ao mesmo tempo?

Não, esse recurso pode ser ativado para apps específicos e não precisa ser usado em todos os seus apps de uma só vez.

O que acontece com os usuários que ainda estão em versões mais antigas do meu app?

Quando você começar a aplicar esse recurso, as solicitações feitas por versões mais antigas do app serão rejeitadas pela Braze e tentadas novamente pelo SDK. Depois que os usuários fizerem upgrade do app para uma versão compatível, essas solicitações enfileiradas começarão a ser aceitas novamente.

Se possível, incentive os usuários a fazer upgrade como faria para qualquer outra atualização obrigatória. Como alternativa, você pode manter o recurso como Opcional até perceber que uma porcentagem aceitável de usuários fez upgrade.

Que validade devo usar ao gerar um JWT?

Recomendamos usar o valor mais alto entre: duração média da sessão, expiração do cookie/token da sessão ou a frequência com que o aplicativo atualizaria o perfil do usuário atual.

O que acontece se um JWT expirar no meio da sessão de um usuário?

Caso o token de um usuário expire no meio da sessão, o SDK possui uma função de retorno de chamada que será invocada para informar ao seu app que um novo JWT é necessário para continuar enviando dados para a Braze.

O que acontecerá se minha integração no lado do servidor falhar e eu não puder mais criar um JWT?

Se o seu servidor não conseguir fornecer um JWT ou se você notar algum problema de integração, você sempre pode desativar o recurso no dashboard da Braze.

Uma vez desativado, todas as solicitações pendentes do SDK que falharam serão eventualmente repetidas pelo SDK e aceitas pela Braze.

Por que esse recurso usa chaves pública/privada em vez de segredos compartilhados?

Ao usar segredos compartilhados, qualquer pessoa com acesso a esse segredo compartilhado, como a página do dashboard da Braze, poderá gerar tokens e se passar por seus usuários finais.

Em vez disso, usamos chaves pública/privada para que nem mesmo os colaboradores da Braze (muito menos os usuários da sua empresa) tenham acesso às suas chaves privadas.

Como as solicitações rejeitadas serão tentadas novamente?

Quando uma solicitação é rejeitada devido a um erro de autenticação, o SDK invocará seu retorno de chamada usado para atualizar o JWT do usuário.

As solicitações serão repetidas periodicamente usando uma abordagem de backoff exponencial. Após 50 tentativas consecutivas sem sucesso, as novas tentativas serão pausadas até o início da próxima sessão. Cada SDK também tem um método para solicitar manualmente uma descarga de dados.

É possível usar a autenticação do SDK para usuários anônimos?

Não. A autenticação do SDK funciona com seu site confirmando a identidade de alguém, então ela se aplica apenas a usuários identificados. Como usuário anônimo, não há identidade a ser confirmada.

A aplicação começa após a chamada de changeUser. Antes de um usuário ser identificado (por exemplo, enquanto navega anonimamente antes de se cadastrar), o SDK ainda pode enviar dados para a Braze sem um JWT. Após a chamada de changeUser, as solicitações para esse perfil identificado exigem um JWT válido.

Isso significa que uma jornada típica de usuário pode ser assim:

1. Um usuário visita seu site ou abre seu app anonimamente. A Braze coleta essa atividade sem um JWT.
2. O usuário se cadastra ou faz login, e seu app chama changeUser com um external_id.
3. A Braze continua coletando atividade para esse usuário, e a autenticação do SDK é aplicada para solicitações desse perfil identificado.

A autenticação do SDK funciona com aliases de usuário?

Não. A autenticação do SDK requer um external_id. Não é possível configurá-la quando apenas um braze_id ou alias_id está disponível, então perfis somente com alias não podem usar a autenticação do SDK.

Ativar a autenticação do SDK bloqueia a coleta de atividade não autenticada?

Não. A autenticação do SDK não bloqueia a coleta legítima de atividade anônima. Ela se aplica apenas após um perfil ser identificado com changeUser.