> Markdown version of [Keycloak](https://vaadin.com/docs/next/tools/sso/integrations/keycloak). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)

# Keycloak Integration (deprecated since V25.3)

> **Warning:** SSO Kit is deprecated and won’t be available in Vaadin 26.
>
> A replacement is already in place: all of the kit’s major features are now available directly in Spring Security and in Vaadin’s Spring Security integration. See [Migrating from SSO Kit to Spring Security](https://vaadin.com/docs/next/tools/sso/migrating-to-spring-security.md) for how to move an existing application, and which features you have to build yourself.

This demo application showcases a minimal setup of SSO Kit and Keycloak. It consists of two views: a *public view*, which is accessible to every user; and a *private view*, which is protected by the `@PermitAll` security annotation and therefore only accessible by authenticated users.

## <a id="pre-requisites"></a>Pre-Requisites

First, you need to get access to [SSO Kit or a trial license](https://vaadin.com/docs/next/tools/sso.md). You’ll then need to clone the [demo application from GitHub](https://github.com/vaadin/vaadin-sso-kit-keycloak-demo), and you’ll need to [install Docker](https://docs.docker.com/get-docker/).

## <a id="running-keycloak-creating-an-admin-account"></a>Running Keycloak & Creating an Admin. Account

You can start the Keycloak server in a Docker container from the command-line. You can also create an initial Keycloak administrator account from the command-line with `admin` as the username and password.

To install Keycloak and to create an administrator account, first execute the following at the command-line:

```terminal
docker run --name keycloak-ssokit -p 8280:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:20.0.3 start-dev
```

Next, open the Keycloak UI locally in your browser at: <http://localhost:8280>

> **Note:** Generic passwords are only for demo applications. Don’t use generic passwords for production applications or anywhere else.

## <a id="creating-new-realms"></a>Creating New Realms

In Keycloak terminology, [a realm](https://www.keycloak.org/docs/latest/server_admin/#configuring-realms) is where you can manage users, applications, roles, and groups in a Keycloak deployment. Every user of your application belongs to and logs into a realm. You can create multiple realms in the same Keycloak deployment as long as there is storage space available in your database.

For more information about Keycloak and related terminology, see the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/).

To create a new realm, select **Administration Console** and sign in using the administrator account credentials like so:

```
Username or email: admin
Password: admin
```

Next, select **Create Realm** from the drop-down menu at the top, left-hand corner of the screen.

[Image: The Create Realm button location shown in the drop-down menu.]

Create Realm Button Location

Then provide `ssokitrealm` as the **Realm name** and select **Create**.

## <a id="creating-new-users"></a>Creating New Users

Now that you have a realm, you can add its first user.

Create a new user by selecting **Users** from the side menu and then selecting **Add user**.

Next, provide `user` as the **Username**, then select **Create** to create `user`.

You are then redirected to the User details page.

### <a id="creating-new-passwords"></a>Creating New Passwords

Every user, of course, requires a password. There are a few simple steps to assign a password to `user`.

First, select `user` in the **Users** menu and then select the **Credentials** tab to create a new password. Choose **Set password** and enter `user` as the password for `user`.

Then toggle the **Temporary password** switch to `Off` and select **Save** to confirm. You can view the credentials afterwards in the Credentials tab.

> **Note:** Generic passwords are only for demo applications. Don’t use generic passwords for production applications or anywhere else.

## <a id="creating-new-clients"></a>Creating New Clients

A client is the application or service which you want to secure with Keycloak. In this example, the Vaadin demo application that you cloned from GitHub acts as the client.

To create a client, navigate to **Clients** in the side menu and then select **Create client** to invoke the client creation wizard.

Fill in the following values and then select **Next**:

```
Client type: OpenID Connect
Client ID: sso-kit-sample
Name: sso-kit-sample
```

Next, toggle the following options:

```
Client authentication: On
Authorization: On
Authentication flow: Standard flow
```

The `Service account role` box should already be pre-checked and grayed out: You only need to check the `Standard flow` option in addition to it.

When you’re finished, select **Save** to save and create the client. You are then redirected to the **Client details** page.

## <a id="configuring-access-logout-settings"></a>Configuring Access & Logout Settings

To configure access, scroll down the **Client details** page to the **Access settings** section and provide in the following values:

```
Root URL: http://localhost:8080
Home URL: /
Valid redirect URIs: http://localhost:8080/login/oauth2/code/keycloak
Valid post logout redirect URIs: http://localhost:8080
Web origins: +
```

To configure the logout settings, scroll further down the Client details page to the Logout settings section and fill in these values:

```
Front channel logout: Off
Backchannel logout URL:	https://192.168.2.158:8080/logout/connect/back-channel/keycloak
Backchannel logout session required: On
Backchannel logout revoke offline sessions: Off
```

In the example here, replace `192.168.2.158` with your public IP address.

Click **Save** to save the new access and logout settings.

> **Note:** The **Front channel logout** option should be set to off so that administrators can use the back-channel logout feature to sign out users via the administration console.

> **Tip:** You can look up the local IP address with the `ipconfig getifaddr en0` command on macOS or with the `ipconfig /all` command on Windows.

## <a id="connecting-keycloak-to-vaadin"></a>Connecting Keycloak to Vaadin

To connect Keycloak to a Vaadin application, navigate to the **Credentials tab** in **Client details** and copy the **Client secret** to your clipboard.

Then add the client secret to the Vaadin application by pasting it into the `application.properties` file at `vaadin-sso-kit-keycloak-demo/src/main/resources/application.properties`. That would look like the following:

```properties
spring.security.oauth2.client.registration.keycloak.client-secret=[paste the client secret here]
spring.security.oauth2.client.provider.keycloak.issuer-uri=http://localhost:8280/realms/ssokitrealm
spring.security.oauth2.client.registration.keycloak.client-id=sso-kit-sample
spring.security.oauth2.client.registration.keycloak.scope=profile,openid,email,roles
vaadin.sso.login-route=/oauth2/authorization/keycloak
```

Once you’ve done this, the Keycloak instance is ready to be used with the Vaadin client application.

## <a id="running-the-demo-application"></a>Running the Demo Application

The demo application is a standard Maven project. To run it, open a terminal window at the `vaadin-sso-kit-keycloak-demo` folder. From there, run the application with the `mvn` command.

After you do that, you may open the application locally in your browser at: `http://localhost:8080`. Incidentally, you can also import and run the project from your IDE.

## <a id="testing-user-authentication"></a>Testing User Authentication

For best practices, you should now test user authentication. To do this, first, when your application is running, open `http://localhost:8080` in your browser.

Then select **Sign in** from the bottom, left corner. From there, sign in with the user credentials like so:

```
Username or email: user
Password: user
```

If all went correctly, you are now authenticated as `user` and can view the secured **Private view** at <http://localhost:8080/private>.

To sign out, select **Sign out** from the bottom, left corner. At that point, you’ll no longer be authenticated and won’t be able to view **Private view**.

For extra measure, sign in again to test back-channel logout, which is covered in the next section here.

### <a id="testing-back-channel-logout"></a>Testing Back-Channel Logout

To test back-channel logout, open the Keycloak UI locally in your browser at: `http://localhost:8280`.

From there, sign in using your administrator account credentials like this:

```
Username or email: admin
Password: admin
```

After you’ve signed in, select the `ssokitrealm` realm from the drop-down menu.

Next, select **Clients** from the side menu and select the `sso-kit-sample` client. From there, select the **Sessions** tab.

You can then view the session for `user` in the list. Select **Sign out** — located by the three vertical dots (i.e., ⋮) — to sign out the user.

This causes the Keycloak server to call the running demo server and perform a back-channel logout of `user`.

To verify that `user` is signed out, navigate to `http://localhost:8080/private` and verify that you are prompted to sign in.

You may have noticed that the page reloaded. Performing a back-channel logout causes the session for `user` to expire and then creates a new, unauthorized session. The session is authorized again when `user` signs in and regains access to **Private view**.

You can find the source code for this demo application on [GitHub](https://github.com/bwajtr/vaadin-sso-kit-keycloak-demo).