Web 應用安全

<debug>

啟用 Spring Security 除錯基礎設施。這將提供人類可讀(多行)的除錯資訊,以監控進入安全過濾器的請求。這可能包含敏感資訊,例如請求引數或頭,因此只能在開發環境中使用。

<http>

如果在應用程式中使用 <http> 元素,則會建立一個名為 "springSecurityFilterChain" 的 FilterChainProxy Bean,並且該元素中的配置用於在 FilterChainProxy 中構建一個過濾器鏈。從 Spring Security 3.1 開始,可以使用額外的 http 元素新增額外的過濾器鏈[1] 用於如何設定從您的 web.xml 的對映]。標準過濾器的位置是固定的(參見名稱空間介紹中的過濾器順序表),消除了框架早期版本中使用者必須在 FilterChainProxy Bean 中顯式配置過濾器鏈時常見的錯誤源。當然,如果需要完全控制配置,您仍然可以這樣做。

所有需要引用 AuthenticationManager 的過濾器都將自動注入由名稱空間配置建立的內部例項。

每個 <http> 名稱空間塊總是建立一個 SecurityContextPersistenceFilter、一個 ExceptionTranslationFilter 和一個 FilterSecurityInterceptor。這些是固定的,不能用替代方案替換。

<http> 屬性

<http> 元素上的屬性控制核心過濾器的一些屬性。

  • use-authorization-manager 使用 AuthorizationManager API 而不是 SecurityMetadataSource(預設為 true)

  • use-authorization-manager 使用此 AuthorizationManager 而不是從 <intercept-url> 元素派生一個

  • access-decision-manager-ref 可選屬性,指定應用於授權 HTTP 請求的 AccessDecisionManager 實現的 ID。預設使用 AffirmativeBased 實現,包含 RoleVoterAuthenticatedVoter

  • authentication-manager-ref 對此 http 元素建立的 FilterChain 使用的 AuthenticationManager 的引用。

  • observation-registry-refFilterChain 和相關元件使用的 ObservationRegistry 的引用

  • auto-config 自動註冊登入表單、BASIC 身份驗證、登出服務。如果設定為 "true",將新增所有這些功能(儘管您仍然可以透過提供相應的元素來自定義每個功能的配置)。如果未指定,預設為 "false"。不推薦使用此屬性。請改用顯式配置元素以避免混淆。

  • create-session 控制 Spring Security 類建立 HTTP 會話的積極性。選項包括

    • always - 如果會話不存在,Spring Security 將主動建立一個。

    • ifRequired - Spring Security 僅在需要會話時才建立會話(預設值)。

    • never - Spring Security 永遠不會建立會話,但如果應用程式建立了會話,則會使用它。

    • stateless - Spring Security 不會建立會話,並忽略會話以獲取 Spring Authentication

  • disable-url-rewriting 阻止會話 ID 附加到應用程式的 URL 中。如果此屬性設定為 true,客戶端必須使用 Cookie。預設值為 true

  • entry-point-ref 通常使用的 AuthenticationEntryPoint 將根據已配置的身份驗證機制來設定。此屬性允許透過定義一個自定義的 AuthenticationEntryPoint Bean 來覆蓋此行為,該 Bean 將啟動身份驗證過程。

  • jaas-api-provision 如果可用,則將請求作為從 JaasAuthenticationToken 獲取的主體執行,這透過向棧中新增 JaasApiIntegrationFilter Bean 來實現。預設為 false

  • name 一個 Bean 識別符號,用於在上下文中的其他地方引用該 Bean。

  • once-per-request 對應於 FilterSecurityInterceptorobserveOncePerRequest 屬性。預設為 false

  • filter-all-dispatcher-types 對應於 AuthorizationFiltershouldFilterAllDispatcherTypes 屬性。當 use-authorization-manager=false 時不起作用。預設為 true

  • patternhttp 元素定義模式控制透過其定義的過濾器列表進行過濾的請求。解釋取決於配置的 request-matcher。如果未定義模式,則將匹配所有請求,因此應首先宣告最具體的模式。

  • realm 設定基本身份驗證(如果啟用)使用的 Realm 名稱。對應於 BasicAuthenticationEntryPoint 上的 realmName 屬性。

  • request-matcher 定義 FilterChainProxyintercept-url 建立的 Bean 中用於匹配傳入請求的 RequestMatcher 策略。目前選項包括 mvcantregexciRegex,分別對應 Spring MVC、ant、正則表示式和不區分大小寫的正則表示式。使用其 patternmethodservlet-path 屬性為每個 intercept-url 元素建立一個單獨的例項。Ant 路徑使用 AntPathRequestMatcher 進行匹配,正則表示式使用 RegexRequestMatcher 進行匹配,Spring MVC 路徑匹配使用 MvcRequestMatcher。有關匹配如何執行的詳細資訊,請參閱這些類的 Javadoc。如果在 classpath 中存在 Spring MVC,則 MVC 是預設策略,否則使用 Ant 路徑。

  • request-matcher-ref 對實現 RequestMatcher 的 Bean 的引用,該 Bean 將確定是否應使用此 FilterChain。這比 pattern 更強大的替代方案。

  • security 透過將此屬性設定為 none,請求模式可以對映到空過濾器鏈。將不應用安全,也無法使用 Spring Security 的任何特性。

  • security-context-repository-ref 允許將自定義的 SecurityContextHolderStrategy 注入到 SecurityContextPersistenceFilterSecurityContextHolderFilterBasicAuthenticationFilterUsernamePasswordAuthenticationFilterExceptionTranslationFilterLogoutFilter 等中。

  • security-context-explicit-save 如果為 true,則使用 SecurityContextHolderFilter 而不是 SecurityContextPersistenceFilter。需要顯式儲存

  • security-context-repository-ref 允許將自定義的 SecurityContextRepository 注入到 SecurityContextPersistenceFilter 中。

  • servlet-api-provision 提供 HttpServletRequest 安全方法的版本,如 isUserInRole()getPrincipal(),透過向棧中新增 SecurityContextHolderAwareRequestFilter Bean 實現。預設為 true

  • use-expressions 啟用 access 屬性中的 EL 表示式,如基於表示式的訪問控制章節所述。預設值為 true。

<access-denied-handler>

