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.

Depois de ativar esse recurso em seu app, você pode configurar o dashboard da Braze para rejeitar quaisquer solicitações com uma assinatura JSON Web Token (JWT) inválida 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 no Braze
• Atualização das atribuições do perfil de usuário padrão
• Receber ou disparar mensagens

Agora é possível impedir que usuários registrados não autenticados usem a chave de API SDK do seu app para executar ações mal-intencionadas, como simulação de outros usuários.

Primeiros passos

Há quatro etapas de alto nível para começar:

1. Integração lado a lado com o servidor - Gere um par de chaves públicas e privadas e use sua chave privada para criar um JWT para o usuário atualmente registrado.
   
   
2. Integração de SDK - Ative esse recurso no SDK da Braze e solicite o JWT gerado em seu servidor.
   
   
3. Adição de chaves públicas - Adicione sua chave pública ao dashboard do Braze na página Gerenciar configurações.
   
   
4. Alternar a aplicação no dashboard da Braze - Alternar a aplicação desse recurso no dashboard da Braze em uma base de aplicativo por aplicativo.

Integração lado a lado com o servidor

Gerar um par de chaves públicas/privadas

Gerar um par de chaves públicas/privadas 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 de RSA com 2048 bits para uso com o algoritmo RS256 JWT.

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

Bibliotecas JWT

Para saber mais sobre os tokens da Web JSON ou para navegar pelas muitas bibliotecas de código aberto que simplificam esse processo de fazer login, consulte https://jwt.io.

integração de SDK

Esse recurso está disponível a partir das seguintes versões do SDK:

Ative esse recurso no SDK da Braze.

Quando essa capacitação for ativada, o SDK da Braze anexará o último JWT conhecido do usuário atual às solicitações de rede feitas aos Braze Currents.

• javascript
• java
• kotlin
• objective c
• rápido
• 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

Definir o token JWT do usuário atual

Sempre que seu app chamar o método Braze changeUser, forneça também o token 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.

• javascript
• java
• kotlin
• objective c
• rápido
• 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")

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 de SDK sejam rejeitadas pelo Braze:

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

Você pode usar o site 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 os dados relevantes errorCodereason para o erro, o userId da solicitação (se o usuário não for anônimo) e a autenticação signature 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 do Braze esse novo token válido.

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

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 aplicativo da sua lista de aplicativos 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 aplicativo da sua lista de aplicativos disponíveis.
3. Em Autenticação do SDK, escolha uma chave e selecione Gerenciar > Tornar chave primária.

Exclusão de uma tecla

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 aplicativo da sua lista de aplicativos disponíveis.
3. Em Autenticação do SDK, escolha uma chave não primária e selecione Gerenciar > Excluir chave pública.

Ativação no dashboard do Braze

Quando a integração do lado a lado do servidor e a integração do SDK estiverem concluídas, você poderá começar a ativar esse recurso para esses apps específicos.

Lembre-se de que as solicitações de 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 do Braze e os dados voltarão a fluir normalmente sem verificação.

Opções de aplicação

Na página Manage Settings (Configurações de gerenciamento) 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.

As assinaturas JWT inválidas serão relatadas nos estados Optional (opcional ) e Required (obrigatório ), mas somente o estado Required (obrigatório ) rejeitará as solicitações do SDK, fazendo com que os apps tentem novamente e solicitem novas assinaturas.

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

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

Não, esse recurso pode ser ativado para aplicativos específicos e não precisa ser usado em todos os seus aplicativos, 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, empurre os usuários para fazer o upgrade como faria para qualquer outra atualização obrigatória. Como alternativa, você pode manter o recurso opcional até perceber que uma porcentagem aceitável de usuários fez upgrade.

Que expiração devo usar ao gerar tokens JWT?

Recomendamos usar o valor mais alto de 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?

Se o token de um usuário expirar no meio da sessão, o SDK tem uma função de retorno de chamada que será invocada para que seu app saiba que um novo token JWT é necessário para continuar enviando dados para a Braze.

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

Se o seu servidor não for capaz de fornecer tokens JWT ou se você notar algum problema de integração, sempre será possível desativar o recurso no dashboard da Braze.

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

Por que esse recurso usa chaves públicas/privadas em vez de segredos compartilhados?

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

Em vez disso, usamos chaves públicas/privadas para que nem mesmo os Colaboradores do Braze (muito menos os usuários do seu dashboard) tenham acesso às suas chaves privadas.

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

Quando uma solicitação for rejeitada devido a um erro de autenticação, o SDK invocará o retorno de chamada usado para atualizar a assinatura 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.