Skip to main content

Keycloak

This guide explains how to integrate HridaAI with Keycloak for OIDC Single Sign-On (SSO).

1. Environment Preparation and Port Change​

HridaAI Server Port​

  • Default Port: 8080

Keycloak Port Conflict Issue​

Keycloak also uses port 8080 by default, which causes a conflict. Change the Keycloak port to 9090.

bin/kc.sh start-dev --http-port=9090

2. Create a Keycloak Realm​

  1. Open your browser and go to http://localhost:9090. Create an administrator account.
  2. Log in to the admin console at http://localhost:9090/admin.
  3. From the realm dropdown at the top, click Add realm.
  4. Enter hridaai as the Realm name and click Create.

create-realm

3. Create an OpenID Connect Client​

info

Make sure you have selected the hridaai realm. The default is master.

select-realm

  1. Ensure the hridaai realm you just created is selected.
  2. In the left menu, click Clients → Create client.
  3. Set Client ID to hrida-ai.
  4. Keep Client protocol as openid-connect.
  5. Set Access Type to confidential and click Save.

access-setting-client

4. Enable Client Authentication and Get Credentials​

By default, Keycloak 26.x sets Client Authentication to "None", so it needs to be configured manually.

  1. Go to Clients → hrida-ai → Settings.
  2. Check the Client Authenticator dropdown.
  3. Change "None" to Client ID and secret and click Save.
  4. Click the Advanced tab.
  5. In the Client authentication section, click Reveal secret and copy the secret.
  6. Paste this secret into the OAUTH_CLIENT_SECRET variable in your .env file.

5. Create a Test User​

  1. In the left menu, go to Users → Add user.
  2. Fill in the Username, Email, etc., and click Save.
  3. Click on the newly created user, then go to the Credentials tab.
  4. Enter a new password, uncheck Temporary, and click Set Password.
    • Example: Username testuser, Password Test1234!

6. Configure HridaAI .env​

Add or modify the following variables in your .env file.


# Enable OAuth2/OIDC Login
ENABLE_OAUTH_SIGNUP=true

# Keycloak Client Information
OAUTH_CLIENT_ID=hrida-ai
OAUTH_CLIENT_SECRET=<YOUR_COPIED_SECRET>

# OIDC Discovery Document URL
OPENID_PROVIDER_URL=http://localhost:9090/realms/hridaai/.well-known/openid-configuration

# (Optional) SSO Button Label
OAUTH_PROVIDER_NAME=Keycloak

# (Optional) OAuth Callback URL
OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback

Restart the HridaAI server after modifying the .env file.

7. HTTP vs. HTTPS​

  • HTTP (Development/Test):
    • Scheme: http://
    • Example: http://localhost:9090
  • HTTPS (Production Recommended):
    • Requires Keycloak TLS setup or a reverse proxy with SSL termination.
    bin/kc.sh start --https-port=9090 \
  --https-key-store=keystore.jks \
  --https-key-store-password=<password>

8. Test the Integration​

  1. Go to http://localhost:8080. You should see a "Continue with Keycloak" button.
  2. Click the button. You should be redirected to the Keycloak login page.
  3. Log in with testuser / Test1234!. You should be successfully redirected back to HridaAI.

9. Configure Keycloak Group Mapping​

9.1. Overview​

By default, Keycloak clients do not include group information in tokens. Follow these steps to pass group information.

9.2. Locate Mapper Creation​

  1. Go to the Keycloak Admin Console: http://localhost:9090/admin.

  2. Select the hridaai realm.

  3. Navigate to Clients and select the hrida-ai client.

  4. Go to the Client scopes tab.

  5. Select the scope that will contain the group information (e.g., profile or hrida-ai-dedicated).

    scope-client

  6. In the selected scope's details, go to the Mappers tab.

9.3. Create Mapper​

Click Create or Add builtin to start creating a new mapper.

9.4. Mapper Settings​

Configure the mapper with the appropriate settings to include group membership.

mappers-setting-group-client

9.5. Save and Apply​

  • Save the mapper configuration.
  • Restart the HridaAI server to apply the changes.

9.6. Configure HridaAI Environment Variables​

Add or modify these variables in your .env file:


# Enable group synchronization
ENABLE_OAUTH_GROUP_MANAGEMENT=true

# (Optional) Enable Just-In-Time group creation
ENABLE_OAUTH_GROUP_CREATION=true

# The claim key for groups in the token
OAUTH_GROUP_CLAIM=groups
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Hrida AI is proprietary software owned by Zlabs Innovation, provided "as is." See your license for applicable terms. © 2026 Zlabs Innovation. All rights reserved.