Authlete サービスの JWK セット設定

はじめに

本記事では、サービスに JWK セットを登録する方法について説明します。
JWK セットの準備

まず何らかの方法により、JWK セットを用意します。以下は mkjwk.org サービスを用いて ES256 の鍵ペアを作成する例です。ここでは以下の通り選択・入力しています。

• 鍵タイプ: EC (Elliptic Curve)
• 曲線: P-256
• 鍵の用途: Signing
• アルゴリズム: ES256
• 鍵の ID: 1

Authlete コンソール経由での JWK セットの登録

生成された “公開鍵と秘密鍵を含む JWK Set” を、対象サービス設定の キーマネージメント > JWK Set に移動し 認可サーバー タブ内の JWK セットの内容 に追加し 「変更を保存」ボタンを押下します。

これにより、サービスへの JWK セットドキュメントの登録が完了しました。

また JWK セットエンドポイントの URI に認可サーバーのエンドポイントを追加することで、jwks_uri が認可サーバーのメタデータドキュメントに反映されます。

Authlete API 経由での JWK セットの登録

前述の Web ベースの管理者コンソールを用いる代わりに、Authlete のサービス管理 API を用いて JWK セットを登録することも可能です。以下は /service/update API にリクエストする例です。“jwks” キーの値として JWK セットを指定しています。サービス設定の更新には組織アクセストークンが必要です。

1. 対象サービスの設定情報を取得

/service/get API を用いて、サービスの設定情報を取得します。

curl -s {Authlete API}/service/get/{Service API Key} \
   -H 'Authorization: Bearer {Organization Access Token}' \
   -H 'Content-type: application/json' \
   > service.json

2. 設定情報に新たな JWK セットを追加

以下の Key/Value を JWK セットとして、上記にて取得した JSON 形式の設定情報に追加し、それを updated-service.json として保存します。

{
  "jwks": {
    "keys": [
      {
        "kty": "EC",
        "d": "eb4BggIO87SUjzP1M56MeXj0NQajWBwpwiDq8yoL5n4",
        "use": "sig",
        "crv": "P-256",
        "kid": "2019-07-25_02",
        "x": "f8a6jovcRTNLDWi3_c62YcW_3ZN-GH1RkiVOZgSgIYI",
        "y": "EB3R8W12a3tgZfNer1RP0DizT3qpRybGw_krfsE0JzY",
        "alg": "ES256"
      }
    ]
  }
}

もし複数の JWK を登録する場合、どの JWK を用いて署名するかを指定します。たとえば ID トークンの署名に、“kid”:“2019-07-25_02” のキー ID により識別される JWK を用いる場合には、以下の Key/Value を併せて追加します。（idTokenSignatureKeyId については API リファレンス をご参照ください）

"idTokenSignatureKeyId": "2019-07-25_02"

3. 新しい設定情報を用いてサービスを更新

/service/update API を用いて、上記の JWK セットを含む、新しい設定情報を読み込ませます。

cat updated-service.json | \
    curl -s -X PUT {Authlete API}/service/update/{Service API Key} \
    -H 'Authorization: Bearer {Organization Access Token}' \
    -H 'Content-type: application/json' \
    -d @-

すると、新たに “jwks” が、以下のように出力結果に含まれるはずです。

{
  //[...]
"jwks": "{\"keys\":[
    {
        \"kty\":\"EC\",
        \"d\":\"eb4BggIO87SUjzP1M56MeXj0NQajWBwpwiDq8yoL5n4\",
        \"use\":\"sig\",
        \"crv\":\"P-256\",
        \"kid\":\"2019-07-25_02\",
        \"x\":\"f8a6jovcRTNLDWi3_c62YcW_3ZN-GH1RkiVOZgSgIYI\",
        \"y\":\"EB3R8W12a3tgZfNer1RP0DizT3qpRybGw_krfsE0JzY\",
        \"alg\":\"ES256\"
    }
]}",
//[...]
}

キーのローテーション

ダウンタイムなしにキーのローテーションを実施するには、以下の手順でキーの更新することが一般的です。

1. jwks_uri に新しい署名用キーを追加で登録 (複数のキーが含まれる状態)
2. クライアントや RP の jwks_uri キャッシュが破棄され、複数のキーが認識されるまで待つ
3. 署名用キーを新しいキーに切り替える
4. 古い署名用キーを削除する

Authlete を利用している認可サーバーの場合、1, 3 はサービスの JWKセットの内容 (jwks) の更新、3 はサービスの IDトークン署名キーID (idTokenSignatureKeyId) などの更新に対応します。