{"id":23762391,"url":"https://github.com/thymeleaf/thymeleaf-extras-springsecurity","last_synced_at":"2025-05-15T19:01:44.510Z","repository":{"id":4197609,"uuid":"5316748","full_name":"thymeleaf/thymeleaf-extras-springsecurity","owner":"thymeleaf","description":"Thymeleaf \"extras\" integration module for Spring Security 3.x and 4.x","archived":false,"fork":false,"pushed_at":"2022-12-08T18:30:14.000Z","size":432,"stargazers_count":487,"open_issues_count":23,"forks_count":105,"subscribers_count":41,"default_branch":"3.1-master","last_synced_at":"2025-04-03T05:09:30.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.thymeleaf.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thymeleaf.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":"CONTRIBUTING.markdown","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-06T16:48:02.000Z","updated_at":"2025-03-30T18:37:08.000Z","dependencies_parsed_at":"2023-01-13T13:00:00.969Z","dependency_job_id":null,"html_url":"https://github.com/thymeleaf/thymeleaf-extras-springsecurity","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-springsecurity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-springsecurity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-springsecurity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-springsecurity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thymeleaf","download_url":"https://codeload.github.com/thymeleaf/thymeleaf-extras-springsecurity/tar.gz/refs/heads/3.1-master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248489286,"owners_count":21112542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-31T21:19:06.643Z","updated_at":"2025-04-11T22:29:40.756Z","avatar_url":"https://github.com/thymeleaf.png","language":"Java","readme":"\nThymeleaf - Spring Security integration modules\n===============================================\n\n\n**[Please make sure to select the branch corresponding to the version of Thymeleaf you are using]**\n\n\nStatus\n------\n\nThis is a *Thymeleaf Extras* module, not a part of the Thymeleaf core (and as\nsuch following its own versioning schema), but fully supported by the Thymeleaf\nteam.\n\nThis repository contains 3 projects:\n\n * **thymeleaf-extras-springsecurity5** for integration with Spring Security 5.x\n * **thymeleaf-extras-springsecurity6** for integration with Spring Security 6.x\n\nCurrent versions: \n\n * **Version 3.0.4.RELEASE** - for Thymeleaf 3.0 (requires Thymeleaf 3.0.10+)\n * **Version 2.1.3.RELEASE** - for Thymeleaf 2.1 (requires Thymeleaf 2.1.2+)\n\n\nLicense\n-------\n\nThis software is licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).\n\n\nRequirements (3.0.x)\n--------------------\n\n * Thymeleaf **3.0.10+**\n * Spring Framework version **3.0.x** to **5.1.x**\n * Spring Security version **3.0.x** to **5.1.x**\n * Web environment (Spring Security integration cannot work offline). Works with\n   both Spring MVC and Spring WebFlux.\n\n\nMaven info\n----------\n\n * groupId: `org.thymeleaf.extras`   \n * artifactId: \n    * Spring Security 5 integration package: `thymeleaf-extras-springsecurity5`\n    * Spring Security 6 integration package: `thymeleaf-extras-springsecurity6`\n\n\nDistribution packages\n---------------------\n\nDistribution packages (binaries + sources + javadoc) can be downloaded from\n[bintray](https://dl.bintray.com/thymeleaf/downloads).\n\n\nFeatures\n--------\n\nThis module provides a new dialect called `org.thymeleaf.extras.springsecurity5.dialect.SpringSecurityDialect` or \n`org.thymeleaf.extras.springsecurity6.dialect.SpringSecurityDialect` (depending\non the Spring Security version), with default prefix `sec`. It includes:\n  \n * New expression utility objects:\n    * `#authentication` representing the Spring Security authentication object\n      (an object implementing the `org.springframework.security.core.Authentication`\n      interface).\n    * `#authorization`: a expression utility object with methods for checking\n       authorization based on expressions, URLs and Access Control Lists.\n * New attributes:\n    * `sec:authentication=\"prop\"` outputs a `prop` property of the\n      authentication object, similar to the Spring Security `\u003csec:authentication/\u003e`\n      JSP tag.\n    * `sec:authorize=\"expr\"` or `sec:authorize-expr=\"expr\"` renders the element\n      children (*tag content*) if the authenticated user is authorized to see it\n      according to the specified *Spring Security expression*.\n    * `sec:authorize-url=\"url\"` renders the element children (*tag content*) if\n      the authenticated user is authorized to see the specified URL.\n    * `sec:authorize-acl=\"object :: permissions\"` renders the element children\n      (*tag content*) if the authenticated user has the specified permissions on\n      the specified domain object, according to Spring Source's Access Control\n      List system.\n\n\nConfiguration\n-------------\n\nIn order to use the thymeleaf-extras-springsecurity[5|6] modules in our Spring\nMVC application (or thymeleaf-extras-springsecurity6 in a Spring WebFlux\napplication), we will first need to configure our application in the usual way\nfor Spring + Thymeleaf applications (*TemplateEngine* bean, *template resolvers*, \netc.), and add the SpringSecurity dialect to our Template Engine so that we can\nuse the `sec:*` attributes and special expression utility objects:\n\n```xml\n\u003cbean id=\"templateEngine\" class=\"org.thymeleaf.spring5.SpringTemplateEngine\"\u003e\n  ...\n  \u003cproperty name=\"additionalDialects\"\u003e\n    \u003cset\u003e\n      \u003c!-- Note the package would change to 'springsecurity[5]' if you are using that version --\u003e\n      \u003cbean class=\"org.thymeleaf.extras.springsecurity6.dialect.SpringSecurityDialect\"/\u003e\n    \u003c/set\u003e\n  \u003c/property\u003e\n...\n\u003c/bean\u003e\n```\n\nAnd that's all!\n\n**NOTE**: If we are using Thymeleaf in a Spring Boot application, all that will\nbe needed is to add the corresponding Thymeleaf and Spring Security starters to\nour application as well as the `thymeleaf-extras-springsecurity[5|6]`\ndependency, and this dialect will be automatically configured for us.\n\n\nUsing the expression utility objects\n------------------------------------\n\nThe `#authentication` object can be easily used, like this:\n\n```html\n\u003cdiv th:text=\"${#authentication.name}\"\u003e\n  The value of the \"name\" property of the authentication object should appear here.\n\u003c/div\u003e\n```\n\nThe `#authorization` object can be used in a similar way, normally in `th:if`\nor `th:unless` tags:\n\n```html\n\u003cdiv th:if=\"${#authorization.expression('hasRole(''ROLE_ADMIN'')')}\"\u003e\n  This will only be displayed if authenticated user has role ROLE_ADMIN.\n\u003c/div\u003e\n```\n\nThe `#authorization` object is an instance of `org.thymeleaf.extras.springsecurity[5|6].auth.Authorization`,\nsee this class and its documentation to understand all the methods offered.\n\n\nUsing the attributes\n--------------------\n\nUsing the `sec:authentication` attribute is equivalent to using the `#authentication`\nobject, but using its own attribute:\n\n```html\n\u003cdiv sec:authentication=\"name\"\u003e\n  The value of the \"name\" property of the authentication object should appear here.\n\u003c/div\u003e\n```\n\nThe `sec:authorize` and `sec:authorize-expr` attributes are exactly the same.\nThey work equivalently to a `th:if` that evaluated an `#authorization.expression(...)`\nexpression, by evaluating a *Spring Security Expression*:\n\n```html\n\u003cdiv sec:authorize=\"hasRole('ROLE_ADMIN')\"\u003e\n  This will only be displayed if authenticated user has role ROLE_ADMIN.\n\u003c/div\u003e\n```\n\nThese *Spring Security Expressions* in `sec:authorize` attributes are in fact\nSpring EL expressions evaluated on a SpringSecurity-specific root object\ncontaining methods such as `hasRole(...)`, `getPrincipal()`, etc.\n\nAs with normal Spring EL expressions, Thymeleaf allows you to access a series of\nobjects from them including the context variables map (the `#vars` object). In\nfact, you are allowed to surround your access expression with `${...}` if it\nmakes you feel more comfortable:\n\n```html\n\u003cdiv sec:authorize=\"${hasRole(#vars.expectedRole)}\"\u003e\n  This will only be displayed if authenticated user has a role computed by the controller.\n\u003c/div\u003e\n```\n\nRemember that Spring Security sets a special security-oriented object as\nexpression root, which is why you would not be able to access the `expectedRole`\nvariable directly in the above expression. \n\nAnother way of checking authorization is `sec:authorize-url`, which allows you\nto check whether a user is authorized to visit a specific URL or not:\n\n```html\n\u003cdiv sec:authorize-url=\"/admin\"\u003e\n  This will only be displayed if authenticated user can call the \"/admin\" URL.\n\u003c/div\u003e\n```\n\nFor specifying a specific HTTP method, do:\n\n```html\n\u003cdiv sec:authorize-url=\"POST /admin\"\u003e\n  This will only be displayed if authenticated user can call the \"/admin\" URL\n  using the POST HTTP method.\n\u003c/div\u003e\n```\n\nFinally, there is an attribute for checking authorization using Spring Security's\n*Access Control Lists*, which needs the specification of a domain object and the\n*permissions* defined on it that we are asking for.\n\n```html\n\u003cdiv sec:authorize-acl=\"${obj} :: '1,3'\"\u003e\n  This will only be displayed if authenticated user has permissions \"1\" and \"3\"\n  on domain object referenced by context variable \"obj\".\n\u003c/div\u003e\n```\n\nIn this attribute, both domain object and permission specifications are considered\nto be thymeleaf *Standard Expressions*.\n\n\n### Namespace\n\nThe namespace for all versions of this dialect is `http://www.thymeleaf.org/extras/spring-security`.\n\n```html\n\u003chtml xmlns:sec=\"http://www.thymeleaf.org/extras/spring-security\"\u003e\n```\n\nGetting the namespace incorrect won't impact processing of your template. It\nmight however impact your IDE when it comes to things like suggestions/auto-completion\nin your templates.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-springsecurity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-springsecurity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-springsecurity/lists"}