此元素允許您使用 error-page 屬性設定 ExceptionTranslationFilter 使用的預設 AccessDeniedHandlererrorPage 屬性,或使用 ref 屬性提供您自己的實現。這在 ExceptionTranslationFilter 部分有更詳細的討論。

<access-denied-handler> 的父元素

<access-denied-handler> 屬性

  • error-page 如果已透過身份驗證的使用者請求他們無權訪問的頁面,將被重定向到的訪問拒絕頁面。

  • ref 定義對 AccessDeniedHandler 型別的 Spring Bean 的引用。

<cors>

此元素允許配置 CorsFilter。如果未指定 CorsFilterCorsConfigurationSource,並且 classpath 中存在 Spring MVC,則使用 HandlerMappingIntrospector 作為 CorsConfigurationSource

<cors> 屬性

<cors> 元素上的屬性控制 headers 元素。

  • ref 可選屬性,指定 CorsFilter 的 Bean 名稱。

  • cors-configuration-source-ref 可選屬性,指定要注入到由 XML 名稱空間建立的 CorsFilter 中的 CorsConfigurationSource 的 Bean 名稱。

<cors> 的父元素

<headers>

此元素允許配置要隨響應傳送的額外(安全)頭。它使多個頭的配置變得容易,並且還允許透過 header 元素設定自定義頭。更多資訊可以在參考手冊的 安全頭 部分找到。

  • Cache-Control, Pragma, 和 Expires - 可以使用 cache-control 元素設定。這確保瀏覽器不會快取您的安全頁面。

  • Strict-Transport-Security - 可以使用 hsts 元素設定。這確保瀏覽器在未來請求中自動使用 HTTPS。

  • X-Frame-Options - 可以使用 frame-options 元素設定。X-Frame-Options 頭可用於防止點選劫持攻擊。

  • X-XSS-Protection - 可以使用 xss-protection 元素設定。瀏覽器可以使用 X-XSS-Protection 頭進行基本控制。

  • X-Content-Type-Options - 可以使用 content-type-options 元素設定。X-Content-Type-Options 頭阻止 Internet Explorer 從宣告的 content-type 中進行 MIME 嗅探。這也適用於 Google Chrome 在下載擴充套件時。

  • Public-Key-PinningPublic-Key-Pinning-Report-Only - 可以使用 hpkp 元素設定。這允許 HTTPS 網站抵禦使用錯誤頒發或其他欺詐證書的攻擊者的冒充。

  • Content-Security-PolicyContent-Security-Policy-Report-Only - 可以使用 content-security-policy 元素設定。內容安全策略 (CSP) 是一種網路應用程式可以利用的機制,用於減輕內容注入漏洞,例如跨站指令碼 (XSS)。

  • Referrer-Policy - 可以使用 referrer-policy 元素設定,Referrer-Policy 是一種網路應用程式可以利用的機制,用於管理 referrer 欄位,該欄位包含使用者訪問的上一頁。

  • Feature-Policy - 可以使用 feature-policy 元素設定,Feature-Policy 是一種允許 Web 開發人員選擇性地啟用、停用和修改瀏覽器中某些 API 和 Web 功能行為的機制。

  • Cross-Origin-Opener-Policy - 可以使用 cross-origin-opener-policy 元素設定,Cross-Origin-Opener-Policy 是一種允許您確保頂級文件不與跨域文件共享瀏覽上下文組的機制。

  • Cross-Origin-Embedder-Policy - 可以使用 cross-origin-embedder-policy 元素設定,Cross-Origin-Embedder-Policy 是一種阻止文件載入任何未明確授予文件許可權的跨域資源的機制。

  • Cross-Origin-Resource-Policy - 可以使用 cross-origin-resource-policy 元素設定,Cross-Origin-Resource-Policy 是一種機制,表達瀏覽器應阻止對給定資源進行無 CORS 的跨域/跨站請求的意願。

<headers> 屬性

<headers> 元素上的屬性控制 headers 元素。

  • defaults-disabled 可選屬性,指定是否停用 Spring Security 的預設 HTTP 響應頭。預設值為 false(包含預設頭)。

  • disabled 可選屬性,指定是否停用 Spring Security 的 HTTP 響應頭。預設值為 false(頭已啟用)。

<headers> 的父元素

<cache-control>

新增 Cache-Control、Pragma 和 Expires 頭,以確保瀏覽器不快取您的安全頁面。

<cache-control> 屬性

  • disabled 指定是否應停用 Cache Control。預設 false。

<cache-control> 的父元素

<hsts>

啟用後,為任何安全請求向響應新增 Strict-Transport-Security 頭。這允許伺服器指示瀏覽器在未來的請求中自動使用 HTTPS。

<hsts> 屬性

  • disabled 指定是否應停用 Strict-Transport-Security。預設 false。

  • include-sub-domains 指定是否應包含子域名。預設 true。

  • max-age-seconds 指定主機應被視為已知 HSTS 主機的最大時間。預設一年。

  • request-matcher-ref 用於確定是否應設定頭的 RequestMatcher 例項。預設值是當 HttpServletRequest.isSecure() 為 true 時。

  • preload 指定是否應包含預載入。預設 false。

<hsts> 的父元素

<hpkp>

啟用後,為任何安全請求向響應新增 HTTP 公鑰固定擴充套件頭。這允許 HTTPS 網站抵禦使用錯誤頒發或其他欺詐證書的攻擊者的冒充。

<hpkp> 屬性

  • disabled 指定是否應停用 HTTP 公鑰固定 (HPKP)。預設 true。

  • include-sub-domains 指定是否應包含子域名。預設 false。

  • max-age-seconds 設定 Public-Key-Pins 頭中 max-age 指令的值。預設 60 天。

  • report-only 指定瀏覽器是否應僅報告固定驗證失敗。預設 true。

  • report-uri 指定瀏覽器應報告固定驗證失敗的 URI。

<hpkp> 的父元素

<pins>

固定列表

<pins> 的子元素

<pin>

使用 base64 編碼的 SPKI 指紋作為值,並使用加密雜湊演算法作為屬性來指定一個固定

<pin> 屬性

  • algorithm 加密雜湊演算法。預設 SHA256。

<pin> 的父元素

<content-security-policy>

啟用後,為響應新增 內容安全策略 (CSP) 頭。CSP 是一種網路應用程式可以利用的機制,用於減輕內容注入漏洞,例如跨站指令碼 (XSS)。

