こんにちは、ISSUEの寒河江です。

今回はfirebaseのカスタムクレームの実装について書きました。先日実装する機会があり、ハマりやすいポイントがあるなと感じたので基本的な使い方と共にお話しできたらと思います。

## カスタムクレームとは
Firebase Authenticationで提供されている仕組みで、ユーザーごとにカスタム属性をセットすることができます。これによりさまざまなアクセス制御戦略を実装することができます。[公式](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja)では以下の例が紹介されています。

- データとリソースにアクセスするための管理者権限をユーザーに付与する。
- ユーザーが属するさまざまなグループを定義する。
- マルチレベルアクセス権限を指定する。
- ユーザーに ID を追加する

要はカスタムクレームに認証に使える情報(user_id, adminかどうか)などをセットしてアクセス制限を区別できるようにするため使われます。Goで言うとcontextに[リクエストスコープの値(userIDなど)](https://i-ssue.com/topics/c0795114-2628-4b17-9826-9eed142c80b8)をセットしてserviceに必要な情報を渡すイメージに近いと思います。


## カスタムクレームを使うメリット
- アクセス制御のデータ管理をfirebase firestoreなどで行う必要がなくなり読み取りの課金額が減る
- Realtime Databaseルールなどでのアクセス制御が可能になる

## カスタムクレームを使うデメリット
- 既存でアクセス制御の仕組みがある場合はスイッチコスト(バグや実装修正など)がかかる
- 障害時のデバッグがやや大変
- クライアントへのカスタムクレーム更新の伝播がやや面倒


## カスタムクレームの設定方法
カスタムクレームはAdmin SDKにより設定することができます。カスタムクレームには機密データが含まれている可能性があるため、Firebase Admin SDKによって特権サーバー環境からのみ設定される必要があります。

以下はGoの例になります。
![img](/mosaic-code.jpg)

セット方法はこれだけでとても簡単です。

## カスタムクレームの取得方法

カスタムクレームの実装方法は下記になります。
![img](/mosaic-code.jpg)
取得方法もとても簡単です。

## カスタムクレームセット時の注意点

### 格納するデータは1,000バイト以下にする
カスタムクレームにはアクセス制御に関するデータのみを格納します。オブジェクトやその他大きなデータはfirestoreやgoogle storageへデータを格納することがおすすめされています。[(参考)](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja#best_practices_for_custom_claims)

### フロントへのクレーム伝播方法をしっかり検討する
カスタムクレームは更新しただけではフロントへ伝播されません。最新のカスタムクレームがセットされたIdTokenを取得するには、**IdTokenのリフレッシュ**が必要になります。
[公式](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja#propagate_custom_claims_to_the_client)にあるようにカスタムクレームの伝播方法は以下です。

- **カスタムクレーム更新後に、ユーザーの再認証を行う**
  - 最新のカスタムクレームが入ったidTokenが発行されます。
- **トークンの有効期限(1時間)切れになる**
  - データ参照の不整合を防ぐために有効期限切れを待つのではなく、なるべく早くトークンの更新を行う必要があると思います。
- **フロントで`currentUser.getIdToken(true)` を呼び出して ID トークンが強制的に更新する。**

#### カスタムクレーム更新後に、ユーザーの再認証を行う
カスタムクレームを更新した後に、すぐにIdTokenを失効させユーザーに再認証を求める方法です。ただ実際は、IdTokenを失効させることはできません。IdTokenを[リフレッシュさせるリフレッシュトークンを失効](https://firebase.google.com/docs/auth/admin/manage-sessions#revoke_refresh_tokens)させます。


こちらのメリデメは下記になります。

**デメリット**
- サービス利用中に再認証が必要になるのでUXが下がる

**メリット**
- バックエンドの実装だけでIdTokenの更新をコントロールできる

サービス内で利用頻度の高い機能で実装するのは避けた方が良さそうです。

こちらが実装サンプルです。
![img](/mosaic-code.jpg)
IdTokenの検証にはVerifyIDTokenではなく**VerifyIDTokenAndCheckRevoked**を利用しましょう。VerifyIDTokenだとrefreshトークンが失効したかは確認していません。なのでIdTokenの有効期限(1時間)が切れていない場合はカスタムクレームが更新されていない状態となっていまいます。

[VerifyIDTokenAndCheckRevokedを利用したIdToken検証](https://firebase.google.com/docs/auth/admin/manage-sessions#detect_id_token_revocation_in_the_sdk)
![img](/mosaic-code.jpg)`

#### フロントで`currentUser.getIdToken(true)` を呼び出して ID トークンが強制的に更新する。
こちらは最も簡単な方法です。フロント側でIdTokenをリフレッシュすることができます。しかし、リフレッシュ処理はやや重たい処理となるので、カスタムクレームを更新した場合のみに発火するように実装をする必要があります。また実際は`currentUser.getIdToken(true)`したとしてもリフレッシュ済みのIdTokenを取得するには画面をリロードする必要があります。フロント側のレンダリング設計によっては実装が難しい場合もあるのでよく検討することをおすすめします。


## 参考
https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja

以上Firebaseのカスタムクレームを扱う上での注意点になります！

こんにちは、ISSUEの寒河江です。

今回はfirebaseのカスタムクレームの実装について書きました。先日実装する機会があり、ハマりやすいポイントがあるなと感じたので基本的な使い方と共にお話しできたらと思います。

## カスタムクレームとは
Firebase Authenticationで提供されている仕組みで、ユーザーごとにカスタム属性をセットすることができます。これによりさまざまなアクセス制御戦略を実装することができます。[公式](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja)では以下の例が紹介されています。

- データとリソースにアクセスするための管理者権限をユーザーに付与する。
- ユーザーが属するさまざまなグループを定義する。
- マルチレベルアクセス権限を指定する。
- ユーザーに ID を追加する

要はカスタムクレームに認証に使える情報(user_id, adminかどうか)などをセットしてアクセス制限を区別できるようにするため使われます。Goで言うとcontextに[リクエストスコープの値(userIDなど)](https://i-ssue.com/topics/c0795114-2628-4b17-9826-9eed142c80b8)をセットしてserviceに必要な情報を渡すイメージに近いと思います。


## カスタムクレームを使うメリット
- アクセス制御のデータ管理をfirebase firestoreなどで行う必要がなくなり読み取りの課金額が減る
- Realtime Databaseルールなどでのアクセス制御が可能になる

## カスタムクレームを使うデメリット
- 既存でアクセス制御の仕組みがある場合はスイッチコスト(バグや実装修正など)がかかる
- 障害時のデバッグがやや大変
- クライアントへのカスタムクレーム更新の伝播がやや面倒


## カスタムクレームの設定方法
カスタムクレームはAdmin SDKにより設定することができます。カスタムクレームには機密データが含まれている可能性があるため、Firebase Admin SDKによって特権サーバー環境からのみ設定される必要があります。

以下はGoの例になります。
```go
// auth clientの取得
client, err := app.Auth(ctx)
if err != nil {
        log.Fatalf("error getting Auth client: %v\n", err)
}

//
// カスタムクレームの更新
//

// adminの設定
claims := map[string]interface{}{"admin": true}
err = client.SetCustomUserClaims(ctx, uid, claims)
if err != nil {
        log.Fatalf("error setting custom claims %v\n", err)
}

// user_idの設定
claims := map[string]interface{}{"user_id": "clcsk95114-2628-4s17-9826-9eed149890b8"}
err = client.SetCustomUserClaims(ctx, uid, claims)
if err != nil {
        log.Fatalf("error setting custom claims %v\n", err)
}
```

セット方法はこれだけでとても簡単です。

## カスタムクレームの取得方法

カスタムクレームの実装方法は下記になります。
```go
// リクエストで渡ってきたidTokenを検証してtokenを取得します。
token, err := client.VerifyIDToken(ctx, idToken)
if err != nil {
        log.Fatal(err)
}

// tokenに含まれるClaimsを取得する
claims := token.Claims
if admin, ok := claims["admin"]; ok {  // claimsはmap形式なので取得したいkeyを指定します。
        if admin.(bool) { // 値はinterface型で格納されているので型アサーションする
                // リクエストスコープの値としてcontextにセットするなど
        }
}

```
取得方法もとても簡単です。

## カスタムクレームセット時の注意点

### 格納するデータは1,000バイト以下にする
カスタムクレームにはアクセス制御に関するデータのみを格納します。オブジェクトやその他大きなデータはfirestoreやgoogle storageへデータを格納することがおすすめされています。[(参考)](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja#best_practices_for_custom_claims)

### フロントへのクレーム伝播方法をしっかり検討する
カスタムクレームは更新しただけではフロントへ伝播されません。最新のカスタムクレームがセットされたIdTokenを取得するには、**IdTokenのリフレッシュ**が必要になります。
[公式](https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja#propagate_custom_claims_to_the_client)にあるようにカスタムクレームの伝播方法は以下です。

- **カスタムクレーム更新後に、ユーザーの再認証を行う**
  - 最新のカスタムクレームが入ったidTokenが発行されます。
- **トークンの有効期限(1時間)切れになる**
  - データ参照の不整合を防ぐために有効期限切れを待つのではなく、なるべく早くトークンの更新を行う必要があると思います。
- **フロントで`currentUser.getIdToken(true)` を呼び出して ID トークンが強制的に更新する。**

#### カスタムクレーム更新後に、ユーザーの再認証を行う
カスタムクレームを更新した後に、すぐにIdTokenを失効させユーザーに再認証を求める方法です。ただ実際は、IdTokenを失効させることはできません。IdTokenを[リフレッシュさせるリフレッシュトークンを失効](https://firebase.google.com/docs/auth/admin/manage-sessions#revoke_refresh_tokens)させます。


こちらのメリデメは下記になります。

**デメリット**
- サービス利用中に再認証が必要になるのでUXが下がる

**メリット**
- バックエンドの実装だけでIdTokenの更新をコントロールできる

サービス内で利用頻度の高い機能で実装するのは避けた方が良さそうです。

こちらが実装サンプルです。
```go
claims := map[string]interface{}{"admin": true}
err = client.SetCustomUserClaims(ctx, uid, claims)
if err != nil {
        log.Fatalf("error setting custom claims %v\n", err)
}

// カスタムクレーム更新後、すぐにrefreshTokenを失効させる
if err := client.RevokeRefreshTokens(ctx, uid); err != nil {
        log.Fatalf("error revoking tokens for user: %v, %v\n", uid, err)
}
```
IdTokenの検証にはVerifyIDTokenではなく**VerifyIDTokenAndCheckRevoked**を利用しましょう。VerifyIDTokenだとrefreshトークンが失効したかは確認していません。なのでIdTokenの有効期限(1時間)が切れていない場合はカスタムクレームが更新されていない状態となっていまいます。

[VerifyIDTokenAndCheckRevokedを利用したIdToken検証](https://firebase.google.com/docs/auth/admin/manage-sessions#detect_id_token_revocation_in_the_sdk)
```go
token, err := client.VerifyIDTokenAndCheckRevoked(ctx, idToken)
if err != nil {
        if err.Error() == "ID token has been revoked" {
                // Token is revoked. Inform the user to reauthenticate or signOut() the user.
        } else {
                // Token is invalid
        }
}
log.Printf("Verified ID token: %v\n", token)
````

#### フロントで`currentUser.getIdToken(true)` を呼び出して ID トークンが強制的に更新する。
こちらは最も簡単な方法です。フロント側でIdTokenをリフレッシュすることができます。しかし、リフレッシュ処理はやや重たい処理となるので、カスタムクレームを更新した場合のみに発火するように実装をする必要があります。また実際は`currentUser.getIdToken(true)`したとしてもリフレッシュ済みのIdTokenを取得するには画面をリロードする必要があります。フロント側のレンダリング設計によっては実装が難しい場合もあるのでよく検討することをおすすめします。


## 参考
https://firebase.google.com/docs/auth/admin/custom-claims?hl=ja

以上Firebaseのカスタムクレームを扱う上での注意点になります！

カスタムクレームとは

続きを読むには単価診断を受けてください（30秒）