Keycloak Setup
This page shows an example of setting up Keycloak as the identity provider for single sign-on (SSO) in Flowset Control. Configure Control first as described in Single Sign-On (SSO), then follow the steps below.
Setting Up a Local Keycloak Instance
One of the most popular OpenID providers is Keycloak. To explore the Jmix OIDC add-on, you can run Keycloak locally using Docker.
Running Keycloak with Docker
Use the following command to run a Keycloak instance via Docker on port 8180:
docker run -p 8180:8080 \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin \
--name keycloak \
quay.io/keycloak/keycloak:22.0 start-dev
See the Keycloak documentation for more details.
Keycloak URL: http://localhost:8180
Admin credentials:
Username: admin
Password: admin
You can read about configuring a Keycloak instance in the Server Administration Guide.
Configuring Keycloak for Flowset Control
Creating a Realm
Log in to the Keycloak Admin Console and complete the following steps:
-
In the left panel, click Add Realm.
-
Enter a realm name, for example
flowset. -
Click Create.
Creating a Client
A client represents the Flowset Control application that will use Keycloak for authentication.
-
Open Clients and click Create.
-
Specify parameters:
Parameter Value Client ID
flowset-controlClient Protocol
openid-connect
-
In the Capability config section:
Parameter Value Client authentication
ON
-
In the Login Settings section, set:
Parameter Value Valid Redirect URIs
*(development only)Valid post logout redirect URIs
*(development only)Web Origins
*(development only)
After saving the client, go to the Credentials tab and copy the Client Secret. This secret will be used in the Flowset Control configuration.
Creating Roles
Roles in Keycloak must match the role codes used in Jmix/Flowset Control.
-
Open Realm roles → Add Role.
-
Enter a role name, for example
system-full-access. -
Save the changes.
Creating a User
-
Open Users → Add User.
-
Enter a username, for example
johndoe. -
Save.
After saving:
-
On the Credentials tab, set a password for the user.
-
On the Role Mappings tab, assign the
system-full-accessrole.
-
Configuring a Role Mapper
To ensure roles are included in the ID Token, create a mapper:
-
Go to Client scopes →
roles→ Mappers →realm roles. -
Click Create and fill in the fields:
Field Value Mapper Type
User Realm RoleToken Claim Name
realm rolesClaim JSON Type
StringAdd to ID token
ONAdd to access token
ONAdd to userinfo
ON