Skip to main content

Keycloak

This document was generated using AI assistance

Content may include inaccuracies, outdated information, or technical errors. Users are advised to cross-check critical information before implementation.

Architeezy authenticates users through Keycloak. The bundled keycloak container carries the architeezy realm definition and a Russian language provider.

Realm import​

The realm is created on the first start against an empty keycloak database. On later starts the existing realm is kept, so anything you change in the admin console survives restarts and image rebuilds.

Two client settings are taken from the environment at that first start: the valid redirect URI becomes API_GATEWAY_URL/login/oauth2/code/keycloak, and the post-logout redirect URI becomes APPLICATION_URL. Both are resolved once. Changing APPLICATION_URL or API_GATEWAY_URL later does not update the realm - update the client in the admin console instead.

Admin console access​

Open the address in KEYCLOAK_URL - http://localhost:8181 in the default setup. Sign in with KEYCLOAK_ADMIN_USERNAME and KEYCLOAK_ADMIN_PASSWORD. This account belongs to the master realm and administers the server; it is not an Architeezy user.

Select Manage realms, then Architeezy, to work with the application realm.

Realm settings​

The imported realm arrives with these settings:

  • Display name Architeezy, users may sign in with either username or email.
  • Self-registration and password reset are turned off, so an administrator creates accounts. Turn them on under Realm settings → Login.
  • Internationalization is on, with en and ru supported and en as the default locale.
  • SSO session idle is 30 days and the access token lifespan is 5 minutes. The session idle value matches the SESSION_TIMEOUT variable of the API gateway; change one and change the other.
  • SSL is required for external requests.

Clients​

The realm defines two clients for the application, alongside the built-in Keycloak clients (account, account-console, admin-cli, broker, realm-management, security-admin-console).

architeezy​

The confidential client the API gateway signs in with. It uses the standard authorization code flow.

  • Valid redirect URIs must contain API_GATEWAY_URL/login/oauth2/code/keycloak.
  • Valid post logout redirect URIs must contain APPLICATION_URL.
  • The secret on the Credentials tab must be the value you put in OAUTH2_CLIENT_SECRET.

To rotate the secret: open Clients → architeezy → Credentials, click Regenerate, copy the new value into .env, and restart the API gateway.

architeezy-api​

A public client for tools that call the API on a user's behalf, such as a desktop application or a script. Its redirect URIs are http://localhost:* and http://127.0.0.1:*, which is what a local callback listener needs. The client id is passed to the application as OAUTH2_API_CLIENT_ID.

Roles​

The realm carries the standard Keycloak roles - default-roles-architeezy, offline_access and uma_authorization - plus the realm-management roles that grant administration of the realm itself. Give an account realm-management realm-admin to let it manage users without handing out the master realm administrator password.

Permissions inside Architeezy do not come from realm roles. Every account that can sign in gets the same starting point, and access to projects is granted per project and per scope by their owners.

Using an existing Keycloak​

If you already run Keycloak, point Architeezy at it instead of starting the bundled container:

  1. In your Keycloak, choose Manage realms → Create realm, use Browse to select architeezy.json, and create the realm. Alternatively, create the realm by hand and add a confidential client and a public client with the redirect URIs described above.
  2. Open Clients → architeezy → Credentials and copy the secret.
  3. Fill in the OAUTH2_* variables. OAUTH2_ISSUER_URL, OAUTH2_AUTHORIZATION_URL and OAUTH2_ACCOUNT_URL are opened by the browser and must be public addresses. OAUTH2_TOKEN_URL, OAUTH2_JWK_SET_URL and OAUTH2_USER_INFO_URL are called by the application and may be internal addresses.
  4. Remove the keycloak and keycloak-db services from the compose file and drop them from the depends_on lists of backend and api-gateway.

Any OAuth 2.0 provider that issues JWT access tokens with a sub claim containing a UUID and a preferred_username claim works the same way.

Reverse proxy configuration​

The bundled container is prepared for a proxy that terminates TLS: it reads X-Forwarded-* headers and takes its public hostname from KEYCLOAK_URL. Give Keycloak its own host name, such as auth.example.com, and forward the headers listed in the proxy configuration on the prebuilt images page. If the headers are missing, Keycloak builds its redirect and issuer URLs from the internal address and sign-in fails.