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 log in 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.

Access the Keycloak Admin Console (/auth)
Press the Administration Console and provide the admin credentials
Open the Realm dropdown in the top-left corner
Press the Create Realm button
Fill the Realm name with local and press the Create button
Open the Menu and press the Realm Settings button
In the General tab enable the User-managed access toggle and press the Save button
In the Login tab on top and enable the User registration toggle
Now press the Clients menu
Press the Create Client button
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
Press the Next button
Keep the Capability config as default and press the Next button
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 *
Press the Save button
Press on the Client scopes tab
Press on the self-service-dedicated client scope
Select Configure a new mapper
Select User Attribute
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
Press Save button
Press on the self-service-dedicated client scope
Press on the Add Mapper and select By Configuration
Select User Attribute
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
Press Save button
Now you have properly configured the self-service client

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.

Access the Keycloak Admin Console (/auth)
Press the Administration Console and provide the admin credentials

Before proceeding, note down the tenant-short-name for your Organization

Open the Realm dropdown in the top left corner and open the Local realm
Open the Menu and press the Users menu
Click on the local user you are configuring the SSO Realm
Click the Attribute tab
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

Open the Realm dropdown in the top-left corner
Press the Create Realm button
Fill the Realm name with test123 and press the Create button
Open the Menu and press the Clients menu
Press the Create Client button
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
Press the Next button
Keep the Capability config as default and press the Next button
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 *
Press the Save button
Open the Menu and press the Identity providers menu
Configure the Identity Provider with the system of your choice (Azure AD, Google Auth, LDAP, etc.)
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