【翻译】Thymeleaf – Spring Security集成模块

原文链接：Thymeleaf - Spring Security integration modules

来源：thymeleaf/thymeleaf-extras-springsecurity自述文件

状态

这是一个Thymeleaf附加模块，不是Thymeleaf核心的一部分（因此它有自己的版本号），但是Thymeleaf团队提供全部支持。

这个仓库包含3个项目：

• thymeleaf-extras-springsecurity5是与Spring Security 5.x相匹配的集成模块
• thymeleaf-extras-springsecurity6是与Spring Security 6.x相匹配的集成模块

当前版本：

• 3.0.4.RELEASE适用于Thymeleaf 3.0（要求Thymeleaf版本高于或等于3.0.10）
• 2.1.3.RELEASE适用于Thymeleaf 2.1（要求Thymeleaf版本高于或等于2.1.2）

许可

本软件按照Apache License 2.0提供许可。

要求（3.0.x）

• Thymeleaf版本高于或等于3.0.10
• Spring框架版本在3.0.x至5.1.x之间
• Spring Security版本在3.0.x至5.1.x之间
• 联网环境（Spring Security集成不能离线工作）。还需要Spring MVC和Spring WebFlux才能工作。

Maven信息

• groupId: org.thymeleaf.extras
• artifactId:
  • Spring Security 5集成包：thymeleaf-extras-springsecurity5
  • Spring Security 6集成包：thymeleaf-extras-springsecurity6

分发包

分发包（二进制文件、源代码和文档）可以在bintray下载。

特性

模块提供名为org.thymeleaf.extras.springsecurity5.dialect.SpringSecurityDialect或org.thymeleaf.extras.springsecurity6.dialect.SpringSecurityDialect的新方言（具体是哪个方言取决于Spring Security版本），方言默认前缀是sec。这些方言包括：

• 新的表达式工具对象：
  • #authentication表示Spring Security认证对象（一个实现了org.springframework.security.core.Authentication接口的对象）
  • #authorization：一个表达式工具对象，可以根据表达式、url和访问控制列表检查授权。
• 新属性：
  • sec:authentication="prop"输出authentication对象的prop属性值，这与JSP标签<sec:authentication />类似。
  • sec:authorize="expr"或sec:authorize-expr="expr"根据用户能否通过expr表达式的授权验证，决定是否渲染该属性所在标签。（sec:authorize="expr" or sec:authorize-expr="expr" renders the element children (tag content) if the authenticated user is authorized to see it according to the specified Spring Security expression.）（译注：上句翻译不贴合本意，是译者根据自己的使用体验写的，下面两句翻译可能也不贴合本意）
  • sec:authorize-url="url"根据用户能否访问特定URL决定是否渲染该属性所在标签。
  • sec:authorize-acl="object :: permissions"根据Spring Source的访问控制列表系统和用户对特定领域对象是否有指定权限来决定是否渲染属性所在标签。

配置

为了在Spring MVC应用中使用thymeleaf-extras-springsecurity[5][6]模块（或者在Spring WebFlux应用中使用thymeleaf-extras-springsecurity6），对于使用Spring和Thymeleaf的应用首先需要使用通常的方式配置应用（TemplateEngine bean、模板解析器等等），然后将Spring Security方言添加到模板引擎中，这样就可以使用sec:*属性和专用表达式工具对象：

<bean id="templateEngine" class="org.thymeleaf.spring5.SpringTemplateEngine">
  ...
  <property name="additionalDialects">
    <set>
      <!-- Note the package would change to 'springsecurity[5]' if you are using that version -->
      <bean class="org.thymeleaf.extras.springsecurity6.dialect.SpringSecurityDialect"/>
    </set>
  </property>
...
</bean>

以上就是全部内容了！

注意：如果是在Spring Boot应用中使用Thymeleaf，只需要把相应的Thymeleaf和Spring Security的starter以及thymeleaf-extras-springsecurity[5|6]依赖添加到应用中，方言就自动配置好了。

使用表达式工具对象

#authentication对象使用起来很简单，就像下面这样：

<div th:text="${#authentication.name}">
  The value of the "name" property of the authentication object should appear here.
</div>

#authorization也可以以同样的方式使用，通常用在th:if或th:unless标签中：

<div th:if="${#authorization.expression('hasRole(''ROLE_ADMIN'')')}">
  This will only be displayed if authenticated user has role ROLE_ADMIN.
</div>

#authorization对象是org.thymeleaf.extras.springsecurity[5|6].auth.Authorization类的实例，参阅该类与它的文档来理解它的方法。

使用属性

使用sec:authentication属性基本等同于使用#authentication对象，但是仅能使用该对象的属性：

<div sec:authentication="name">
  The value of the "name" property of the authentication object should appear here.
</div>

sec:authorize和sec:authorize-expr属性完全相同。它们和在th:if中使用#authorization.expression(...)效果相同：

<div sec:authorize="hasRole('ROLE_ADMIN')">
  This will only be displayed if authenticated user has role ROLE_ADMIN.
</div>

这些sec:authorize属性中的Spring安全表达式实际上是在springsecurity特定的根对象上计算的Spring EL表达式，根对象包含hasRole(…)、getPrincipal()等方法。（These Spring Security Expressions in sec:authorize attributes are in fact Spring EL expressions evaluated on a SpringSecurity-specific root object containing methods such as hasRole(...), getPrincipal(), etc.）

与普通的Spring EL表达式一样，可以在Thymeleaf中访问一系列对象，这些对象包括上下文变量映射（#vars对象）。事实上，可以用${…}包围访问表达式，如果你觉得这样让你更舒服（译注：意思是不用${…}包围表达式也可以）：

<div sec:authorize="${hasRole(#vars.expectedRole)}">
  This will only be displayed if authenticated user has a role computed by the controller.
</div>

记住，Spring Security将一个特殊的安全导向的对象设置为表达式根，这就是不能在上述表达式中直接访问expctedRole变量的原因。

另一种检查授权的方式是sec:authorize-url，可以用这个属性检查用户能否访问特定URL：

<div sec:authorize-url="/admin">
  This will only be displayed if authenticated user can call the "/admin" URL.
</div>

对于指定特定的HTTP方法，可以这样做：

<div sec:authorize-url="POST /admin">
  This will only be displayed if authenticated user can call the "/admin" URL
  using the POST HTTP method.
</div>

最后，有一个使用Spring Security的访问控制列表检查授权的属性，它需要一个域对象的规范和我们要求的在它上定义的权限。

<div sec:authorize-acl="${obj} :: '1,3'">
  This will only be displayed if authenticated user has permissions "1" and "3"
  on domain object referenced by context variable "obj".
</div>

在上面的属性中，域对象和权限规范都是thymeleaf标准表达式。

命名空间

所有版本方言都可用的命名空间是http://www.thymeleaf.org/extras/spring-security。

<html xmlns:sec="http://www.thymeleaf.org/extras/spring-security">

错误的命名空间不会影响模板处理，它可能会影响在IDE中编辑模板时的建议和自动补全。