Keycloak and Hasura Setup Guide

This guide provides step-by-step instructions to set up Keycloak for the UBI beneficiary backend system based on the realm configuration.

Prerequisites

• A running PostgreSQL database (uba_beneficiary_mw)

• Docker and Docker Compose installed

• Environment variables configured

Keycloak Setup

Keycloak provides identity and access management for the UBI Beneficiary system, handling user authentication, authorization, and session management.

1. Starting Keycloak

The docker-compose.yml file located in the root of the repository provisions the Keycloak services.

Run the following command:

docker-compose up -d keycloak

This will start Keycloak on: 👉 http://localhost:8080

Login credentials:

• Use the username and password defined in the Docker environment variables

2. Initial Keycloak Configuration

You need to manually configure the realm with users, groups, clients, and roles based on the realm configuration.

Steps:

1. Login to Keycloak Admin Console

   • Navigate to: 👉 http://localhost:8080/admin

   • Use admin credentials from environment variables

2. Create a New Realm

   • Top left → Dropdown → Create Realm

   • Realm name: <your-realm-name>

   • Display name: <your-display-name>

   • Display name HTML: <div class="kc-logo-text"><span>your-display-name SSO</span></div>

   • Click "Create"

3. Configure Clients

   A. Create Admin CLI Client:

   • Go to Clients → Create client

   • Client ID: admin-cli

   • Client authentication: On

   • Authorization: On

   • Service accounts roles: On

   • Standard flow: Off

   • Direct access grants: On

   • Service accounts: On

   • Authorization services: On

   • Public client: Off

   • Click "Save"

   Configure Client Secret:

   • Go to Credentials tab

   • Copy the Secret value

   • Update your .env file with this secret

   B. Create Beneficiary App Client:

   • Go to Clients → Create client

   • Client ID: <your-client-name>

   • Client authentication: Off (Public client)

   • Standard flow: On

   • Direct access grants: On

   • Public client: On

   • Front channel logout: On

   • Full scope allowed: On

   • Click "Save"

   Configure Redirect URIs:

   • Go to Settings tab

   • Valid redirect URIs: /*

   • Web origins: /*

   • Valid post logout redirect URIs: /*

   • Click "Save"

4. Configure Roles

   A. Create Client Roles for :

   • Go to Clients → → Roles

   • Create role: admin

   • Create role: beneficiary

   B. Assign Roles to Admin CLI Service Account

   1. Go to Clients → admin-cli → Service account role tab 3.To manage detail and group mappings, click on the username service-account-admin-cli

   2. Role mapping tab

   3. Client roles: realm-management

   4. Assign roles->Filter by clients

      • manage-users

      • query-users

      • `view-users

5. Configure Groups

   A. Create Groups:

   • Go to Groups → Create group

   • Name: admin

   • Path: /admin

   • Click "Save"

   • Go to Groups → Create group

   • Name: beneficiary

   • Path: /beneficiary

   • Click "Save"

   B. Assign Client Roles to Groups:

   • Admin Group:

     • Go to Groups → admin → Role mapping

     • Client roles: <your-client-name>

     • Assign: admin role

   • Beneficiary Group:

     • Go to Groups → beneficiary → Role mapping

     • Client roles: <your-client-name>

     • Assign: beneficiary role

6. Realm Settings Configuration

   A. General Settings:

   • Go to Realm settings → General -2. Realm name: <your-realm-name>

   • Display name: <your dispaly name>

   • Display name HTML: <div class="kc-logo-text"><span>your dispaly name SSO</span></div>

   • Default signature algorithm: RS256

   • Revoke refresh token: Off

   • Access token lifespan: 82800 (23 hours)

   • SSO session idle timeout: 86400 (24 hours)

   • SSO session max lifespan: 86400 (24 hours)

   B. Login Settings:

   • Go to Realm settings → Login

   • User registration: Off

   • Login with email: On

   • Duplicate emails: Off

   • Reset password: Off

   • Edit username: On

   • Brute force detection: Off

   C. Security Defenses:

   • Go to Realm settings → Security defenses

   • Brute force detection: Off

   • SSL required: External

7. Create Test Users

   A. Create Admin User:

   • Go to Users → Create new user

   • Username: test-admin

   • Email: [e-mail]

   • First name: Test

   • Last name: Admin

   • Email verified: On

   • Enabled: On

   • Click "Save"

   Set password:

   • Go to Credentials tab

   • Set password: test123

   • Temporary: Off

   Assign to group:

   • Go to Groups tab

   • Join group: admin

   B. Create Beneficiary User:

   • Go to Users → Create new user

   • Username: test-beneficiary

   • Email: [e-mail]

   • First name: Test

   • Last name: Beneficiary

   • Email verified: On

   • Enabled: On

   • Click "Save"

   Set password:

   • Go to Credentials tab

   • Set password: test123

   • Temporary: Off

   Assign to group:

   • Go to Groups tab

   • Join group: beneficiary

8. Test Authentication

1. Admin CLI Token:

curl -X POST http://localhost:8080/realms/<your-realm-name>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=admin-cli&client_secret=YOUR_CLIENT_SECRET"

1. User Token:

curl -X POST http://localhost:8080/realms/<your-realm-name>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=<your-client-name>&username=test-admin&password=test123"

9. Start Your Application

1. Update your application's environment variables

2. Verify integration by testing API endpoints with Keycloak tokens

Keycloak Setup Complete

At this point:

• ✅ PostgreSQL is running

• ✅ Keycloak is up (via docker-compose)

• ✅ Realm is configured successfully

• ✅ Users, groups, clients, and roles are created

• ✅ Authentication flows are configured

Hasura Setup

Hasura GraphQL Engine exposes GraphQL APIs on top of the PostgreSQL database, providing a powerful and flexible way to interact with your data.

1. Starting Hasura

The docker-compose.yml file located in the root of the repository provisions the Hasura services.

Run the following command:

docker-compose up -d hasura

This will start Hasura on: 👉 http://localhost:8081

2. Connect Hasura to the Database

Open the Hasura Console in your browser: 👉 http://localhost:8081/console

Navigate to: Data → Manage Databases → default → Edit

Hasura supports 4 ways to connect your database:

A. Connection Parameters Enter parameters individually in Hasura Console:

Host: postgres       # service name in docker-compose
Port: 5432
Username: DATABASE_USERNAME
Password: DATABASE_PASSWORD
Database Name: DATABASE_NAME

B. Connection String (Direct URL)

postgres://<DATABASE_USERNAME>:<DATABASE_PASSWORD>@postgres:5432/<DATABASE_NAME>

C. Connection String from Environment Variable In docker-compose.yml, set:

HASURA_GRAPHQL_DATABASE_URL: postgres://<DATABASE_USERNAME>:<DATABASE_PASSWORD>@postgres:5432/<DATABASE_NAME>

Then in Hasura Console → Add Database → select Environment Variable → use:

HASURA_GRAPHQL_DATABASE_URL

✅ Recommended for production

D. From Connection Template Use Hasura's Template Gallery → Select Postgres template → Fill in DB details

3. Track Tables

In the Hasura Console:

1. Go to Data → default → Untracked tables/views

2. Click Track All to expose all tables in GraphQL

If tables don't appear:

• Navigate to Settings → Metadata Actions → Reload

4. Verify GraphQL Endpoint

Test GraphQL API at: 👉 http://localhost:8081/v1/graphql

You can test with a simple query:

query {
  users {
    id
    firstName
    lastName
  }
}

5. Populate Benefit Data via Content API

Your backend provides a Content API that populates benefit data into the system.

Example Endpoint:

http://beneficiary-backend-url/api/content/create

Run with curl:

curl --location --request POST 'http://localhost:3000/content/create' \
--data ''

This ensures that benefit schemes and related data are inserted into the database.

Verification Checklist

Keycloak Verification

• Keycloak is accessible at http://localhost:8080

• Admin console is accessible at http://localhost:8080/admin

• Realm configuration is set up successfully

• Users, groups, clients, and roles are visible in the admin console

• Test users can authenticate successfully

• Admin CLI service account has proper permissions

Hasura Verification

• Hasura is accessible at http://localhost:8081

• Hasura Console is accessible at http://localhost:8081/console

• Database connection is established

• Tables are tracked and visible in the console

• GraphQL endpoint is responding at http://localhost:8081/v1/graphql

• Benefit data is loaded via Content API

Troubleshooting

Common Issues

Keycloak not starting

• Check Docker logs: docker-compose logs keycloak

• Verify PostgreSQL is running

• Check port 8080 is not in use

Hasura connection issues

• Verify database credentials in docker-compose.yml

• Check PostgreSQL is accessible from Hasura container

• Review Hasura logs: docker-compose logs hasura

Tables not appearing in Hasura

• Reload metadata in Hasura Console

• Check database permissions

• Verify table names and schema

Realm configuration issues

• Verify all required clients are created

• Check service account permissions

• Ensure proper role assignments

• Test admin token generation

User registration fails

• Check admin CLI service account has manage-users role

• Verify realm name in environment variables

• Ensure client secret is correct

• Test with manual user creation in admin console