Edit Page

Configure Keycloak

Rhize uses Keycloak as an OpenID provider. In your cluster, the Keycloak server to authenticate users, services, and manage Role-based access controls.

This topic describes how to set up Keycloak in your Rhize cluster. For a conceptual overview of the authentication flow, read About OpenID Connect

Prerequisites

First, ensure that you have followed the instructions from Set up Kubernetes. All prerequisites for that step apply here.

Steps

Follow these steps to configure a Keycloak realm and associate Rhize services to Keycloak clients, groups, roles, and policies.

Log in

  1. Go to localhost on the port where you forwarded the URL. If you used the example values from the last step, that’s localhost:5101.

  2. Use the container credentials to log in.

    To find this, look in the keycloak.yaml file.

Create a realm

A Keycloak realm is like a tenant that contains all configuration.

To create your Rhize realm, follow these steps.

  1. In the side menu, select Master then Create Realm.
  2. For the Realm Name, enter libre. Create.
  3. In the side menu, select Realm Settings.
  4. Enter the following values:
    Fieldvalue
    Frontend URLKeycloak frontend URL
    Require SSLExternal requests

After you’ve created the realm, you can create clients.

Note If created with the Libre Theme init container, configure the Login Theme in Realm settings for libre.

Create clients

In Keycloak, clients are entities that request Keycloak to authenticate a user. You need to create a client for each service.

The DB client requires additional configuration of flows and grants. Other clients, such as the UI and Dashboard, use the standard flow to coordinate authorization between the browser and Keycloak to simplify security and improve user convenience.

Note Each standard-flow client has its own subdomain. Refer to Default URLs and Ports for our recommended conventions.

Create DB client

Create a client for the DB as follows:

  1. In the side menu, select Clients > create client.

  2. Configure the General Settings:

    • Client Type: OpenID Connect
    • Client ID: libreBaas
    • Name: Libre Backend as a Service
    • Description: Libre Backend as a Service

    When finished, select Next.

  3. Configure the Capability config:

    • Client Authentication: On
    • Authorization: On
    • For Authentication flow, enable:
      • 🗸 Standard flow
      • 🗸 Direct access grants
      • 🗸 Implicit flow

  4. Select Next, then Save.

    On success, this opens the Client details page for the newly created client.

  5. Select the Roles tab and add the following roles to the libreBaas service account:

    • manage-clients
    • manage-account
    • manage-users

Create UI client

Create a client for the UI as follows:

  1. In the side menu, select Clients > create client.

  2. Configure the General Settings:

    • Client Type: OpenID Connect
    • Client ID: libreUI
    • Name: Libre User Interface
    • Description: Libre User Interface

    When finished, select Next.

  3. Configure the Capability config:

    • Client Authentication: On
    • Authorization: On
    • For Authentication flow, enable:
      • 🗸 Standard flow
      • 🗸 Direct access grants
      • 🗸 Implicit flow

  4. Configure the Access Settings:

    • Root URL: <UI_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes
    • Home URL: <UI_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes
    • Web Origins: <UI_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes

  5. Select Next, then Save.

Create dashboard client

  1. In the side menu, select Clients > create client.

  2. Configure the General Settings:

    • Client Type: OpenID Connect
    • Client ID: dashboard
    • Name: Libre Dashboard
    • Description: Libre Dashboard

  3. Configure the Capability config:

    • Client Authentication: On
    • Authorization: On
    • For Authentication flow, enable:
      • 🗸 Standard flow
      • 🗸 Direct access grants
      • 🗸 Implicit flow

  4. Configure the Access Settings:

    • Root URL: <DASHBOARD_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes
    • Home URL: <DASHBOARD_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes
    • Valid redirect URIs: <DASHBOARD_URL>/login/generic_oauth without trailing slashes
    • Valid post logout redirect URIs: + without trailing slashes
    • Home URL: <DASHBOARD_SUBDOMAIN>.<YOUR_DOMAIN> without trailing slashes

  5. Select Next, then Save.

Create other service clients

The other services do not need authorization but do need client authentication. By default you need to add only the client ID.

For example, to create the BPMN engine client:

  1. In the side menu, select Clients > create client.
  2. For Client ID, enter libreBpmn
  3. Configure the Capability config:
    • Client Authentication: On
  4. Select Next, then Save.

Repeat this process for each of the following services:

Client IDDescription
libreAuditThe audit log service
libreCoreThe edge agent
libreRouterAPI router

Based on your architecture, repeat for any Libre Edge Agents, libreAgent.

Scope services

In Keycloak, a scope bounds the access a service has. Rhize creates a default client scope, then binds services to that scope.

Create a client scope

To create a scope for your Rhize services, follow these steps:

  1. Select Client Scopes > Create client scope.
  2. Fill in the following values:
    • Name: libreClientScope
    • Description: Libre Client Scope
    • Type: None
    • Display on consent screen: On
    • Include in token scope: On
  3. Create.
  4. Select the Mappers tab, then Configure new mapper. Add an audience mapper for the DB client:
    • Mapper Type: Audience
    • Name: libreBaasAudienceMapper
    • Include Client Audience: libreBaas
    • Add to ID Token: On
    • Add to access token: On
  5. Repeat the preceding step for a mapper for the UI client:
    • Mapper Type: Audience
    • Name: libreUIAudienceMapper
    • Include Client Audience: libreUI
    • Add to ID Token: On
    • Add to access token: Off
  6. Repeat the preceding step for a mapper for the BPMN client:
    • Mapper Type: Audience
    • Name: libreBPMNAudienceMapper
    • Include Client Audience: libreBpmn
    • Add to ID Token: On
    • Add to access token: On
  7. If using the Rhize Audit microservice, repeat the preceding step for an Audit scope and audience mapper:
    • Mapper Type: Audience
    • Name: libreAuditAudienceMapper
    • Include Client Audience:
    • Included Custom Audience: audit
    • Add to ID Token: On
    • Add to access token: On

