SDK 認証

SDK 認証を使用すると、ログイン ユーザーに代わって行われた SDK 要求に暗号化証明 (サーバー側で生成) を提供できます。

アプリでこの機能を有効にすると、JSON Web Token(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 トークンを作成する

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

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

JWT を生成する場合、次のフィールドが必要です。

JWT ヘッダー

JWT ペイロード

JWT ライブラリ

JSON Web Tokenの詳細や、この署名プロセスを簡素化する多くのオープンソースライブラリを参照するには、 https://jwt.io をご覧ください。

SDK統合

この機能は、次の [SDK バージョン](/docs/ja 以降で使用できます。/user_guide/engagement_tools/campaigns/ideas_and_strategies/new_features/#filtering-by-most-recent-app-versions):

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

この機能を有効にすると、Braze SDKは、Braze Serverへのネットワークリクエストに、現在のユーザーの最後に認識された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")

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

この機能を 必須に設定すると、次のシナリオで SDK リクエストが Braze によって拒否されます。 - Braze APIが受信するまでにJWTの有効期限が切れている - JWTが空または欠落している - JWTは、Brazeダッシュボードにアップロードした公開鍵の検証に失敗しました。

サブ subscribeToSdkAuthenticationFailures スクライブを使用すると、これらの理由のいずれかで SDK 要求が失敗したときに通知を受け取ることができます。コールバック関数には、エラーuserIdに関連する ‘errorCode’ reason を持つオブジェクト、要求の (ユーザーが匿名でない場合)、およびエラーの原因となった認証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);
  appboy.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)
})

公開鍵の追加

ダッシュボードの「 設定の管理 」ページで、Brazeダッシュボードの特定のアプリに公開鍵を追加します。各アプリは、最大 3 つの公開キーをサポートします。複数のアプリで同じ公開鍵と秘密鍵が使用される可能性があることに注意してください。

公開鍵を追加するには、次のようにします。

1. 利用可能なアプリの一覧からアプリを選択します。
2. 「 SDK認証」で、「 公開鍵の追加」をクリックします。
3. 公開鍵を貼り付け、オプションの説明を追加します。
4. 変更を保存すると、公開キーの一覧にキーが表示されます。

キーを削除したり、キーを主キーに昇格したりするには、各キーの横にあるオーバーフローメニューで対応するアクションを選択します。

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

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

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

統合に問題が発生した場合(たとえば、アプリが誤ってトークンをSDKに渡している、サーバーが無効なトークンを生成しているなど)、Brazeダッシュボードでこの機能を無効にすると、検証なしでデータの流れが通常どおり再開されます。

適用オプション

ダッシュボードの [Manage Settings ] ページには、Braze がリクエストを検証する方法を制御する 3 つの SDK 認証状態があります。

[省略可能] 設定は、この機能がアプリの SDK トラフィックに及ぼす潜在的な影響を監視するのに便利な方法です。

無効な JWT 署名は Optional 状態と Required 状態の両方で報告されますが、SDK 要求が拒否されるのは Required 状態のみで、アプリは再試行して新しい署名を要求します。

分析

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

データはリアルタイムで利用でき、グラフ内のポイントにカーソルを合わせると、特定の日付のエラーの内訳を確認できます。

![認証エラーのインスタンス数を示すグラフ。また、エラーの合計数、エラーの種類、および調整可能な日付範囲も表示されます。10

エラーコード

よくある質問

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

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

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

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

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

JWTトークンを生成するときは、どの有効期限を使用する必要がありますか?

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

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

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

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

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

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

この機能が共有シークレットの代わりに公開キー/秘密キーを使用するのはなぜですか?

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

代わりに、公開鍵/秘密鍵を使用しているため、Brazeの従業員(ダッシュボードユーザーは言うまでもなく)でさえ、秘密鍵にアクセスできません。

拒否された要求はどのように再試行されますか?

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

要求は、エクスポネンシャル バックオフ アプローチを使用して定期的に再試行されます。50回連続して失敗すると、次のセッションが開始されるまで再試行が一時停止されます。各 SDK には、データ フラッシュを手動で要求する方法もあります。