Private Key JWT 認証を設定する

新規および既存のアプリケーションで Private Key JWT 認証を使用するための設定方法について説明します。

Private Key JWT は Enterprise plan のお客様のみご利用いただけます。アップグレードするには、Auth0 pricing にお問い合わせください。

Private Key JWT 認証は、非対称鍵ペアで署名された JWT アサーションを使用する OIDC Connect Core Client Authentication 1.0 のクライアント認証をサポートしています。新しいアプリケーションを作成して private_key_jwt を使用することも、既存のアプリケーションで認証に鍵ペアを使用できるようにすることもできます。

​

前提条件

Private Key JWT を使用して認証を行うアプリケーションを設定する前に、RSA キーペアを生成する必要があります。

​

Private Key JWT の設定

Auth0 Dashboard

Auth0 Dashboard を使用して、新しいアプリケーションを作成して資格情報を設定したり、既存のアプリケーションを更新したりできます。

アプリケーションの認証方法を Private Key JWT に設定する前に、現在の client_secret パラメーターを安全に保存しておくことを推奨します。Private Key JWT の設定が完了すると、client_secret パラメーターは表示されなくなります。

​

private_key_jwt 用の新しいアプリケーションを設定する

1. Auth0 Dashboard > アプリケーション > アプリケーション に移動します。

2. Create Application を選択します。

3. アプリケーションの種類を選択します。

4. アプリケーションの設定で、Credentials タブを選択します。

5. Authentication Methods で、Private Key JWT を選択します。

   

6. 資格情報の詳細を設定します。

   1. 資格情報の名前を入力します。

   2. PEM 形式または X.509 証明書をアップロードします。

   3. アサーションの署名に使用するアルゴリズムを選択します。

   4. 任意: カスタムの有効期限を有効にします。Set an explicit expiry date for this Credential を選択し、将来の日付を設定します。

      形式が不正なキー素材を送信すると、無効な証明書エラーが発生する場合があります。問題を避けるため、openssl で直接作成したファイルをアップロードすることをおすすめします。

7. Add Credential を選択します。

​

既存のアプリケーションを設定する

1. Auth0 Dashboard > アプリケーション に移動します。

2. 更新するアプリケーションを選択します。

3. Credentials タブを選択します。

4. Private Key JWT を選択します。

5. 資格情報の詳細を設定します。

   1. 資格情報の名前を入力します。
   2. PEM 形式または X.509 証明書をアップロードします。
   3. アサーションの署名に使用するアルゴリズムを選択します。
   4. 任意: カスタムの有効期限を有効にします。Set an explicit expiry date for this Credential を選択し、将来の日付を設定します。

6. Add Credential を選択します。

​

Client Secret 認証を使用するようにアプリケーションを設定する

1. Auth0 Dashboard > アプリケーション > アプリケーション に移動し、更新するアプリケーションを選択します。
2. Credentials タブを選択します。
3. Client Secret (Post) または Client Secret (Basic) を選択します。
4. Save を選択します。

​

資格情報の有効期限を更新する

有効期限が設定された既存の資格情報は、Auth0 Dashboard で更新できます。

1. Auth0 Dashboard > アプリケーション > アプリケーション に移動し、更新するアプリケーションを選択します。

2. Credentials タブを選択します。

3. 更新する資格情報を選択し、Edit Credential を選択します。

   

4. Set an explicit expiry date for this Credential を選択し、将来の日付を設定します。

5. Update Credential を選択します。

Management API

​

private_key_jwt 用の新しいアプリケーションを設定する

Management API を使用して、private_key_jwt を認証方法とする新しいアプリケーションを作成できます。以下のペイロードを指定して、Create a Client エンドポイントに POST リクエストを送信してください。

curl --location --request POST 'https://{domain}/api/v2/clients' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
 "name": "{clientName}",
 "app_type": "non_interactive",
 "client_authentication_methods": {
   "private_key_jwt": {
     "credentials": [
       { 
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at": "{expiresAt}"
       }
     ]
   },
   "jwt_configuration": {
     "alg": "RS256"
   }
 }
}'

パラメーター	説明
algorithm	アサーションの署名に使用するアルゴリズム。サポート対象の値は RS256、RS384、PS256 です。指定しない場合、デフォルトで RS256 が使用されます。
clientName	新しいクライアントの名前。
credentialName	公開キーの名前。
expires_at	任意。資格情報の有効期限を ISO 8601 形式で指定します。たとえば 2020-08-20T19:10:06.299Z です。有効期限を過ぎると、資格情報は無効になります。
managementApiAccessToken	Management API 用のアクセストークン (スコープ create:credentials が付与されたもの) 。
pem	PEM 形式でエンコードされた公開キー、または x.509 証明書。
parse_expiry_from_cert	任意。証明書が指定された場合に Auth0 がその有効期限を解析することを示すブール値です。証明書が指定されていない場合、Auth0 はエラーを返します。parse_expiry_from_cert と expires_at は相互に排他的でもあります。この場合も、Auth0 はエラーを返します。

公開キーのPEMは、Auth0 に渡す前に JSON エスケープしておく必要があります。この例では、渡す必要がある内容は次のとおりです。

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----

レスポンスには、アプリケーションをリソースサーバーにリンクする client_id プロパティが含まれています。また、作成した認証情報に対して生成された kid も含まれており、後で client_assertion を生成する際に使用します。

