メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://developers.authlete.com/llms.txt

Use this file to discover all available pages before exploring further.

For Authlete 2.x documentation, see 2.x version.

​
はじめに

本記事では、サービスに JWK セットを登録する方法について説明します。
JWK セットの準備
まず何らかの方法により、JWK セットを用意します。以下は mkjwk.org サービスを用いて ES256 の鍵ペアを作成する例です。ここでは以下の通り選択・入力しています。
  • 鍵タイプ: EC (Elliptic Curve)
  • 曲線: P-256
  • 鍵の用途: Signing
  • アルゴリズム: ES256
  • 鍵の ID: 1
スクリーンショット_2019-12-17_16 Generating a JWK Set using mkjwk

​
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) などの更新に対応します。