クライアントの mTLS 認証を設定する

クライアントの mTLS 認証を設定する方法を説明します。

Management API と Auth0 Dashboard を使用して、クライアントの mTLS 認証を設定する方法を確認します。

Auth0 Dashboard

Auth0 Dashboard を使用すると、クライアントの mTLS を設定して、認可サーバーに対する mTLS クライアント認証を有効にできます。

1. Auth0 Dashboard > Applications > Applications に移動します。

2. mTLS で使用するアプリケーションを選択するか、新しいアプリケーションを作成 します。

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

4. 必要な Authentication Method を選択します。選択肢は次のとおりです。

   • 自己署名証明書 を使用する mTLS
   • 認証局署名証明書を使用する mTLS

5. 使用する証明書の種類を選択したら、次の操作を実行できます。

   • 既存の資格情報 (証明書) をクライアントアプリケーションに割り当てる
   • 証明書をアップロードして新しい資格情報を追加する

Management API

Auth0 Management API を使用して、クライアントの mTLS を設定します。

以下の例では、$management_access_token、つまり Management API アクセストークン を指定しています。これを、少なくとも次のスコープを含むアクセストークンに置き換える必要があります。

• create:custom_domains
• read:custom_domains
• create:clients
• update:clients
• update:client_credentials
• update:client_keys
• update:tenant_settings

必要なスコープを持つアクセストークンを取得する方法について詳しくは、アクセストークンの取得 を参照してください。

​

自己署名証明書

mTLS認証時にクライアントのIDを検証するために自己署名証明書を使用します。ただし、自己署名証明書には次の制限があります

• 自己署名証明書は、Amazon などの一部のクラウドプロバイダーでは受け入れられません。
• プラットフォームの安定性を確保するため、Auth0 では登録できる証明書を 2 件までに制限しています。

証明書を生成する

自己署名mTLSを使用して認証するには、新しい自己署名クライアント証明書を作成する必要があります。

次のコードサンプルは、新しい自己署名証明書を生成します。

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

curl または Wget を使用する場合、PEM 証明書を Auth0 に渡す前に JSON エスケープする必要があります。たとえば、改行は \r\n に置き換えてください。

