nginx http shibboleth

NginxのShibboleth Authリクエストモジュール

このモジュールにより、NginxはShibbolethのFastCGI Authorizerを使用して、Shibbolethを使用できます。このモジュールは、正しく動作するために特定の構成と、システムで利用可能なShibbolethのFastCGI Authorizerアプリケーションを必要とします。 Shibbolethの承認と認証設定は、Webサーバーの構成ではなくShibboleth2.xmlを介して構成されていますが、Apacheのmod_shibの一部に似ていることを目的としています。

このモジュールがlocationブロックに対して構成されている場合、シブベレスのFastCGI Authorizerのサブレクエストの結果に基づいて、NGINX内で着信要求が承認されます。このプロセスでは、このモジュールを使用して、バックエンドアプリケーションで使用するヘッダーまたは環境パラメーターとして、成功した承認者応答からNginxの元の要求にユーザー属性をコピーできます。承認が成功しない場合、承認者の応答ステータスとヘッダーがクライアントに返され、それに応じてユーザーのブラウザのアクセスを拒否またはリダイレクトします（Wayfページなど、設定されている場合）。

このモジュールはアクセスフェーズで動作するため、 satisfy指令を介して他のアクセスモジュール（ access 、 auth_basicなど）と組み合わせることができます。このモジュールは、 ngx_http_auth_request_moduleと一緒にコンパイルすることもできますが、同じlocationブロックでこれらのモジュールの両方を使用することはテストされておらず、アドバイスされていません。

以下の動作の詳細を読んで、属性にヘッダーを使用している場合のスプーフィングの回避に関する重要なメモについて構成を参照してください。

これが専用モジュールである理由の詳細については、https：//forum.nginx.org/read.php?2,238523,238523#msg-238523を参照してください。

指令

NGINX構成ファイルに次のディレクティブが追加されます。以下のコンテキストは、それらがどこに追加されるかを示しています。

shib_request <uri> | off

コンテキスト： http 、 server 、 location

デフォルト： off

Shibboleth Auth Request Module onを切り替え、承認を求められるURIを設定します。構成されたURIは、Shibboleth FastCGI Authorizerを指すNginxロケーションブロックを参照する必要があります。

設定されたURIへのサブレクエストから生じる応答のHTTPステータスとヘッダーは、FASTCGI Authorizer仕様に従ってユーザーに返されます。 1つの（潜在的に重要な）警告は、Nginxが現在サブレクエストに関して動作する方法のために（承認者が効果的に必要とするもの）、リクエスト本体は承認者に転送されず、同様に、承認者からの応答本体はクライアントに返されないことです。

ただし、構成されたURIは、応答を生成するためにFastCGIバックエンドを使用することに制限されていません。これは、テスト中またはその他の方法で役立つ場合があります。NGINXの組み込みのreturnを使用して指令rewriteて適切な応答を作成できるためです。さらに、このモジュールは任意のFastCGI Authorizerで使用できますが、操作は上記の警告の影響を受ける場合があります。

警告

shib_requestディレクティブには、 shib_authorizerフラグが必要ありません。これは、nginxを開始するには削除する必要があります。他の変更は必要ありません。

shib_request_set <variable> <value>

コンテキスト： http 、 server 、 location

デフォルト： none

認証要求が完了した後、 variableを指定されたvalueに設定します。 value 、認証要求の応答からの変数が含まれている場合があります。たとえば、 $upstream_http_* 、 $upstream_status 、およびnginx_http_upstream_moduleドキュメントで言及されているその他の変数。

この指令を使用して、Shibboleth属性をFastCGI PHPアプリケーションの$ _Serverなどのバックエンドアプリケーションの環境に導入でき、推奨される方法です。例については、構成ドキュメントを参照してください。

shib_request_use_headers on | off

コンテキスト： http 、 server 、 location

デフォルト： off

注記

v2.0.0に追加されました。

Shibboleth Authorizer Responseからメインリクエストへの属性をヘッダーとしてコピーして、アップストリームサーバーやアプリケーションで利用できるようにします。上流/アプリケーションがshib_request_setを介してサーバーパラメーターをサポートしていない場合にのみ、このオプションを使用します。

この設定が有効になっているため、 Variable-*で始まる承認者応答ヘッダーが抽出され、ヘッダー名からVariable-サブストリングを剥ぎ取り、バックエンドに送信する前にメインリクエストにコピーしました。たとえば、 Variable-Commonname: John Smithなどの承認者応答ヘッダーはCommonname: John Smithメインリクエストに追加され、バックエンドに送信されます。

