Athash jwt

「解説記事を幾つも読んだけど OpenID Connect を理解できた気がしない」 ― この文書は、そういう悩みを抱えたエンジニアの方々に向けた OpenID Connect 解説文書です。 概念的・抽象的な話を避け、具体例を用いて OpenID Connect を解説していこうと思います。

この文書では、 JWS (RFC 7515)、 JWE (RFC 7516)、 JWK (RFC 7517)、 JWT (RFC 7519)、 ID トークン の説明をおこないます。

追記(2020-03-20)
この記事の内容を含む、筆者本人による『 OAuth & OIDC 入門編 』解説動画を公開しました !

一般の方々に対しては「OpenID Connect は認証の仕様である」という説明で良いと思います。 一方、技術的な理解を渇望しているエンジニアの方々に対しては、**「OpenID Connect は『ID トークン』を発行するための仕様である」*という割り切り方を勧めたほうが良いと考えています。 というわけで、まず、 ID トークン について説明しようと思います。

一般の方々に対しては「ID トークンは認証の結果得られるトークンである」という説明で良いと思います。 一方、エンジニアの方々には、「ID トークンは具体的にはこんな感じの文字列データです」と言って、まず具体例を見ていただくのが良いと考えています。 そういうわけで、早速ですが、OpenID Connect の中心となる仕様書「 OpenID Connect Core 1.0 」の「A.2. Exemple d’utilisation response_type=id_token」から抜粋した ID トークンの例を掲載します。 なお、この ID トークンの例には改行が含まれていますが、本来は ID トークンの中に改行は含まれません。 ここでは単に見やすいように改行を入れているだけです。

この ID トークンの例の中には、ピリオドが二つ含まれています。 一つ目は一行目の右から 9 文字目に、二つ目は九行目の右から 22 文字目にあります。 この二つのピリオドにより、ID トークンは三つの部分に分けられます。 (三つにならないケースについては後述します。 )

三つの部分は、先頭から順に、ヘッダー、ペイロード (本文)、署名、を表しています。 つまり、ID トークンは形式的には次のような形になっています。

前掲の ID トークンの場合、ヘッダー、ペイロード、署名の値を別々に切り出すと、次のようになります。

前節で紹介した「ヘッダー.ペイロード.署名」という形式は、実は RFC 7515 ( JSON Web Signature ( JWS )) の「7.1. JWS Compact Serialization」で定義されている「JSON Web Signature (JWS) の Compact Serialization 形式」です。 具体的には次のように定義されています。 ^{(RFC 7515 は JSON Serialization 形式も定義していますが、ここでは扱いません。 )}

この定義を見ると、三つの部分はそれぞれ、元のデータを base64URL (RFC 4648, 5. Encodage en Base 64 avec URL et nom de fichier Safe Alphabet) でエンコードしたものだということが分かります。 ということは、base64URL でデコードすると、元のデータが得られます。 早速やってみましょう。

3.1. JWS ヘッダーのデコード

まず、ヘッダー部をデコードしてみます。 ここでは、base64-URL-CLI をインストールし、コマンドラインでデコードをおこないます。

結果、次のような JSON が得られます。

この JSON には、 と という二つのパラメーターが含まれています。 これらに加え、その他の有効なパラメーターは RFC 7515 の「4.1. Registered Header Parameter Names」に列挙されています。

パラメーター名	説明
アルゴリズム
JWK セット URL
JSON Web キー
キー ID
X.509 URL
X.509 証明書チェーン
X.509 証明書 SHA-1 Thumbprint
X.509 証明書 SHA-256 Thumbprint
JWS 自身のメディアタイプ
ペイロードのメディアタイプ
必須パラメーター群指定

これらのうち、 は署名で使用するアルゴリズムを指定するものです。 署名については後述します。

3.2. JWS ペイロードのデコード

同様にして、ペイロードを base64url でデコードすると、

次の JSON が得られます。

この内容については、のちほど詳述します。 なお、この例では、ペイロード部分の元データが上記のように JSON となっていますが、RFC 7515 自体は JSON を要求しておらず、任意のデータ (an arbitrary sequence of octets) で構わないとしています。

3.3. JWS 署名のデコード

ヘッダーに含まれている パラメーターの値は、署名のアルゴリズムを示しています。 の値として有効な値は、RFC 7515 ではなく、別仕様書 RFC 7518 ( JSON Web Algorithms ( JWA )) の「3.1. Valeurs des paramètres d’en-tête « alg » (algorithme) pour JWS」に列挙されています。

の値	アルゴリズム
HMAC avec SHA-256
HMAC avec SHA-384
HMAC avec SHA-512
RSASSA-PKCS1-v1_5 avec SHA-256
RSASSA-PKCS1-v1_5 avec SHA-384
RSASSA-PKCS1-v1_5 avec SHA-512
ECDSA avec P-256 et SHA-256
ECDSA avec P-384 et SHA-384
ECDSA avec P-521 et SHA-512
RSASSA-PSS avec SHA-256 et MGF1 avec SHA-256
RSASSA-PSS avec SHA-384 et MGF1 avec SHA-384
RSASSA-PSS avec SHA-512 et MGF1 avec SHA-512
Aucune signature numérique ou MAC effectuée