<content-security-policy> 屬性

  • policy-directives Content-Security-Policy 頭的安全策略指令;如果 report-only 設定為 true,則使用 Content-Security-Policy-Report-Only 頭。

  • report-only 設定為 true,以啟用 Content-Security-Policy-Report-Only 頭,僅用於報告策略違規。預設為 false。

<content-security-policy> 的父元素

<referrer-policy>

啟用後,為響應新增 Referrer Policy 頭。

<referrer-policy> 屬性

  • policy Referrer-Policy 頭的策略。預設 "no-referrer"。

<referrer-policy> 的父元素

<feature-policy>

啟用後,為響應新增 Feature Policy 頭。

<feature-policy> 屬性

  • policy-directives Feature-Policy 頭的安全策略指令。

<feature-policy> 的父元素

<frame-options>

啟用後,為響應新增 X-Frame-Options 頭,這允許較新的瀏覽器進行一些安全檢查並防止點選劫持攻擊。

<frame-options> 屬性

  • disabled 如果停用,將不包含 X-Frame-Options 頭。預設 false。

  • policy

    • DENY 頁面不能顯示在框架中,無論哪個站點嘗試顯示。這是指定 frame-options-policy 時的預設值。

    • SAMEORIGIN 頁面只能在與頁面本身同源的框架中顯示

    換句話說,如果你指定 DENY,不僅從其他網站載入頁面到框架中會失敗,從同一網站載入也會失敗。另一方面,如果你指定 SAMEORIGIN,只要包含該頁面的網站與提供該頁面的網站相同,你仍然可以在框架中使用該頁面。

<frame-options> 的父元素

<permissions-policy>

Permissions-Policy header 新增到響應中。

<permissions-policy> 屬性

  • policy 用於 Permissions-Policy header 的策略值。

<permissions-policy> 的父元素

<xss-protection>

X-XSS-Protection header 新增到響應中,以協助防禦 反射型 / Type-1 跨站點指令碼 (XSS) 攻擊。這絕不是對 XSS 攻擊的全面保護!

<xss-protection> 屬性

<xss-protection> 的父元素

<content-type-options>

向響應新增值為 nosniff 的 X-Content-Type-Options header。這會為 IE8+ 和 Chrome 擴充套件程式停用 MIME 嗅探

<content-type-options> 屬性

  • disabled 指定是否應停用內容型別選項。預設為 false。

<content-type-options> 的父元素

<cross-origin-embedder-policy>

啟用時,將 Cross-Origin-Embedder-Policy header 新增到響應中。

<cross-origin-embedder-policy> 屬性
  • policy Cross-Origin-Embedder-Policy header 的策略。

<cross-origin-embedder-policy> 的父元素

<cross-origin-opener-policy>

啟用時,將 Cross-Origin-Opener-Policy header 新增到響應中。

<cross-origin-opener-policy> 屬性
  • policy Cross-Origin-Opener-Policy header 的策略。

<cross-origin-opener-policy> 的父元素

<cross-origin-resource-policy>

啟用時,將 Cross-Origin-Resource-Policy header 新增到響應中。

<cross-origin-resource-policy> 屬性
  • policy Cross-Origin-Resource-Policy header 的策略。

<cross-origin-resource-policy> 的父元素

<header>

向響應新增額外的 header,需要同時指定名稱和值。

<header-attributes> 屬性

  • header-name header 的 name

  • value 要新增的 header 的 value

  • refHeaderWriter 介面的自定義實現的引用。

<header> 的父元素

<anonymous>

向棧中新增一個 AnonymousAuthenticationFilter 和一個 AnonymousAuthenticationProvider。如果你使用 IS_AUTHENTICATED_ANONYMOUSLY 屬性,則需要此元素。

<anonymous> 的父元素

<anonymous> 屬性

  • enabled 在預設的名稱空間設定下,匿名“認證”功能會自動啟用。你可以使用此屬性停用它。

  • granted-authority 應分配給匿名請求的已授權許可權。通常用於為匿名請求分配特定的角色,隨後可用於授權決策。如果未設定,預設為 ROLE_ANONYMOUS

  • key 提供者和過濾器之間共享的 key。通常不需要設定。如果未設定,預設為一個安全的隨機生成值。這意味著,在使用匿名功能時設定此值可以提高啟動時間,因為安全隨機值的生成可能需要一些時間。

  • username 應分配給匿名請求的使用者名稱。這允許識別主體,這對於日誌記錄和審計可能很重要。如果未設定,預設為 anonymousUser

<csrf>

此元素將為應用程式新增 跨站請求偽造 (CSRF) 防護。它還會更新預設的 RequestCache,使其僅在成功認證後重放“GET”請求。更多資訊請參見參考資料的 跨站請求偽造 (CSRF) 部分。[2]

<csrf> 的父元素

<csrf> 屬性

  • disabled 可選屬性,用於指定停用 Spring Security 的 CSRF 防護。預設為 false(CSRF 防護已啟用)。強烈建議保持啟用 CSRF 防護。

  • token-repository-ref 要使用的 CsrfTokenRepository。預設為 HttpSessionCsrfTokenRepository

  • request-handler-ref 可選的 CsrfTokenRequestHandler。預設為 CsrfTokenRequestAttributeHandler

  • request-matcher-ref 用於確定是否應應用 CSRF 的 RequestMatcher 例項。預設為除 "GET", "TRACE", "HEAD", "OPTIONS" 之外的任何 HTTP 方法。

<custom-filter>

此元素用於向過濾器鏈新增一個過濾器。它不會建立任何額外的 bean,而是用於選擇應用程式上下文中已定義的 jakarta.servlet.Filter 型別的 bean,並將其新增到 Spring Security 維護的過濾器鏈中的特定位置。完整的詳細資訊請參見 名稱空間章節

<custom-filter> 的父元素

<custom-filter> 屬性

  • after custom-filter 應放置在鏈中緊隨其後的過濾器。此功能僅適用於希望將其自己的過濾器混合到安全過濾器鏈中並對標準 Spring Security 過濾器有所瞭解的高階使用者。過濾器名稱對映到特定的 Spring Security 實現過濾器。

  • before custom-filter 應放置在鏈中緊靠其前的過濾器。

  • position custom-filter 應放置在鏈中的顯式位置。如果你要替換標準過濾器,請使用此選項。

  • ref 定義對實現 Filter 介面的 Spring bean 的引用。