Add services to the scope

  1. Go to Clients. Select libreBaas.
  2. Select the Client Scopes tab.
  3. Select Add Client scope
  4. Select libreClientScope from the list.
  5. Add > Default.

Repeat this process for the dashboard, libreUI, libreBpmn, libreCore, libreRouter, libreAudit (if applicable). Based on your architecture repeat for any Libre Edge Agent clients.

Create roles and groups

In Keycloak, roles identify a category or type of user. Groups are a common set of attributes for a set of users.

Rhize creates an ADMIN role and group.

Add the admin realm role

  1. Select Realm Roles. Then Create role.
  2. Enter the following values:
    • Role name: ADMIN
    • Description: ADMIN
  3. Save.

Add the Admin Group

  1. In the left hand menu, select Groups > Create group.
  2. Give the group a name like libreAdminGroup.
  3. Create.

Now map a role.

  1. From the group list, select the group you just created.
  2. Select the Role mapping tab.
  3. Select Assign Role
  4. Select ADMIN.
  5. Assign.

Add the dashboard realm roles

  1. Select Realm Roles, and then Create role.
  2. Name the role dashboard-admin.
  3. Save.
  4. Repeat the process to create a role dashboard-dev.

Add the dashboard groups

  1. In the left hand menu, select Groups, and then Create Group.
  2. Name the group dashboard-admin
  3. Create.
  4. Repeat the process to create dashboard-dev and dashboard-user groups.

Now map the group to a role:

  1. Select dashboard-admin from the list
  2. Select the Role mapping tab.
  3. Select Assign Role.
  4. Select dashboard-admin
  5. Assign.
  6. Repeat the process for dashboard-dev

Add the group client scope

  1. In the left hand menu, select Client scopes and Create client scope.
  2. Name it groups and provide a description.
  3. Save.

Now map the scope:

  1. Select the Mappers tab.
  2. Add predefined mappers.
  3. Select groups.
  4. Add.

Add new client scopes to dashboard client

  1. In the left hand menu, select Clients, and then dashboard.
  2. Select the Client scopes tab.
  3. Add client scope.
  4. Select groups and libreClientScope.
  5. Add Default.

Add Client Policy

In Keycloak, policies define authorization. Rhize requires authorization for the database service.

  1. In the left hand menu, select Clients, and then libreBaas.
  2. Select the Authorization tab.
  3. Select Policies > Create Policy
  4. Select Group > Create Policy.
  5. Name the policy libreAdminGroupPolicy.
  6. Select Add Groups.
  7. Select libreAdminGroup.
  8. Add.
  9. For Logic, choose Positive.
  10. Save.

Add users

  1. In the left hand menu, select Users, and Add User.
  2. Fill in the following values:
    • Username: system@libremfg.ai.
    • Email: system@libremfg.ai.
    • Email Verified: On
    • First name: system
    • Last name: Libre
    • Join Groups: libreAdminGroup
  3. Create.

Now create a user password:

  1. Select the Credentials tab.
  2. Set Password.
  3. Enter a strong password.
  4. For Temporary, choose Off.
  5. Save.

Repeat this process for the following accounts:

  • Audit:
    • Username: libreAudit@libremfg.ai
    • Email: libreAudit@libremfg.ai
    • Email Verified: On
    • First name: Audit
    • Last name: Libre
    • Join Groups: libreAdminGroup
  • Core:
    • Username: libreCore@libremfg.ai
    • Email: libreCore@libremfg.ai
    • Email Verified: On
    • First name: Core
    • Last name: Libre
    • Join Groups: libreAdminGroup
  • BPMN
    • Username: libreBpmn@libremfg.ai
    • Email: libreBpmn@libremfg.ai
    • Email Verified: On
    • First name: Bpmn
    • Last name: Libre
    • Join Groups: libreAdminGroup
  • Router
    • Username: libreRouter@libremfg.ai
    • Email: libreRouter@libremfg.ai
    • Email Verified: On
    • First name: Router
    • Last name: Libre
    • Join Groups: libreAdminGroup
  • Agent
    • Username: libreAgent@libremfg.ai
    • Email: libreAgent@libremfg.ai
    • Email Verified: On
    • First name: Agent
    • Last name: Libre
    • Join Groups: libreAdminGroup

Enable Keycloak Audit Trail

With the libre realm selected:

  1. Select Realm Settings, and then Events.
  2. Select the tab User event settings.
  3. Enable Save Events and set an expiration.
  4. Save.
  5. Repeat the process for the Admin event settings tab.

Configure password policy

With the libre realm selected:

  1. Select Authentication and then the Policies tab.
  2. Select the Password policy tab.
  3. Add your organisation’s password policy.

Configure brute-force protections

With the libre realm selected:

  1. Select Realm settings and then the Security defenses tab.
  2. In Brute force detection, enable the feature and configure it to your requirements.

Next steps

Install services.