SAML要求の署名と暗号化

トランザクションのセキュリティを強化するために、SAMLプロトコルで要求と応答の両方に署名または暗号化できます。この記事では、特定のシナリオの構成について、2つのユースケースに分けて説明します。

• Auth0をSAMLサービスプロバイダーとして使用する場合（たとえば、SAML接続）

• Auth0をSAML IDプロバイダーとして使用する場合（たとえば、SAML Web Appアドオンで構成されたアプリケーション）

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

Auth0がSAMLサービスプロバイダーの場合、Auth0がIdPに送信する認証要求に署名することができます。

1. ［Auth0 Dashboard］>［Authentication（認証）］>［Enterprise（エンタープライズ）］に移動し、［SAML］を選択します。

2. 表示する接続の名前を選択します。

3. ［Sign Request（要求に署名する）］を見つけて、そのスイッチを有効にします。

4. ［Sign Request（要求に署名する）］スイッチの下にある証明書をダウンロードし、署名を検証してもらえるようにIdPに提供します。

デフォルトでは、SAML認証要求はHTTPリダイレクト経由で送信され、deflateエンコードを使用します。これにより、署名がクエリパラメーターに配置されます。

deflateエンコードを無効にするには、Management APIの接続の更新エンドポイントに対してPATCH呼び出しを行い、deflateオプションをfalseに設定します。

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

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

ペイロード：

{
	{ 
		"options" : {
			[...], // all the other connection 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（接続の更新）」エンドポイントを使用し、以下のペイロード例に示すように、optionsオブジェクトにsigning_keyプロパティを追加する必要があります。

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

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

ペイロード：

{
	{ 
		"options" : {
			[...], // all the other connection 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文字列としてフォーマットされた秘密鍵と証明書を取得する方法については、「証明書とキーと文字列の操作」を参照してください。

Auth0がSAMLサービスプロバイダーの場合、IDプロバイダーからのすべてのSAML応答に署名して、承認されていないサードパーティによって改ざんされていないことを示す必要があります。

IDプロバイダーから署名証明書を取得し、その証明書をIDプロバイダーからAuth0接続に読み込むことで、応答の署名を検証するようにAuth0を構成する必要があります。

1. ［Auth0 Dashboard］>［Authentication（認証）］>［Enterprise（エンタープライズ）］に移動し、［SAML］を選択します。

2. 表示する接続の名前を選択します。

3. X509署名証明書を見つけ、証明書をアップロードします。

4. ［Save Changes（変更の保存）］を選択します。

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

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

次のリンクを使用して、異なる形式で公開鍵を取得してください。

• CER

• PEM

• raw PEM

• PKCS#7

• 指紋

IdPが要求する形式の証明書をダウンロードしてください。

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

接続で要求の暗号化と復号化に使用されるキーペアをダッシュボードUIで変更することはできません。そのため、次のペイロードの例に示すように、Management API v2のUpdate a Connection（接続の更新）エンドポイントを使用し、decryptionKeyプロパティをoptionsオブジェクトに追加する必要があります。

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

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

ペイロード：

{
	{ 
		"options" : {
			[...], // all the other connection 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応答に署名できるようになります。

このシナリオは、Auth0がアプリケーションのSAML IDプロバイダーである場合に適用されます。これは、DashboardでSAML Web Appアドオンが有効になっているアプリケーションによって表されます。

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

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

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

2. ［Settings（設定）］ページの下までスクロールし、［Show Advanced Settings（詳細設定を表示）］、［Certificates（証明書）］ビューの順に選択します。

3. ［Download Certificate（証明書のダウンロード）］を選択し、署名証明書を受け取る形式を選択します。

4. 証明書をサービスプロバイダーに送信します。

デフォルトでは、Auth0は応答内でSAMLアサーションに署名します。SAML応答に署名するには：

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

2. ［Addons（アドオン）］ビューを選択します。

3. SAML2 Webアプリを選択して設定を表示し、［（Settings）設定］コードブロックを見つけます。

4. "signResponse"キーを見つけます。コメントを解除（または必要に応じて追加）し、値をtrueに設定します（デフォルト値はfalse）。構成はこのようになっているはずです。

   {
     [...], // other settings
     "signResponse": true
   }

   Was this helpful?

   Yes /No

デフォルトでは、Auth0はSAML応答やアサーションに署名するためのテナントに割り当てられた秘密鍵/公開鍵のペアを使用します。非常に特殊なシナリオでは、独自のキーペアを提供する必要がある場合があります。次のようなルールでこれを行うことができます：

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {

    // replace with the ID of the application that has the SAML Web App Addon enabled
      // for which you want to change the signing key pair.
      const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID';

    // only do this for the specific client ID.  If you have multiple IdPs that require 
    // custom certificates, you will have an "if" statement for each one.  
    if (event.client.client_id === samlIdpClientId) {

    // provide your own private key and certificate here  
    // see https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings 
    // for formatting instructions basically you start with a PEM format certificate and
    // replace the line enedings with "\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 IDプロバイダーの場合、サービスプロバイダーの秘密鍵で署名された要求を受信できます。Auth0は、公開鍵/証明書を使用して署名を検証します。

署名の検証を構成するには：

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

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

3. ［Addons（アドオン）］ビューを選択します。

4. SAML2 Webアプリを選択して設定を表示し、［（Settings）設定］コードブロックを見つけます。

5. "signingCert"キーを見つけます。コメントを解除し（または、必要に応じて追加）、その値をサービスプロバイダーからダウンロードした証明書に設定します。構成はこのようになっているはずです。

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

   Was this helpful?

   Yes /No

Auth0がSAML IDプロバイダーである場合は、Actionsを使用して送信するSAMLアサーションを暗号化できます。

サービスプロバイダーから証明書と公開鍵を取得する必要があります。証明書のみを取得した場合は、opensslを使用して公開鍵を取得できます。証明書のファイル名がcertificate.pemであると仮定すると、以下のように実行できます。

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

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

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

// this Action sets a specific public key to encrypt the SAML assertion generated from Auth0
  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);
  }
};

次のアルゴリズムが使用されます。

• アサーション暗号化にはAES256

• キー転送には、RSA-OAEP（MGF1およびSHA1を含む）

• 証明書やキーの文字列表現で作業する