<expression-handler>

定義如果啟用了基於表示式的訪問控制,將使用的 SecurityExpressionHandler 例項。如果未提供,將使用預設實現(不含 ACL 支援)。

<expression-handler> 屬性

  • ref 定義對實現 SecurityExpressionHandler 介面的 Spring bean 的引用。

<form-login>

用於向過濾器棧中新增一個 UsernamePasswordAuthenticationFilter,並嚮應用程式上下文新增一個 LoginUrlAuthenticationEntryPoint 以提供按需認證。這將始終優先於其他名稱空間建立的入口點。如果未提供屬性,將在 URL "/login" 自動生成一個登入頁面[2]。可以使用 <form-login> 屬性來自定義行為。

<form-login> 的父元素

<form-login> 屬性

  • always-use-default-target 如果設定為 true,無論使用者如何到達登入頁面,他們都將始終從 default-target-url 給定的值開始。對映到 UsernamePasswordAuthenticationFilteralwaysUseDefaultTargetUrl 屬性。預設值為 false

  • authentication-details-source-ref 對認證過濾器將使用的 AuthenticationDetailsSource 的引用。

  • authentication-failure-handler-ref 可用作 authentication-failure-url 的替代方案,使你能夠完全控制認證失敗後的導航流程。該值應是應用程式上下文中 AuthenticationFailureHandler bean 的名稱。

  • authentication-failure-url 對映到 UsernamePasswordAuthenticationFilterauthenticationFailureUrl 屬性。定義登入失敗時瀏覽器將被重定向到的 URL。預設為 /login?error,這將由自動登入頁面生成器自動處理,重新渲染帶有錯誤訊息的登入頁面。

  • authentication-success-handler-ref 可用作 default-target-urlalways-use-default-target 的替代方案,使你能夠完全控制成功認證後的導航流程。該值應是應用程式上下文中 AuthenticationSuccessHandler bean 的名稱。預設情況下,使用 SavedRequestAwareAuthenticationSuccessHandler 的實現,並注入 default-target-url

  • default-target-url 對映到 UsernamePasswordAuthenticationFilterdefaultTargetUrl 屬性。如果未設定,預設值為 "/"(應用程式根目錄)。使用者登入後將被帶到此 URL,前提是他們在嘗試訪問受保護資源時沒有被要求登入,在這種情況下,他們將被帶到最初請求的 URL。

  • login-page 應用於渲染登入頁面的 URL。對映到 LoginUrlAuthenticationEntryPointloginFormUrl 屬性。預設為 "/login"。

  • login-processing-url 對映到 UsernamePasswordAuthenticationFilterfilterProcessesUrl 屬性。預設值為 "/login"。

  • password-parameter 包含密碼的請求引數的名稱。預設為 "password"。

  • username-parameter 包含使用者名稱的請求引數的名稱。預設為 "username"。

  • authentication-success-forward-urlForwardAuthenticationSuccessHandler 對映到 UsernamePasswordAuthenticationFilterauthenticationSuccessHandler 屬性。

  • authentication-failure-forward-urlForwardAuthenticationFailureHandler 對映到 UsernamePasswordAuthenticationFilterauthenticationFailureHandler 屬性。

<oauth2-login>

OAuth 2.0 登入功能透過使用 OAuth 2.0 和/或 OpenID Connect 1.0 提供者配置認證支援。

<oauth2-login> 的父元素

<oauth2-login> 屬性

  • client-registration-repository-refClientRegistrationRepository 的引用。

  • authorized-client-repository-refOAuth2AuthorizedClientRepository 的引用。

  • authorized-client-service-refOAuth2AuthorizedClientService 的引用。

  • authorization-request-repository-refAuthorizationRequestRepository 的引用。

  • authorization-request-resolver-refOAuth2AuthorizationRequestResolver 的引用。

  • authorization-redirect-strategy-ref 對授權 RedirectStrategy 的引用。

  • access-token-response-client-refOAuth2AccessTokenResponseClient 的引用。

  • user-authorities-mapper-refGrantedAuthoritiesMapper 的引用。

  • user-service-refOAuth2UserService 的引用。

  • oidc-user-service-ref 對 OpenID Connect OAuth2UserService 的引用。

  • login-processing-url 過濾器處理認證請求的 URI。

  • login-page 傳送使用者進行登入的 URI。

  • authentication-success-handler-refAuthenticationSuccessHandler 的引用。

  • authentication-failure-handler-refAuthenticationFailureHandler 的引用。

  • jwt-decoder-factory-refOidcAuthorizationCodeAuthenticationProvider 使用的 JwtDecoderFactory 的引用。

<oauth2-client>

配置 OAuth 2.0 Client 支援。

<oauth2-client> 的父元素

<oauth2-client> 屬性

  • client-registration-repository-refClientRegistrationRepository 的引用。

  • authorized-client-repository-refOAuth2AuthorizedClientRepository 的引用。

  • authorized-client-service-refOAuth2AuthorizedClientService 的引用。

<oauth2-client> 的子元素

<authorization-code-grant>

<authorization-code-grant> 的父元素

<authorization-code-grant> 屬性

  • authorization-request-repository-refAuthorizationRequestRepository 的引用。

  • authorization-redirect-strategy-ref 對授權 RedirectStrategy 的引用。

  • authorization-request-resolver-refOAuth2AuthorizationRequestResolver 的引用。

  • access-token-response-client-refOAuth2AccessTokenResponseClient 的引用。

<client-registrations>

與 OAuth 2.0 或 OpenID Connect 1.0 提供者註冊的客戶端 (ClientRegistration) 的容器元素。

<client-registrations> 的子元素

<client-registration>

表示與 OAuth 2.0 或 OpenID Connect 1.0 提供者註冊的客戶端。

<client-registration> 的父元素