« 3.1. JWS ヘッダーのデコード」の結果、 の値は だということが分かっています。 「3.1. « alg » (algorithme) Header Parameter Values for JWS」の表と照合すると、 は「RSASSA-PKCS1-v1_5 using SHA-256」を示していますので、RSA アルゴリズムによる署名ということが分かります。

RSA の署名はバイナリデータなので、base64url でデコードするとバイナリデータが得られます (ヘッダーやペイロードのように JSON は得られません)。 署名部分を base64URL デコードし、続けて 10 進数表記すると、次のようになります。 (見ても意味は分かりませんが。 )

3.4. JWS 署名の対象

そもそも何に対する署名なのか、という話が最後になってしまいました。 署名処理に対する入力データは、「ヘッダー.ペイロード」です。 これまでの例でいうと、次のデータが署名に対する入力データとなります。

3.5. JWS デコードのまとめ

ID トークンは Compact Serialization 形式で表現されているため、下記に再掲するように、そのままでは表現している情報の内容が分かりません。

しかし、RFC 7515 の情報をもとに base64URL デコードしていくことにより、上記の無味乾燥な文字列は、次の情報を持っていることが分かりました。

ここまでの話で、ID トークンとは何かを具体的にイメージできるようになったのではないでしょうか。

3.6. JWS

non garanti せっかくですので、 Unsecured JWS を紹介します。 Unsecured JWS は、署名の無い JWS です。 下記は、RFC 7515 の A.5. Example Unsecured JWS から抜粋した Unsecured JWS の例です。

Unsecured JWS は次のような形式となっており、JWS 内の三番目のフィールドが空になっています。

署名が無いということは、署名アルゴリズムも無いので、JWS ヘッダーの には を指定することになっています。 上記例の JWS ヘッダー部分である を base64url でデコードすると、

次のような JSON が得られます。

確かに が になっていることが分かります。

さて、ID トークンの形式には、これまで説明してきた「ヘッダー.ペイロード.署名」の他に、次のように 5 つのフィールドを持つ形式もあります。

この形式は、 RFC 7516 ( JSON Web Encryption ( JWE )) の「7.1. JWE Compact Serialization」で定義されている「JSON Web Encryption (JWE) の Compact Serialization 形式」です。 具体的には次のように定義されています。 ^{(RFC 7516 は JSON Serialization 形式も定義していますが、ここでは扱いません。 )}

この形式は、ID トークンを暗号化したいときに利用されます。

暗号化の対象となる平文は、暗号化されたあと、4 番目のフィールドに置かれます。 RFC 7516 自体は平文の内容は何でもよいとしていますが、ID トークンの文脈では、平文は「ヘッダー.ペイロード.署名」となります。 つまり、JWE の中に JWS が入っている形になります。

4.1. 二段階の暗号処理

「7.1. JWE Compact Serialization」によれば、Compact Serialization 形式の 2 番目のフィールドは「JWE Encrypted Key」となっています。 Encryption ではなく Encrypted となっているので、日本語に訳すとすれば、「暗号キー」ではなく「暗号化されたキー」となります。 このような表現になっているのには理由があります。

JWE に限った話ではありませんが、特に非対称鍵系暗号を用いる場合、暗号が次のような二段階で行われることがあります。

1. 対称鍵系暗号の共有鍵を用いて、平文を暗号化する。
2. 上記の暗号処理に用いた共有鍵自体を、別の非対称鍵系暗号の鍵を用いて暗号化する。

二段階にすることで、平文の暗号化に対称鍵系暗号を用いて暗号化・復号化にかかる時間を抑えつつ、非対称鍵系暗号の利点を得ることができます。 なお、ここで用いる対称鍵系暗号の共有鍵は、事前に共有しておく必要はなく、暗号処理をおこなう側が暗号処理実行時にランダムに生成することができます。 というのは、ランダムに生成しても、その共有鍵を非対称鍵系暗号の鍵で暗号化して相手側に渡せば、相手側は、その暗号化された共有鍵を非対称鍵系暗号の鍵で復号化することで、当該共有鍵を取り出せるからです。

下図は、二段階の暗号処理を図にしたものです。 JWE Encrypted Key は図中の「暗号化された共有鍵」に相当します。

4.2. 暗号アルゴリズム

JWE では二段階の暗号処理をおこなっています。 それぞれに暗号アルゴリズムがありますので、JWE には二つの暗号アルゴリズムが関わることになります。

平文を暗号文へと暗号化するときに使用するアルゴリズムは、RFC 7518 (JSON Web Algorithms) の「5.1. Valeurs des paramètres d’en-tête « enc » (algorithme de cryptage) pour JWE」に次のようにリストアップされています。

