First-Time Setup: Keycloak Realm, Admin User & Role Assignment

Once the containers are running, you must configure Keycloak to establish enterprise identity and create the first administrator account.

sequenceDiagram
    autonumber
    actor Admin as Platform Admin
    participant KC as Keycloak (port 8081)
    participant VDA as VDA Web UI (port 8080)

    Admin->>KC: Log in to Admin Console (admin / KEYCLOAK_ADMIN_PASSWORD)
    Admin->>KC: Create realm 'vda'
    Admin->>KC: Create client 'vda-client' (Redirect URI: http://localhost:8080/*)
    Admin->>KC: Create realm roles (SUPERADMIN, DATA_CONSUMER)
    Admin->>KC: Create user 'vda-admin' & set permanent password
    Admin->>KC: Assign role 'SUPERADMIN' to 'vda-admin'
    Admin->>VDA: Open http://localhost:8080 & Log in
    VDA->>KC: Authenticate via OIDC
    KC-->>VDA: JWT Token with SUPERADMIN role
    VDA-->>Admin: Grant full access to VDA Dashboard

Step 1: Access Keycloak Administration Console

1. Open your web browser and navigate to http://localhost:8081 (or your configured Keycloak URL).
2. Log in using the master administrator credentials defined in your .env file:
3. Username: admin (or ${KEYCLOAK_ADMIN})
4. Password: ${KEYCLOAK_ADMIN_PASSWORD}

Step 2: Create the vda Realm

1. In the top-left dropdown (currently displaying master), click Create Realm.
2. Set the Realm name to vda.
3. Ensure Enabled is toggled ON.
4. Click Create.

Step 3: Create the OpenID Connect Client

1. In the left navigation sidebar under vda realm, click Clients.
2. Click Create client.
3. Set Client type: OpenID Connect.
4. Set Client ID: vda-client.
5. Click Next.
6. Ensure Standard flow and Direct access grants are enabled.
7. Click Next.
8. Configure redirect URIs:
9. Root URL: http://localhost:8080
10. Home URL: http://localhost:8080
11. Valid redirect URIs: http://localhost:8080/*
12. Valid post logout redirect URIs: http://localhost:8080/*
13. Web origins: * (or http://localhost:8080)
14. Click Save.

Step 4: Define Realm Roles

1. In the left sidebar, click Realm roles.
2. Click Create role and add the following roles:
3. SUPERADMIN: Full administrative privileges across all datasources, policies, and system settings.
4. DATA_CONSUMER: Standard business user role with read access to non-restricted catalog assets and text-to-SQL.
5. DATA_STEWARD: Governance role authorized to curate descriptions, approve metadata, and define glossary terms.

Step 5: Create the Initial Admin User

1. In the left sidebar, click Users > Add user.
2. Set Username: vda-admin.
3. Enter an email address and full name.
4. Toggle Email verified to ON.
5. Click Create.
6. Switch to the Credentials tab:
7. Click Set password.
8. Enter a secure password.
9. Toggle Temporary to OFF (so password change is not required on first login).
10. Click Save > Save password.
11. Switch to the Role mapping tab:
12. Click Assign role.
13. Filter by SUPERADMIN.
14. Select SUPERADMIN and click Assign.

Step 6: Perform First Login

1. Open your browser and navigate to the VDA Web UI: http://localhost:8080.
2. Click Sign in with Enterprise SSO.
3. You will be redirected to the Keycloak login screen.
4. Enter the credentials for vda-admin.
5. Upon successful authentication, Keycloak redirects back to the VDA portal, granting full administrative access to all modules.