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

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

Auth0 Dashboard
Management API

Authorization Server に対する mTLS クライアント認証を有効にするには、Auth0 Dashboard を使用してクライアントの mTLS を設定できます。

Auth0 Dashboard > Applications > Applications に移動します。
mTLS で使用するアプリケーションを選択するか、新しいアプリケーションを作成します。
Credentials タブを選択します。
必要な Authentication Method を選択します。選択できるのは次のいずれかです。
- 自己署名証明書を使用した mTLS
- 認証局が署名した証明書を使用した mTLS
使用する証明書の種類を選択したら、次のことができます。
- 既存の認証情報 (証明書) をクライアントアプリケーションに割り当てる
- 証明書をアップロードして新しい認証情報を追加する

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

必要なスコープを持つアクセストークンの取得方法について詳しくは、Get Access Tokens をご覧ください。

自己署名証明書

mTLS認証時に自己署名証明書を使用してクライアントの識別を検証します。ただし、自己署名証明書には次のような制限があります：

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"

証明書は1行のJSON文字列値として送信する必要があるため、PEMファイル内のすべての改行文字をAuth0に渡す前にJSONエスケープする必要があります。各行末を \n (ファイルがWindows形式の改行を使用している場合は \r\n) に置き換えてください。多くのHTTPツールやライブラリはこの変換を行わないため、リクエストを送信する前にエスケープが正しく行われているか確認してください。例：

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

新しいクライアントを作成するには、以下のペイロードを使用して/clientsエンドポイントにPOSTリクエストを送信してください：

$client_name: 新しいクライアントの名前
$credential_name: 公開鍵の名前
$credential_certificate: 前の手順で生成された cert.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ドキュメントをご覧ください。

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

token_endpoint_auth_method フィールドの値を削除し、client_authentication_methods フィールドに値を追加することで、既存のクライアントが mTLS クライアント認証を受け入れるよう更新できます。

クライアントを mTLS 用に設定すると、mTLS を使わないように token_endpoint_auth_method を設定しない限り、Client Secret を使用して認証することはできません。詳しくは、クライアントが Client Secret を使用するように戻すをご覧ください。

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

証明書を生成したら、認証情報リソースを作成します。

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に設定することでクライアントシークレット認証を無効にします。また、client_authentication_methodsをクレデンシャルIDで更新します。

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) によって署名された証明書は、信頼できる第三者が発行するためより信頼性が高いと見なされます。Amazonなどの一部のクラウドプロバイダーでは、CA署名の証明書のみが受け入れられます。CA署名証明書の識別情報には識別名 (DN) という概念が埋め込まれています。特定の CA によって作成された各証明書は固有ですが、共通の DN を共有することがあります。CA 署名証明書を使用する場合、Auth0 は DN を保存し、転送されたクライアント証明書を登録済みの DN と照合します。

証明書を生成する

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

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

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

$client_name: 新しいクライアントの名前
$credential_name: 公開鍵の名前
$credential_certificate: CA が生成した 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専用の鍵ペアを生成したら、クレデンシャルリソースを作成します。/clients/$client_id/credentials エンドポイントに以下の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ハンドシェイク中に送信されたクライアント証明書から抽出された識別名 (DN) と一致している必要があります。次のコードサンプルは、サブジェクト DN を使用して認証情報リソースを作成します。

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 Secretを使用した認証に戻すには、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 ドキュメントを参照してください。

Quickstarts

Auth0 の概要

Auth0 を設定する

アプリケーション

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

自己署名証明書

証明書を生成する

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

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

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

クライアントに認証情報を関連付け、`token_endpoint_auth_method` を無効にする

認証局によって署名された証明書

証明書を生成する

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

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

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

クライアントに認証情報を関連付け、`token_endpoint_auth_method` を無効にする

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

詳しく見る

​自己署名証明書

証明書を生成する

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

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

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

クライアントに認証情報を関連付け、token_endpoint_auth_method を無効にする

​認証局によって署名された証明書

証明書を生成する

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

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

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

クライアントに認証情報を関連付け、token_endpoint_auth_method を無効にする

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

​詳しく見る

自己署名証明書

クライアントに認証情報を関連付け、`token_endpoint_auth_method` を無効にする

認証局によって署名された証明書

クライアントに認証情報を関連付け、`token_endpoint_auth_method` を無効にする

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

詳しく見る