keycloak-scim/securing_apps/topics/oidc/java/spring-boot-adapter.adoc

[[_spring_boot_adapter]]
==== 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`).  Let's go over these steps.

[[_spring_boot_adapter_installation]]
===== Adapter Installation

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 https://start.spring.io/[Spring Start Page].
To add it manually 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]]
===== Required Spring Boot Adapter Configuration

This section describes how to configure your Spring Boot app to use Keycloak.

Instead of a `keycloak.json` file, you configure the realm for the Spring Boot Keycloak adapter via the normal Spring Boot configuration.
For example:

[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
----

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, `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:

[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.
Revert "fixed Wildfly mentions and faulty links with underscores" This reverts commit 1ecbc1ba14075203af437295927699adf84cc428. 2019-01-21 17:01:40 +00:00			`[[_spring_boot_adapter]]`
Fix headers in oidc chapter 2016-06-09 13:12:10 +00:00			`==== Spring Boot Adapter`
initial import 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.`
update spring's documentation 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.
initial import 2016-04-18 19:10:32 +00:00
Revert "fixed Wildfly mentions and faulty links with underscores" This reverts commit 1ecbc1ba14075203af437295927699adf84cc428. 2019-01-21 17:01:40 +00:00			`[[_spring_boot_adapter_installation]]`
Fix headers in oidc chapter 2016-06-09 13:12:10 +00:00			`===== Adapter Installation`
initial import 2016-04-18 19:10:32 +00:00
reflect usage of the starter 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.`
Fix missing variables test 2018-07-30 07:44:27 +00:00			`They Keycloak Spring Boot Starter is also directly available from the https://start.spring.io/[Spring Start Page].`
Cleaned up a couple sentences and removed extraneous spaces 2018-01-10 12:29:25 +00:00			`To add it manually using Maven, add the following to your dependencies:`
initial import 2016-04-18 19:10:32 +00:00

Project version for Maven dependency snippets 2016-08-27 21:10:39 +00:00			`[source,xml,subs="attributes+"]`
initial import 2016-04-18 19:10:32 +00:00			`----`


			`<dependency>`
			`<groupId>org.keycloak</groupId>`
reflect usage of the starter 2017-05-22 08:54:16 +00:00			`<artifactId>keycloak-spring-boot-starter</artifactId>`
initial import 2016-04-18 19:10:32 +00:00			`</dependency>`
reflect usage of the starter 2017-05-22 08:54:16 +00:00
update spring's documentation 2017-01-20 08:38:00 +00:00			`----`

Cleaned up a couple sentences and removed extraneous spaces 2018-01-10 12:29:25 +00:00			`Add the Adapter BOM dependency:`
reflect usage of the starter 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>`
Convert documentation to AsciiDoctor 2017-08-28 12:50:14 +00:00			`<version>{project_versionMvn}</version>`
reflect usage of the starter 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:`
update spring's documentation 2017-01-20 08:38:00 +00:00
			`* Tomcat`
			`* Undertow`
			`* Jetty`
initial import 2016-04-18 19:10:32 +00:00
Revert "fixed Wildfly mentions and faulty links with underscores" This reverts commit 1ecbc1ba14075203af437295927699adf84cc428. 2019-01-21 17:01:40 +00:00			`[[_spring_boot_adapter_configuration]]`
Fix headers in oidc chapter 2016-06-09 13:12:10 +00:00			`===== Required Spring Boot Adapter Configuration`
initial import 2016-04-18 19:10:32 +00:00
update spring's documentation 2017-01-20 08:38:00 +00:00			`This section describes how to configure your Spring Boot app to use Keycloak.`
initial import 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.
update spring's documentation 2017-01-20 08:38:00 +00:00			`For example:`
initial import 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`
			`----`

KEYCLOAK-4814 disable keycloak spring boot by configuration 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`.

update spring's documentation 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:`
initial import 2016-04-18 19:10:32 +00:00
			`[source]`
			`----`


KEYCLOAK-4208: update documentation to reflect implementation change 2017-04-21 14:29:41 +00:00			`keycloak.securityConstraints[0].authRoles[0] = admin`
			`keycloak.securityConstraints[0].authRoles[1] = user`
initial import 2016-04-18 19:10:32 +00:00			`keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff`
			`keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure`

KEYCLOAK-4208: update documentation to reflect implementation change 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`
Fixing numbering of roles Otherwise "user" will overwrite "admin" in array index 0 2017-01-12 16:49:24 +00:00			`----`
add warning for Spring Boot deployed as WARs 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.