Spring Security 安全命名空间

Appendix B. 安全命名空间

安全命名空间

这个附录提供了对安全命名空间中可用元素的参考信息，也介绍了它们创建的bean的信息（对单独类的知识和它们是如何在一起工作的 - 你可以在工程的Javadoc和这个文档的其他部分找到更多信息）。 如果你以前没有使用过命名空间，请阅读命名空间配置部分的介绍章节，这部分的信息是作为那些章节的一个补充资料的。 我们推荐你在编辑基于schema的配置时使用一个高质量的XML编辑器，这会为你提供上下文环境相关的信息，哪些元素和属性是可用的，注释会解释它们的用途。 命名空间是使用RELAX NG兼容格式编写的，随后转换为XSD Schema。 如果你对这种格式很熟悉，很可能希望直接查看schema 文件。

B.1. Web应用安全 - <http>元素

<http>元素为你的应用程序的web层封装了安全性配置。 它创建了一个名为"springSecurityFilterChain"的FilterChainProxy bean，这个bean维护了一系列的建立了web安全配置的安全过滤器。^[14]。 一些核心的过滤器总是要被创建的，其他的将根据子元素的配置添加到过滤器队列中。 标准过滤器的位置都是固定的（参考命名空间配置中的过滤器顺序表格），这避免了之前版本中的一个常见问题，那时候用户必须自己在FilterChainProxy bean中配置过滤器链。当然如果你需要对配置进行完全控制，依然可以这样做。

所有需要引用AuthenticationManager的过滤器，都会自动注入命名空间配置创建的内部实例（查看介绍章节获得AuthenticationManager的更多信息）。

<http>命名空间块会创建一个HttpSessionContextIntegrationFilter，一个ExceptionTranslationFilter和一个FilterSecurityInterceptor。 它们是固定的，不能使用其他可选方式替换。

B.1.1. <http>属性

<http>元素的属性控制核心过滤器的一些属性。

B.1.1.1. servlet-api-provision

支持一些版本的HttpServletRequest提供的安全方法，必须isUserInRole()和getPrincipal()，通过向堆栈中添加一个SecurityContextHolderAwareRequestFilter bean来实现。 默认是"true"。

B.1.1.2. path-type

控制拦截URL的时候，使用ant路径（默认）或是使用正则表达式。 实际中，它向FilterChainProxy中设置了特定的UrlMatcher。

B.1.1.3. lowercase-comparisons

是否在对URL进行匹配前，先将URL转换成小写。 如果没有定义，默认是"true"。

B.1.1.4. realm

为基础认证设置realm名称（如果启用）。 对应BasicAuthenticationEntryPoint中的realmName属性。

B.1.1.5. entry-point-ref

正常情况下AuthenticationEntryPoint将根据配置的认证机制进行设置。 这个属性让这个行为使用自定义的AuthenticationEntryPoint bean进行覆盖，它会启动认证流程。

B.1.1.6. access-decision-manager-ref

可选的属性，指定AccessDecisionManager实现的ID，这应该被认证的HTTP请求使用。 默认情况下一个AffirmativeBased实现会被RoleVoter和AuthenticatedVoter使用。

B.1.1.7. access-denied-page

这个属性已经被access-denied-handler子元素取代了。

B.1.1.8. once-per-request

对应FilterSecurityInterceptor的observeOncePerRequest属性。 默认是"true"。

B.1.1.9. create-session

控制创建一个HTTP会话的紧急程度。 如果不设置，默认是"ifRequired"。 其他选项是"always"和"never"。 这个属性的设置影响HttpSessionContextIntegrationFilter的allowSessionCreation和forceEagerSessionCreation属性。 除非把属性设置为"never"allowSessionCreation会一直为"true"。 除非把属性设置为"always"forceEagerSessionCreation会一直为"false"。 所以默认的配置允许会话的创建，但不会强制。 如果启用同步会话控制，当forceEagerSessionCreation被设置为"true"，不管这里设置的什么都会抛出异常。 使用"never"会在HttpSessionContextIntegrationFilter初始化的过程中导致异常。

B.1.2. <access-denied-handler>

这个元素允许你为默认的AccessDeniedHandler 设置errorPage属性， 它会被ExceptionTranslationFilter用到， （使用error-page属性，或通过ref属性 提供你自己的实现。参考 ExceptionTranslateFilter 获得更多信息。）

B.1.3. <intercept-url>元素