の値	アルゴリズム
AES utilisant IV 128 bits et SHA-256
AES utilisant IV 192 bits et SHA-384
AES utilisant IV 256 bits et SHA-512
AES GCM utilisant une clé 128 bits
AES GCM utilisant une clé 192 bits
AES GCM utilisant une clé 256 bits

一方、共有鍵を暗号化するときに使用するアルゴリズムは「4.1. Valeurs des paramètres d’en-tête « alg » (algorithme) pour JWE」に次のようにリストアップされています。

の値	アルゴリズム
RSAES-PKCS1-v1_5
RSAES OAEP à l’aide des paramètres par défaut
RSAES OAEP à l’aide de SHA-256 et MGF1 à l’aide de SHA-256
Encapsulation de clé AES avec valeur initiale par défaut à l’aide d’une clé de 128 bits
Encapsulation de clé AES avec valeur initiale par défaut à l’aide d’une clé de 192 bits
Encapsulation de clé AES avec valeur initiale par défaut à l’aide d’une clé de 256 bits
Utilisation directe d’une clé symétrique partagée en tant que
clé statique éphémère de Diffie-Hellman à courbe elliptique CEK à l’aide de Concat KDF
ECDH-ES à l’aide de Concat KDF et CEK encapsulé avec « A128KW »
ECDH-ES à l’aide de Concat KDF et CEK enveloppé de « A192KW »
ECDH-ES à l’aide de Concat KDF et CEK enveloppé de « A256KW »
Encapsulation de clés avec AES GCM à l’aide d’une clé de 128 bits
Encapsulation de clés avec AES GCM à l’aide d’une clé de 192 bits
Encapsulation de clés avec AES GCM à l’aide d’une clé de 256 bits
PBES2 avec HMAC SHA-256 et « A128KW » Encapsulation
de PBES2 avec HMAC SHA-384 et « A192KW » d’encapsulation
de PBES2 avec HMAC SHA-512 et d’encapsulation d’un « A256KW »

4.3. 共有鍵を暗号化するアルゴリズム

前節に挙げた「共有鍵を暗号化するアルゴリズム」の識別子のうち、 は特殊です。 というのは、RFC 7518 の「4.5. Chiffrement direct avec une clé symétrique partagée」に次のように書かれているように、 は、二段階暗号方式ではなく直接共有鍵暗号処理をおこなう方式だからです。

Cette section définit les spécificités de l’exécution directe du chiffrement de clé symétrique sans effectuer d’étape d’encapsulation de clé.

RFC 7518 では、共有鍵の決め方について特にルールは定めていません。 一方、OpenID Connect Core 1.0 の「10.2. Encryption」では、対称鍵系暗号使用時のキーに対する要求事項を次のように定めています。

Chiffrement symétrique
La clé de chiffrement symétrique est dérivée de la valeur à l’aide d’un hachage SHA-2 tronqué à gauche des octets de la représentation UTF-8 de la . Pour les touches de 256 bits ou moins, SHA-256 est utilisé ; pour les touches de 257-384 bits, SHA-384 est utilisé ; pour les touches de 385-512 bits, SHA-512 est utilisé. La valeur de hachage DOIT être laissée tronquée à la longueur de bit appropriée pour l’encapsulation de clé AES ou l’algorithme de chiffrement direct utilisé, par exemple, en tronquant le hachage SHA-256 à 128 bits pour . Si une clé symétrique avec plus de 512 bits est nécessaire, une méthode différente de dérivation de la clé à partir de la client_secret devrait être définie par une extension. Le cryptage symétrique NE DOIT PAS être utilisé par des Clients publics (non confidentiels) en raison de leur l’incapacité de garder des secrets.

つまり、「クライアントシークレットを UTF-8 で表現し、SHA-2 系のアルゴリズムでハッシュ値を求め、適切な長さで切り詰めたものを、キーとして用いる」というルールを定めています。

4.4. JWE の例

次のものは、RFC 7516 の「A.1.7. Complete Representation」から抜粋した JWE の例です。 途中改行が含まれていますが、見やすいように入れているだけであり、実際の JWE には改行は含まれません。 なお、この JWE は ID トークンではありません。 暗号化前の平文は「Le vrai signe de l’intelligence n’est pas la connaissance mais l’imagination.」という文字列です。

4.5. JWE ヘッダーのデコード

JWE 内のピリオドで区切られた 5 つのフィールドのうち、一番目のフィールドは JWE ヘッダーです。 base64url でエンコードされてはいますが暗号化はされていないので、前節で挙げた JWE の例のヘッダー部分を base64url でデコードしてみましょう。

結果、次のような JSON が得られます。

ここで、 は共有鍵を暗号化する際のアルゴリズム、 は平文を暗号化する際のアルゴリズムを示しています。 それぞれの有効な値は、「4.2. 暗号アルゴリズム」に挙げたとおりです。

と を含め、JWE ヘッダーで指定可能なパラメーターは、RFC 7516 の「4.1. Registered Header Parameter Names」に列挙されています。

