2016-06-03 07:05:27 +00:00
[[_spring_boot_adapter]]
2016-06-09 13:12:10 +00:00
==== Spring Boot Adapter
2016-04-18 19:10:32 +00:00
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
2017-01-20 08:38:00 +00:00
You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`). Let's go over these steps.
2016-04-18 19:10:32 +00:00
[[_spring_boot_adapter_installation]]
2016-06-09 13:12:10 +00:00
===== Adapter Installation
2016-04-18 19:10:32 +00:00
2017-05-22 08:54:16 +00:00
The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add the Keycloak Spring Boot starter to your project.
They Keycloak Spring Boot Starter is also directly available from the http://start.spring.io/[Spring Start Page].
To add it manually and if you are using Maven, add the following to your dependencies :
2016-04-18 19:10:32 +00:00
2016-08-27 21:10:39 +00:00
[source,xml,subs="attributes+"]
2016-04-18 19:10:32 +00:00
----
<dependency>
<groupId>org.keycloak</groupId>
2017-05-22 08:54:16 +00:00
<artifactId>keycloak-spring-boot-starter</artifactId>
2016-04-18 19:10:32 +00:00
</dependency>
2017-05-22 08:54:16 +00:00
2017-01-20 08:38:00 +00:00
----
2017-11-16 03:51:42 +00:00
Make also sure to add the Adapter POM dependency :
2017-05-22 08:54:16 +00:00
[source,xml,subs="attributes+"]
----
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.keycloak.bom</groupId>
<artifactId>keycloak-adapter-bom</artifactId>
2017-08-28 12:50:14 +00:00
<version>{project_versionMvn}</version>
2017-05-22 08:54:16 +00:00
<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:
2017-01-20 08:38:00 +00:00
* Tomcat
* Undertow
* Jetty
2016-04-18 19:10:32 +00:00
[[_spring_boot_adapter_configuration]]
2016-06-09 13:12:10 +00:00
===== Required Spring Boot Adapter Configuration
2016-04-18 19:10:32 +00:00
2017-01-20 08:38:00 +00:00
This section describes how to configure your Spring Boot app to use Keycloak.
2016-04-18 19:10:32 +00:00
Instead of a `keycloak.json` file, you configure the realm for the Spring Boot Keycloak adapter via the normal Spring Boot configuration.
2017-01-20 08:38:00 +00:00
For example:
2016-04-18 19:10:32 +00:00
[source]
----
keycloak.realm = demorealm
keycloak.auth-server-url = http://127.0.0.1:8080/auth
keycloak.ssl-required = external
keycloak.resource = demoapp
keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111
keycloak.use-resource-role-mappings = true
----
2017-04-28 09:05:24 +00:00
You can disable the Keycloak Spring Boot Adapter (for example in tests) by setting `keycloak.enabled = false`.
2017-01-20 08:38:00 +00:00
To configure a Policy Enforcer, unlike keycloak.json, `policy-enforcer-config` must be used instead of just `policy-enforcer`.
You also need to specify the Java 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:
2016-04-18 19:10:32 +00:00
[source]
----
2017-04-21 14:29:41 +00:00
keycloak.securityConstraints[0].authRoles[0] = admin
keycloak.securityConstraints[0].authRoles[1] = user
2016-04-18 19:10:32 +00:00
keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff
keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure
2017-04-21 14:29:41 +00:00
keycloak.securityConstraints[1].authRoles[0] = admin
keycloak.securityConstraints[1].securityCollections[0].name = admin stuff
keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin
2017-01-12 16:49:24 +00:00
----
2017-11-29 09:31:25 +00:00
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.
