WebsiteDashboard

Configuring Keycloak

Suggest Edits

Hook0 relies on Keycloak to manage users and permissions.
You will need administrative access to a dedicated Keycloak realm.

👍

If you need a managed Keycloak instance, check out Cloud IAM!

Automatic Configuration

We built a script that handle most of the configuration automatically.

You will need:

  • access to kcadm.sh (included in most Keycloak distribution)
    • you might need to define the KEYCLOAK_HOME environment variable so the script finds kcadm.sh in $KEYCLOAK_HOME/bin/kcadm.sh
  • credentials of a user in the master realm
./self-hosted/configure-keycloak.sh SERVER_URL ADMIN_USER ADMIN_PASSWORD REALM_NAME

For example:

./self-hosted/configure-keycloak.sh http://localhost:8080 admin admin hook0

🚧

Limitations

  • This script is only intended to work on initial setup. If something changes in the Keycloak configuration Hook0 requires, the script will not migrate your existing Keycloak realm.
  • This script will not configure authentication policies, you have to do it by yourself (see the Authentication Settings section below).

Manual Configuration

The following sections will help you configure your realm for Hook0.

Groups Scope

Let's create a new client scope that will include in JWT every group our users belong to.

  • create a new Client Scope:
    • Name: groups
    • Protocol: OpenID Connect
    • Display on consent screen: OFF
    • Include In Token Scope: ON
  • create a new Mapper for this Client Scope:
    • Mapper Type: Group Membership
    • Name: group_membership
    • Token Claim Name: groups
    • Full group path: ON
    • Add to ID token: ON
    • Add to access token: ON
    • Add to userinfo : ON

Console Client

Now we need a client for Hook0 web console.

  • create a new Client:
    • Client Type: OpenID Connect
    • Client ID: hook0
    • Name: Hook0
    • Client Authentication: OFF
    • Authentication flow: Standard flow
    • Root URL: the URL where you want to deploy Hook0's API/console (example: https://app.hook0.com)
    • Home URL: /
    • Valid redirect URIs: /*
    • Valid post logout redirect URIs: +
    • Web Origins: +
  • configure this client's client scopes:
    • in the client's details, go to the Client scopes tab
    • click on Add client scope
    • check the groups entry
    • add as Default
  • configure this client's scope:
    • in the client's details, go to the Client scopes tab
    • in the main table, click on the [your client's name]-dedicated link
    • go to the Scope tab
    • Full Scope Allowed: OFF

API Client

Next, Hook0's API will need its own private client with a service account so that it can register new users or organizations.

  • create a new Client:
    • Client Type: OpenID Connect
    • Client ID: hook0-api
    • Name: Hook0 API
    • Client Authentication: ON
    • Authorization: OFF
    • Authentication flow: Direct access grants and Service accounts roles
    • Root URL: the URL where you want to deploy Hook0's API/console (example: https://app.hook0.com)
    • Home URL: empty
    • Valid redirect URIs: empty
    • Valid post logout redirect URIs: empty
    • Web Origins: empty
  • configure this client's scope:
    • in the client's details, go to the Client scopes tab
    • in the main table, click on the [your client's name]-dedicated link
    • go to the Scope tab
    • Full Scope Allowed: ON
  • configure this client's service account roles:
    • in the client's details, go to the Service account roles tab
    • click on Assign role
    • select Filter by clients
    • check the (realm-management) manage-users role
    • click on Assign

Authentication Settings

We also need to enable a few settings to ensure the overall security of the system.

  • in Authentication > Policies > Password Policy:
    • add a Minimum Length policy
    • add a Not Email policy
  • in Authentication > Required Actions:
    • check Update Password as a Default Action

Updated 8 months ago