パラメーター名	説明
共有鍵を暗号化するアルゴリズム
平文を暗号化するアルゴリズム
圧縮アルゴリズム
JWK セット URL
JSON Web キー
キー ID
X.509 URL
X.509 証明書チェーン
X.509 証明書 SHA-1 Thumbprint
X.509 証明書 SHA-256 Thumbprint
JWE 自身のメディアタイプ
ペイロードのメディアタイプ
必須パラメーター群指定

4.6. その他の JWE フィールド

説明は割愛します。 詳細は RFC 7516 を参照してください。

JWS の署名や JWE の暗号に非対称鍵系アルゴリズムが使われている場合、そのような JWS や JWE を受け取った側は、署名を検証したり暗号文を復号化するために、署名・暗号で使用された鍵とペアとなる鍵が必要となります。 これは、何らかの形で鍵に関する情報を表現し、JWS や JWE を受け取った側に渡す必要があるということです。

そこで登場するのが、 RFC 7517 ( JSON Web Key ( JWK )) です。 この仕様により、暗号鍵の情報を JSON 形式で表現することができるようになりました。

5. ?. TODO

後日追記します。 動画『OAuth & OIDC 入門編』の 1:06:26 〜 をご覧ください。

JWS と JWE の説明が済んでいるので、 JWT の説明をすることができます。 JWT はジョットと読みます。 この読み方は、RFC 7519 の Introduction に書かれています。

La prononciation suggérée de JWT est la même que celle du mot anglais « jot ».

JWT の仕様は RFC 7519 ( JSON Web Token ( JWT )) で定められています。 簡単に言うと、**「JWT とは、JSON 形式で表現されたクレーム (claim) の集合を、JWS もしくは JWE に埋め込んだもの」**です。

「JSON 形式で表現されたクレームの集合」がどのように JWS や JWE に埋め込まれるのかを先に説明し、その後、クレーム集合の部分を説明します。

6.1. Harmonisation JWS 形式の JWT

JWS 形式の JWT の場合、JSON 形式で表現されたクレームの集合は、BASE64URL エンコード後、JWS の二番目のフィールドに埋め込まれます。

6.2. JWE 形式の JWT

JWE 形式の JWT の場合は、クレームの集合は平文として用いられ、暗号化と BASE64URL エンコードを経て、JWE の四番目のフィールドに埋め込まれます。

6.3. Assurer la traduction Nested JWT

署名もしたいし暗号化もしたい、という場合、JWS を JWE でくるむか、もしくはその逆で、JWE を JWS でくるむか、のどちらかをおこなえば実現できます。 このように、JWE/JWS の中に JWS/JWE がネストしている形式の JWT は、 Nested JWT と呼ばれます。 次の図は、JWS が JWE に含まれているパターンの Nested JWT を示しています。

なお、ID トークンの文脈では、署名は必須で、暗号化をする場合は「signé puis crypté」(署名後に暗号化) という順番が MUST とされています。

(OpenID Connect Core 1.0, 2. ID Token より抜粋)

ID Tokens MUST be signed à l’aide de JWS et, éventuellement, à la fois signés puis chiffrés à l’aide de JWS et JWE respectivement, assurant ainsi l’authentification, l’intégrité, la non-répudiation et, éventuellement, la confidentialité, conformément à l’article 16.14. Si le jeton d’ID est chiffré, il DOIT être signé puis chiffré, le résultat étant un JWT imbriqué , tel que défini dans JWT.

そのため、暗号化された ID トークンは、ちょうど上記の図と同じ「JWS が JWE に含まれている形の Nested JWT」になります。

説明が前後してしまいましたが、 ID トークンは JWT の一種です 。

6.4. JWT クレーム

JWT はクレームの集合なわけですが、形式的には、クレームは JSON オブジェクト内のキー・バリューのペアとして表現されています。 つまり、クレーム集合の部分は次のような形式になっています。

次に挙げる JSON は、RFC 7519 の「3.1. Example JWT」から抜粋したクレーム集合部分の例です。

RFC 7519 では、「4.1. Noms de revendication enregistrés」において幾つかクレーム名を定義しています。

クレーム名	説明
Issuer クレーム
Subject クレーム
Audience クレーム
Expiration Time クレーム
Not Before クレーム
Issued At クレーム
JWT ID クレーム

「3.1. Exemple JWT」から抜粋した例にもあるように、クレーム名にはこれら以外のものを用いても構いませんが、名前衝突を避けるなどの配慮が必要です。

JWT に含めるべきクレームとして必須のものは、実はありません。 「4. JWT Claims」の第二段落には次のように書かれており、JWT がどのようなクレーム群を含むべきかは、JWT を利用する個々のアプリケーションの定める範疇としています。

