Keycloak Integration
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.
Pre-Requisites
First, you need to get access to SSO Kit or a trial license. You’ll then need to clone the demo application from GitHub, and you’ll need to install Docker.
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:
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. |
Creating New Realms
In Keycloak terminology, a realm 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.
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.
Then provide ssokitrealm
as the Realm name and select Create.
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.
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. |
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.
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: http://192.168.2.158:8080/logout/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.
|
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:
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
vaadin.sso.back-channel-logout=true
Once you’ve done this, the Keycloak instance is ready to be used with the Vaadin client application.
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.
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.
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.