# API Shield の JWT 検証が HS256・HS384・HS512 に対応、対称鍵もこれでバッチリだよ！

やっほー、しぃちゃんだよ！

今日は Cloudflare の API Shield に関するうれしいアップデートを見つけたよ。地味に見えて、実は API 認証まわりの選択肢がぐっと広がる話なんだ。さっそく紹介していくね！

## なにが発表されたの？

Cloudflare の Changelog によると、API Shield の JSON Web Token(JWT)検証機能が、HS256 / HS384 / HS512 アルゴリズムを使う対称鍵(HMAC)に新しく対応したんだって。設定方法は Cloudflare ダッシュボードからでも、Cloudflare API からでも OK。しかも Cloudflare は対称鍵の認証情報を平文で保存しないし、API レスポンスにもその認証情報は含まれないようになっているよ。セキュリティ面もちゃんと配慮されてるのがうれしいポイントだね。

## 今までどうだったの？

もともと API Shield の JWT 検証は、JWT の発行者が公開する JWKS(JSON Web Key Set)をコピー&ペーストして設定する形が中心で、RSA や EC といった非対称鍵での検証が前提になっていたの。だから、認証基盤が HS256 のような HMAC 方式で JWT を署名している場合は、そのままでは API Shield の検証に乗せられなかったんだよね。

## これで何が変わるの？

今回のアップデートで、HMAC でトークンを署名している認証基盤でも、そのまま Cloudflare のエッジで JWT 検証ができるようになったよ。多くの認証ライブラリやシンプルな内製認証基盤では HS256 がデフォルトだったりするから、これまで「API Shield を使うために署名方式を変えなきゃ」となっていたケースでも、そのまま導入できる可能性が広がるの。API を守りたい開発者やセキュリティ担当さんにとって、選択肢が増えるのはシンプルに嬉しいことだよね。

## 深く潜ってみよう

対称鍵の設定にはちょっとしたお作法があるから、ここでまとめておくね。

- 鍵の種類を表す `kty` は `oct` を指定する
- 共有シークレットは `k` フィールドに、パディングなしの Base64url 形式でエンコードして渡す
- デコード後の長さは、HS256 で 32 バイト以上、HS384 で 48 バイト以上、HS512 で 64 バイト以上が必要
- `kty`・`alg`・`kid`・`k` はいずれも必須フィールドで、`alg` は必ず指定する必要がある

さらに注意したいのが、HMAC 方式は署名と検証に同じ秘密鍵を使う仕組みだということ。つまりこの認証情報を持っている人は誰でも JWT に署名も検証もできてしまうから、ソースコードやログに絶対に漏らさないように扱う必要があるよ。だからこそ Cloudflare 側も、この認証情報を平文で保存せず、API レスポンスにも含めないという設計にしているんだね。

設定自体は、JWT がどこにあるかを指定する「トークン設定」と、検証結果に応じた挙動を決める「ルール」の 2 段構えになっている点は既存の JWT 検証と同じだよ。詳しい鍵フォーマットや認証情報の要件は、Cloudflare の API ドキュメント「Configure JWT validation via the API」に載っているから、実際に設定するときはそちらも確認してね。

## まとめ

- API Shield の JWT 検証が HS256 / HS384 / HS512 の対称鍵(HMAC)に新対応
- これまでは JWKS を使った非対称鍵での検証が中心だった
- HMAC でトークンを署名している認証基盤も、そのまま Cloudflare のエッジで検証できるようになった
- 対称鍵は `kty: oct` と Base64url エンコードした `k` で指定し、鍵長は HS256 で 32 バイト以上などアルゴリズムごとに条件がある
- 認証情報は平文保存されず、API レスポンスにも含まれない

HS256 のような HMAC 方式で API 認証を組んでいて、API Shield の導入を検討してた人にとっては、まさに待ってましたのアップデートだよ！