スプーフィングに注意してください- バックエンドアプリケーションがヘッダーの注入から保護されていることを確認する必要があります。これを達成する方法については、構成例を参照してください。

インストール

このモジュールは、nginx 1.9.11に動的モジュールが導入されるため、静的または動的にコンパイルできます。動的モジュールの実用的な結果は、永続的に存在して有効になっている静的モジュールとは対照的に、それらをロードできることです。

このモジュールのパッケージバージョンを取得する最も簡単な方法は、NginxのPKG-OSSツールを使用することです。これは、メインリポジトリからNGINXの公式リリースとともにインストール用の動的モジュールのパッケージを提供し、NGINXを手作業でコンパイルする必要性を回避するのに役立ちます。

それ以外の場合は、このモジュールでNginxを動的にコンパイルするには、NGINXを構築するときに次のオプションを./configureに渡します。

 -add-dynamic-module = <path>

以下を含めることにより、 nginx.confのモジュールを明示的にロードする必要があります。

 load_module/path/to/modules/ngx_http_shibboleth_module.so;

nginxをリロードまたは再起動します。

このモジュールでnginxを静的にコンパイルするには、nginxを構築するときに次のオプションを./configureに渡します。

 -add-module = <path>

静的ビルドでは、モジュールがNginxに組み込まれているため、追加の負荷は必要ありません。

構成

Nginx/Shibboleth環境の構成の詳細については、https：//github.com/nginx-shib/nginx-http-shibboleth/blob/master/config.rstのドキュメントを参照してください。

サンプルserverブロックは、次のもので構成されています。

 #FastCGI authorizer for Auth Request module
location = /shibauthorizer {
    internal ;
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;
}

#FastCGI responder
location /Shibboleth.sso {
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;
}

# Using the ``shib_request_set`` directive, we can introduce attributes as
# environment variables for the backend application. In this example, we
# set ``fastcgi_param`` but this could be any type of Nginx backend that
# supports parameters (by using the appropriate *_param option)
#
# The ``shib_fastcgi_params`` is an optional set of default parameters,
# available in the ``includes/`` directory in this repository.
#
# Choose this type of configuration unless your backend application
# doesn't support server parameters or specifically requires headers.
location /secure-environment-vars {
    shib_request /shibauthorizer;
    include shib_fastcgi_params;
    shib_request_set $shib_commonname $upstream_http_variable_commonname ;
    shib_request_set $shib_email $upstream_http_variable_email ;
    fastcgi_param COMMONNAME $shib_commonname ;
    fastcgi_param EMAIL $shib_email ;
    fastcgi_pass unix:/path/to/backend.socket;
}

# A secured location. All incoming requests query the Shibboleth FastCGI authorizer.
# Watch out for performance issues and spoofing!
#
# Choose this type of configuration for ``proxy_pass`` applications
# or backends that don't support server parameters.
location /secure {
    shib_request /shibauthorizer;
    shib_request_use_headers on;

    # Attributes from Shibboleth are introduced as headers by the FastCGI
    # authorizer so we must prevent spoofing. The
    # ``shib_clear_headers`` is a set of default header directives,
    # available in the `includes/` directory in this repository.
    include shib_clear_headers;

    # Add *all* attributes that your application uses, including all
    #variations.
    more_clear_input_headers 'displayName' 'mail' 'persistent-id' ;

    # This backend application will receive Shibboleth variables as request
    # headers (from Shibboleth's FastCGI authorizer)
    proxy_pass http://localhost:8080;
}

Headers-More-Nginx-Moduleを使用して、潜在的に危険な入力ヘッダーをクリアし、スプーフィングの可能性を回避することに注意してください。環境変数を備えた後者の例は、バックエンドが環境パラメーターのみからデータを読み取る限り、ヘッダーのスプーフィングの影響を受けにくくなりません。

デフォルトの構成は、Shibboleth Authorizerから基本的なヘッダーをクリアするために利用できますが、アプリケーションが使用するすべての属性に対して独自の明確な指令を記述する必要があります。一部のアプリケーションでは、環境からShibboleth属性を読み取ってからヘッダーに戻るようにするため、 shib_request_use_headersを使用していない場合でも、アプリケーションのコードを確認することに注意してください。

shib_request_setを使用すると、nginxとしてincludeできるデフォルトのparamsファイルが利用可能です。多数のデフォルトの属性が含まれているため、アプリケーションで必要とされていないものを削除し、必要なフェデレーションまたはIDP属性を追加します。このデフォルトのParamsファイルは、 fastcgi_paramディレクティブをuwsgi_param 、 scgi_paramなどに変更するだけで、FASTCGIではないアップストリームに対して再利用できます。