L’ensemble de revendications qu’un JWT doit contenir pour être considéré comme valide dépend du contexte et sort du champ d’application de cette spécification. Les applications spécifiques des JWT nécessiteront des mises en œuvre pour comprendre et traiter certaines réclamations d’une manière particulière. Cependant, en l’absence de telles exigences, toutes les revendications qui ne sont pas comprises par les implémentations DOIVENT être ignorées.

RFC 7519 の立場から見ると、OpenID Connect Core 1.0 が定める ID トークンは、JWT 応用例の一つとなります。 勘の良い方はすぐに予想されたかもしれませんが、ID トークンの仕様では、RFC 7519 で定義されているクレームの幾つかが必須のクレームとされています。 具体的には、, , , , は必須とされています。

JWT の説明が済んだので、いよいよ ID トークン の説明に入ります。

既に述べてはいますが、改めまして、 ID トークンは JWT の一種です 。 ここで、OpenID Connect Core 1.0 の「2. ID Token」の第一段落を見てみましょう。

L’extension principale qu’OpenID Connect fait à OAuth 2.0 pour permettre aux utilisateurs finaux d’être authentifiés est la structure de données ID Token . Le jeton d’ID est un jeton de sécurité qui contient des revendications relatives à l’authentification d’un utilisateur final par un serveur d’autorisation lors de l’utilisation d’un client, et potentiellement d’autres revendications demandées. L’ID Le jeton est représenté sous la forme d’un jeton Web JSON (JWT).

これによれば、OpenID Connect が OAuth 2.0 に対しておこなった主要な拡張が、まさに ID トークンというデータ構造だということが分かります。 ID トークンが JWT として表現されることも、この段落の末尾に明記されています。

ID トークンには、エンドユーザー認証に関するクレーム群 (Claims about the Authentication) とその他のクレーム群が含まれます。 ID トークンで利用するクレーム群のうち、主要なものは OpenID Connect Core 1.0 の「2. Jeton d’identification」と「5.1. Standard Claims」で説明されています。 また、細かい話ですが、「3.3.2.11. ID Token」では、, というクレームも定義されています。

それでは、ID トークンのクレームを一つ一つ見ていくことにします。

7.1. iss クレーム

仕様	説明
RFC 7519	La revendication « iss » (émetteur) identifie le mandant qui a émis le JWT. Le traitement de cette revendication est généralement spécifique à l’application. La valeur « iss » est une chaîne sensible à la casse contenant une valeur StringOrURI. Utilisation de cette revendication est FACULTATIF.
TRONC COMMUN DE L’OÏDC	REQUIS. Identifiant de l’émetteur de la réponse. La valeur est une URL sensible à la casse utilisant le schéma qui contient les composants scheme, host et, éventuellement, numéro de port et chemin d’accès, ainsi que aucun composant de requête ou de fragment.

クレームは、JWT の発行者 (issuer) を識別するための識別子です。 クレームの値は、RFC 7519 では文字列か URI (StringOrURI) とされていますが、OpenID Connect Core 1.0 のほうの定義では、より条件が多くなっており、「 で始まる URL (ただしクエリー部とフラグメント部は含まない)」とされています。

次に挙げる例は、 クレームの値として有効な URL です。

ID トークン発行サーバーは、他者の識別子との衝突を避けるため、 クレームの値を自分の管理下にあるドメイン名の URL とすべきです。 これに加えて、もしも、 OpenID Connect Discovery 1.0 という仕様をサポートするのであれば、「」という URL でリクエストを受け付ける必要があることを念頭に置いて クレームの値を決める必要があります。

例えば、もし上記の例のように クレームの値を とし、かつ、OpenID Connect Discovery 1.0 をサポートするのであれば、次の URL で HTTP GET リクエストを受け付けて適切な JSON データを返せなければなりません。

参考までに、Google 社による実装はこちらになります。

7.2. sub クレーム

仕様	説明
RFC 7519	La revendication « sub » (sujet) identifie le principal qui fait l’objet du JWT. Les affirmations d’un JWT sont normalement des déclarations sur le sujet. La valeur du sujet DOIT soit être délimitée de manière à être unique localement dans le contexte de l’émetteur, soit être unique à l’échelle mondiale. Le traitement de cette revendication est généralement spécifique à l’application. La valeur « sub » est une chaîne sensible à la casse contenant une valeur StringOrURI. L’utilisation de cette revendication est FACULTATIVE.
TRONC COMMUN DE L’OÏDC	REQUIS. Identificateur de l’objet. Un identifiant unique localement et jamais réattribué au sein de l’Émetteur pour l’Utilisateur final, qui est destiné à être consommé par le Client, par exemple, ou . Il NE DOIT PAS dépasser 255 caractères ASCII en longueur. La valeur est une chaîne sensible à la casse.

クレームは、ユーザーの一意識別子を表します。 値の形式は、RFC 7519 では文字列か URI (StringOrURI) とされており、OpenID Connect Core 1.0 では 255 文字以内の ASCII 文字列とされています。

