Create and Configure a Keycloak Realm

This doc provides steps to create a Keycloak realm to be used with Axual Platform.

Local vs SSO Users

The Axual Platform will support two types of users.

  • Local Users — These are users who directly sign up via Google or email address to access the system.

  • SSO Users — SSO users originating from Customer’s identity system (like Azure AD, LDAP, etc.) and accessing the system via a dedicated URL. These users skip the signup stage and directly login to Axual Platform via SSO.

Before SSO users can log in, a local user must configure SSO settings for their Organization.

Local Realm

To sign up with the Axual Platform, a Local Realm is required to be available in the Keycloak with proper clients and mappers.

  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 Clients menu

    Keycloak Client memu

  7. Press the Create Client button

    Keycloak Create Client menu

  8. 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

  9. Press the Next button

    Keycloak Create Client general config

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

    Keycloak Create Client capability config

  11. In the Login Settings provide the following values

    1. As Root URL use the hostname of your installation (e.g., https://platform.local/)

    2. Leave Home URL empty

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

  12. Press the Save button

    Keycloak Create Client login settings

  13. Press on the Client scopes tab

    Keycloak Client Scopes tab

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

  15. Select Configure a new mapper

    Keycloak Create New Client Mapper

  16. 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

  17. Press Save button

    Keycloak Tenant Name Mapper

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

  19. Press on the Add Mapper and select By Configuration

    Keycloak Add Second Mapper

  20. 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

  21. Press Save button

    Keycloak Tenant ShortName Mapper

  22. Now you have properly configured the self-service client

    Keycloak Self-Service client-mappers

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

<self-service.host>/login/local

or simply

<self-service.host>/

SSO Realm

Once you have signed up with the Axual Platform using a local user, and you have provided your Organization information, you can configure your identity system for your Realm.

  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
Before proceeding, note down the tenant-short-name for your Organization

  1. Open the Realm dropdown in the top left corner and open the Local realm

  2. Open the Menu and press the Users menu

    Keycloak User memu

  3. Click on the local user you are configuring the SSO Realm

    Keycloak Users list

  4. Click the Attribute tab

    Keycloak User Attributes

  5. Note down the tenant-short-name value, it will be used in the next steps

Let’s assume that the tenant-short-name you are configuring the SSO Realm is test123

  1. Open the Realm dropdown in the top left corner

    Keycloak Create Realm menu

  2. Press the Create Realm button

  3. Fill the Realm name with test123 and press the Create button

    Keycloak Create test realm

  4. Open the Menu and press the Clients menu

    Keycloak Client memu

  5. Press the Create Client button

    Keycloak Create Client menu

  6. 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

  7. Press the Next button

    Keycloak Create Client general config

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

    Keycloak Create Client capability config

  9. In the Login Settings provide the following values

    1. As Root URL use the hostname of your installation (e.g., https://platform.local/)

    2. Leave Home URL empty

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

  10. Press the Save button

    Keycloak Create Client login settings

  11. Open the Menu and press the Identity providers menu

    Keycloak Identity Providers memu

  12. Configure the Identity Provider with the system of your choice (Azure AD, Google Auth, LDAP, etc.)

    Keycloak Identity Providers options

  13. Once configured the identity provider, press the Save button

You are now able to log into your existing Organization using the configured Identity provider.

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

<self-service.host>/login/<tenant-short-name>

In our example, given tenant-short-name equals to test123 the login URL will be

<self-service.host>/login/test123