thymeleaf / Thymeleaf Extras Springsecurity
Programming Languages
Thymeleaf - Spring Security integration modules
[Please make sure to select the branch corresponding to the version of Thymeleaf you are using]
Status
This is a Thymeleaf Extras module, not a part of the Thymeleaf core (and as such following its own versioning schema), but fully supported by the Thymeleaf team.
This repository contains 3 projects:
- thymeleaf-extras-springsecurity3 for integration with Spring Security 3.x
- thymeleaf-extras-springsecurity4 for integration with Spring Security 4.x
- thymeleaf-extras-springsecurity5 for integration with Spring Security 5.x
Current versions:
- Version 3.0.4.RELEASE - for Thymeleaf 3.0 (requires Thymeleaf 3.0.10+)
- Version 2.1.3.RELEASE - for Thymeleaf 2.1 (requires Thymeleaf 2.1.2+)
License
This software is licensed under the Apache License 2.0.
Requirements (3.0.x)
- Thymeleaf 3.0.10+
- Spring Framework version 3.0.x to 5.1.x
- Spring Security version 3.0.x to 5.1.x
- Web environment (Spring Security integration cannot work offline). Works with both Spring MVC and Spring WebFlux.
Maven info
- groupId:
org.thymeleaf.extras
- artifactId:
- Spring Security 3 integration package:
thymeleaf-extras-springsecurity3
- Spring Security 4 integration package:
thymeleaf-extras-springsecurity4
- Spring Security 5 integration package:
thymeleaf-extras-springsecurity5
- Spring Security 3 integration package:
Distribution packages
Distribution packages (binaries + sources + javadoc) can be downloaded from bintray.
Features
This module provides a new dialect called org.thymeleaf.extras.springsecurity3.dialect.SpringSecurityDialect
,
org.thymeleaf.extras.springsecurity4.dialect.SpringSecurityDialect
or
org.thymeleaf.extras.springsecurity5.dialect.SpringSecurityDialect
(depending
on the Spring Security version), with default prefix sec
. It includes:
- New expression utility objects:
-
#authentication
representing the Spring Security authentication object (an object implementing theorg.springframework.security.core.Authentication
interface). -
#authorization
: a expression utility object with methods for checking authorization based on expressions, URLs and Access Control Lists.
-
- New attributes:
-
sec:authentication="prop"
outputs aprop
property of the authentication object, similar to the Spring Security<sec:authentication/>
JSP tag. -
sec:authorize="expr"
orsec: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"
renders the element children (tag content) if the authenticated user is authorized to see the specified URL. -
sec:authorize-acl="object :: permissions"
renders the element children (tag content) if the authenticated user has the specified permissions on the specified domain object, according to Spring Source's Access Control List system.
-
Configuration
In order to use the thymeleaf-extras-springsecurity[3|4|5] modules in our Spring
MVC application (or thymeleaf-extras-springsecurity5 in a Spring WebFlux
application), we will first need to configure our application in the usual way
for Spring + Thymeleaf applications (TemplateEngine bean, template resolvers,
etc.), and add the SpringSecurity dialect to our Template Engine so that we can
use the sec:*
attributes and special expression utility objects:
<bean id="templateEngine" class="org.thymeleaf.spring5.SpringTemplateEngine">
...
<property name="additionalDialects">
<set>
<!-- Note the package would change to 'springsecurity[3|4]' if you are using that version -->
<bean class="org.thymeleaf.extras.springsecurity5.dialect.SpringSecurityDialect"/>
</set>
</property>
...
</bean>
And that's all!
NOTE: If we are using Thymeleaf in a Spring Boot application, all that will
be needed is to add the corresponding Thymeleaf and Spring Security starters to
our application as well as the thymeleaf-extras-springsecurity[3|4|5]
dependency, and this dialect will be automatically configured for us.
Using the expression utility objects
The #authentication
object can be easily used, like this:
<div th:text="${#authentication.name}">
The value of the "name" property of the authentication object should appear here.
</div>
The #authorization
object can be used in a similar way, normally in th:if
or th:unless
tags:
<div th:if="${#authorization.expression('hasRole(''ROLE_ADMIN'')')}">
This will only be displayed if authenticated user has role ROLE_ADMIN.
</div>
The #authorization
object is an instance of org.thymeleaf.extras.springsecurity[3|4].auth.Authorization
,
see this class and its documentation to understand all the methods offered.
Using the attributes
Using the sec:authentication
attribute is equivalent to using the #authentication
object, but using its own attribute:
<div sec:authentication="name">
The value of the "name" property of the authentication object should appear here.
</div>
The sec:authorize
and sec:authorize-expr
attributes are exactly the same.
They work equivalently to a th:if
that evaluated an #authorization.expression(...)
expression, by evaluating a Spring Security Expression:
<div sec:authorize="hasRole('ROLE_ADMIN')">
This will only be displayed if authenticated user has role ROLE_ADMIN.
</div>
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.
As with normal Spring EL expressions, Thymeleaf allows you to access a series of
objects from them including the context variables map (the #vars
object). In
fact, you are allowed to surround your access expression with ${...}
if it
makes you feel more comfortable:
<div sec:authorize="${hasRole(#vars.expectedRole)}">
This will only be displayed if authenticated user has a role computed by the controller.
</div>
Remember that Spring Security sets a special security-oriented object as
expression root, which is why you would not be able to access the expectedRole
variable directly in the above expression.
Another way of checking authorization is sec:authorize-url
, which allows you
to check whether a user is authorized to visit a specific URL or not:
<div sec:authorize-url="/admin">
This will only be displayed if authenticated user can call the "/admin" URL.
</div>
For specifying a specific HTTP method, do:
<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>
Finally, there is an attribute for checking authorization using Spring Security's Access Control Lists, which needs the specification of a domain object and the permissions defined on it that we are asking for.
<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>
In this attribute, both domain object and permission specifications are considered to be thymeleaf Standard Expressions.
Namespace
The namespace for all versions of this dialect is http://www.thymeleaf.org/extras/spring-security
.
<html xmlns:sec="http://www.thymeleaf.org/extras/spring-security">
Getting the namespace incorrect won't impact processing of your template. It might however impact your IDE when it comes to things like suggestions/auto-completion in your templates.