突然、「ユーザーの一意識別子」というものがでてきました。 これまで説明はしていませんでしたが、ID トークンはユーザーを認証した結果発行されるものなので、どのユーザーが認証されたのかの情報が含まれることになります。 その「どのユーザーが認証されたのか」という情報にあたる部分が、 クレームです。 クレームの値は、ID トークン発行者のシステム内において、ユーザーを一意に特定することが可能な識別子です。

ユーザーの一意識別子は、一般的には、データベース内のユーザーテーブルのプライマリーキーやそれに準ずるものです。 特に気にしないのであれば、プライマリーキーの値をそのまま の値として用いてもかまいません。 気にするのであれば、何らかのロジックを用いて元々の値を変換してから クレームの値として用いることになります。 場合によっては、ID トークンの発行を依頼したプログラムの違いによって、同じプライマリーキーから異なる クレーム値を生成してもかまいません。 これについては、OpenID Connect Core 1.0 の「8. Subject Identifier Types」に言及があります。

7.3. aud クレーム

仕様	説明
RFC 7519	La revendication « aud » (audience) identifie les destinataires auxquels le JWT est destiné. Chaque principe destiné à traiter le JWT DOIT s’identifier avec une valeur dans la revendication d’audience. Si le mandant traitant la revendication ne s’identifie pas avec une valeur dans la revendication « aud » lorsque cette revendication est présente, alors le JWT DOIT être rejeté. Dans le cas général, la valeur « aud » est un tableau de chaînes sensibles à la casse, chacune contenant une valeur StringOrURI. Dans le cas particulier où le JWT a une seule audience, la valeur « aud » PEUT être une seule chaîne sensible à la casse contenant une valeur StringOrURI. L’interprétation des valeurs d’auditoire est généralement propre à l’application. L’utilisation de cette revendication est FACULTATIVE.
TRONC COMMUN DE L’OÏDC	REQUIS. Public(s) à qui(s) ce jeton d’identification est destiné. Il DOIT contenir l’OAuth 2.0 de la partie de confiance en tant que valeur d’audience. Il PEUT également contenir des identifiants pour d’autres publics. Dans le En général, la valeur est un tableau de chaînes sensibles à la casse. Dans le cas particulier courant où il y a une audience, la valeur PEUT être une chaîne sensible à la casse unique.

クレームは、当該 JWT が、誰を対象として発行されたのかを示すものです。 別の言い方をすると、JWT の受け取り手が誰であるべきかを示しています。 ID トークンの場合、この クレームの値は、ID トークンの発行を依頼したクライアントアプリケーションのクライアント ID となります。

7.4. exp クレーム

仕様	説明
RFC 7519	La revendication « exp » (délai d’expiration) identifie le délai d’expiration à partir duquel le JWT ne doit pas être accepté pour traitement. Le traitement de la demande « exp » exige que la date et l’heure actuelles DOIVENT être antérieures à la date et à l’heure d’expiration indiquées dans la demande « exp ». Les implémenteurs PEUVENT prévoir une petite marge de manœuvre, généralement pas plus de quelques minutes, pour tenir compte du décalage d’horloge. Son value DOIT être un nombre contenant une valeur NumericDate. L’utilisation de cette revendication est FACULTATIVE.
TRONC COMMUN DE L’OÏDC	REQUIS. Délai d’expiration à partir duquel le jeton d’identification NE DOIT PAS être accepté pour le traitement. Le traitement de ce paramètre nécessite que la date/heure actuelle DOIT être antérieure à la date/heure d’expiration indiquée dans la valeur. Les implémenteurs PEUVENT prévoir une petite marge de manœuvre, généralement pas plus de quelques minutes, pour tenir compte du décalage d’horloge. Sa valeur est un nombre JSON représentant le nombre de secondes entre 1970-01-01T0:0:0Z mesuré en UTC jusqu’à la date/heure. Voir la RFC 3339 pour plus de détails concernant la date/heure en général et l’UTC en particulier.

クレームは JWT の有効期限を示しています。 ID トークンでは、Unix エポック (1970 年 1 月 1 日 (世界標準時)) からの経過秒数となっています。 単位はミリ秒ではなく秒なので、ID トークンを生成もしくはパースするプログラムを書く際には注意が必要です。

7.5. iat クレーム

La

RFC
7519	revendication « iat » (émis à) identifie le moment où le JWT a été émis. Cette affirmation peut être utilisée pour déterminer l’âge du JWT. Sa valeur DOIT être un nombre contenant une valeur NumericDate. L’utilisation de cette revendication est FACULTATIVE.
TRONC COMMUN DE L’OÏDC	REQUIS. Heure à laquelle le JWT a été émis. Sa valeur est un nombre JSON représentant le nombre de secondes entre 1970-01-01T0:0:0Z mesuré en UTC jusqu’à la date/heure.

クレームは JWT が発行された日時を示しています。 クレームと同様、Unix エポックからの経過秒数で表現されています。

7.6. auth_time クレーム

仕様

説明

OIDC Core

