SDK認証を設定する

SDK 認証を使用すると、ログインしているユーザーの代わりに行われた SDK リクエストに対して（サーバー側で生成された）暗号証明を提供できます。

仕組み

アプリでこの機能を有効にした後、無効または欠落しているJSON Web Token（JWT）を含むリクエストを拒否するようにBrazeダッシュボードを設定できます。これには次のものが含まれます。

• カスタムイベント、属性、購入、セッションデータの送信
• Brazeワークスペースでの新規ユーザーの作成
• 標準ユーザープロファイル属性の更新
• メッセージの受信またはトリガー

認証されていないログインユーザーが、アプリのSDK APIキーを使って悪意のあるアクション（他のユーザーになりすますなど）を行うのを防げるようになります。

認証のセットアップ

ステップ1:サーバーのセットアップ

ステップ1.1：公開鍵と秘密鍵のペアを生成する

RSA256公開鍵/秘密鍵ペアを生成します。公開キーは最終的にBrazeのダッシュボードに追加されますが、秘密キーはサーバーに安全に保管する必要があります。

RS256 JWTアルゴリズムで使用する2048ビットのRSA鍵を推奨します。

ステップ1.2：現在のユーザーのJSON Web Tokenを作成する

秘密キーが手に入ったら、サーバー側のアプリケーションはそれを使って、現在ログインしているユーザーのアプリまたはWebサイトにJWTを返す必要があります。

通常、このロジックは、アプリが通常現在のユーザーのプロファイルをリクエストする任意の場所に配置できます。たとえば、ログインエンドポイントや、アプリが現在のユーザープロファイルを更新する場所などです。

JWTを生成する際には、以下のフィールドが必要です：

JWTヘッダー

JWTペイロード

ステップ2:SDKの設定

この機能は以下のSDKバージョンから利用可能です：

ステップ2.1:Braze SDKで認証を有効にする

この機能が有効な場合、Braze SDKは、Brazeサーバーに対して行われたネットワークリクエストに、現在のユーザーの最新の既知のJWTを追加します。

• 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
        }
      ]
    ]
  }
}

ステップ2.2:現在のユーザーのJWTを設定する

アプリがBrazeのchangeUserメソッドを呼び出すたびに、サーバー側で生成されたJWTも指定します。

また、トークンが現在のユーザーのセッションの途中でリフレッシュされるように設定することもできます。

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

ステップ2.3:無効なトークンのコールバック関数を登録する

この機能が必須に設定されている場合、以下のシナリオでSDKリクエストがBrazeによって拒否されます：

• Braze APIが受信した時点でJWTの有効期限が切れていた
• JWTが空または欠落していた
• Brazeダッシュボードにアップロードした公開鍵でJWTの検証に失敗した

subscribeToSdkAuthenticationFailuresを使用して、これらのいずれかの理由でSDKリクエストが失敗したときに通知を受け取るようにサブスクライブできます。コールバック関数には、関連するerrorCode、エラーのreason、リクエストのuserId（ユーザーは匿名にはなれません）、およびエラーを引き起こした認証トークン（JWT）を含むオブジェクトが渡されます。

失敗したリクエストは、アプリが新しい有効なJWTを提供するまで、定期的に再試行されます。そのユーザーがまだログインしている場合、このコールバックをサーバーに新しいJWTを要求する機会として使用し、この新しい有効なトークンをBraze SDKに提供することができます。

認証エラーが発生した場合は、エラー内のuserIdが現在ログイン中のユーザーと一致するか確認し、サーバーから新しい署名を取得してBraze SDKに提供してください。これらのエラーを監視サービスやエラーレポートサービスに記録することもできます。

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

ステップ3:ダッシュボードで認証を有効にする

次に、前に設定したアプリのBrazeダッシュボードで認証を有効にできます。

BrazeダッシュボードでアプリのSDK認証設定が必須に設定されていない限り、SDKリクエストは認証なしで通常どおり処理され続けることに注意してください。

統合に何か問題が発生した場合（例えば、アプリがSDKにトークンを不正に渡している、またはサーバーが無効なトークンを生成している）、Brazeダッシュボードでこの機能を無効にすると、データは検証なしで通常通り流れるようになります。

適用オプション

ダッシュボードの設定の管理ページでは、各アプリに3つのSDK認証ステートがあり、Brazeがどのようにリクエストを検証するかを制御します。

オプション設定は、この機能がアプリのSDKトラフィックに与える潜在的な影響を監視するのに便利な方法です。

無効なJWTはオプションと必須の両方の状態で報告されますが、必須状態でのみSDKリクエストが拒否され、アプリは再試行して新しいJWTをリクエストします。

公開鍵を管理する

公開鍵を追加する

アプリごとに、プライマリ、セカンダリ、ターシャリの最大3つの公開キーを追加できます。必要に応じて、同じキーを複数のアプリに追加することもできます。公開鍵を追加するには：

1. Brazeのダッシュボードに行き、設定 > アプリ設定を選択します。
2. 利用可能なアプリのリストからアプリを選びます。
3. SDK認証で、公開キーを追加を選択します。
4. オプションの説明を入力し、公開キーを貼り付け、公開キーを追加を選択します。