<client-registration> 屬性

  • registration-id 唯一標識 ClientRegistration 的 ID。

  • client-id 客戶端識別符號。

  • client-secret 客戶端 secret。

  • client-authentication-method 用於與提供者進行客戶端認證的方法。支援的值包括 client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwtnone (公共客戶端)

  • authorization-grant-type OAuth 2.0 授權框架定義了四種授權許可型別。支援的值包括 authorization_code, client_credentials, password,以及擴充套件許可型別 urn:ietf:params:oauth:grant-type:jwt-bearer

  • redirect-uri 客戶端註冊的重定向 URI,授權伺服器在終端使用者認證並授權訪問客戶端後,將終端使用者的使用者代理重定向到此處。

  • scope 客戶端在授權請求流程中請求的 scope,例如 openid, email 或 profile。

  • client-name 用於客戶端的描述性名稱。該名稱可能在某些場景中使用,例如在自動生成的登入頁面中顯示客戶端名稱時。

  • provider-id 對關聯提供者的引用。可以引用 <provider> 元素或使用常見的提供者之一(google, github, facebook, okta)。

<provider>

OAuth 2.0 或 OpenID Connect 1.0 提供者的配置資訊。

<provider> 的父元素

<provider> 屬性

  • provider-id 唯一標識提供者的 ID。

  • authorization-uri 授權伺服器的授權端點 URI。

  • token-uri 授權伺服器的令牌端點 URI。

  • user-info-uri 用於訪問已認證終端使用者的宣告/屬性的使用者資訊端點 URI。

  • user-info-authentication-method 向用戶資訊端點發送訪問令牌時使用的認證方法。支援的值包括 header, formquery

  • user-info-user-name-attribute 使用者資訊響應中返回的屬性名稱,該屬性引用終端使用者的名稱或識別符號。

  • issuer-uri 用於使用 OpenID Connect Provider 的 配置端點 或授權伺服器的 元資料端點 進行發現來初始配置 ClientRegistration 的 URI。

<oauth2-resource-server>

向配置中新增 BearerTokenAuthenticationFilter, BearerTokenAuthenticationEntryPointBearerTokenAccessDeniedHandler。此外,必須指定 <jwt><opaque-token> 之一。

<oauth2-resource-server> 的父元素

<oauth2-resource-server> 的子元素

<oauth2-resource-server> 屬性

  • authentication-manager-resolver-ref 對將在請求時解析 AuthenticationManagerAuthenticationManagerResolver 的引用。

  • bearer-token-resolver-ref 對將從請求中檢索 bearer token 的 BearerTokenResolver 的引用。

  • entry-point-ref 對將處理未經授權請求的 AuthenticationEntryPoint 的引用。

<jwt>

表示將授權 JWT 的 OAuth 2.0 資源伺服器。

<jwt> 的父元素

<jwt> 屬性

  • jwt-authentication-converter-refConverter<Jwt, AbstractAuthenticationToken> 的引用。

  • jwt-decoder-refJwtDecoder 的引用。這是一個較大的元件,它會覆蓋 jwk-set-uri

  • jwk-set-uri 用於從 OAuth 2.0 授權伺服器載入簽名驗證 key 的 JWK Set Uri。

<opaque-token>

表示將授權不透明令牌 (opaque tokens) 的 OAuth 2.0 資源伺服器。

<opaque-token> 的父元素

<opaque-token> 屬性

  • introspector-refOpaqueTokenIntrospector 的引用。這是一個較大的元件,它會覆蓋 introspection-uri, client-idclient-secret

  • introspection-uri 用於內省不透明令牌詳細資訊的內省 URI。應與 client-idclient-secret 一起提供。

  • client-id 用於針對提供的 introspection-uri 進行客戶端認證的 Client Id。

  • client-secret 用於針對提供的 introspection-uri 進行客戶端認證的 Client Secret。

  • authentication-converter-refOpaqueTokenAuthenticationConverter 的引用。負責將成功的內省結果轉換為 Authentication 例項。

<relying-party-registrations>

與 SAML 2.0 身份提供者註冊的依賴方 (ClientRegistration) 的容器元素。

<relying-party-registrations> 屬性

  • id 唯一標識 RelyingPartyRegistrationRepository 的 ID。

<relying-party-registrations> 的子元素

<relying-party-registration>

表示與 SAML 2.0 身份提供者註冊的依賴方。

<relying-party-registration> 的父元素

<relying-party-registration> 屬性

  • registration-id 唯一標識 RelyingPartyRegistration 的 ID。

  • metadata-location 斷言方元資料位置。

  • assertion-consumer-service-location AssertionConsumerService 位置。等同於依賴方 <SPSSODescriptor><AssertionConsumerService Location="…​"/> 中的值。

  • assertion-consumer-service-binding AssertionConsumerService 繫結。等同於依賴方 <SPSSODescriptor><AssertionConsumerService Binding="…​"/> 中的值。支援的值為 POSTREDIRECT

  • single-logout-service-location SingleLogoutService 位置。等同於依賴方 <SPSSODescriptor> 中 <SingleLogoutService Location="…​"/> 中的值。

  • single-logout-service-response-location SingleLogoutService 響應位置。等同於依賴方 <SPSSODescriptor> 中 <SingleLogoutService ResponseLocation="…​"/> 中的值。

  • single-logout-service-binding SingleLogoutService 繫結。等同於依賴方 <SPSSODescriptor> 中 <SingleLogoutService Binding="…​"/> 中的值。支援的值為 POSTREDIRECT

  • asserting-party-id 對關聯斷言方的引用。必須引用一個 <asserting-party> 元素。

<relying-party-registration> 的子元素

<decryption-credential>

與依賴方關聯的解密憑據。

<decryption-credential> 的父元素

<decryption-credential> 屬性

  • certificate-location 獲取證書的位置。

  • private-key-location 獲取依賴方私鑰的位置。

<signing-credential>

與依賴方關聯的簽名憑據。

<verification-credential> 的父元素

<verification-credential> 屬性

  • certificate-location 獲取此證書的位置。

  • private-key-location 獲取依賴方私鑰的位置。

<asserting-party>

SAML 2.0 斷言方的配置資訊。

<asserting-party> 的父元素