Time lors de l’authentification de l’utilisateur final s’est produite. Sa valeur est un nombre JSON représentant le nombre de secondes entre 1970-01-01T0:0:0Z mesuré en UTC jusqu’à la date/heure. Lorsqu’une demande est faite ou lorsqu’elle est demandée en tant que Réclamation Essentielle, alors cette Réclamation est REQUISE ; sinon, son inclusion est FACULTATIVE. (La revendication correspond sémantiquement au paramètre de réponse PAPE OpenID 2.0.)

クレームは、ユーザーが認証された時刻を Unix エポックからの経過秒数で表現しています。 このクレームは RFC 7519 では定義されていません。

ユーザー認証は、ID トークンの発行と同じタイミングで実行されるとは限りません。 認証後しばらくたってから ID トークン発行依頼が届いたものの、「既にログイン状態だから認証が終わっているものとみなす」ということで、認証処理をスキップして ID トークンが発行されることがあります。 このようなケースの場合、ユーザーが認証された時刻 () と ID トークンが発行された時刻 () には、差がでてきます。

クレームを ID トークンに含めるかどうかは、基本的には任意です。 しかし、ID トークン発行依頼が「認証後許容経過時間」を指定する リクエストパラメーターを伴っていたり (「OAuth & OpenID Connect 関連仕様まとめ」の「17. 認証後許容経過時間 」参照)、ID トークン発行依頼を出したクライアントアプリケーションのメタ情報設定が「ID トークン発行時に クレームを必須とする」となっていたりすると (OpenID Connect Dynamic Enregistrement du client 1.0 の「2. Client Metadata」の 参照)、 クレームは必須となります。

7.7. nonce クレーム

仕様

説明

Valeur de la chaîne de caractères de base OIDC

utilisée pour associer une session client à un jeton d’ID et pour atténuer les attaques par rejeu. La valeur est transmise sans modification de la demande d’authentification au jeton d’ID. S’il est présent dans le jeton d’ID, les clients DOIVENT vérifier que la valeur de revendication est égale à la valeur du paramètre envoyé dans la demande d’authentification. S’ils sont présents dans la demande d’authentification, les serveurs d’autorisation DOIVENT inclure une revendication dans le jeton d’identification, la valeur de revendication étant la valeur nonce envoyée dans la demande d’authentification. Les serveurs d’autorisation ne devraient effectuer aucun autre traitement sur les valeurs utilisées. La valeur est une chaîne sensible à la casse.

主にリプレイアタックを防ぐ目的で、ID トークン発行依頼に というリクエストパラメーターが付いてくることがあります。 このとき、ID トークン発行側は、受け取った の値をそのまま ID トークンに埋め込みます。

7.8. acr クレーム

仕様

説明

OIDC Core

OPTIONAL. Référence de la classe de contexte d’authentification. Chaîne spécifiant une valeur de référence de classe de contexte d’authentification qui identifie la classe de contexte d’authentification que l’authentification effectuée a satisfaite. La valeur « 0 » indique que l’authentification de l’utilisateur final n’a pas satisfait aux exigences de la norme ISO/IEC 29115 niveau 1. Les authentifications de niveau 0 NE DOIVENT PAS être utilisées pour autoriser l’accès à une ressource de n’importe quelle valeur monétaire. (Cela correspond à l’OpenID 2.0, OpenID 2.0, PAPE 0.) Une URI absolue ou un nom enregistré RFC 6711 DEVRAIT être utilisé comme valeur ; les dénominations enregistrées NE DOIVENT PAS être utilisées avec un sens différent de celui qui est recommandé. Les parties qui utilisent cette revendication devront s’entendre sur la signification des valeurs utilisées, qui peut être spécifique au contexte. La valeur est une chaîne sensible à la casse.

クレームは、ユーザー認証が満たした認証コンテキストのクラスを示しています。 例えば、パスワードによる認証という基準を満たしたとか、X.509 での認証という基準を満たした、というような情報です。 認証コンテキストに関連する仕様についは、「OAuth & OpenID Connect 関連仕様まとめ」の「16. 認証コンテキストクラス」を参照してください。

7.9. amr クレーム

仕様

説明

OIDC Core

OPTIONAL. Références sur les méthodes d’authentification. Tableau JSON de chaînes qui sont des identificateurs pour les méthodes d’authentification utilisées dans l’authentification. Par exemple, les valeurs peuvent indiquer que les méthodes d’authentification par mot de passe et OTP ont été utilisées. La définition des valeurs particulières à utiliser dans la revendication dépasse le champ d’application de la présente spécification. Les parties qui utilisent cette revendication devront s’entendre sur la signification des valeurs utilisées, qui peut être spécifique au contexte. La valeur est un tableau de chaînes sensibles à la casse.

クレームは、認証手法を示しています。 その具体的な値については、(少なくとも) OpenID Connect Core 1.0 の仕様の範囲外とされており、 クレームの利用者が規則を決めて運用すべきもの、という扱いになっています。