这个元素用来定义URL模式集合，应用对什么感兴趣并配置它们应该如何处理。 它用来构建被FilterSecurityInterceptor使用的FilterInvocationDefinitionSource，也可以从过滤器链中排除特定的模式（通过使用filters="none"属性）。 它也负责配置ChannelAuthenticationFilter，如果特定的URL需要通过HTTPS访问，比如。 当匹配时指定的模式对应了进入的请求，匹配过程就会完成，按照声明的元素顺序。 所以最希望被匹配的模式应该放在上面，最常用的模式应该放在最后。

B.1.3.1. pattern

这个模式定义了URL路径。 内容依赖于http元素中的path-type属性，它的默认值是ant路径语法。

B.1.3.2. method

HTTP Method会被用来结合模式来匹配进入的请求。 如果忽略，所有的Method都会匹配。 如果一个相同的模式指定了，使用method和没有使用method两种方式， 指定了method的匹配将被优先使用。

B.1.3.3. access

列出会被存储在FilterInvocationDefinitionSource中的访问属性，为定义的模式/Method结合的形式。 这应该是由分号分隔的安全配置属性队列（比如角色名称）。

B.1.3.4. requires-channel

可以是http或https， 这是根据一个特定的URL模式是否应该通过HTTP或HTTPS访问。 如果没有偏好还可以选择any。 如果这个属性已经出现在任何一个<intercept-url>上，一个ChannelAuthenticationFilter会添加到过滤器堆栈里， 它的附加依赖也会添加到application context中。 查看信道安全获得使用传统bean的例子配置。

如果添加了一个<port-mappings>配置，它会被SecureChannelProcessor和InsecureChannelProcessor使用来决定在重定向到HTTP/HTTPS的时候使用什么端口。

B.1.3.5. filters

可以只使用“none”作为属性值。 它会导致任何匹配的请求完全被Spring Security忽略。所有<http> 中的其他配置，影响在请求上，在这个过程中都无法访问安全上下文。在这个请求过程中访问 被保护的方法都会失败。

B.1.4. <port-mappings>元素

默认情况下，PortMapperImpl的实例会添加到配置中，在重定向到安全和不安全的URL时使用到。 这个元素可以选择用来覆盖类定义的默认映射。 每个子<port-mapping>元素都定义了一对HTTP:HTTPS端口。 默认的映射是80:443和8080:8443。 一个覆盖这些的例子可以在命名空间介绍中看到。

B.1.5. <form-login>元素

用来把一个UsernamePasswordAuthenticationFilter添加到过滤器堆栈中，把一个LoginUrlAuthenticationEntryPoint添加到application context中来提供需要的认证。 这将永远凌驾于其他命名空间创建的切入点。 如果没有提供属性，一个登录页面会自动创建在"/spring-security-login"这个URL下^[15]。 这个行为可以使用下面的属性自定义。

B.1.5.1. login-page

这个URL应该用来生成登录页面。 对应LoginUrlAuthenticationEntryPoint的loginFormUrl属性。 默认是"/spring-security-login"。

B.1.5.2. login-processing-url

对应UsernamePasswordAuthenticationFilter的filterProcessesUrl属性。 默认是"/j_spring_security_check"

B.1.5.3. default-target-url

对应UsernamePasswordAuthenticationFilter的defaultTargetUrl属性。 如果没有设置，默认值是"/"（应用的根路径）。 一个用户会在登录之后到达这个URL，在他们没有在登录之前尝试访问一个安全资源，否则他们就会被转向到原来请求的URL。

B.1.5.4. always-use-default-target

如果设置成"true"，用户会一直转发到default-target-url指定的位置，无论他们在登录页面之前访问的什么位置。 对应UsernamePasswordAuthenticationFilter的alwaysUseDefaultTargetUrl属性。

B.1.5.5. authentication-failure-url

对应UsernamePasswordAuthenticationFilter的authenticationFailureUrl属性。 定义了在登录失败时浏览器会重定向的URL。 默认是"/spring_security_login?login_error"，它会自动被登陆页面生成器处理，并使用一个错误信息重新渲染登录页面。

B.1.5.6. authentication-success-handler-ref

这可以用来替换default-target-url 和always-use-default-target，你可以完全控制 成功认证之后的导航流向。这个值应该是application context中的 AuthenticationSuccessHandlerbean的名称。

B.1.5.7. authentication-failure-handler-ref

可以用来替换 authentication-failure-url， 你可以完全控制认证失败之后的导航流向。这个值应该是application context中的 AuthenticationFailureHandlerbean的名称。

