702495fe22
Closes #21176 Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> Co-authored-by: Stian Thorgersen <stianst@gmail.com>
99 lines
3.5 KiB
Text
99 lines
3.5 KiB
Text
[[_spring_boot_adapter]]
|
|
==== Spring Boot adapter
|
|
|
|
[WARNING]
|
|
====
|
|
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features
|
|
will be added to this adapter.
|
|
|
|
We recommend that you leverage the OAuth2/OpenID Connect support from Spring Security.
|
|
|
|
For more details about how to integrate {project_name} with Spring Boot applications, consider looking at the
|
|
{quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
|
|
====
|
|
|
|
|
|
[[_spring_boot_adapter_installation]]
|
|
===== Installing the Spring Boot adapter
|
|
|
|
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
|
|
You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`).
|
|
|
|
The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add this adapter Keycloak Spring Boot starter to your project.
|
|
|
|
.Procedure
|
|
|
|
. To add the starter to your project using Maven, add the following to your dependencies:
|
|
+
|
|
[source,xml,subs="attributes+"]
|
|
----
|
|
<dependency>
|
|
<groupId>org.keycloak</groupId>
|
|
<artifactId>keycloak-spring-boot-starter</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
. Add the Adapter BOM dependency:
|
|
+
|
|
[source,xml,subs="attributes+"]
|
|
----
|
|
<dependencyManagement>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.keycloak.bom</groupId>
|
|
<artifactId>keycloak-adapter-bom</artifactId>
|
|
<version>{project_versionMvn}</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
----
|
|
|
|
|
|
Currently the following embedded containers are supported and do not require any extra dependencies if using the Starter:
|
|
|
|
* Tomcat
|
|
* Undertow
|
|
* Jetty
|
|
|
|
[[_spring_boot_adapter_configuration]]
|
|
===== Configuring the Spring Boot Adapter
|
|
|
|
Use the procedure to configure your Spring Boot app to use {project_name}.
|
|
|
|
.Procedure
|
|
|
|
. Instead of a `keycloak.json` file, you configure the realm for the Spring Boot adapter via the normal Spring Boot configuration. For example:
|
|
+
|
|
[source,subs="attributes+"]
|
|
----
|
|
keycloak.realm = demorealm
|
|
keycloak.auth-server-url = http://127.0.0.1:8080{kc_base_path}
|
|
keycloak.ssl-required = external
|
|
keycloak.resource = demoapp
|
|
keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111
|
|
keycloak.use-resource-role-mappings = true
|
|
----
|
|
+
|
|
You can disable the Keycloak Spring Boot Adapter (for example in tests) by setting `keycloak.enabled = false`.
|
|
|
|
. To configure a Policy Enforcer, unlike keycloak.json, use `policy-enforcer-config` instead of just `policy-enforcer`.
|
|
|
|
. Specify the Jakarta EE security config that would normally go in the `web.xml`.
|
|
+
|
|
The Spring Boot Adapter will set the `login-method` to `KEYCLOAK` and configure the `security-constraints` at startup time. Here's an example configuration:
|
|
+
|
|
[source]
|
|
----
|
|
keycloak.securityConstraints[0].authRoles[0] = admin
|
|
keycloak.securityConstraints[0].authRoles[1] = user
|
|
keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff
|
|
keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure
|
|
|
|
keycloak.securityConstraints[1].authRoles[0] = admin
|
|
keycloak.securityConstraints[1].securityCollections[0].name = admin stuff
|
|
keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin
|
|
----
|
|
|
|
WARNING: If you plan to deploy your Spring Application as a WAR then you should not use the Spring Boot Adapter and use the dedicated adapter for the application server or servlet container you are using. Your Spring Boot should also contain a `web.xml` file.
|