> ## 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.

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

> AuthleteサービスのJWKセット設定方法について解説します。

<Info>
  For **Authlete 2.x** documentation, see [2.x version](/v2/configuration-reference/discovery-metadata/jwk-set-for-service).
</Info>

## はじめに

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

***

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

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

<img src="https://mintcdn.com/authlete/NmFoIJ4VSX_LOgob/img/kb/ja/deployment/security/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%88_2019-12-17_16.08.05.png?fit=max&auto=format&n=NmFoIJ4VSX_LOgob&q=85&s=90e81c96ba1664bf4b0c374fa702c08f" alt="スクリーンショット_2019-12-17_16" width="2496" height="2462" data-path="img/kb/ja/deployment/security/スクリーンショット_2019-12-17_16.08.05.png" />

*Generating a JWK Set using mkjwk*

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

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

<img src="https://mintcdn.com/authlete/NmFoIJ4VSX_LOgob/img/kb/ja/deployment/security/jwk-set-for-service-v3.png?fit=max&auto=format&n=NmFoIJ4VSX_LOgob&q=85&s=77d6c4207f30cdab3c069f255e4aab35" alt="" width="1441" height="599" data-path="img/kb/ja/deployment/security/jwk-set-for-service-v3.png" />

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

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

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

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

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

[/service/get API](/api-reference/service-management/get-service)
を用いて、サービスの設定情報を取得します。

```sh theme={null}
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 として保存します。

```json theme={null}
{
  "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 リファレンス](/api-reference/service-management/get-service)
をご参照ください）

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

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

[/service/update API](/api-reference/service-management/update-service)
を用いて、上記の JWK セットを含む、新しい設定情報を読み込ませます。

```sh theme={null}
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" が、以下のように出力結果に含まれるはずです。

```json theme={null}
{
  //[...]
"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`) などの更新に対応します。