B.1.6. <http-basic>元素

向配置中添加一个BasicAuthenticationFilter 和BasicAuthenticationEntryPoint。 后一个只有在基于表单登录没有启用的时候才会被用作配置入口。

B.1.7. <remember-me>元素

向堆栈中添加RememberMeAuthenticationFilter。 这会在配置了一个TokenBasedRememberMeServices，或一个PersistentTokenBasedRememberMeServices，或一个用户自定义的实现了RememberMeServices的配置设置后启用。

B.1.7.1. data-source-ref

如果设置了这个，PersistentTokenBasedRememberMeServices会被使用到，并配置上一个JdbcTokenRepositoryImpl实例。

B.1.7.2. token-repository-ref

配置一个PersistentTokenBasedRememberMeServices但是允许使用一个自定义的PersistentTokenRepository bean。

B.1.7.3. services-ref

允许对将要用在过滤器里的RememberMeServices的实现提供完全控制。 这个值将是application context里的一个实现了这个接口的bean的id。

B.1.7.4. token-repository-ref

配置一个PersistentTokenBasedRememberMeServices但是允许使用一个自定义的PersistentTokenRepository bean。

B.1.7.5. key属性

对应AbstractRememberMeServices的"key"属性。 应该设置一个唯一的值来确定remember-me的cookies只对唯一的应用有效。^[16]。

B.1.7.6. token-validity-seconds

对应AbstractRememberMeServices的tokenValiditySeconds属性。 指定remember-me cookie生效的秒数周期。 默认它会在14日内生效。

B.1.7.7. user-service-ref

remember-me服务实现要求可以访问UserDetailsService，所以在application context中必须有一个定义。 如果只定义了一个，它会被选中，并被命名空间配置自动使用。 如果这里有多个实例，你可以使用这个树形指定一个bean的id。

B.1.8. <session-management> 元素

会话管理相关的功能由额外的 过滤器栈中的SessionManagementFilter实现。

B.1.8.1. session-fixation-protection

分析一个已存在的绘画是否应该被销毁，当一个用户认证通过，并启动了一个新会话。 如果设置为"none"，则不会出现任何改变。"newSession"会创建一个新的空会话。 "migrateSession"会创建一个新会话，并把之前会话中的属性都复制到新会话中。 默认是"migrateSession"。

如果启用了会话伪造防御， SessionManagementFilter会使用一个 匹配的DefaultSessionAuthenticationStrategy。 参考这个类的javadoc获得更多细节。

B.1.9. <concurrent-control>元素

添加对同步会话控制的支持，允许限制一个用户可以拥有的活动会话的数量。 会创建一个ConcurrentSessionFilter， 连同一个ConcurrentSessionControllerStrategy 和SessionManagementFilter的实例。 如果已经声明了form-login元素，策略对象也会注入到创建的 验证过滤器中。一个SessionRegistry的实例（ SessionRegistryImpl的实例，除非用户希望使用自定义bean） 会被创建，交给策略使用。

B.1.9.1. max-sessions属性

对应ConcurrentSessionControllerImpl的maximumSessions属性。

B.1.9.2. expired-url属性

如果一个用户尝试使用一个已经过期"expired"的会话，同步会话控制器会重定性到的URL。因为用户超过了允许的会话数量，但是又在其他地方登录了系统。 除非设置exception-if-maximum-exceeded，其他时候都应该设置这个属性。 如果没有设置值，一个过期信息会直接写到响应中。

B.1.9.3. error-if-maximum-exceeded属性

如果设置成"true"，一个SessionAuthenticationException会被抛出， 当一个用户尝试超过最大会话允许数量。 默认行为是让原始会话过期。

B.1.9.4. session-registry-alias和session-registry-ref属性

用户可以提供他们自己的SessionRegistry实现，使用session-registry-ref属性。 其他同步会话控制bean就可以使用它。

它也可以用来使用内部会话注册的引用，用在你自己的bean或一个管理接口里。 你可以使用session-registry-alias属性暴露内部bean，给它一个名字你可以在你的配置的任意地方都使用它。

B.1.10. <anonymous>元素

添加一个AnonymousAuthenticationFilter 和AnonymousAuthenticationProvider到堆栈里。 如果你使用IS_AUTHENTICATED_ANONYMOUSLY属性，就是必要的。

B.1.11. <x509>元素

