https://github.com/thymeleaf/thymeleaf-extras-springsecurity
Thymeleaf "extras" integration module for Spring Security 3.x and 4.x
https://github.com/thymeleaf/thymeleaf-extras-springsecurity
Last synced: 10 months ago
JSON representation
Thymeleaf "extras" integration module for Spring Security 3.x and 4.x
- Host: GitHub
- URL: https://github.com/thymeleaf/thymeleaf-extras-springsecurity
- Owner: thymeleaf
- License: apache-2.0
- Created: 2012-08-06T16:48:02.000Z (over 13 years ago)
- Default Branch: 3.1-master
- Last Pushed: 2022-12-08T18:30:14.000Z (about 3 years ago)
- Last Synced: 2025-04-03T05:09:30.341Z (11 months ago)
- Language: Java
- Homepage: http://www.thymeleaf.org
- Size: 422 KB
- Stars: 487
- Watchers: 41
- Forks: 105
- Open Issues: 23
-
Metadata Files:
- Readme: README.markdown
- Contributing: CONTRIBUTING.markdown
- License: LICENSE.txt
Awesome Lists containing this project
README
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-springsecurity5** for integration with Spring Security 5.x
* **thymeleaf-extras-springsecurity6** for integration with Spring Security 6.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](http://www.apache.org/licenses/LICENSE-2.0.html).
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 5 integration package: `thymeleaf-extras-springsecurity5`
* Spring Security 6 integration package: `thymeleaf-extras-springsecurity6`
Distribution packages
---------------------
Distribution packages (binaries + sources + javadoc) can be downloaded from
[bintray](https://dl.bintray.com/thymeleaf/downloads).
Features
--------
This module provides a new dialect called `org.thymeleaf.extras.springsecurity5.dialect.SpringSecurityDialect` or
`org.thymeleaf.extras.springsecurity6.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 the `org.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 a `prop` property of the
authentication object, similar to the Spring Security ``
JSP tag.
* `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"` 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[5|6] modules in our Spring
MVC application (or thymeleaf-extras-springsecurity6 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:
```xml
...
...
```
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[5|6]`
dependency, and this dialect will be automatically configured for us.
Using the expression utility objects
------------------------------------
The `#authentication` object can be easily used, like this:
```html
The value of the "name" property of the authentication object should appear here.
```
The `#authorization` object can be used in a similar way, normally in `th:if`
or `th:unless` tags:
```html
This will only be displayed if authenticated user has role ROLE_ADMIN.
```
The `#authorization` object is an instance of `org.thymeleaf.extras.springsecurity[5|6].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:
```html
The value of the "name" property of the authentication object should appear here.
```
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*:
```html
This will only be displayed if authenticated user has role ROLE_ADMIN.
```
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:
```html
This will only be displayed if authenticated user has a role computed by the controller.
```
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:
```html
This will only be displayed if authenticated user can call the "/admin" URL.
```
For specifying a specific HTTP method, do:
```html
This will only be displayed if authenticated user can call the "/admin" URL
using the POST HTTP method.
```
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.
```html
This will only be displayed if authenticated user has permissions "1" and "3"
on domain object referenced by context variable "obj".
```
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
```
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.