Configuring Keycloak

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!

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