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

SAML リクエストに署名して暗号化する特別な構成シナリオについて説明します

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

• SAML サービスプロバイダーとしての Auth0 (例: SAML 接続)
• SAML IDプロバイダー としての Auth0 (例: SAML Web App アドオンで構成されたアプリケーション)

​

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

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

​

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

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

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

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

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

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

ペイロード:

{
	{ 
		"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 文字列形式の秘密鍵と証明書を取得する方法については、文字列として証明書と鍵を扱うを参照してください。

​

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

Auth0 が SAML サービスプロバイダーである場合、IDプロバイダーからのすべての SAML レスポンスには、権限のない第三者によって改ざんされていないことを示す署名が必要です。

レスポンスの署名を検証できるようにするには、IDプロバイダーから署名証明書を取得し、その証明書を Auth0 の接続に読み込むよう Auth0 を設定する必要があります。

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

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

​

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

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

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

証明書は、IdP で指定された形式でダウンロードしてください。

​

コンテンツ復号アルゴリズムを設定する

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

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

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

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

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

{
  "options": {
    [...], // 他のすべての接続オプション
    "assertion_decryption_settings": {
      "algorithm_profile": "v2026-1",
      "algorithm_exceptions": []
    }
  }
}

​

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

前述のとおり、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メタデータは、指定された証明書で更新されるため、IDプロバイダーはその証明書を取得してSAMLレスポンスの署名に使用できます。

​

SAML IDプロバイダーとしての Auth0

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

​

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

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

SAML アサーションに署名するには:

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

デフォルトでは、Auth0 はレスポンス内の SAML assertion に署名します。代わりに SAML response に署名するには:

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

2. Addons ビューを選択します。

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

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);

  }
  };

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

​

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

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

署名検証を設定するには:

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

2. Auth0 Dashboard > Applications に移動し、表示するアプリケーションの名前を選択します。

3. Addons ビューを選択します。

4. SAML2 Web App を選択してその設定を表示し、Settings コードブロックを見つけます。

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

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

​

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

Auth0 が SAML IDプロバイダーである場合は、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 は、アサーションの暗号化について以下のアルゴリズムをサポートしています。

• 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 コードで暗号化アルゴリズムを設定します。

​

関連情報

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