<asserting-party> 屬性

  • asserting-party-id 唯一標識斷言方的 ID。

  • entity-id 斷言方的 EntityID。

  • want-authn-requests-signed WantAuthnRequestsSigned 設定,指示斷言方偏好依賴方在傳送前應簽署 AuthnRequest

  • single-sign-on-service-binding SingleSignOnService 繫結。支援的值為 POSTREDIRECT

  • signing-algorithms 此斷言方的 org.opensaml.saml.ext.saml2alg.SigningMethod 演算法列表,按優先順序排序。

  • single-logout-service-location SingleLogoutService 位置。等同於斷言方 <IDPSSODescriptor> 中 <SingleLogoutService Location="…​"/> 中的值。

  • single-logout-service-response-location SingleLogoutService 響應位置。等同於斷言方 <IDPSSODescriptor> 中 <SingleLogoutService ResponseLocation="…​"/> 中的值。

  • single-logout-service-binding SingleLogoutService 繫結。等同於斷言方 <IDPSSODescriptor> 中 <SingleLogoutService Binding="…​"/> 中的值。支援的值為 POSTREDIRECT

<asserting-party> 的子元素

<encryption-credential>

與斷言方關聯的加密憑據。

<encryption-credential> 的父元素

<encryption-credential> 屬性

  • certificate-location 獲取證書的位置。

  • private-key-location 獲取依賴方私鑰的位置。

<verification-credential>

與斷言方關聯的驗證憑據。

<verification-credential> 的父元素

<verification-credential> 屬性

  • certificate-location 獲取此證書的位置。

  • private-key-location 獲取依賴方私鑰的位置。

<http-basic>

向配置中新增 BasicAuthenticationFilterBasicAuthenticationEntryPoint。後者僅在未啟用基於表單的登入時用作配置入口點。

<http-basic> 的父元素

<http-basic> 屬性

  • authentication-details-source-ref 對認證過濾器將使用的 AuthenticationDetailsSource 的引用。

  • entry-point-ref 設定 BasicAuthenticationFilter 使用的 AuthenticationEntryPoint

<http-firewall> 元素

這是一個頂級元素,可用於將 HttpFirewall 的自定義實現注入到名稱空間建立的 FilterChainProxy 中。預設實現應適用於大多數應用程式。

<http-firewall> 屬性

  • ref 定義對實現 HttpFirewall 介面的 Spring bean 的引用。

<intercept-url>

此元素用於定義應用程式感興趣的 URL 模式集,並配置它們的處理方式。它用於構建 `FilterSecurityInterceptor` 所使用的 `FilterInvocationSecurityMetadataSource`。例如,如果特定的 URL 需要透過 HTTPS 訪問,它還負責配置一個 `ChannelProcessingFilter`。當根據指定的模式匹配傳入請求時,匹配會按照元素宣告的順序進行。因此,最具體的模式應該放在前面,最通用的模式應該放在後面。

<intercept-url> 的父元素

<intercept-url> 屬性

  • access 列出將儲存在 `FilterInvocationSecurityMetadataSource` 中用於定義的 URL 模式/方法組合的訪問屬性。這應該是安全配置屬性(例如角色名稱)的逗號分隔列表。

  • method 將與模式和 servlet 路徑(可選)結合使用以匹配傳入請求的 HTTP 方法。如果省略,將匹配任何方法。如果指定了相同模式但分別帶有和不帶有方法,則帶有方法的匹配項將優先。

  • pattern 定義 URL 路徑的模式。其內容取決於包含此元素的 http 元素的 `request-matcher` 屬性,因此如果 classpath 中存在 Spring MVC,則預設為 MVC 匹配器。

  • request-matcher-ref 對 `RequestMatcher` 的引用,用於確定是否使用此 `<intercept-url>`。

  • requires-channel 可以是 "http" 或 "https",取決於特定 URL 模式是應透過 HTTP 還是 HTTPS 訪問。或者,當沒有偏好時,可以使用值 "any"。如果此屬性存在於任何 `<intercept-url>` 元素上,則會將一個 `ChannelProcessingFilter` 新增到過濾器堆疊中,並將其額外的依賴項新增到應用程式上下文中。

如果添加了 `<port-mappings>` 配置,`SecureChannelProcessor` 和 `InsecureChannelProcessor` bean 將使用此配置來確定用於重定向到 HTTP/HTTPS 的埠。

此屬性對 filter-security-metadata-source 無效
  • servlet-path 將與模式和 HTTP 方法結合使用以匹配傳入請求的 servlet 路徑。此屬性僅當 request-matcher 為 'mvc' 時適用。此外,僅在以下兩種用例中需要該值:1) 在 `ServletContext` 中註冊了 2 個或更多 `HttpServlet`,它們的對映以 '/' 開頭且不同;2) 模式以註冊的 `HttpServlet` 路徑的相同值開頭,但不包括預設(根)`HttpServlet` '/'

此屬性對 filter-security-metadata-source 無效

<jee>

向過濾器鏈新增一個 J2eePreAuthenticatedProcessingFilter,以提供與容器認證的整合。

<jee> 的父元素

<jee> 屬性

  • mappable-roles 一個逗號分隔的角色列表,用於在傳入的 HttpServletRequest 中查詢。

  • user-service-ref 對使用者服務(或 UserDetailsService bean)ID 的引用

<logout>

向過濾器堆疊新增一個 `LogoutFilter`。此過濾器配置有 `SecurityContextLogoutHandler`。

<logout> 的父元素

<logout> 屬性

  • delete-cookies 一個逗號分隔的 cookie 名稱列表,使用者登出時應刪除這些 cookie。

  • invalidate-session 對映到 `SecurityContextLogoutHandler` 的 `invalidateHttpSession` 屬性。預設為 "true",因此會話將在登出時失效。

  • logout-success-url 使用者登出後將被帶往的目標 URL。預設為 <form-login-login-page>/?logout(即 /login?logout)

    設定此屬性將為 `SessionManagementFilter` 注入一個配置了該屬性值的 `SimpleRedirectInvalidSessionStrategy`。當提交無效會話 ID 時,將呼叫此策略,重定向到配置的 URL。

  • logout-url 將導致登出的 URL(即由過濾器處理的 URL)。預設為 "/logout"。

  • success-handler-ref 可用於提供一個 `LogoutSuccessHandler` 例項,該例項將在登出後被呼叫以控制導航。

<saml2-login>

The SAML 2.0 登入 功能配置使用 SAML 2.0 服務提供商的身份驗證支援。

<saml2-login> 的父元素