Auth0 は、資格情報の kid を生成するために、JSON Web Key Thumbprint 標準に準拠しています。

kid は、公開キーの JWK 表現を SHA256 でダイジェスト化し、それを base64URL エンコードしたもので構成されます。

​

既存のアプリケーションを設定する

Auth0 Management API を使用して、既存のアプリケーションに Private Key JWT 認証を設定することもできます。token_endpoint_auth_method フィールドの値を削除し、client_authentication_methods フィールドに値を追加する必要があります。

既存の本番環境のアプリケーションを private_key_jwt で認証するように更新する場合は、後で参照できるよう、現在の client_secret の値を安全に保存しておくことをお勧めします。

private_key_jwt を設定すると、アプリケーションの設定を Client Secret を使用する構成に戻さない限り、client_secret の値にはアクセスできなくなります。

認証情報リソースを作成する

キーペアを生成したら、クレデンシャルリソースを作成します。Management APIの/clientsエンドポイントに以下のPOSTリクエストを送信してください。

curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/credentials' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at ": "{expiresAt}",
}'

パラメーター	説明
algorithm	アサーションの署名に使用するアルゴリズム。指定できる値は RS256、RS384、PS256 です。指定しない場合、デフォルトのアルゴリズムは RS256 です。
clientId	更新対象のアプリケーションの ID。
credentialName	公開キーの名前。
managementApiAccessToken	Management API 用アクセストークン (スコープ create:credentials が付与されたもの) 。
pem	PEM 形式でエンコードされた公開キー、または X.509 証明書。
expires_at	任意。認証情報の有効期限を ISO 8601 形式で指定します。たとえば、2020-08-20T19:10:06.299Z です。有効期限を過ぎると、その認証情報は無効になります。
parse_expiry_from_cert	省略可能。証明書が指定された場合に、Auth0 がその有効期限を解析することを示すブール値です。証明書が指定されていない場合、Auth0 はエラーを返します。parse_expiry_from_cert と expires_at は同時に指定できません。この場合も、Auth0 はエラーを返します。

PEM公開キーは、Auth0 に渡す前に JSON 用にエスケープする必要があります。この例で渡す必要がある内容は、次のとおりです。

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb
jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g
Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg
IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx
+wIDAQAB
-----END PUBLIC KEY-----

クレデンシャル ID がレスポンスで返されます。次のステップでこの ID を使用してください。

認証情報を関連付ける

資格情報を作成したら、アプリケーションに関連付けます。アプリケーションは、private_key_jwt による認証時にこれらの資格情報を使用します。

Management API の Update a Client エンドポイントに PATCH リクエストを送信します：

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": null, 
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": {credentialId} }]
             }
          }
   }​​'​​

パラメーター	説明
clientId	更新対象のアプリケーションのID。
managementApiAccessToken	update:client および update:credentials のスコープを持つ Management API 用のアクセストークン。
credentialId	作成した認証情報のID。
pem	PEM形式の公開キー。

Auth0 では、アプリケーションの JWT 署名アルゴリズムとして HS256 を使用することはサポートされていません。jwt_configuration.alg フィールドは RS256 に設定する必要があります。署名アルゴリズムの変更方法については、Application Signing Algorithms を変更する を参照してください。

​

クライアントシークレット認証を使用するようにアプリケーションを設定する

アプリケーションの設定をClient Secretを使用する状態に戻すには、client_authentication_methodsを無効にし、認証方法を指定してtoken_endpoint_auth_methodを再度有効にする必要があります。

認証方法を client_secret に設定すると、アプリケーションは client_secret を使用するように更新するまで、private_key_jwt を使用して認証できなくなります。

例

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": "{tokenEndpointAuthMethod}", 
          "client_authentication_methods": null
   }​​'​​

パラメーター	説明
clientId	更新後のアプリケーションのID。
managementApiAccessToken	スコープ update:client および update:credentials を持つ Management API 用アクセストークン。
tokenEndpointAuthMethod	最終的に使用する認証方法。たとえば、client_secret_basic または client_secret_post。

​

有効期限フィールドを使用して資格情報にパッチを適用する

Management API の Update a credential エンドポイントを使用して、既存の資格情報に有効期限を追加して更新できます。

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId} ' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "expires_at": {expiresAt}
   }'

パラメータ	説明
managementApiAccessToken	Management API の update:credentials スコープが付与されたアクセストークン。
clientId	更新対象のクライアント。
expires_at	認証情報の有効期限を ISO 8601 形式で指定します。たとえば、2020-08-20T19:10:06.299Z です。

更新できるフィールドは expires_at フィールドのみです。その他の属性は変更不可のため、変更するにはクレデンシャルをローテーションする必要があります。

​

資格情報の制限

Auth0 では、RSA キーの最小サイズは 2048 ビット、最大サイズは 4096 ビットです。アプリケーションに設定できる資格情報は最大 2 つです。

​

資格情報のローテーション

キーの漏えいによるリスクを防ぐため、Auth0 ではキー ペアを定期的にローテーションすることを推奨しています。方法については、資格情報のローテーションをご覧ください。

​

詳しくはこちら

• アプリケーションの資格情報
• 資格情報の設定
• Private Key JWT を使用して認証する