7.10. azp クレーム

仕様

説明

OIDC Core

OPTIONAL. Partie autorisée : la partie à laquelle le jeton d’identification a été émis. S’il est présent, il DOIT contenir l’ID client OAuth 2.0 de cette partie. Cette revendication n’est nécessaire que lorsque le jeton d’identification a une valeur d’audience unique et que cette audience est différente de la partie autorisée. Il PEUT être inclus même lorsque la partie autorisée est la même que le seul public. La valeur est une chaîne sensible à la casse contenant un Valeur StringOrURI.

クレームは、認可された対象者を示しています。 認可されたクライアントアプリケーションのクライアント ID の値です。 このクレームは、ID トークンの発行を依頼したクライアントアプリケーションと認可されたクライアントアプリケーションが異なる場合、必要となります。 しかし、発行依頼したクライアントと認可されたクライアントが異なるというのは、あまりきかないユースケースです。

7.11. ユーザー属性クレーム群

ユーザーの属性に関するクレームは、「5.1. Standard Claims」でまとめて定義されています。

クレーム名	説明
ユーザーの一意識別子
フルネーム
名
姓
ミドルネーム
ニックネーム
好みのユーザー名
プロフィールページの URL
プロフィール画像の URL
Web サイトやブログの URL
メールアドレス
メールアドレスが検証済みか否かの真偽値
性別。 と が定義済み。
誕生日。 という書式。
タイムゾーン。 など。
ロケール。 など。
電話番号
電話番号が検証済みか否かの真偽値
住所。 書式は「5.1.1. Réclamation d’adresse」に記載。
情報最終更新日。 Unix エポックからの経過秒数。

これらのクレーム群を ID トークンに含める際、クレームによっては多言語化可能なものがあります。 例えば、 クレームの場合、英語なら「Kawasaki」、日本語なら「川崎」や「カワサキ」というように、値が幾つか考えられます。 このような多言語化への対応のため、クレーム名の後ろに「」をつけるという仕組みがあり、「5.2. Claims Languages and Scripts」で詳細に説明されています。

次の JSON の断片は、言語タグ付きの クレームの例です。

言語タグそのものの詳細については RFC 5646 (Tags for Identifying Languages) を参照してください。

7.12. ハイブリッドフロー関連のクレーム群

詳細は後編で説明する予定ですが、ID トークンと同時に、アクセストークンや認可コードというものが一緒に発行される場合があります。 もしこれらが同時に発行される場合、ID トークンに幾つかクレームが追加されます。 「3.3.2.11. ID Token」に詳細説明があります。

クレーム名	説明
Valeur de hachage du jeton d’accès. Sa valeur est l’encodage base64url de la moitié la plus à gauche du hachage des octets de la représentation ASCII de la valeur, où l’algorithme de hachage utilisé est l’algorithme de hachage utilisé dans le paramètre d’en-tête de l’en-tête JOSE du jeton d’ID. Par exemple, si le est , hachez la valeur avec SHA-256, puis prenez les 128 bits les plus à gauche et encodez-les en base64url. La valeur est une chaîne sensible à la casse. Si le jeton d’ID est émis à partir du point de terminaison d’autorisation avec une valeur, ce qui est le cas pour la valeur , celle-ci est OBLIGATOIRE ; sinon, son inclusion est FACULTATIVE.
Valeur de hachage du code. Sa valeur est l’encodage base64url de la moitié la plus à gauche du hachage du octets de la représentation ASCII de la valeur, où l’algorithme de hachage utilisé est l’algorithme de hachage utilisé dans le paramètre d’en-tête de l’en-tête JOSE du jeton d’ID. Par exemple, si le est , hachez la valeur avec SHA-512, puis prenez les 256 bits les plus à gauche et encodez-les en base64url. La valeur est une chaîne sensible à la casse. Si le jeton d’ID est émis à partir du point de terminaison d’autorisation avec un , ce qui est le cas pour les valeurs et , cela est OBLIGATOIRE ; sinon, son inclusion est FACULTATIVE.

ID トークンと同時にアクセストークンも発行される場合、 というクレームが追加されます。 の値は、アクセストークンのハッシュをとり、結果として得られたハッシュ値の左半分のビット群を base64URL でエンコードしたものです。 同様に、認可コードが同時に発行される場合は、 というクレームが追加されます。

加えて、 クレームが必須となります。

**「OpenID Connect は『ID トークン』を発行するための仕様である」*という割り切り方のもと、 ID トークン とは具体的にどんなものであるかを理解することに努めました。

ID トークンは、形式は JWT (RFC 7519)、意味内容はクレームの集合、ということが分かりました。 JWT という形式なので、署名や暗号化が可能であり、認証の事実やユーザー属性情報のやりとりが、より安全に行えるようになっています。

---

こちらも併せてご覧いただければと思います。

---

追記(2020-03-20)
この記事の内容を含む、筆者本人による『 OAuth & OIDC 入門編 』解説動画を公開しました !