SAMLリクエストの署名と暗号化

SAMLリクエストに署名し、暗号化するための特別な設定について説明します

トランザクションのセキュリティを強化するために、SAMLプロトコルでは、リクエストとレスポンスの両方に署名または暗号化を適用できます。この記事では、特定のシナリオ向けの設定を、次の 2 つのユースケースに分けて紹介します。

• SAMLサービスプロバイダーとしての Auth0 (例: SAML 接続)
• SAML アイデンティティプロバイダーとしての Auth0 (例: SAML Web App addon が設定されたアプリケーション)

​

SAMLサービスプロバイダーとしてのAuth0

これらのシナリオは、Auth0がSAMLサービスプロバイダーである場合に該当します。つまり、Auth0はSAML接続を作成してSAMLアイデンティティプロバイダーに接続します。

​

SAML認証リクエストに署名する

Auth0 が SAML サービスプロバイダーである場合、Auth0 が IdP に送信する認証リクエストには、次の手順で署名できます。

1. Auth0 Dashboard > Authentication > Enterprise に移動し、SAML を選択します。
2. 表示したい接続の名前を選択します。
3. Sign Request を見つけて、スイッチを有効にします。
4. Sign Request スイッチの下にある証明書をダウンロードし、署名を検証できるよう IdP に渡します。

​

deflate エンコーディングの有効化/無効化

デフォルトでは、SAML 認証リクエストは HTTP-Redirect 経由で送信され、deflate エンコーディングが使用されます。この場合、署名はクエリパラメータに含まれます。

deflate エンコーディングを無効にするには、Management API の Update a connection エンドポイントに PATCH リクエストを送信し、deflate オプションを false に設定します。

接続の options オブジェクトを更新すると、options オブジェクト全体が上書きされます。以前の接続オプションを保持するには、既存の options オブジェクトを取得し、そこに新しいキー/値を追加します。

エンドポイント: https://{yourDomain}/api/v2/connections/{yourConnectionId}

ペイロード:

{
	{ 
		"options" : {
			[...], // 他のすべての接続オプション
		  "deflate": false
    }
  }
}

​

カスタムキーを使用してリクエストに署名する

デフォルトでは、Auth0 は SAML リクエストの署名にテナントの秘密キーを使用します (Sign Request トグルが有効になっている場合) 。また、特定の接続から送信されるリクエストに署名するために、独自の秘密キーと公開鍵のキーペアを指定することもできます。

次のコマンドを使用すると、独自の証明書と秘密キーを生成できます。

openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout private_key.key -out certificate.crt

接続でリクエストの署名に使用するキーは Auth0 Dashboard の UI では変更できないため、Management API v2 の Update a Connection endpoint を使用し、以下のペイロード例のように options オブジェクトに signing_key プロパティを追加する必要があります。

接続の options オブジェクトを更新すると、options オブジェクト全体が上書きされます。既存の接続オプションを維持するには、現在の options オブジェクトを取得し、そこに新しいキー/値を追加してください。

Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}

Payload:

{
	{ 
		"options" : {
			[...], // 他のすべての接続オプション
		  "signing_key": {
				"key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----",
				"cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----"
			}
    }
	}
}

ペイロードで使用するJSON文字列形式の秘密キーと証明書を取得する方法については、Work with Certificates and Keys and Stringsを参照してください。

​

署名付きの SAML 認証レスポンスを受信する

Auth0 が SAML のサービスプロバイダーである場合、アイデンティティプロバイダーから送信されるすべての SAML レスポンスには、不正なサードパーティによって改ざんされていないことを示すための署名が必要です。

そのためには、アイデンティティプロバイダーから署名証明書を取得し、その証明書を Auth0 Connection に読み込んで、レスポンスの署名を検証するよう Auth0 を設定する必要があります。

1. Auth0 Dashboard > Authentication > Enterprise に移動し、SAML を選択します。
2. 表示する接続の名前を選択します。
3. X509 Signing Certificate を見つけて、証明書をアップロードします。
4. 変更を保存 を選択します。

Auth0 は、アサーション、レスポンス、またはその両方のいずれかに署名されたレスポンスを受け入れることができます。

​

暗号化されたSAML認証アサーションを受信する