<saml2-login> 屬性

  • relying-party-registration-repository-ref 對 `RelyingPartyRegistrationRepository` 的引用。

  • authentication-request-repository-ref 對 `Saml2AuthenticationRequestRepository` 的引用。

  • authentication-request-context-resolver-ref 對 `Saml2AuthenticationRequestResolver` 的引用。

  • authentication-converter-ref 對 `AuthenticationConverter` 的引用。

  • login-processing-url 過濾器處理認證請求的 URI。

  • login-page 傳送使用者進行登入的 URI。

  • authentication-success-handler-refAuthenticationSuccessHandler 的引用。

  • authentication-failure-handler-refAuthenticationFailureHandler 的引用。

  • authentication-manager-ref 對 `AuthenticationManager` 的引用。

<saml2-logout>

The SAML 2.0 單點登出 功能配置支援 RP 和 AP 發起的 SAML 2.0 單點登出。

<saml2-logout> 的父元素

<saml2-logout> 屬性

  • logout-url 依賴方或斷言方可以觸發登出的 URL。

  • logout-request-url 斷言方可以傳送 SAML 2.0 登出請求的 URL。

  • logout-response-url 斷言方可以傳送 SAML 2.0 登出響應的 URL。

  • relying-party-registration-repository-ref 對 `RelyingPartyRegistrationRepository` 的引用。

  • logout-request-validator-ref 對 `Saml2LogoutRequestValidator` 的引用。

  • logout-request-resolver-ref 對 `Saml2LogoutRequestResolver` 的引用。

  • logout-request-repository-ref 對 `Saml2LogoutRequestRepository` 的引用。

  • logout-response-validator-ref 對 `Saml2LogoutResponseValidator` 的引用。

  • logout-response-resolver-ref 對 `Saml2LogoutResponseResolver` 的引用。

<password-management>

此元素配置密碼管理。

<password-management> 的父元素

<password-management> 屬性

  • change-password-page 更改密碼頁面。預設為 "/change-password"。

<port-mappings>

預設情況下,將在配置中新增一個 `PortMapperImpl` 例項,用於重定向到安全和非安全 URL。此元素可選擇用於覆蓋該類定義的預設對映。每個子 `<port-mapping>` 元素定義一對 HTTP:HTTPS 埠。預設對映為 80:443 和 8080:8443。覆蓋這些對映的示例可以在 重定向到 HTTPS 中找到。

<port-mappings> 的父元素

<port-mappings> 的子元素

<port-mapping>

提供一種在強制重定向時將 http 埠對映到 https 埠的方法。

<port-mapping> 的父元素

<port-mapping> 屬性

  • http 要使用的 http 埠。

  • https 要使用的 https 埠。

<remember-me>

將 `RememberMeAuthenticationFilter` 新增到堆疊。根據屬性設定,此過濾器將配置 `TokenBasedRememberMeServices`、`PersistentTokenBasedRememberMeServices` 或使用者指定的實現 `RememberMeServices` 介面的 bean。

<remember-me> 的父元素

<remember-me> 屬性

  • authentication-success-handler-ref 如果需要自定義導航,則在 `RememberMeAuthenticationFilter` 上設定 `authenticationSuccessHandler` 屬性。該值應該是應用程式上下文中 `AuthenticationSuccessHandler` bean 的名稱。

  • data-source-ref 對 `DataSource` bean 的引用。如果設定此屬性,將使用 `PersistentTokenBasedRememberMeServices` 並配置 `JdbcTokenRepositoryImpl` 例項。

  • remember-me-parameter 切換記住我認證的請求引數名稱。預設為 "remember-me"。對映到 `AbstractRememberMeServices` 的 "parameter" 屬性。

  • key 對映到 `AbstractRememberMeServices` 的 "key" 屬性。應設定為唯一值,以確保記住我 cookie 僅在同一個應用程式內有效 [3]。如果未設定此值,將生成一個安全的隨機值。由於生成安全的隨機值可能需要一些時間,因此顯式設定此值有助於在使用記住我功能時提高啟動時間。

  • services-alias 將內部定義的 `RememberMeServices` 匯出為 bean 別名,以便應用程式上下文中的其他 bean 可以使用它。

  • services-ref 允許完全控制過濾器將使用的 `RememberMeServices` 實現。該值應該是應用程式上下文中實現此介面的 bean 的 `id`。如果正在使用登出過濾器,該 bean 也應實現 `LogoutHandler` 介面。

  • token-repository-ref 配置 `PersistentTokenBasedRememberMeServices`,但允許使用自定義的 `PersistentTokenRepository` bean。

  • token-validity-seconds 對映到 `AbstractRememberMeServices` 的 `tokenValiditySeconds` 屬性。指定記住我 cookie 有效的秒數。預設情況下,有效期為 14 天。

  • user-service-ref 記住我服務實現需要訪問 `UserDetailsService`,因此必須在應用程式上下文中定義一個。如果只有一個,名稱空間配置將自動選擇並使用它。如果存在多個例項,可以使用此屬性顯式指定 bean 的 `id`。

<request-cache> 元素

設定 `RequestCache` 例項,`ExceptionTranslationFilter` 將在呼叫 `AuthenticationEntryPoint` 之前使用此例項儲存請求資訊。

<request-cache> 的父元素

<request-cache> 屬性

  • ref 定義對實現 `RequestCache` 介面的 Spring bean 的引用。

<session-management>

透過向過濾器堆疊新增 `SessionManagementFilter` 來實現與會話管理相關的功能。

<session-management> 的父元素

