User Management

AI-in-a-Box uses Keycloak as the default identity provider. Users, credentials, clients, and realm roles are managed in the Keycloak admin console at http://localhost:8180/admin.

The application realm is aibox.

Access the Admin Console

Start the platform, then open:

http://localhost:8180/admin

Use:

Field	Value
Username	Value of KEYCLOAK_ADMIN in deploy/.env
Password	Value of KEYCLOAK_ADMIN_PASSWORD in deploy/.env

make bootstrap generates the password. The static values in deploy/.env.example are development placeholders only.

After login, switch from the master realm to the aibox realm.

Create a User

1. Go to Users > Add User.
2. Set username and email.
3. Save the user.
4. Open Credentials.
5. Set a password and turn Temporary off when creating a permanent dev user.

Assign Roles

Assign realm roles from Users > Role mapping.

Role	Effect
user	Standard application access.
admin	Admin UI and admin API access.
tenant_admin	Tenant administration where supported by services.
platform_admin	Platform-wide administration where supported by services.

The shipped realm seeds admin and user. Add tenant_admin or platform_admin in Keycloak if you need those role names for your deployment.

Development Users

The realm import includes development users:

Username	Password	Roles
admin	admin-dev-password	admin, user
testuser	user-dev-password	user

These are not production credentials. Rotate or delete them before exposing a shared environment.

API Tokens

The aibox-frontend client has password grants disabled (directAccessGrantsEnabled=false). Do not use password-grant curl snippets as the normal token acquisition path.

For manual API testing, obtain a bearer token through one of these supported paths:

• Sign in through the frontend and inspect/copy the dev access token from the browser tooling used by your environment.
• Use an operator-approved confidential client or service account.
• Temporarily enable direct access grants only in an isolated development realm, then disable it again.

Example API call once you have a token:

curl http://localhost:8080/v1/user/profile \
  -H "Authorization: Bearer $TOKEN"

For chat API shape, see Chat Reference.

SSO Identity Providers

The gateway exposes an admin SSO route at /v1/admin/sso/idps when the Keycloak admin integration is configured:

Variable	Purpose
KEYCLOAK_ADMIN_BASE_URL	Internal Keycloak base URL.
KEYCLOAK_ADMIN_REALM	Realm to administer, usually aibox.
KEYCLOAK_ADMIN_CLIENT_ID	Admin client id.
KEYCLOAK_ADMIN_CLIENT_SECRET	Admin client secret.

Use Authentication Reference for the full identity flow.

Troubleshooting

Problem	Check
Cannot log into Keycloak admin	Confirm KEYCLOAK_ADMIN_PASSWORD in deploy/.env, not deploy/.env.example.
User cannot access admin UI	Confirm realm role mapping includes admin, tenant_admin, or platform_admin as needed.
API returns 401	Verify the token issuer and audience match gateway auth configuration.
Password grant examples fail	Expected by default; the frontend client disables direct access grants.