nginx http shibboleth下載nginx http shibboleth源代碼下載

nginx http shibboleth

網站數據

v2.0.2

下載

Nginx的Shibboleth auth請求模塊

該模塊允許Nginx通過Shibboleth的FastCGI授權者與Shibboleth合作。該模塊需要特定的配置才能正確工作，以及系統上可用的Shibboleth的FastCGI授權器應用程序。它的目的是類似於Apache的MOD_SHIB的一部分，儘管Shibboleth授權和身份驗證設置是通過Shibboleth2.xml而不是在Web服務器配置中配置的。

使用此模塊針對location塊配置，根據Shibboleth的FastCGI授權者的子要求的結果，在NGINX中授權傳入請求。在此過程中，該模塊可用於將成功的授權者響應從NGINX的原始請求復制為標題或環境參數，以供任何後端應用程序使用。如果授權不成功，則授權者響應狀態和標題將返回客戶端，拒絕訪問或重定向用戶的瀏覽器（例如，如果是這樣的，則是Wayf頁面）。

該模塊在訪問階段起作用，因此可以通過satisfy指令將其與其他訪問模塊（例如access ， auth_basic ）結合使用。該模塊也可以與ngx_http_auth_request_module一起編譯，儘管在同一location塊中使用這兩個模塊的使用未經測試且不建議。

閱讀有關下面行為的更多信息，並諮詢配置，以獲取有關避免使用標頭屬性的重要說明。

有關為什麼這是一個專用模塊的更多信息，請參見https://forum.nginx.org/read.php?2,2,238523,238523#mmsg-238523

指令

以下指令添加到您的NGINX配置文件中。下面提到的上下文顯示了它們可以添加的位置。

shib_request <uri> |關閉

上下文： http ， server ， location

默認值： off

切換Shibboleth auth請求模塊並設置URI，該模塊將被要求授權。配置的URI應參考指向您的Shibboleth FastCGI授權器的NGINX位置塊。

根據FASTCGI授權者規範，將返回由子要求引起的HTTP狀態和響應的標題。一個（潛在意義的）警告是，由於NGINX目前對子要求的運作方式（授權者有效地要求），請求主體不會轉發給授權者，同樣，授權機的響應機構也不會將其退還給客戶。

但是，配置的URI不限於使用FastCGI後端來生成響應。這在測試期間或其他方式可能很有用，因為您可以使用Nginx內置的return並rewrite指令來產生合適的響應。此外，儘管操作可能受到上述警告的影響，但該模塊可與任何FASTCGI授權者一起使用。

警告

shib_request指令不再需要shib_authorizer標誌。必須將其刪除才能開始。無需其他更改。

shib_request_set <變量> <value>

上下文： http ， server ， location

默認值： none

驗證請求完成後，將variable設置為指定value 。該value可能包含驗證請求響應中的變量。例如， $upstream_http_* ， $upstream_status以及nginx_http_upstream_module文檔中提到的任何其他變量。

該指令可用於將Shibboleth屬性引入後端應用程序的環境，例如用於FastCGI PHP應用程序的$ _SERVER，這是建議這樣做的方法。有關示例，請參見配置文檔。

shib_request_use_headers打開|關閉

上下文： http ， server ， location

默認值： off

筆記

在v2.0.0中添加。

將shibboleth授權者響應中的屬性複製到主要請求中，作為標題，使其可用於上游服務器和應用程序。僅當您的上游/應用程序不通過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 = <路徑>

您需要通過nginx.conf ：

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

並重新加載或重新啟動NGINX。

要使用此模塊靜態編譯Nginx，請在構建Nginx時將以下選項傳遞給./configure ：

 -add-module = <路徑>

使用靜態構建，由於模塊是內置的NGINX，因此無需額外加載。

配置

有關配置nginx/shibboleth環境的完整詳細信息，請參見https://github.com/nginx-shib/nginx-http-shibboleth/blob/blob/master/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;
}

請注意，我們使用標頭摩爾 - nginx模塊清除潛在的危險輸入標頭，並避免欺騙的潛力。只要後端僅從環境參數讀取數據，就不容易帶有環境變量的示例。

可以使用默認配置來清除Shibboleth授權者的基本標頭，但是您必須確保為應用程序使用的所有屬性編寫自己的清晰指令。請記住，某些應用程序將嘗試從環境中讀取shibboleth屬性，然後倒入標題，因此，即使您不使用shib_request_use_headers ，請查看您的應用程序代碼。

通過使用shib_request_set ，可以使用一個默認的參數文件，您可以用作NGINX include該文件，以確保所有Core Shibboleth變量都從FastCGI授權器傳遞給了應用程序。包括許多默認屬性，因此請刪除應用程序不需要的屬性，並添加所需的聯邦或IDP屬性。可以通過簡單地將fastcgi_param指令更改為uwsgi_param ， scgi_param ，或者是FastCGI的上游，可以重複使用此默認參數文件。

陷入困境