-----BEGIN PRIVATE KEY-----\r\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDDXAVKQo2SUMHH\r\no9ecWYNiL5\/yva5NSj8uQjKoeRAsOIOAyOBTLxgwmno13xZ8VDkcT1cHTlC+2CkE\r\noBII4OUbHPVof+dtknkL+jUBdIPX1QvlGSUbzduZE4hEEQ8zH6w4EAA2VN72Bymn\r\nT8i\/+Tz9Dx6M1nkuXPCwM7sYEuq5OrqT5yVB6KByKKElp\/tauJkHp0st04iGDgl2\r\nFJUt3QJFCFewTDDdGq62otVJxHfouXPmHBQjzf+f1CZy+N0q2z+JGRt44YZq+F9y\r\ne3RWawvv2x3TXgRBLpvIKqf99LoPVdwozHl8QODu52dyelvLQ866XLhAALuMwic\/\r\nbQbolnMpAgMBAAECggEAf6LliekFmezNTmQLgIkzP7kh5XRsJu81bEGv20aNfHbH\r\n5CJZ\/b8tLMQgyIWiqURVs9taXtmaA7YyxmTWo5pb1WUMKWQ3je0+zMaCTxsS8Lau\r\n+NV+2zWaHd8XDnGe3qX43QAHQ3gb294+JqQH4vUyFZwFN7sAnXv3fQevW0Ewvics\r\nOua\/xNa7y5hbJUPZiQjRhO+n+gTEqpfsnPWNlm9hk\/wVnnjKvMfstN4zUbznRAoN\r\nW8TK82tiVWAXW4CjgIBtVRZjTA9x3UOtbhcvNzaTRxc+scCpIpAVuurS+ZIKZdpm\r\nNnhiOk3akpLU3KZrm8C5JQRn8cupY9WkfCiLXbMFAQKBgQD9JfVMv6zDeNvExneR\r\n7fZDIT2UAEhYExwRJwQPyxkVPwev9HBYuuaaknIbomWTkt\/B6Q3k3p6VI4lxhnVl\r\nbkpOYl5UquP3VoVROEJts224hKgVcLw6s+i+lZDOAleNgbN7rj82l4BIu+SEj\/7c\r\nz94hAa\/wRRvsW+QnxF1sZnpY+QKBgQDFj2h8I4noFJk3sbbk3qQdi5+49ibWSuhc\r\nXVpU+0dQ1lRlhXYT9cDMc22HRt8hjXUNRhdpXvOqVaFiBjv9wBsmFyaJO3tOK3uE\r\ndBgD4lF03bnbGI7\/I3DivW\/tyEMS5JXI\/qrpdWor+wR30c5M\/45y2AGpjwnoGf+D\r\nX8SAMzknsQKBgQCrSljuIrBK3+eNAWH821CL4d0h3QMWnW+bZ5QG\/70sNCcGd1bh\r\noy3Qn5EYg81JitNfCUw+dihF7\/LbX0jmZjdfTI5Zqfxw6xlweKnyQrvWY+S8BTlI\r\nW138P4Xo74rAlGeXI7NgRCkojgK1dB3W2cyK9vJOmOSpDRCXm\/Y\/GCRnOQKBgCE\/\r\n75\/lA1LSFK9w8401g32NgEZK92JdnRnehFOFLw2F5RJpEeRuGhLO4oJABVHKUwb2\r\n4v3TA0OJwe2Tiwk8CdWxU8UJA8m2O8WhHGGa94apwpwDWB3MwzUGGQ52BAPsAOGh\r\nKva70jCwwKHB5+zBniHqBO2aq1oq9fwQZCwHcvkhAoGBAIa8QMHNrX7AuCSAeR4\/\r\n\/7XrGU1a4oExz417AYgZOuGaYQAI5BMIjRZZ3JTzO\/QsmkzeS1tFuBlih8li\/t4l\r\nE2TdnKhy376A6QWfbTDkJN6gzFeaMKwe98mOHKeq0KZITGYVTSa2AYH5zaro0Yku\r\nonOH1NdyEKFFgxGLg7wveYUW\r\n-----END PRIVATE KEY-----

新しいクライアントを作成する

新しいクライアントを作成するには、以下のペイロードを指定して /clients エンドポイントにPOSTリクエストを送信します。

• $client_name: 新しいクライアントの名前
• $credential_name: 公開鍵の名前
• $credential_certificate: 前のステップで生成した$certificate_pemの内容

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "x509_cert", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

詳細については、クライアントの作成 API ドキュメントを参照してください。

既存のクライアントを更新する

既存のクライアントをmTLSクライアント認証に対応させるには、token_endpoint_auth_method フィールドの値を削除し、client_authentication_methods フィールドに値を設定します。

クライアントを mTLS 用に設定すると、mTLS を使用しないように token_endpoint_auth_method を設定しない限り、クライアントシークレットを使用して認証できなくなります。詳しくは、クライアントでクライアントシークレットを使用する設定に戻すを参照してください。

認証情報リソースの作成

証明書を生成したら、クレデンシャルリソースを作成します。

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "x509_cert", 
  "pem": "$credential_certificate"
}'

Auth0 はレスポンスでクレデンシャル ID を返します。この ID を使用して、クレデンシャルをクライアントに関連付けてください。

詳細については、クライアント資格情報の作成 API ドキュメントを参照してください。

クライアントへの認証情報の関連付けと token_endpoint_auth_method の無効化

アップロードされた資格情報は、クライアント認証に対して自動的に有効化されません。新しい自己署名クライアント証明書を使用するように、クライアント認証を更新してください。

次のPATCHリクエストは、token_endpoint_auth_methodをnullに設定することでクライアントシークレット認証を無効にします。また、認証情報IDを使用してclient_authentication_methodsを更新します。

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

このリクエストが完了すると、クライアントシークレットは受け付けられなくなり、クライアントはmTLSを使用して認証する必要があります。

詳細については、クライアントの更新 API ドキュメントを参照してください。

​

認証局署名付き証明書

