How to Create the Local Realm in Keycloak

This guide shows you how to create the local realm in Keycloak, the realm users sign up through and the one the first user of every tenant is created in.

Type

How-to guide

Goal

Give a Keycloak installation the local realm, so users can sign up and log in to Self-Service.

Audience

Platform Operator with admin access to Keycloak.

When to use

Use this guide once per Keycloak installation, after the governance components are running and before the first user signs up.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • The Keycloak admin credentials for the Administration Console.

Tools and versions required

You need the following tools:

  • A browser that reaches the Keycloak Administration Console at <keycloak.host>/auth.

Resources that must exist before starting

The following must already exist:

  • A running Keycloak, deployed with the governance components. See Install Axual Governance.

  • The Self-Service hostname, which the client’s Root URL and the login URL are built from.

Replace every <…​> placeholder with your own value before opening a URL.

Local users and SSO users

The Axual Platform supports two types of users, and each type logs in through its own realm:

  • Local Users: users who sign up directly with Google or an email address. They log in through the local realm this guide creates.

  • SSO Users: users who come from the customer’s own identity system, such as Azure AD or Lightweight Directory Access Protocol (LDAP), and reach the platform through a dedicated URL. They skip the sign-up stage and log in through a per-tenant realm, which How to Create an SSO Realm in Keycloak covers.

Before SSO users can log in, a local user must configure SSO settings for their Organization, so the local realm comes first on any installation.

Create the local realm

The realm needs the Self-Service client and the two tenant mappers alongside it, so a signed-up user reaches Self-Service with the tenant they belong to.

  1. Access the Keycloak Admin Console (/auth)

    Keycloak Admin Console screen

  2. Press the Administration Console and provide the admin credentials

    Keycloak Admin login screen

  3. Open the Realm dropdown in the top-left corner

    Keycloak Create Realm menu

  4. Press the Create Realm button

  5. Fill the Realm name with local and press the Create button

    Keycloak Create local realm

  6. Open the Menu and press the Realm Settings button

    Keycloak Configure realm

  7. In the General tab enable the User-managed access toggle and press the Save button

    Keycloak Configure realm User-Managed

  8. In the Login tab on top and enable the User registration toggle

    Keycloak Configure realm User-Registration

  9. Now press the Clients menu

  10. Press the Create Client button

    Keycloak Create Client menu

  11. Provide the following General Configuration

    1. Select OpenID Connect as Client Type

    2. Fill the Client ID as self-service

    3. Fill the Name as Self Service Client

    4. Provide a meaningful Description as Client used by the Self-Service to authenticate users

  12. Press the Next button

    Keycloak Create Client general config

  13. Keep the Capability config as default and press the Next button

    Keycloak Create Client capability config

  14. In the Login Settings provide the following values

    1. As Root URL use the hostname of your installation, for example https://platform.<domain>/

    2. Leave Home URL empty

    3. For the Valid redirect URIs, Valid post logout redirect URIs, and Web Origins use the wildcard *

      The wildcard accepts any redirect target and any browser origin. An attacker who can craft a login link can then have Keycloak send the authorisation code somewhere you do not control. Use the wildcard while you install, then replace all three with the exact Self-Service URLs before the realm serves real users.

  15. Press the Save button

    Keycloak Create Client login settings

  16. Press on the Client scopes tab

    Keycloak Client Scopes tab

  17. Press on the self-service-dedicated client scope

  18. Select Configure a new mapper

    Keycloak Create New Client Mapper

  19. Select User Attribute

    Keycloak Select Client Mapper

    1. Fill the Name as Tenant Name Mapper

    2. Fill the User Attribute as tenant-name

    3. Fill the Token Claim Name as tenant_name

  20. Press Save button

    Keycloak Tenant Name Mapper

  21. Press on the self-service-dedicated client scope

  22. Press on the Add Mapper and select By Configuration

    Keycloak Add Second Mapper

  23. Select User Attribute

    Keycloak Select Client Mapper

    1. Fill the Name as Tenant Short Name Mapper

    2. Fill the User Attribute as tenant-short-name

    3. Fill the Token Claim Name as tenant_short_name

  24. Press Save button

    Keycloak Tenant ShortName Mapper

The Self-Service URL to access the Local Realm login screen is

<self-service.host>/login/local

or

<self-service.host>/

Verify the local realm

Check that the client emits both tenant claims and that the realm serves the Self-Service login screen.

  1. Open the Mappers tab of the self-service-dedicated client scope.

    Expected result: the list holds both Tenant Name Mapper and Tenant Short Name Mapper. A missing mapper means Self-Service receives a token without the tenant it belongs to, so the login fails after Keycloak has already accepted the credentials.

    Keycloak Self-Service client-mappers

  2. Open <self-service.host>/login/local in a browser.

    Expected result: the login screen of the local realm loads and offers a registration link, because User registration is enabled on the realm. A Client not found error instead means the Client ID is not self-service.