セキュリティを強化し、ユーザー エクスペリエンスを向上させるために、 F5 NGINX Plus (R29+) では、Security Assertion Markup Language (SAML) がサポートされるようになりました。 SAML は、Web アプリケーションにシングル サインオン (SSO) を提供する確立されたプロトコルであり、ID プロバイダー (IdP) がリソースへのアクセスに対してユーザーを認証し、その情報をサービス プロバイダー (SP) に渡して承認を受けることを可能にします。
このブログ記事では、SAML をネイティブにサポートしていない Web アプリケーションを使用して、NGINX をMicrosoft Entra ID (旧称 Azure Active Directory (Azure AD)) と統合する方法について、手順を追って説明します。 また、アプリケーションに SSO を実装し、Microsoft Entra ID エコシステムと統合する方法についても説明します。 このチュートリアルに従うことで、NGINX が SAML アサーションからクレーム (UPN、名、姓、グループ メンバーシップを含む) を抽出し、それを HTTP ヘッダー経由でアプリケーションに渡す方法についても学習します。
チュートリアルには 3 つのステップが含まれます。
このチュートリアルを完了するには、次のものが必要です。
dev.sports.com.crt と dev.sports.com.key
を使用します)demonginx.cerを
ダウンロードして実行できます。注記: キー値ストアはNGINX Plus 専用であるため、このチュートリアルは NGINX オープンソースのデプロイメントには適用されません。
この設定では、NGINX Plus は SAML SP として機能し、ユーザー エージェントを介して NGINX Plus と間接的に通信する SAML IdP を使用した SSO 実装に参加できます。
以下の図は、SP の開始と、要求および応答の POST バインディングを含む SSO プロセス フローを示しています。 この通信チャネルは直接的なものではなく、ユーザー エージェントを通じて管理されることに再度注意することが重要です。
図1: AuthnRequest と Response の POST バインディングを使用した SAML SP 開始 SSO
Microsoft Entra ID 管理ポータルにアクセスするには、サインインして左側のパネルに移動します。 Microsoft Entra ID を選択し、SSO 構成が必要なディレクトリのタイトルをクリックします。 選択したら、エンタープライズ アプリケーションを選択します。
図2: 管理ポータルでエンタープライズ アプリケーションを選択する
アプリケーションを作成するには、ポータルの上部にある [新しいアプリケーション]ボタンをクリックします。 この例では、 demonginxというアプリケーションを作成しました。
図3: Microsoft Entra ID で新しいアプリケーションを作成する
新しく作成されたアプリケーションの概要にリダイレクトされたら、左側のメニューから「はじめに」に移動し、 「管理」の下にある「シングル サインオン」をクリックします。 次に、シングル サインオン方法としてSAML を選択します。
図4: SSOセクションを使用してSAML構成を開始する
エンタープライズ アプリケーションで SSO を設定するには、Microsoft Entra ID 内で NGINX Plus を SP として登録する必要があります。これを行うには、図 5 に示すように、基本的な SAML 構成の編集の横にある鉛筆アイコンをクリックします。
次の値を追加し、 「保存」をクリックします。
検証証明書の使用はオプションです。 この設定を有効にする場合、NGINX の 2 つの構成オプションに対処する必要があります。
$saml_sp_sign_authn を
trueに設定する必要があります。 これは、IdP に送信された AuthnRequest に署名するように SP に指示します。$saml_sp_signing_key
を設定して、この署名に使用される秘密キーへのパスを指定します。 署名の検証のために、対応する公開キー証明書を Microsoft Entra ID にアップロードしてください。注記: このデモでは、属性とクレームが変更され、新しい SAML 属性が追加されています。 これらの SAML 属性は IdP によって送信されます。 NGINX 構成がこれらの属性を適切に受信して処理するように設定されていることを確認してください。 NGINX GitHub リポジトリで関連設定を確認および調整できます。
Microsoft Entra ID から IdP証明書 (Raw)をダウンロードし、NGINX Plus インスタンスに保存します。
図5: Microsoft Entra ID から IdP 証明書 (Raw) をダウンロードする
図6: 新しいユーザーまたはグループの追加
Microsoft Entra ID では、ユーザーとグループを追加または割り当てることで、SSO 対応の会社のアプリケーションへのアクセスを許可できます。
左側のメニューで、 [ユーザーとグループ]をクリックし、上部のボタン[ユーザー/グループの追加] をクリックします。
NGINX Plus SP でファイルを構成する前に、必要な証明書があることを確認してください。
dev.sports.com.crt および dev.sports.com.key
)demonginx.cer
)注記: 証明書は SPKI 形式である必要があります。
この手順を開始するには、署名検証のために Microsoft Entra ID から IdP 証明書をダウンロードします。 次に、PEM を DER 形式に変換します。
SAML SP アサーションを検証する場合は、TLS 終了に使用されるものとは異なる公開キー/秘密キーを使用することをお勧めします。
SPKI 形式で公開鍵証明書を抽出します。
frontend.conf ファイルを編集して、次の項目を更新します。
ssl_certificate
– TLS 証明書パスを含めるように更新します。ssl_certificate_key
– TLS 秘密キーのパスを含めるように更新します。実稼働環境では、ビジネス要件に基づいてさまざまなバックエンドの宛先を使用できます。 この例では、バックエンドはカスタマイズされた応答を提供します。
ユーザーのメールとobjectidに新しいクレームを追加することにより、Microsoft Entra ID の属性とクレームを変更しました。 これらの更新により、アプリケーションに対してよりパーソナライズされカスタマイズされた応答を提供できるようになり、ユーザー エクスペリエンスが向上します。
図7: Microsoft Entra ID の属性とクレームの変更
次のステップは、バックエンド アプリケーションへのトラフィックをプロキシする NGINX を構成することです。 このデモでは、バックエンド SAML アプリケーションはhttps://dev.sports.comで公開されています。
frontend.conf
ファイルを編集します。
# This is file frontend.conf
# This is the backend application we are protecting with SAML SSO
upstream my_backend {
zone my_backend 64k;
server dev.sports.com;
}
# Custom log format to include the 'NameID' subject in the REMOTE_USER field
log_format saml_sso '$remote_addr - $saml_name_id [$time_local] "$request" "$host" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
# The frontend server - reverse proxy with SAML SSO authentication
#
server {
# Functional locations implementing SAML SSO support
include conf.d/saml_sp.server_conf;
# Reduce severity level as required
error_log /var/log/nginx/error.log debug;
listen 443 ssl;
ssl_certificate /home/ubuntu/dev.sports.com.crt;
ssl_certificate_key /home/ubuntu/dev.sports.com.key;
ssl_session_cache shared:SSL:5m;
location / {
# When a user is not authenticated (i.e., the "saml_access_granted."
# variable is not set to "1"), an HTTP 401 Unauthorized error is
# returned, which is handled by the @do_samlsp_flow named location.
error_page 401 = @do_samlsp_flow;
if ($saml_access_granted != "1") {
return 401;
}
# Successfully authenticated users are proxied to the backend,
# with the NameID attribute passed as an HTTP header
proxy_set_header mail $saml_attrib_mail; # Microsoft Entra ID's user.mail
proxy_set_header objectid $saml_attrib_objectid; # Microsoft Entra ID's objectid
access_log /var/log/nginx/access.log saml_sso;
proxy_pass http://my_backend;
proxy_set_header Host dev.sports.com;
return 200 "Welcome to Application page\n My objectid is $http_objectid\n My email is $http_mail\n";
default_type text/plain;
}
}
# vim: syntax=nginx
属性saml_attrib_mail
とsaml_attrib_ objectid を
NGINX 構成に反映するには、 saml_sp_configuration.conf
のキー値ストア部分を次のように更新します。
keyval_zone zone=saml_attrib_mail:1M state=/var/lib/nginx/state/saml_attrib_email.json timeout=1h;
keyval $cookie_auth_token $saml_attrib_mail zone=saml_attrib_mail;
keyval_zone zone=saml_attrib_objectid:1M state=/var/lib/nginx/state/saml_attrib_objectid.json timeout=1h;
keyval $cookie_auth_token $saml_attrib_objectid zone=saml_attrib_objectid;
次に、SAML SSO 構成ファイルを設定します。 このファイルには、SP と IdP の主な構成が含まれています。 特定の SP および IdP 設定に応じてカスタマイズするには、ファイルに含まれる複数の map{} ブロックを調整する必要があります。
この表は、 saml_sp_configuration.conf
内の変数の説明を示しています。
変数 | 説明 |
---|---|
saml_sp_エンティティID | ユーザーがアプリケーションにアクセスするために使用する URL。 |
saml_sp_acs_url | サービス プロバイダーが SAML 応答を受信して処理し、ユーザーの ID を抽出し、提供された情報に基づいて要求されたリソースへのアクセスを許可または拒否するために使用する URL。 |
saml_sp_sign_authn | SP から IdP への SAML リクエストに署名するかどうかを指定します。 署名は SP 署名キーを使用して行われ、署名を検証するには関連する証明書を IdP にアップロードする必要があります。 |
saml_sp_署名キー | SP から IdP への SAML リクエストに署名するために使用される署名キー。 署名を検証するには、関連する証明書を IdP にアップロードしてください。 |
saml_idp_エンティティID | IdP を定義するために使用される ID。 |
saml_idp_sso_url | SP が認証要求を開始するために SAML アサーション要求を送信する IdP エンドポイント。 |
saml_idp_検証証明書 | IdP から受信した署名済み SAML アサーションを検証するために使用される証明書。 証明書は IdP によって提供され、SPKI 形式である必要があります。 |
saml_sp_slo_url | IdP が SAML LogoutRequest (ログアウト プロセスを開始するとき) または LogoutResponse (ログアウトを確認するとき) を送信する SP エンドポイント。 |
saml_sp_sign_slo | ログアウト SAML が SP によって署名されるかどうかを指定します。 |
saml_idp_slo_url | SP が LogoutRequest (ログアウト プロセスを開始するとき) または LogoutResponse (ログアウトを確認するとき) を送信する IdP エンドポイント。 |
saml_sp_want_signed_slo | SAML SP が IdP からの SAML ログアウト応答または要求に署名するかどうかを指定します。 |
以下のコードは、 saml_sp_configuration.conf でこのユースケースに対してのみ編集された値を示しています。
注記: 構成ファイルの残りの部分 (キー値ストアなど) がファイルにまだ表示されていることを確認します。 また、展開に応じて、 saml_sp_configuration.conf
ファイル内の変数を適切に調整してください。
# SAML SSO configuration
map $host $saml_sp_entity_id {
# Unique identifier that identifies the SP to the IdP.
# Must be URL or URN.
default "https://dev.sports.com";
}
map $host $saml_sp_acs_url {
# The ACS URL, an endpoint on the SP where the IdP
# will redirect to with its authentication response.
# Must match the ACS location defined in the "saml_sp.serer_conf" file.
default "https://dev.sports.com/saml/acs";
}
map $host $saml_sp_request_binding {
# Refers to the method by which an authentication request is sent from
# the SP to an IdP during the Single Sign-On (SSO) process.
# Only HTTP-POST or HTTP-Redirect methods are allowed.
default 'HTTP-POST';
}
map $host $saml_sp_sign_authn {
# Whether the SP should sign the AuthnRequest sent to the IdP.
default "false";
}
map $host $saml_sp_decryption_key {
# Specifies the private key that the SP uses to decrypt encrypted assertion
# or NameID from the IdP.
default "";
}
map $host $saml_sp_force_authn {
# Whether the SP should force re-authentication of the user by the IdP.
default "false";
}
map $host $saml_sp_nameid_format {
# Indicates the desired format of the name identifier in the SAML assertion
# generated by the IdP. Check section 8.3 of the SAML 2.0 Core specification
# (http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf)
# for the list of allowed NameID Formats.
default "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified";
}
map $host $saml_sp_relay_state {
# Relative or absolute URL the SP should redirect to
# after successful sign on.
default "";
}
map $host $saml_sp_want_signed_response {
# Whether the SP wants the SAML Response from the IdP
# to be digitally signed.
default "false";
}
map $host $saml_sp_want_signed_assertion {
# Whether the SP wants the SAML Assertion from the IdP
# to be digitally signed.
default "true";
}
map $host $saml_sp_want_encrypted_assertion {
# Whether the SP wants the SAML Assertion from the IdP
# to be encrypted.
default "false";
}
map $host $saml_idp_entity_id {
# Unique identifier that identifies the IdP to the SP.
# Must be URL or URN.
default "https://sts.windows.net/8807dced-9637-4205-a520-423077750c60/";
}
map $host $saml_idp_sso_url {
# IdP endpoint that the SP will send the SAML AuthnRequest to initiate
# an authentication process.
default "https://login.microsoftonline.com/8807dced-9637-4205-a520-423077750c60/saml2";
}
map $host $saml_idp_verification_certificate {
# Certificate file that will be used to verify the digital signature
# on the SAML Response, LogoutRequest or LogoutResponse received from IdP.
# Must be public key in PKCS#1 format. See documentation on how to convert
# X.509 PEM to DER format.
default "/etc/nginx/conf.d/demonginx.spki";
}
######### Single Logout (SLO) #########
map $host $saml_sp_slo_url {
# SP endpoint that the IdP will send the SAML LogoutRequest to initiate
# a logout process or LogoutResponse to confirm the logout.
default "https://dev.sports.com/saml/sls";
}
map $host $saml_sp_slo_binding {
# Refers to the method by which a LogoutRequest or LogoutResponse
# is sent from the SP to an IdP during the Single Logout (SLO) process.
# Only HTTP-POST or HTTP-Redirect methods are allowed.
default 'HTTP-POST';
}
map $host $saml_sp_sign_slo {
# Whether the SP must sign the LogoutRequest or LogoutResponse
# sent to the IdP.
default "false";
}
map $host $saml_idp_slo_url {
# IdP endpoint that the SP will send the LogoutRequest to initiate
# a logout process or LogoutResponse to confirm the logout.
# If not set, the SAML Single Logout (SLO) feature is DISABLED and
# requests to the 'logout' location will result in the termination
# of the user session and a redirect to the logout landing page.
default "https://login.microsoftonline.com/8807dced-9637-4205-a520-423077750c60/saml2";
}
map $host $saml_sp_want_signed_slo {
# Whether the SP wants the SAML LogoutRequest or LogoutResponse from the IdP
# to be digitally signed.
default "true";
}
map $host $saml_logout_landing_page {
# Where to redirect user after requesting /logout location. This can be
# replaced with a custom logout page, or complete URL.
default "/_logout"; # Built-in, simple logout page
}
map $proto $saml_cookie_flags {
http "Path=/; SameSite=lax;"; # For HTTP/plaintext testing
https "Path=/; SameSite=lax; HttpOnly; Secure;"; # Production recommendation
}
map $http_x_forwarded_port $redirect_base {
"" $proto://$host:$server_port;
default $proto://$host:$http_x_forwarded_port;
}
map $http_x_forwarded_proto $proto {
"" $scheme;
default $http_x_forwarded_proto;
}
# ADVANCED CONFIGURATION BELOW THIS LINE
# Additional advanced configuration (server context) in saml_sp.server_conf
######### Shared memory zones that keep the SAML-related key-value databases
# Zone for storing AuthnRequest and LogoutRequest message identifiers (ID)
# to prevent replay attacks. (REQUIRED)
# Timeout determines how long the SP waits for a response from the IDP,
# i.e. how long the user authentication process can take.
keyval_zone zone=saml_request_id:1M state=/var/lib/nginx/state/saml_request_id.json timeout=5m;
# Zone for storing SAML Response message identifiers (ID) to prevent replay attacks. (REQUIRED)
# Timeout determines how long the SP keeps IDs to prevent reuse.
keyval_zone zone=saml_response_id:1M state=/var/lib/nginx/state/saml_response_id.json timeout=1h;
# Zone for storing SAML session access information. (REQUIRED)
# Timeout determines how long the SP keeps session access decision (the session lifetime).
keyval_zone zone=saml_session_access:1M state=/var/lib/nginx/state/saml_session_access.json timeout=1h;
# Zone for storing SAML NameID values. (REQUIRED)
# Timeout determines how long the SP keeps NameID values. Must be equal to session lifetime.
keyval_zone zone=saml_name_id:1M state=/var/lib/nginx/state/saml_name_id.json timeout=1h;
# Zone for storing SAML NameID format values. (REQUIRED)
# Timeout determines how long the SP keeps NameID format values. Must be equal to session lifetime.
keyval_zone zone=saml_name_id_format:1M state=/var/lib/nginx/state/saml_name_id_format.json timeout=1h;
# Zone for storing SAML SessionIndex values. (REQUIRED)
# Timeout determines how long the SP keeps SessionIndex values. Must be equal to session lifetime.
keyval_zone zone=saml_session_index:1M state=/var/lib/nginx/state/saml_session_index.json timeout=1h;
# Zone for storing SAML AuthnContextClassRef values. (REQUIRED)
# Timeout determines how long the SP keeps AuthnContextClassRef values. Must be equal to session lifetime.
keyval_zone zone=saml_authn_context_class_ref:1M state=/var/lib/nginx/state/saml_authn_context_class_ref.json timeout=1h;
# Zones for storing SAML attributes values. (OPTIONAL)
# Timeout determines how long the SP keeps attributes values. Must be equal to session lifetime.
keyval_zone zone=saml_attrib_uid:1M state=/var/lib/nginx/state/saml_attrib_uid.json timeout=1h;
keyval_zone zone=saml_attrib_name:1M state=/var/lib/nginx/state/saml_attrib_name.json timeout=1h;
keyval_zone zone=saml_attrib_memberOf:1M state=/var/lib/nginx/state/saml_attrib_memberOf.json timeout=1h;
######### SAML-related variables whose value is looked up by the key (session cookie) in the key-value database.
# Required:
keyval $saml_request_id $saml_request_redeemed zone=saml_request_id; # SAML Request ID
keyval $saml_response_id $saml_response_redeemed zone=saml_response_id; # SAML Response ID
keyval $cookie_auth_token $saml_access_granted zone=saml_session_access; # SAML Access decision
keyval $cookie_auth_token $saml_name_id zone=saml_name_id; # SAML NameID
keyval $cookie_auth_token $saml_name_id_format zone=saml_name_id_format; # SAML NameIDFormat
keyval $cookie_auth_token $saml_session_index zone=saml_session_index; # SAML SessionIndex
keyval $cookie_auth_token $saml_authn_context_class_ref zone=saml_authn_context_class_ref; # SAML AuthnContextClassRef
# Optional:
keyval $cookie_auth_token $saml_attrib_uid zone=saml_attrib_uid;
keyval $cookie_auth_token $saml_attrib_name zone=saml_attrib_name;
keyval $cookie_auth_token $saml_attrib_memberOf zone=saml_attrib_memberOf;
keyval_zone zone=saml_attrib_mail:1M state=/var/lib/nginx/state/saml_attrib_mail.json timeout=1h;
keyval $cookie_auth_token $saml_attrib_mail zone=saml_attrib_mail;
keyval $cookie_auth_token $saml_attrib_objectid zone=saml_attrib_objectid;
keyval_zone zone=saml_attrib_objectid:1M state=/var/lib/nginx/state/saml_attrib_objectid.json timeout=1h;
######### Imports a module that implements SAML SSO and SLO functionality
js_import samlsp from conf.d/saml_sp.js;
構成をテストするには、次の 2 つの部分が必要です。
NGINX Plus を使用して SAML SP を構成し、Microsoft Entra ID を使用して IdP を構成した後、SAML フローを検証することが重要です。 この検証プロセスにより、IdP を介したユーザー認証が成功し、SP で保護されたリソースへのアクセスが許可されることが保証されます。
SP によって開始された SAML フローを確認するには、任意のブラウザを開き、アドレス バーにhttps://dev.sports.comと入力します。 これにより、IdP ログイン ページに移動します。
図8: IdPログインページ
IdP のログイン ページで設定されているユーザーの資格情報を入力します。 IdP は送信時にユーザーを認証します。
図9: 設定されたユーザーの資格情報を入力する
セッションが正常に確立されると、ユーザーには以前に要求した保護されたリソースへのアクセスが許可されます。 その後、そのリソースはユーザーのブラウザに表示されます。
図10: 正常に読み込まれたアプリケーションページ
SP および IdP ログを確認することで、SAML フローに関する貴重な情報を取得できます。 SP 側 (NGINX Plus) で、auth_token クッキーが正しく設定されていることを確認します。 IdP 側 (Microsoft Entra ID) では、認証プロセスがエラーなしで完了し、SAML アサーションが SP に送信されていることを確認します。
NGINX access.log は
次のようになります。
127.0.0.1 - - [14/Aug/2023:21:25:49 +0000] "GET / HTTP/1.0" 200 127 "https://login.microsoftonline.com/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15" "-"
99.187.244.63 - Akash Ananthanarayanan [14/Aug/2023:21:25:49 +0000] "GET / HTTP/1.1" "dev.sports.com" 200 127 "https://login.microsoftonline.com/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15" "-
NGINX debug.log は
次のようになります。
2023/08/14 21:25:49 [info] 27513#27513: *399 js: SAML SP success, creating session _d4db9b93c415ee7b4e057a4bb195df6cd0be7e4d
SAML シングル ログアウト (SLO) を使用すると、ユーザーは 1 回のアクションで関連するすべての IdP および SP からログアウトできます。 NGINX Plus は、SP 開始および IdP 開始のログアウト シナリオをサポートし、SSO 環境におけるセキュリティとユーザー エクスペリエンスを強化します。 この例では、SP によって開始されるログアウト シナリオを使用します。
図11: LogoutRequest および LogoutResponse の POST/リダイレクト バインディングを使用した SAML SP 開始 SLO
セッションを認証した後、SP で設定されたログアウト URL にアクセスしてログアウトします。 たとえば、NGINX Plus でログアウト URL としてhttps://dev.sports.com/logoutを設定している場合は、ブラウザのアドレスバーにその URL を入力します。
図12: セッションから正常にログアウトしました
安全なログアウトを確実に行うには、SP が SAML リクエストを開始し、それを IdP が検証して処理する必要があります。 このアクションにより、ユーザーのセッションが事実上終了し、IdP は SAML 応答を送信してユーザーのブラウザを SP にリダイレクトします。
おめでとう! NGINX Plus は SAML SP として機能できるようになり、認証プロセスにさらなるセキュリティと利便性を提供します。 この新しい機能は NGINX Plus にとって大きな前進であり、セキュリティと効率性を優先する組織にとって、より堅牢で多用途なソリューションとなります。
NGINX Plus の 30 日間無料トライアルを開始することで、今すぐ NGINX Plus で SAML を使い始めることができます。 この情報がお役に立てば幸いです。フィードバックをお待ちしています。
SAML を使用した NGINX Plus の詳細については、以下のリソースを参照してください。
「このブログ投稿には、入手できなくなった製品やサポートされなくなった製品が参照されている場合があります。 利用可能な F5 NGINX 製品およびソリューションに関する最新情報については、 NGINX 製品ファミリーをご覧ください。 NGINX は現在 F5 の一部です。 q。"