<session-management> 屬性

  • authentication-strategy-explicit-invocation 將此屬性設定為 true 意味著不會注入 `SessionManagementFilter`,並且需要顯式呼叫 SessionAuthenticationStrategy。

  • invalid-session-url 設定此屬性將為 `SessionManagementFilter` 注入一個配置了該屬性值的 `SimpleRedirectInvalidSessionStrategy`。當提交無效會話 ID 時,將呼叫此策略,重定向到配置的 URL。

  • invalid-session-url 允許注入 `SessionManagementFilter` 使用的 InvalidSessionStrategy 例項。請使用此屬性或 `invalid-session-url` 屬性,但不要同時使用兩者。

  • session-authentication-error-url 定義當 SessionAuthenticationStrategy 丟擲異常時應顯示的錯誤頁面的 URL。如果未設定,則向客戶端返回未經授權 (401) 的錯誤程式碼。請注意,如果在基於表單的登入期間發生錯誤,此屬性不適用,此時認證失敗 URL 將優先。

  • session-authentication-strategy-ref 允許注入 `SessionManagementFilter` 使用的 SessionAuthenticationStrategy 例項。

  • session-fixation-protection 指示使用者認證時如何應用會話固定攻擊防護。如果設定為 "none",則不應用任何防護。 "newSession" 將建立一個新的空會話,僅遷移與 Spring Security 相關的屬性。 "migrateSession" 將建立一個新會話並將所有會話屬性複製到新會話中。在 Servlet 3.1 (Java EE 7) 及更新的容器中,指定 "changeSessionId" 將保留現有會話並使用容器提供的會話固定攻擊防護 (HttpServletRequest#changeSessionId())。在 Servlet 3.1 及更新的容器中預設為 "changeSessionId",在舊容器中預設為 "migrateSession"。如果在舊容器中使用 "changeSessionId",則會丟擲異常。

    如果啟用會話固定攻擊防護,將為 `SessionManagementFilter` 注入一個配置適當的 `DefaultSessionAuthenticationStrategy`。有關更多詳細資訊,請參閱此類的 Javadoc。

<session-management> 的子元素

<concurrency-control>

新增對併發會話控制的支援,允許限制使用者可以擁有的活動會話數量。將建立一個 `ConcurrentSessionFilter`,並與 `SessionManagementFilter` 一起使用 `ConcurrentSessionControlAuthenticationStrategy`。如果聲明瞭 `form-login` 元素,策略物件也將注入到建立的認證過濾器中。將為策略建立一個 `SessionRegistry` 例項(除非使用者希望使用自定義 bean,否則為 `SessionRegistryImpl` 例項)。

<concurrency-control> 的父元素

<concurrency-control> 屬性

  • error-if-maximum-exceeded 如果設定為 "true",當用戶試圖超出最大允許會話數時,將丟擲 `SessionAuthenticationException`。預設行為是使原始會話過期。

  • expired-url 使用者因超出允許會話數並在其他地方再次登入而嘗試使用被併發會話控制器“過期”的會話時,將被重定向到的 URL。除非設定了 exception-if-maximum-exceeded,否則應設定此屬性。如果未提供值,過期訊息將直接寫入響應。

  • expired-url 允許注入 `ConcurrentSessionFilter` 使用的 ExpiredSessionStrategy 例項。

  • max-sessions 對映到 `ConcurrentSessionControlAuthenticationStrategy` 的 `maximumSessions` 屬性。指定值 -1 支援無限會話。

  • session-registry-alias 將內部會話登錄檔引用用於您自己的 bean 或管理介面也可能很有用。您可以使用 session-registry-alias 屬性暴露內部 bean,併為其指定一個可在配置其他地方使用的名稱。

  • session-registry-ref 使用者可以使用 session-registry-ref 屬性提供自己的 `SessionRegistry` 實現。其他的併發會話控制 bean 將被配置為使用它。

<x509>

新增對 X.509 認證的支援。將一個 `X509AuthenticationFilter` 新增到堆疊,並建立一個 `Http403ForbiddenEntryPoint` bean。後者僅在沒有使用其他認證機制時使用(其唯一功能是返回 HTTP 403 錯誤程式碼)。還將建立一個 `PreAuthenticatedAuthenticationProvider`,它將使用者許可權的載入委託給 `UserDetailsService`。

<x509> 的父元素

<x509> 屬性

  • authentication-details-source-ref 對 `AuthenticationDetailsSource` 的引用

  • subject-principal-regex 定義一個正則表示式,用於從證書中提取使用者名稱(供 `UserDetailsService` 使用)。

  • user-service-ref 在配置了多個例項的情況下,允許為 X.509 指定特定的 `UserDetailsService`。如果未設定,將嘗試自動查詢合適的例項並使用它。

<filter-chain-map>

用於使用 FilterChainMap 顯式配置 FilterChainProxy 例項。

<filter-chain-map> 屬性

  • request-matcher 定義用於匹配傳入請求的策略。當前選項包括 'ant'(用於 ant 路徑模式)、'regex'(用於正則表示式)和 'ciRegex'(用於不區分大小寫的正則表示式)。

<filter-chain-map> 的子元素

<filter-chain>

用於在內部定義特定的 URL 模式以及適用於匹配該模式的 URL 的過濾器列表。當多個 filter-chain 元素按順序組裝成列表以配置 FilterChainProxy 時,最具體的模式必須放在列表頂部,最通用的模式放在底部。

<filter-chain> 的父元素

<filter-chain> 屬性

  • filters 一個逗號分隔的引用列表,指向實現 `Filter` 介面的 Spring bean。值 "none" 表示此 `FilterChain` 不應使用任何 `Filter`。

  • request-matcher-ref 對 `RequestMatcher` 的引用,用於確定是否應呼叫 `filters` 屬性中的任何 `Filter`。

<filter-security-metadata-source>

用於顯式配置 FilterSecurityMetadataSource bean,以便與 FilterSecurityInterceptor 一起使用。通常僅在您顯式配置 FilterChainProxy 而非使用 <http> 元素時需要。所使用的 intercept-url 元素應僅包含 pattern、method 和 access 屬性。任何其他屬性將導致配置錯誤。

<filter-security-metadata-source> 屬性

  • id 一個 bean 識別符號,用於在上下文的其他地方引用該 bean。

  • request-matcher 定義用於匹配傳入請求的策略。當前選項包括 'ant'(用於 ant 路徑模式)、'regex'(用於正則表示式)和 'ciRegex'(用於不區分大小寫的正則表示式)。

  • use-expressions 啟用在 <intercept-url> 元素的 'access' 屬性中使用表示式,而不是傳統的配置屬性列表。預設為 'true'。如果啟用,每個屬性應包含一個布林表示式。如果表示式評估為 'true',則授予訪問許可權。

<filter-security-metadata-source> 的子元素


1. 請參閱 xref:servlet/configuration/xml-namespace.adoc#ns-web-xml[介紹性章節
2. 此功能僅為方便起見而提供,不適用於生產環境(生產環境中會選擇檢視技術來渲染自定義登入頁面)。`DefaultLoginPageGeneratingFilter` 類負責渲染登入頁面,並在需要時提供普通表單登入和/或 OIDC 的登入表單。
3. 這不影響 `PersistentTokenBasedRememberMeServices` 的使用,因為令牌儲存在伺服器端。