ゴッチャス

• Shibboleth Authリクエストなどのサブレクエストは、ヘッダーフィルターを介して処理されません。これは、A /shibauthorizerブロックの一部として構成されていても、 add_headerなどの組み込みディレクティブが機能しないことを意味します。サブレクエストヘッダーを操作する必要がある場合は、モジュールheaders-moreからmore_set_headersを使用してください。

  https://forum.nginx.org/read.php?29,257271,257272#msg-257272を参照してください。

行動

このモジュールは、可能であればFastCGI承認者の仕様に従いますが、正当な理由でいくつかの顕著な逸脱があります。したがって、動作は次のとおりです。

• nginxはリクエストボディのバッファリングをサポートしていないため、リクエスト本体を除き、承認者サブレクエストは元の要求のすべての側面で構成されています。 Shibboleth FastCGI Authorizerはリクエスト本体を考慮していないため、これは問題ではありません。

• 承認者のサブレクエストが200ステータスを返した場合、アクセスが許可されます。

  shib_request_use_headersが有効になり、 Variable-*で始まる応答ヘッダーが抽出され、ヘッダー名からVariable-サブストリングを剥ぎ取り、メインリクエストにコピーします。他の承認者応答ヘッダーは、 Variable-および応答本体が付いていないものではありません。 FASTCGI仕様は、FASTCGI環境にVariable-*名前値ペアを含めるように呼びますが、任意のバックエンド（ proxy_passなど）で使用できるようにヘッダーを作成し、FastCGIアプリケーションに限定するだけではありません。代わりに、 Variable-*データをヘッダーとして渡すことで、これらのユーザー属性をヘッダーとして渡すapacheのShibUseHeaders Onのmod_shibに従うことになります。

  属性を環境変数（ ShibUseEnvironment On in mod_shibの荷物と同等）として渡すには、各属性のshib_request_setディレクティブを使用して属性を手動で抽出する必要があります。各バックエンドは異なる方法でパラメーターを受け入れる可能性があるため、これは（現在）すべての属性に対して一致することはできません（ fastcgi_param 、 uwsgi_paramなど）。この動作を自動化するためのプルリクエストは歓迎されます。

• Authorizer SubRequestが他のステータス（リダイレクトまたはエラーを含む）を返す場合、authizer Responseのステータスとヘッダーがクライアントに返されます。

  これは、 401 Unauthorizedまたは403 Forbidden場合、アクセスが拒否され、承認者からのヘッダー（ WWW-Authenticateなど）がクライアントに渡されることを意味します。他のすべての承認者の応答（ 3xxリダイレクトなど）は、ステータスやヘッダーを含むクライアントに渡され、Wayf PagesやShibboleth Responder（ Shibboleth.sso ）などのリダイレクトが正しく動作します。

  FastCGI Authorizer Specは、応答本体をクライアントに返すことを求めていますが、Nginxは現在サブレクエスト応答（ NGX_HTTP_SUBREQUEST_IN_MEMORY ）のバッファリングをサポートしていないため、承認者の応答本体は事実上無視されます。回避策は、nginxにそれ自体のerror_pageを提供することです。

   location /secure {
     shib_request /shibauthorizer;
     error_page 403 /shibboleth-forbidden.html;
     ...
  }

  これにより、Shibboleth Authorizerがユーザーのアクセスをこの場所へのアクセスを拒否した場合、特定のエラーページが提供されます。 error_pageが指定されていないと、NGINXは一般的なエラーページを提供します。

  これは、Shibboleth Responder（通常はShibboleth.ssoでホストされる）には適用されないことに注意してください。これは、fastCGI Responderであり、Nginxはサブレクストが使用されないため、これと完全に互換性があります。

  詳細については、https：//forum.nginx.org/read.php?2,238444,238453を参照してください。

このモジュールは、ShibbolethのFastCGI Authorizer専用に特別に調整されていますが、上記の仕様からの逸脱を念頭に置いて、他の認可者と連携する可能性があります。

テスト

テストは、新しいコミットがリポジトリに行われる場合、または新しいプルリクエストが開かれたときに、GitHubアクション（この構成を使用）で自動的に実行されます。何かが壊れた場合、あなたは通知され、結果はGitHubで報告されます。