諸如Shibboleth auth請求之類的子徵用未通過標頭過濾器處理。這意味著，如果將ADD_HEADER（例如add_header等內置指令配置為A /shibauthorizer塊的一部分。如果您需要操縱子修復標題，請使用more_set_headers中的模塊headers-more 。
請參閱https://forum.nginx.org/read.php?29,257271,257272#MSG-257272。

行為

該模塊在可能的情況下遵循FASTCGI授權器規範，但有一些顯著的偏差 - 有充分的理由。因此，行為是：

授權者子要求由原始請求的各個方面組成，除了請求主體，因為nginx不支持請求實體的緩衝。由於Shibboleth FastCGI授權者不考慮請求主體，因此這不是問題。
如果授權者子要求返回200狀態，則允許訪問。
如果啟用了shib_request_use_headers ，則提取以Variable-*開頭的響應標頭，將Variable- - 子字符串從標題名稱中剝離，然後復製到主請求中。其他授權者響應標頭未在沒有Variable-前綴，並且響應主體被忽略。 FastCGI規格要求將Variable-*名稱值對包含在FastCGI環境中，但是我們將它們製成標題，使它們可以與任何後端一起使用（例如proxy_pass ），而不僅僅是將自己限制在FastCGI應用程序中。通過將Variable-*數據作為標頭傳遞，我們最終會遵循ShibUseHeaders On in mod_shib for apache的行為，該行為將這些用戶屬性作為標頭傳遞。
為了將屬性作為環境變量（等效於mod_shib的ShibUseEnvironment On ），必須使用每個屬性的shib_request_set指令手動提取屬性。對於所有屬性，這都無法（當前）完成，因為每個後端都可以以不同的方式接受參數（ fastcgi_param ， uwsgi_param等）。歡迎拉動請求自動化此行為。
如果授權者子重點返回任何其他狀態（包括重定向或錯誤），則授權者響應的狀態和標題將退還給客戶端。
這意味著，在401 Unauthorized或403 Forbidden ，將拒絕訪問權限，並且將從WWW-Authenticate者傳遞給客戶端。所有其他授權者響應（例如3xx重定向）都將其傳遞給客戶，包括狀態和標題，允許諸如Wayf頁面的重定向和Shibboleth reversonder（ Shibboleth.sso ）正確工作。
FastCGI授權器規格要求響應主體返回客戶端，但是由於NGINX當前不支持緩衝subrequest響應（ NGX_HTTP_SUBREQUEST_IN_MEMORY ），因此有效地忽略了授權者響應主體。解決方法是讓nginx提供自己的error_page ，例如：
```
 location /secure {
   shib_request /shibauthorizer;
   error_page 403 /shibboleth-forbidden.html;
   ...
}
```
如果Shibboleth授權者拒絕用戶訪問此位置，則為給定的錯誤頁面。如果未指定error_page ，則NGINX將提供其通用錯誤頁面。
請注意，這不適用於shibboleth響應者（通常在Shibboleth.sso中託管），因為它是FastCGI響應者，並且NGINX與此完全兼容，因為沒有使用子內容。
有關更多詳細信息，請參見https://forum.nginx.org/read.php?2,238444,238453。

儘管該模塊專門針對Shibboleth的FastCGI授權者，但它可能會與其他授權者一起使用，並牢記與上面規格的偏差。

測試

每當對存儲庫進行新提交或打開新的拉請請求時，測試將在GitHub操作（使用此配置）上自動運行。如果某件事破裂，您將被告知，結果將在Github上報告。

使用簡單的bash腳本的組合編寫測試，以與Nginx的不同版本和配置和Test :: Nginx Perl Test腳手架進行集成測試的組合編輯。請諮詢先前的鏈接，以獲取有關如何擴展測試的信息，也請參考基礎測試::基本文檔，諸如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堆棧的複雜性質，調試配置問題可能很困難。這是一些要點：

確認nginx-http-shibboleth成功地構建和安裝了Nginx。您可以通過運行nginx -V進行檢查，並檢查--add-module=[path]/nginx-http-shibboleth或--add-dynamic-module=[path]/nginx-http-shibboleth 。
如果使用nginx的動態模塊，請確認您已使用load_module指令來加載此模塊。如果您忘記加載模塊，您對shib_request的使用和其他指令將失敗。
如果使用與我們測試的版本不同或使用其他第三方模塊不同的版本，則應在上面運行測試套件以確認兼容性。如果任何測試失敗，請檢查您的配置或考慮更新您的NGINX版本。
Shibboleth配置：檢查您的shibboleth2.xml和關聯的配置，以確保您的主機，路徑和屬性正確發布。示例配置可以幫助您識別鍵“抓”以配置shibboleth2.xml以與FastCGI授權器一起使用。
應用程序級別：在您的代碼中，始終從最簡單的調試輸出（例如打印請求環境）開始，然後從那裡開始工作。如果要創建一個基本的獨立應用程序，請查看Wiki上的瓶子配置。
調試模塊內部：如果您仔細檢查了上述所有內容，則還可以調試該模塊本身的行為。您需要在調試支持（通過./auto/configure --with-debug ... ）中編譯Nginx，並且在運行NGINX時，如果您可以在啟用調試日誌記錄的情況下運行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 。