Private Key JWT 認証を設定する

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

Private Key JWT は Enterprise プランのお客様のみご利用いただけます。アップグレードするには、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 > Applications > Application に移動します。

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 > Applications に移動します。

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 > Applications > Applications に移動し、更新するアプリケーションを選択します。
2. Credentials タブを選択します。
3. Client Secret (Post) または Client Secret (Basic) を選択します。
4. Save を選択します。

​

認証情報の有効期限を更新する

Auth0 Dashboard を使用して、既存の認証情報に設定されている有効期限を更新できます。

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

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	スコープ create:credentials を持つ Management API のアクセストークン。
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 の値にアクセスできなくなります。

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

キーペアを生成したら、認証情報リソースを作成します。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	Management API 用のアクセストークン (スコープ update:client および update:credentials が必要) 。
credentialId	作成した認証情報のID。
pem	PEM形式の公開鍵。

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

​

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

アプリケーションの設定をクライアントシークレット使用に戻すには、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	Management API 用のアクセストークン (update:client および update:credentials スコープが必要) 。
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 で認証する