SDK認証

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

アプリでこの機能を有効にすると、次のような JSON Web トークン (JWT) 署名が無効または存在しないリクエストを拒否するように Braze ダッシュボードを設定できます。

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

これで、認証されていないログインユーザーが、アプリの SDK API キーを使って、他のユーザーになりすますなどの悪意のあるアクションを実行するのを防ぐことができます。

はじめに

始めるには4つのハイレベルなステップがある：

1. サーバー・サイドの統合- 公開鍵と秘密鍵のペアを生成し、秘密鍵を使って現在ログインしているユーザーのJWTを作成する。
   
   
2. SDK 統合- Braze SDK でこの機能を有効にし、サーバーから生成された JWT をリクエストします。
   
   
3. 公開鍵の追加-管理設定ページのBrazeダッシュボードに_公開鍵を_追加する。
   
   
4. Braze ダッシュボード内で適用を切り替える- Braze ダッシュボード内でアプリごとにこの機能の適用を切り替えます。

サーバーサイドの統合

公開鍵と秘密鍵のペアを生成する。

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

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

現在のユーザーのJSONウェブトークンを作成する

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

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

JWTを生成する際には、以下のフィールドが期待される：

JWT ヘッダー

JWT ペイロード

JWTライブラリ

JSONウェブトークンについての詳細や、この署名プロセスを簡素化する多くのオープンソースライブラリを参照するには、https://jwt.io をチェックしてほしい。

SDKの統合

この機能は、以下の SDKバージョン: で利用可能です。

Braze SDKでこの機能を有効にする。

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

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

現在のユーザーのJWTトークンを設定する

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

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

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

無効なトークンのコールバック関数を登録する

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

• Braze APIが受信した時点でJWTの有効期限が切れていた。
• JWTが空か行方不明だった
• Brazeダッシュボードにアップロードした公開鍵のJWT検証に失敗した。

subscribeToSdkAuthenticationFailures を使用して、これらのいずれかの理由で SDK リクエストが失敗したときに通知を受け取るようにサブスクライブできます。コールバック関数は、エラーに関連するオブジェクトを含む。 errorCodereason 、リクエストのuserId (ユーザーが匿名でない場合)、エラーの原因となった認証signature 。

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

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

公開鍵を管理する

公開鍵を追加する

アプリごとに、1次、2次、3次の最大3つの公開キーを追加できます。必要に応じて、同じキーを複数のアプリに追加することもできます。公開鍵を追加する：

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

新しい1次キーを割り当てる

2次キーまたは3次キーを新しい1次キーとして割り当てるには以下の操作を行います。

1. Brazeのダッシュボードに行き、「設定」>「アプリ設定」を選択する。
2. 利用可能なアプリのリストからアプリを選ぶ。
3. [SDK 認証] でキーを選択し、[管理] > [1次キーを作成] を選択します。

キーを削除する

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

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

Brazeのダッシュボードで有効にする

サーバー側の統合と SDK 統合が完了したら、それらの特定のアプリに対してのこの機能の有効化を開始できます。

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

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

適用オプション

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

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

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

分析

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

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

エラーコード

よくある質問

この機能はすべてのアプリで同時に有効にする必要がありますか？{#faq-app-by-app}

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

私のアプリの古いバージョンを使っているユーザーはどうなりますか？{#faq-sdk-backward-compatibility}

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

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

JWT トークンを生成する際、どのような有効期限を使用すべきか？{#faq-expiration}

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

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

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

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

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

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

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

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

その代わり、公開鍵/秘密鍵を使用することで、Brazeの従業員でさえ（ダッシュボードのユーザーはもちろん）秘密鍵にアクセスできないようにしている。

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

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

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