- SAMLサービスプロバイダーとしての Auth0 (例: SAML 接続)
- SAML としての Auth0 (例: SAML Web App addon が設定されたアプリケーション)
SAMLサービスプロバイダーとしてのAuth0
これらのシナリオは、Auth0がSAMLサービスプロバイダーである場合に該当します。つまり、Auth0はSAML接続を作成してSAMLアイデンティティプロバイダーに接続します。SAML認証リクエストに署名する
Auth0 が SAML サービスプロバイダーである場合、Auth0 が IdP に送信する認証リクエストには、次の手順で署名できます。- Auth0 Dashboard > Authentication > Enterprise に移動し、SAML を選択します。
- 表示したい接続の名前を選択します。
- Sign Request を見つけて、スイッチを有効にします。
- 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}
ペイロード:
カスタムキーを使用してリクエストに署名する
デフォルトでは、Auth0 は SAML リクエストの署名にテナントの秘密キーを使用します (Sign Request トグルが有効になっている場合) 。また、特定の接続から送信されるリクエストに署名するために、独自の秘密キーと公開鍵のキーペアを指定することもできます。 次のコマンドを使用すると、独自の証明書と秘密キーを生成できます。options オブジェクトに signing_key プロパティを追加する必要があります。
接続の options オブジェクトを更新すると、options オブジェクト全体が上書きされます。既存の接続オプションを維持するには、現在の options オブジェクトを取得し、そこに新しいキー/値を追加してください。
Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}
Payload:
署名付きの SAML 認証レスポンスを受信する
Auth0 が SAML のサービスプロバイダーである場合、アイデンティティプロバイダーから送信されるすべての SAML レスポンスには、不正なサードパーティによって改ざんされていないことを示すための署名が必要です。 そのためには、アイデンティティプロバイダーから署名証明書を取得し、その証明書を Auth0 Connection に読み込んで、レスポンスの署名を検証するよう Auth0 を設定する必要があります。- Auth0 Dashboard > Authentication > Enterprise に移動し、SAML を選択します。
- 表示する接続の名前を選択します。
- X509 Signing Certificate を見つけて、証明書をアップロードします。
- 変更を保存 を選択します。
暗号化されたSAML認証アサーションを受信する
Auth0 が SAMLサービスプロバイダーである場合、アイデンティティプロバイダーから暗号化されたアサーションを受信する必要があることがあります。そのためには、テナントの公開鍵証明書を IdP に提供する必要があります。IdP は公開鍵を使用して SAML アサーションを暗号化し、Auth0 に送信します。Auth0 はテナントの秘密キーを使用してそれを復号します。 公開鍵を各形式で取得するには、次のリンクを使用します。コンテンツ復号 algorithmsを設定する
Auth0 はデフォルトで、SAMLアサーションの復号に、最新のAlgorithm Profileに記載されているalgorithmsを自動的にサポートします。- 一覧にないアルゴリズムでアサーションが暗号化されている場合、そのアサーションは Auth0 によって拒否されます。
-
IdP が一覧にあるアルゴリズムをサポートしていない場合は、
algorithm_exceptionsパラメータを使用してセキュリティプロファイルを上書きできます。Auth0 では、SAMLアサーションの復号には最新のAlgorithm Profileを使用することを推奨します。
assertion_decryption_settings プロパティを変更する必要があります。
接続の options object を更新すると、新しい設定で options object 全体が上書きされます。既存の 接続オプションを維持するには、現在の options object を取得し、そこに新しいキー/値を追加してください。
エンドポイント: https://{yourDomain}/api/v2/connections/{yourConnectionId}
ペイロード:
鍵ペアを使用して暗号化されたレスポンスを復号する
前述のとおり、Auth0 はデフォルトでテナントの秘密キーと公開鍵のキーペアを使用して暗号化を処理します。高度なシナリオで必要な場合は、独自の公開鍵/秘密キーの鍵ペアを指定することもできます。 接続でリクエストの暗号化と復号に使用する鍵ペアの変更は Auth0 Dashboard の UI では行えないため、Management API v2 の Update a Connection エンドポイント を使用し、以下のペイロード例に示すようにoptions オブジェクトに decryptionKey プロパティを追加する必要があります。
接続の options オブジェクトを更新すると、options オブジェクト全体が上書きされます。以前の接続オプションを保持するには、既存の options オブジェクトを取得し、そこに新しいキー/値を追加してください。
エンドポイント: https://{yourDomain}/api/v2/connections/{yourConnectionId}
ペイロード:
SAMLアイデンティティプロバイダーとしてのAuth0
このシナリオは、Auth0がアプリケーションのSAMLアイデンティティプロバイダーである場合に該当します。Auth0 Dashboard では、これは SAML Web App Addon が有効になっているアプリケーションとして表示されます。SAML レスポンス/アサーションに署名する
Auth0 が SAML アイデンティティプロバイダーである場合、テナントの秘密キーを使って SAML アサーションに署名し、署名の検証に必要な公開鍵/証明書をサービスプロバイダーに提供します。 SAML アサーションに署名するには、次の手順を実行します。- Auth0 Dashboard > Applications に移動し、対象のアプリケーション名を選択します。
- 設定 ページの一番下までスクロールし、Show Advanced Settings を選択してから、Certificates ビューを選択します。
- Download Certificate を選択し、署名証明書の受け取り形式を選択します。
- 証明書をサービスプロバイダーに送信します。
- Auth0 Dashboard > Applications に移動し、対象のアプリケーション名を選択します。
- アドオン ビューを選択します。
- SAML2 Web App を選択して設定を表示し、設定 コードブロックを探します。
-
"signResponse"キーを見つけます。コメントアウトを解除し (必要に応じて追加し) 、値をtrueに設定します (デフォルト値はfalseです) 。設定は次のようになります。
SAML レスポンスの署名鍵を変更する
デフォルトでは、Auth0 はテナントに割り当てられた秘密キーと公開鍵のキーペアを使用して、SAML レスポンスまたはアサーションに署名します。ごく限られた特定のケースでは、独自のキーペアを指定したいこともあるでしょう。その場合は、次のようなルールを使用できます。テナント署名鍵のローテーション
署名鍵のローテーションについては、署名鍵のローテーションを参照してください。 ローテーション前に SAML サービスプロバイダーがnext 証明書をシームレスに信頼するよう設定する方法は、各サービスプロバイダーが一度に複数のアイデンティティプロバイダー署名証明書を保持できるかどうかによって異なります。
ローテーション前に、NEXT IN QUEUE 証明書を取得します。
- Auth0 Dashboard > 設定 > 署名鍵に移動し、List of Valid Keys までスクロールします。
- NEXT IN QUEUE の有効なキーを見つけます。
- 省略記号メニュー (…) から Download Signing Certificate を選択します。
GET リクエストを送信することもできます。レスポンスには、"next": true である有効なキーの "cert" が含まれます。
複数の署名証明書をサポートするサービスプロバイダー
ダウンタイムをゼロにするため、多くのサービスプロバイダーは複数の IdP 署名証明書を受け入れることができます。Auth0 が next 証明書の使用を開始したときに両方の証明書が同時に信頼されるよう、現在の証明書に加えて next の有効な証明書を追加します。
next証明書を、追加の信頼済み署名証明書としてサービスプロバイダーにアップロードします。まだ現在の証明書を削除または置き換えないでください。- サービスプロバイダーに、現在の証明書と
next証明書の両方が信頼済みとして表示されていることを確認します。 - すべてのサービスプロバイダーが両方の証明書を信頼したら、キーをローテーションします。ログインが成功することを確認してから、サービスプロバイダーから古い証明書を削除してください。
- トラフィックが少ない時間帯またはメンテナンスウィンドウ中に変更を実施できるよう、サービスプロバイダーと調整します。
- Auth0 で署名鍵をローテーションし、サービスプロバイダーの信頼済み証明書を
next証明書に可能な限り近いタイミングで置き換えます。この 2 つの操作の間、該当するサービスプロバイダー経由のログインは署名のバリデーションに失敗します。 - サービスプロバイダーに新しい証明書を設定したら、ログインが成功することを確認します。
署名付きの SAML 認証リクエストを受信する
Auth0 が SAML アイデンティティプロバイダーである場合、サービスプロバイダーの秘密キーで署名されたリクエストを受信できます。Auth0 は公開鍵/証明書を使用して署名を検証します。 署名のバリデーションを設定するには、次の手順に従います。- 公開鍵を含むサービスプロバイダーの証明書をダウンロードします。
- Auth0 Dashboard > アプリケーション に移動し、対象のアプリケーション名を選択します。
- アドオンビューを選択します。
- SAML2 Web App を選択して設定を表示し、設定コードブロックを探します。
-
"signingCert"キーを探します。コメントアウトを解除し (必要に応じて追加し) 、その値にサービスプロバイダーからダウンロードした証明書を設定します。設定は次のようになります。
暗号化されたSAML認証アサーションを送信する
Auth0がSAMLアイデンティティプロバイダーである場合は、Actionsを使用して送信するSAMLアサーションを暗号化できます。また、アサーションの暗号化に使用する暗号化アルゴリズムを選択することも可能です。Auth0では、より高いセキュリティを確保するため、aes256-gcmの使用を推奨しています。
サービスプロバイダーから証明書と公開鍵を取得する必要があります。証明書しか入手していない場合は、opensslを使って公開鍵を抽出できます。証明書ファイル名がcertificate.pemだとすると、次を実行できます。
openssl x509 -in certificate.pem -pubkey -noout > public_key.pem
証明書ファイルと公開鍵ファイルを取得したら、Actionで使用するために、それらを文字列に変換する必要があります。Actionは次のようになります。
aes256-gcm(推奨) : 機密性と完全性の両方を提供する認証付き暗号化です。フォーマット妥当性オラクル攻撃に対する耐性があります。aes256-cbc(デフォルト) : 完全性は保証されません。Action で暗号化アルゴリズムの設定にオブジェクトapi.samlResponse.setEncryptionAlgorithmを使用しない場合、Auth0 はデフォルトでaes256-cbcアルゴリズムを使用し、テナントログに非推奨化の警告を記録します。
キー転送には、Auth0 は MGF1 関数と SHA1 関数を含む
rsa-oaep を使用します。