クライアントによって生成され信頼チェーンを持たない自己署名証明書とは異なり、認証局 (CA) 署名証明書は信頼された第三者機関によって発行されるため、より信頼性が高いとみなされます。CA署名証明書は、Amazonなど一部のクラウドプロバイダーで受け入れられる唯一の証明書の種類です。

CA署名証明書のアイデンティティ情報には、識別名 (DN) という概念が埋め込まれています。特定のCAによって作成された個々の証明書はそれぞれ固有ですが、共通のDNを持つことができます。CA署名証明書を使用する場合、Auth0はDNを保存し、転送されたクライアント証明書を登録済みのDNと照合します。

証明書を生成する

CA署名付きクライアント証明書の生成方法は公開鍵基盤に大きく依存するため、本ドキュメントのスコープ外となります。少なくとも 2048ビットのRSA鍵ペア を生成することを推奨します。

新しいクライアントを作成する

クライアントを作成するには、以下のペイロードを指定して /clients エンドポイントにPOSTリクエストを送信します。

• $client_name: 新しいクライアントの名前
• $credential_name: 公開鍵の名称
• $credential_certificate: CA が生成した$certificate_pemの内容

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

完全なPEMファイルを渡す代わりに、サブジェクトDNを渡すこともできます。サブジェクトDNは、mTLSハンドシェイク中に送信されるクライアント証明書の識別名 (DN) と一致している必要があります。

サブジェクト DN の抽出方法は、エコシステムによって異なる場合があります。認可サーバーでサブジェクト DN を確実に照合させる最も信頼できる方法は、PEM ファイル全体をアップロードすることです。

次のPOSTリクエストは、サブジェクトDNを指定して新しいクライアントを作成します。

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

詳細については、クライアントの作成 API ドキュメントを参照してください。

既存のクライアントにパッチを適用する

mTLS を使用するために新しいクライアントを作成したくない場合は、既存のクライアントを更新して mTLS クライアント認証を受け付けるように設定できます。これには、token_endpoint_auth_method フィールドの値を削除し、client_authentication_methods フィールドに値を追加する作業が含まれます。

クライアントを mTLS 用に設定すると、token_endpoint_auth_method を変更して mTLS の使用をやめない限り、クライアントシークレットを使って認証することはできなくなります。詳細については、クライアントがクライアントシークレットを使用するように戻す を参照してください。

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

mTLS専用に鍵ペアを生成したら、認証情報リソースを作成します。/clients エンドポイントに対して、以下のPOSTリクエストを行います。

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "pem": "$credential_certificate"
}'

完全なPEMファイルを渡す代わりに、サブジェクトDNを渡すこともできます。サブジェクトDNは、mTLSハンドシェイク中に送信されるクライアント証明書から抽出されたDistinguished Name (DN) と一致している必要があります。

次のコードサンプルでは、Subject DNを使用してcredentialリソースを作成します。

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
}'

いずれの方法を使用する場合も、レスポンスで返されるクレデンシャルIDは、クレデンシャルをクライアントに関連付けるために必要です。

詳細については、クライアント資格情報の作成 API ドキュメントを参照してください。

クライアントへの認証情報の関連付けとtoken_endpoint_auth_methodの無効化

認証情報は作成しましたが、まだクライアントへの関連付けは完了していません。

これを行うには、/clients エンドポイントに以下の PATCH リクエストを送信して client_authentication_methods を更新します。同じリクエストで token_endpoint_auth_method を null に設定してください。

​​

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

このリクエストが完了すると、クライアントはmTLSによってのみ認証できるようになります。

詳細については、クライアントの更新 API ドキュメントを参照してください。

​

クライアントをクライアントシークレット使用に戻す

クライアントシークレットを使用した認証にクライアントの設定を戻すには、client_authentication_methods を無効にし、使用する認証方式で token_endpoint_auth_method を再度有効にしてください。

次のPATCHリクエストで、token_endpoint_auth_methodをclient_secret_postに設定して、クライアントシークレット認証を再度有効にします。

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": "client_secret_post", 
  "client_authentication_methods": null
}'

詳細については、クライアントの更新 API ドキュメントを参照してください。

​

詳しく見る

• mTLS で認証する
• Customer Edge を設定する
• テナントの mTLS 認証を設定する