テストは、さまざまなバージョンとnginxの構成とテスト:: nginx Perlテストの足場を含むモジュールのコンパイルのための単純なBashスクリプトの組み合わせを使用して作成されます。テストの拡張方法については、以前のリンクを参照してください。また、Blocks（）関数などの側面に関する基礎となるテスト::ベースドキュメントも参照してください。

統合テストはCIによって自動的に実行されますが、手動で実行することもできます（Perl＆CPANをインストールする必要があります）：

 cd nginx-http-shibboleth
cpanm --notest --local-lib= $HOME /perl5 Test::Nginx
# nginx must be present in PATH and built with debugging symbols
PERL5LIB= $HOME /perl5/lib/perl5 prove

ヘルプとサポート

Shibbolethの構成とNginxまたはWebサーバーのセットアップのサポートリクエストは、Shibbolethコミュニティユーザーのメーリングリストに送信する必要があります。詳細については、https：//www.shibboleth.net/community/lists/を参照してください。

デバッグ

Nginx/FastCGI/Shibbolethスタックの複雑な性質のため、設定の問題をデバッグするのは難しい場合があります。ここにいくつかの重要なポイントがあります：

1. nginx-http-shibbolethがNginx内に正常に構築およびインストールされていることを確認してください。 nginx -Vを実行して--add-module=[path]/nginx-http-shibbolethまたは--add-dynamic-module=[path]/nginx-http-shibbolethの出力を検査することで確認できます。

2. nginxに動的モジュールを使用している場合は、 load_moduleディレクティブを使用してこのモジュールをロードしたことを確認してください。 shib_requestおよびその他のディレクティブの使用は、モジュールのロードを忘れた場合、失敗します。

3. テストしたものとは異なるnginxのバージョンを使用する場合、または他のサードパーティモジュールを使用している場合は、上記のテストスイートを実行して互換性を確認する必要があります。テストが失敗した場合は、構成を確認するか、nginxバージョンの更新を検討してください。

4. Shibbolethの構成： shibboleth2.xmlと関連する構成を確認して、ホスト、パス、属性が正しくリリースされるようにします。構成の例は、FastCGI Authorizerで動作するようにshibboleth2.xmlを構成するためのキー「Gotchas」を特定するのに役立ちます。

5. アプリケーションレベル：コード内で、常に可能な限り単純なデバッグ出力（リクエスト環境の印刷など）から始めて、そこからワークアップしてください。基本的なスタンドアロンアプリを作成する場合は、Wikiのボトル構成をご覧ください。

6. デバッグモジュール内部：上記のすべてを注意深くチェックした場合、このモジュール自体の動作をデバッグすることもできます。デバッグサポートでnginxをコンパイルする必要があります（ ./auto/configure --with-debug ... ）。nginxを実行するときは、デバッグロギングを有効にして前景で走ることができる場合に最も簡単です。 nginx.confに以下を追加します。

    daemon off ;
   error_log stderr debug ;

   nginxを実行します。 nginxを起動すると、[デバッグ]を含む行が表示され、リクエストを行うとコンソールロギングが続きます。これが発生しない場合は、nginx構成とコンパイルプロセスを確認してください。

   最終的にshib_request位置ブロックにヒットする（または呼び出す必要がある）リクエストを行うと、出力のような行が表示されます。

   [debug] 1234 #0: shib request handler
   [debug] 1234 #0: shib request set variables
   [debug] 1234 #0: shib request authorizer handler
   [debug] 1234 #0: shib request authorizer allows access
   [debug] 1234 #0: shib request authorizer copied header: "AUTH_TYPE: shibboleth"
   [debug] 1234 #0: shib request authorizer copied header: "REMOTE_USER: [email protected]"
   ...

   Shibリクエストを含むこれらのタイプの行が表示されない場合、または上記の行の一部が表示されているが、ヘッダー/変数がコピーされている場所ではない場合は、nginx構成を再確認してください。まだどこにも行かない場合は、独自のデバッグラインをソースに追加して（このモジュールの例に従って）、最終的に何がうまくいかないかを決定できます。これを行う場合は、変更を加えるたびにnginxおよび/またはnginx-http-shibbolethを再コンパイルすることを忘れないでください。

コアモジュールコードでバグが見つかったと思われる場合は、問題を作成してください。

他の誰かが以前に同様の問題に遭遇した可能性が高いため、既存の問題を検索することもできます。

バージョン化

このモジュールはセマンティックバージョンの使用を使用し、すべてのリリースはGitHubでタグ付けされているため、個々のタグのパッケージダウンロードが可能になります。

ライセンス

このプロジェクトは、Nginxと同じライセンス、2条件BSDのようなライセンスの下でライセンスされています。