添加X.509认证的支持。 一个X509AuthenticationFilter会被添加到堆栈中，会创建一个PreAuthenticatedProcessingFilterEntryPoint。 后一个只有的其他认证机制都没有使用的情况下才会用到（它唯一的功能是返回一个HTTP 403错误代号）。 一个PreAuthenticatedAuthenticationProvider也会被创建，并代理用户权限读取到一个UserDetailsService里。

B.1.11.1. subject-principal-regex属性

定义一个正则表达式，会从证书中取出用户名（与UserDetailsService一起使用）。

B.1.11.2. user-service-ref属性

允许一个特定的UserDetailsService，与X.509一起使用，当多个实例被配置的时候。 如果没有设置，会尝试自动定位一个合适的实例并使用它。

B.1.12. <openid-login>元素

与<form-login>类似，拥有相同的属性。 login-processing-url的默认值是"/j_spring_openid_security_check"。 一个OpenIDAuthenticationFilter 和OpenIDAuthenticationProvider会被注册上。 后者需要一个UserDetailsService的引用。 它也可以使用id指定，使用user-service-ref属性，或者在application context中自动定位。

B.1.13. <logout>元素

添加一个LogoutFilter到过滤器堆栈中。 它和SecurityContextLogoutHandler一起配置。

B.1.13.1. logout-url属性

这个URL会触发注销操作（比如，会被过滤器处理）。 默认是"/j_spring_security_logout"。

B.1.13.2. logout-success-url属性

用户在注销后转向的URL。 默认是"/"。

B.1.13.3. invalidate-session属性

对应SecurityContextLogoutHandler的invalidateHttpSession属性。 默认是"true"，这样注销的时候会销毁会话。

B.1.14. <custom-filter>元素

这个元素用来将一个过滤器添加到过滤器链中。它不会创建额外的bean， 但是它用来选择选择一个javax.servlet.Filter类型的bean， 这个bean已经定义在application context中，把它添加到Spring Security维护的过滤器链的特定位置。 全部信息可以在命名空间章节找到。

B.2. 认证服务

在Spring Security 3.0之前，一个AuthenticationManager会自动注册， 现在你必须使用<authentication-manager>元素注册一个bean。 这个bean是Spring Security的ProviderManager类的一个实例，它需要配置一个或多个AuthenticationProvider的实例。 这里可以使用命名空间支持的语法元素，也可以使用标准的bean定义，使用custom-authentication-provider元素来添加列表。

B.2.1. <authentication-manager>元素

每个Spring Security应用，只要使用了命名空间，就必须在什么地方包含对应的元素。 它负责注册AuthenticationManager，为应用各提供验证服务。 它也允许你定义一个别名，为内部实例，在你的配置中来使用。 这些都写在命名空间介绍中。 所有元素，创建了AuthenticationProvider实例， 应该是这个元素的子元素。

B.2.1.1. <authentication-provider>元素

这个元素基本是配置DaoAuthenticationProvider的简化形式。 DaoAuthenticationProvider读取用户信息，从 UserDetailsService中，比较用户名/密码，来进行用户登录。 UserDetailsService实例可以被定义，无论是命名空间中的 (jdbc-user-service 或使用 user-service-ref 属性来引用一个bean，定义在application context中)。 你可以在命名空间介绍中找到。。

B.2.1.2. 使用 <authentication-provider> 来引用一个 AuthenticationProvider Bean

如果你已经创建了自己的AuthenticationProvider 实现，（或希望配置Spring Security提供的一个实现，因为什么原因使用传统配置方式， 你可以使用下面的语法，来把它添加到内部ProviderManager 列表中：）

  <security:authentication-manager>
    <security:authentication-provider ref="myAuthenticationProvider" />
  </security:authentication-manager>
  <bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
  

B.3. 方法安全

B.3.1. <global-method-security>元素

这个元素是为Spring Security中的bean提供安全方法支持的最基本元素。 方法可以通过使用注解来保护（在接口或类级别进行定义）或者作为子元素的切点集合，使用AspectJ语法。

方法安全使用与web安全相同的AccessDecisionManager配置，但是可以使用Section B.1.1.6, “access-decision-manager-ref”中的解释进行覆盖，使用相同的属性。

B.3.1.1. secured-annotations和jsr250-annotations属性

把这些设置为"true"会分别启用对Spring Security自己的@Secured注解和JSR-250注解的支持， 默认情况下它们两个都是禁用的。 JSR-250注解的应用还需要向AccessDecisionManager添加一个Jsr250Voter，这样你需要确定你需要做这个，如果你使用一个自定义的实现，然后想要使用这些注解。

B.3.1.2. 安全方法使用<protect-pointcut>