Auth0 が SAMLサービスプロバイダーである場合、アイデンティティプロバイダーから暗号化されたアサーションを受信する必要があることがあります。そのためには、テナントの公開鍵証明書を IdP に提供する必要があります。IdP は公開鍵を使用して SAML アサーションを暗号化し、Auth0 に送信します。Auth0 はテナントの秘密キーを使用してそれを復号します。

公開鍵を各形式で取得するには、次のリンクを使用します。

IdP から求められている形式で証明書をダウンロードしてください。

​

コンテンツ復号 algorithmsを設定する

Auth0 はデフォルトで、SAMLアサーションの復号に、最新のAlgorithm Profileに記載されているalgorithmsを自動的にサポートします。

• 一覧にないアルゴリズムでアサーションが暗号化されている場合、そのアサーションは Auth0 によって拒否されます。

• IdP が一覧にあるアルゴリズムをサポートしていない場合は、algorithm_exceptions パラメータを使用してセキュリティプロファイルを上書きできます。Auth0 では、SAMLアサーションの復号には最新のAlgorithm Profileを使用することを推奨します。

別のプロファイルを指定する場合や、一覧にないアルゴリズムを使用する場合は、Update a Connection エンドポイントを使用して接続を更新し、以下のペイロード例に示すように assertion_decryption_settings プロパティを変更する必要があります。

接続の options object を更新すると、新しい設定で options object 全体が上書きされます。既存の 接続オプションを維持するには、現在の options object を取得し、そこに新しいキー/値を追加してください。

エンドポイント: https://{yourDomain}/api/v2/connections/{yourConnectionId} ペイロード:

{
  "options": {
    [...], // 他のすべての接続オプション
    "assertion_decryption_settings": {
      "algorithm_profile": "v2026-1",
      "algorithm_exceptions": [
        // セキュリティプロファイルを上書きして、安全性の低いアルゴリズムを使用することもできます。例:
		// "http://www.w3.org/2001/04/xmlenc#aes128-cbc",
		// "http://www.w3.org/2001/04/xmlenc#aes256-cbc",
		// "http://www.w3.org/2001/04/xmlenc#tripledes-cbc"
	  ]
    }
  }
}

​

鍵ペアを使用して暗号化されたレスポンスを復号する

前述のとおり、Auth0 はデフォルトでテナントの秘密キーと公開鍵のキーペアを使用して暗号化を処理します。高度なシナリオで必要な場合は、独自の公開鍵/秘密キーの鍵ペアを指定することもできます。

接続でリクエストの暗号化と復号に使用する鍵ペアの変更は Auth0 Dashboard の UI では行えないため、Management API v2 の Update a Connection エンドポイント を使用し、以下のペイロード例に示すように options オブジェクトに decryptionKey プロパティを追加する必要があります。

接続の options オブジェクトを更新すると、options オブジェクト全体が上書きされます。以前の接続オプションを保持するには、既存の options オブジェクトを取得し、そこに新しいキー/値を追加してください。

エンドポイント: https://{yourDomain}/api/v2/connections/{yourConnectionId}

ペイロード:

{
	{ 
		"options" : {
			[...], // その他すべての接続オプション
		  "decryptionKey": {
				"key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----",
				"cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----"
			}
	}
}

接続で利用可能なSAMLメタデータは、アイデンティティプロバイダーがその証明書を取得してSAMLレスポンスに署名できるよう、指定された証明書で更新されます。

​

SAMLアイデンティティプロバイダーとしてのAuth0

このシナリオは、Auth0がアプリケーションのSAMLアイデンティティプロバイダーである場合に該当します。Auth0 Dashboard では、これは SAML Web App Addon が有効になっているアプリケーションとして表示されます。

​

SAML レスポンス/アサーションに署名する

Auth0 が SAML アイデンティティプロバイダーである場合、テナントの秘密キーを使って SAML アサーションに署名し、署名の検証に必要な公開鍵/証明書をサービスプロバイダーに提供します。

SAML アサーションに署名するには、次の手順を実行します。

1. Auth0 Dashboard > Applications に移動し、対象のアプリケーション名を選択します。
2. 設定 ページの一番下までスクロールし、Show Advanced Settings を選択してから、Certificates ビューを選択します。
3. Download Certificate を選択し、署名証明書の受け取り形式を選択します。
4. 証明書をサービスプロバイダーに送信します。

デフォルトでは、Auth0 はレスポンス内の SAML アサーション に署名します。代わりに SAML レスポンス に署名するには、次の手順を実行します。

1. Auth0 Dashboard > Applications に移動し、対象のアプリケーション名を選択します。

2. アドオン ビューを選択します。

3. SAML2 Web App を選択して設定を表示し、設定 コードブロックを探します。

4. "signResponse" キーを見つけます。コメントアウトを解除し (必要に応じて追加し) 、値を true に設定します (デフォルト値は false です) 。設定は次のようになります。

   {
     [...], // 他の設定
     "signResponse": true
   }
   

​

SAML レスポンスの署名鍵を変更する

デフォルトでは、Auth0 はテナントに割り当てられた秘密キーと公開鍵のキーペアを使用して、SAML レスポンスまたはアサーションに署名します。ごく限られた特定のケースでは、独自のキーペアを指定したいこともあるでしょう。その場合は、次のようなルールを使用できます。

/**
* PostLogin フローの実行中に呼び出されるハンドラーです。
*
* @param {Event} event - ユーザーおよびログイン時のコンテキストに関する詳細情報。
* @param {PostLoginAPI} api - ログインの動作を変更するために使用できるメソッドを持つインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {

    // 署名鍵ペアを変更したい、SAML Web App Addon が有効になっているアプリケーションの ID に置き換えてください。
      //
      const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID';

    // 特定のクライアント ID に対してのみ処理を行います。カスタム証明書が必要な IdP が複数ある場合は、
    // それぞれに対して "if" 文を追加してください。  
    if (event.client.client_id === samlIdpClientId) {

    // ここに独自の秘密キーと証明書を指定してください。
    // フォーマットの手順については https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings を参照してください。
    // 基本的には PEM 形式の証明書から始め、改行を "\n" に置き換えます。
    const signingCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n";
    const signingKey = "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PRIVATE KEY-----\n";

    api.samlResponse.setCert(signingCert)    
    api.samlResponse.setKey(signingKey);

  }
  };

秘密キーと証明書ファイルをルールで使用できる文字列に変換する方法については、証明書とキーを文字列として扱うを参照してください。

​

テナント署名鍵のローテーション

• Auth0 はテナントの署名鍵を使用して SAML アサーションとレスポンスに署名します。キーをローテーションすると、信頼する証明書に対して署名を検証するすべてのサービスプロバイダーに影響します。
• 新しい証明書を信頼しないサービスプロバイダーは Auth0 の署名付きレスポンスを拒否するため、そのユーザーはログインできなくなります。

署名鍵のローテーションについては、署名鍵のローテーションを参照してください。

ローテーション前に SAML サービスプロバイダーが next 証明書をシームレスに信頼するよう設定する方法は、各サービスプロバイダーが一度に複数のアイデンティティプロバイダー署名証明書を保持できるかどうかによって異なります。

ローテーション前に、NEXT IN QUEUE 証明書を取得します。

1. Auth0 Dashboard > 設定 > 署名鍵に移動し、List of Valid Keys までスクロールします。
2. NEXT IN QUEUE の有効なキーを見つけます。
3. 省略記号メニュー (…) から Download Signing Certificate を選択します。

Management API の Get all Application Signing Keys エンドポイントに GET リクエストを送信することもできます。レスポンスには、"next": true である有効なキーの "cert" が含まれます。

複数の署名証明書をサポートするサービスプロバイダー

ダウンタイムをゼロにするため、多くのサービスプロバイダーは複数の IdP 署名証明書を受け入れることができます。Auth0 が next 証明書の使用を開始したときに両方の証明書が同時に信頼されるよう、現在の証明書に加えて next の有効な証明書を追加します。

1. next 証明書を、追加の信頼済み署名証明書としてサービスプロバイダーにアップロードします。まだ現在の証明書を削除または置き換えないでください。
2. サービスプロバイダーに、現在の証明書と next 証明書の両方が信頼済みとして表示されていることを確認します。
3. すべてのサービスプロバイダーが両方の証明書を信頼したら、キーをローテーションします。ログインが成功することを確認してから、サービスプロバイダーから古い証明書を削除してください。

単一の署名証明書のみをサポートするサービスプロバイダー

一部のサービスプロバイダーは、一度に 1 つのアイデンティティプロバイダー署名証明書しか受け入れません。これらのサービスプロバイダーについては、同じメンテナンスウィンドウ内で署名鍵のローテーションを調整する必要があります。

1. トラフィックが少ない時間帯またはメンテナンスウィンドウ中に変更を実施できるよう、サービスプロバイダーと調整します。
2. Auth0 で署名鍵をローテーションし、サービスプロバイダーの信頼済み証明書を next 証明書に可能な限り近いタイミングで置き換えます。この 2 つの操作の間、該当するサービスプロバイダー経由のログインは署名のバリデーションに失敗します。
3. サービスプロバイダーに新しい証明書を設定したら、ログインが成功することを確認します。

複数または単一の署名証明書をサポートできるかどうかについてサービスプロバイダーに確認し、それに応じて計画してください。

​

署名付きの SAML 認証リクエストを受信する

Auth0 が SAML アイデンティティプロバイダーである場合、サービスプロバイダーの秘密キーで署名されたリクエストを受信できます。Auth0 は公開鍵/証明書を使用して署名を検証します。

署名のバリデーションを設定するには、次の手順に従います。

1. 公開鍵を含むサービスプロバイダーの証明書をダウンロードします。

2. Auth0 Dashboard > アプリケーション に移動し、対象のアプリケーション名を選択します。

3. アドオンビューを選択します。

4. SAML2 Web App を選択して設定を表示し、設定コードブロックを探します。

5. "signingCert" キーを探します。コメントアウトを解除し (必要に応じて追加し) 、その値にサービスプロバイダーからダウンロードした証明書を設定します。設定は次のようになります。

   {
     [...], // その他の設定
     "signingCert": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
   }
   

​

暗号化されたSAML認証アサーションを送信する

Auth0がSAMLアイデンティティプロバイダーである場合は、Actionsを使用して送信するSAMLアサーションを暗号化できます。また、アサーションの暗号化に使用する暗号化アルゴリズムを選択することも可能です。Auth0では、より高いセキュリティを確保するため、aes256-gcmの使用を推奨しています。

サービスプロバイダーから証明書と公開鍵を取得する必要があります。証明書しか入手していない場合は、opensslを使って公開鍵を抽出できます。証明書ファイル名がcertificate.pemだとすると、次を実行できます。

openssl x509 -in certificate.pem -pubkey -noout > public_key.pem

証明書ファイルと公開鍵ファイルを取得したら、Actionで使用するために、それらを文字列に変換する必要があります。Actionは次のようになります。

exports.onExecutePostLogin = async (event, api) => {

// このActionは、Auth0が生成するSAMLアサーションを暗号化するための特定の公開鍵を設定します
  if (
    event.client.client_id ===
    "THE_CLIENT_ID_OF_THE_APP_WITH_THE_SAML_APP_ADDON"
  ) {
    const encryptionCert =
      "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n";
    const encryptionPublicKey =
      "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PUBLIC KEY-----\n";

    api.samlResponse.setEncryptionCert(encryptionCert);
    api.samlResponse.setEncryptionPublicKey(encryptionPublicKey);
    api.samlResponse.setEncryptionAlgorithm("aes256-gcm");
  }
};

Auth0 は、アサーションの暗号化で次の algorithms をサポートしています。

• aes256-gcm (推奨) : 機密性と完全性の両方を提供する認証付き暗号化です。フォーマット妥当性オラクル攻撃に対する耐性があります。
• aes256-cbc (デフォルト) : 完全性は保証されません。Action で暗号化アルゴリズムの設定にオブジェクト api.samlResponse.setEncryptionAlgorithm を使用しない場合、Auth0 はデフォルトで aes256-cbc アルゴリズムを使用し、テナントログに非推奨化の警告を記録します。

キー転送には、Auth0 は MGF1 関数と SHA1 関数を含む rsa-oaep を使用します。

Auth0 は、デフォルトの暗号化アルゴリズムを aes256-gcm に変更する予定です。

デフォルトのアルゴリズムが変更された後も動作を一貫させるため、aes256-gcm への切り替えを推奨します。

1. ご利用の SAMLサービスプロバイダーが aes256-gcm をサポートしていることを確認し、サポートしていない場合はその提供元に問い合わせてください。
2. api.samlResponse.setEncryptionAlgorithm("aes256-gcm"); を使用して、Action コードで暗号化アルゴリズムを設定してください。

​

詳しく見る

• 証明書とキーを文字列として扱う