新しいプライマリキーを割り当てる

セカンダリキーまたはターシャリキーを新しいプライマリキーとして割り当てるには：

1. Brazeのダッシュボードに行き、設定 > アプリ設定を選択します。
2. 利用可能なアプリのリストからアプリを選びます。
3. SDK認証でキーを選択し、管理 > プライマリキーに設定を選択します。

キーを削除する

プライマリキーを削除するには、まず新たなプライマリキーを割り当て、それからキーを削除します。非プライマリキーを削除するには：

1. Brazeのダッシュボードに行き、設定 > アプリ設定を選択します。
2. 利用可能なアプリのリストからアプリを選びます。
3. SDK認証でプライマリキー以外のキーを選択し、管理 > 公開キーを削除を選択します。

分析

各アプリには、この機能がオプション状態と必須状態にある間に収集されたSDK認証エラーの内訳が表示されます。

データはリアルタイムで入手でき、チャート上のポイントにカーソルを合わせると、指定した日付のエラーの内訳を見ることができます。

エラーコード

よくある質問（FAQ）

この機能はすべてのアプリで同時に有効にする必要がありますか？

いいえ、この機能は特定のアプリに対して有効にすることができ、すべてのアプリで一度に使用する必要はありません。

アプリの古いバージョンを使っているユーザーはどうなりますか？

この機能を適用し始めると、古いバージョンのアプリによるリクエストはBrazeによって拒否され、SDKによって再試行されます。ユーザーがアプリをサポートされたバージョンにアップグレードすると、キューに入れられたリクエストは再び受け入れられるようになります。

可能であれば、他の必須アップグレードと同様に、ユーザーにアップグレードを勧めてください。あるいは、許容できる割合のユーザーがアップグレードしたことを確認するまで、この機能をオプションにしておくこともできます。

JWTを生成するときには、どのような有効期限を使用する必要がありますか？

平均セッション期間、セッションCookie/トークンの有効期限、またはアプリケーションが現在のユーザープロファイルを更新する頻度のうち、高い方の値を使用することをお勧めします。

ユーザーのセッションの途中でJWTの有効期限が切れた場合はどうなりますか？

ユーザーのトークンがセッション中に期限切れになると、SDKはコールバック関数を呼び出して、Brazeにデータを送信し続けるために新しいJWTが必要であることをアプリに知らせます。

サーバー側の統合が壊れ、JWTを作成できなくなった場合はどうなりますか？

サーバーがJWTを提供できない場合、または統合に問題がある場合は、Brazeダッシュボードでいつでも機能を無効にできます。

一度無効にすると、保留中の失敗したSDKリクエストは最終的にSDKによって再試行され、Brazeによって受け入れられます。

なぜこの機能では、共有シークレットではなく公開キー/秘密キーを使うのでしょうか？

共有シークレットを使う場合、Brazeのダッシュボードページなど、その共有シークレットにアクセスできる人なら誰でも、トークンを生成してエンドユーザーになりすますことができます。

代わりに、公開キーと秘密キーを使用します。これにより、Brazeの従業員でさえ（ましてや御社のユーザーは言うまでもなく）あなたの秘密キーにアクセスできません。

拒否されたリクエストはどのように再試行されますか？

認証エラーが原因でリクエストが拒否されると、SDKはユーザーのJWTを更新するために使用されるコールバックを呼び出します。

リクエストは指数バックオフアプローチを使用して定期的に再試行されます。50回連続で失敗すると、次のセッション開始まで再試行は一時停止されます。各SDKには、手動でデータフラッシュをリクエストするメソッドもあります。

匿名ユーザーに対してSDK認証は使えますか？

いいえ。SDK認証はWebサイトが誰かのIDを主張することで機能するため、識別済みのユーザーにのみ適用されます。匿名ユーザーの場合、主張するIDがありません。

適用はchangeUserが呼び出された後に開始されます。ユーザーが識別される前（例えば、サインアップ前に匿名で閲覧している間）は、SDKはJWTなしでBrazeにデータを送信できます。changeUserが呼び出された後、その識別済みプロファイルに対するリクエストには有効なJWTが必要になります。

つまり、一般的なユーザージャーニーは次のようになります：

1. ユーザーがWebサイトにアクセスするか、アプリを匿名で開きます。BrazeはJWTなしでこのアクティビティを収集します。
2. ユーザーがサインアップまたはログインし、アプリがexternal_idを指定してchangeUserを呼び出します。
3. Brazeはそのユーザーのアクティビティの収集を続け、その識別済みプロファイルに対するリクエストにはSDK認証が適用されます。

SDK認証はユーザーエイリアスで機能しますか？

いいえ。SDK認証にはexternal_idが必要です。braze_idまたはalias_idのみが利用可能な場合は設定できないため、エイリアスのみのプロファイルではSDK認証を使用できません。

SDK認証を有効にすると、未認証のアクティビティ収集がブロックされますか？

いいえ。SDK認証は正当な匿名アクティビティの収集をブロックしません。changeUserでプロファイルが識別された後にのみ適用されます。