除了在单独的方法或类的基础上使用@Secured定义安全属性，你可以定义交叉安全实体，覆盖你服务层中所有的方法和接口，使用<protect-pointcut>元素。 它有两个属性：

• expression - 切点表达式

• access - 提供的安全属性

你可以在命名空间介绍中找到一个例子。

B.3.1.3.  <after-invocation-provider> 元素

这个元素可以用来装饰一个 AfterInvocationProvider 来使用安全拦截器， 通过<global-method-security>命名空间。 你可以定义0，或者多个类，在global-method-security元素中， 每个都使用一个ref属性引用到一个 AfterInvocationProvider实例， 在你的application context中

B.3.2. LDAP命名空间选项

LDAP已经在它自己的章节中讨论过一些细节了。 我们将在这里进行一些扩展，解释命名空间中的选项如何对应Spring的bean。 LDAP实现使用Spring LDAP扩展，所以最好熟悉一下工程的API。

B.3.2.1. 使用<ldap-server>元素定义LDAP服务器

这个元素使用其他LDAP bean来建立一个Spring LDAP ContextSource，定义LDAP服务器的位置和其他信息（比如用户名和密码，如果它不允许匿名访问）来连接它。 它也可以用来创建一个测试用的嵌入式服务器。 所有选项的语法细节信息都在LDAP章节中。 实际上的ContextSource实现是DefaultSpringSecurityContextSource，它扩展了Spring LDAP的LdapContextSource类。 manager-dn和manager-password属性分别对应后者的userDn和password属性。

如果你只在你的application context中定义了一个服务器，其他LDAP命名空间定义的bean会自动使用它。 否则，你可以为这个元素定义一个"id"属性，然后在其他命名空间bean中使用server-ref属性引用它。 这其实是ContextSource实例的bean的id，如你你想要在其他传统Spring bean中使用它。

B.3.2.2. <ldap-provider>元素

这个元素是为了创建LdapAuthenticationProvider实例的简写。 默认情况下它会和BindAuthenticator实例和一个DefaultAuthoritiesPopulator一起配置。

B.3.2.2.1. user-dn-pattern属性

如果你的用户在目录中的一个固定的位置（比如，你可以不需要进行目录查询，就从用户名直接找到一个DN），你可以使用这个属性来直接映射DN。 它直接对应AbstractLdapAuthenticator的userDnPatterns属性。

B.3.2.2.2. user-search-base和user-search-filter属性

如果你需要执行查询，来定义目录中的用户，然后你可以设置这些属性来控制查询。 BindAuthenticator会被配置在FilterBasedLdapUserSearch中，属性值直接对应bean构造方法的前两个参数。 如果这些属性没有设置，也没有提供可选的user-dn-pattern，就会使用默认的查询值user-search-filter="(uid={0})"和user-search-base=""。

B.3.2.2.3. group-search-filter，group-search-base, group-role-attribute和role-prefix属性

group-search-base的值对应DefaultAuthoritiesPopulator的构造方法参数groupSearchBase，默认是"ou=groups"。 默认过滤器值是"(uniqueMember={0})"，这假设入口是"groupOfUniqueNames"类型。 group-role-attribute对应groupRoleAttribute属性，默认是"cn"。 role-prefix对应于rolePrefix，默认为"ROLE_"。

B.3.2.2.4. <password-compare>元素

它是作为<ldap-provider>的子元素，切换认证策略从BindAuthenticator到PasswordComparisonAuthenticator。 这可以选择性提供hash属性或者使用<password-encoder>子元素来对密码进行编码，在提交到目录进行比较之前。

B.3.2.3. <ldap-user-service>元素

这个元素配置一个LDAP UserDetailsService。 这个类使用LdapUserDetailsService，这是FilterBasedLdapUserSearch和DefaultAuthoritiesPopulator的结合。 它支持的属性与<ldap-provider>的用法相同。

---

^[14] 查看介绍章节来了解如何从你的web.xml文件中建立映射

^[15] 这个特性真是只为了提供便利，没有支持生产环境的意图（应该选择一个视图技术，可以用来渲染一个自定义登录页面）。这个类DefaultLoginPageGeneratingFilter负责生成登录页面，会提供登录表单为正常表单登录和/或OpenID如果需要的话。

^[16] 这不会对PersistentTokenBasedRememberMeServices的使用产生影响，这个标记是保存在服务器一端的

---

Prev	Home
Appendix A. 安全数据库表结构	Sponsored by SpringSource