Realms¶
A realm is an isolated identity domain in HelixIAM — a self-contained tenant with its own users, applications, roles, signing keys, authentication flows, federation, and branding. A realm is protocol-agnostic: the same realm can act as an OpenID Connect / OAuth 2.1 provider and a SAML 2.0 Identity Provider, broker external IdPs (social, enterprise, eIDs), and issue tokens to non-human identities (AI agents and workloads) — all over one shared user base and policy set.
What it is¶
Every realm is a self-contained security domain. Nothing leaks between realms — users, keys, sessions, and configuration are all partitioned by realm. Tenants, environments (dev/staging/prod), or business units are typically modelled as separate realms.
The bootstrap realm is named master. It exists from first start and is used to administer the server. Other realms are created on the master console with Create realm, through the admin API, by import or at start-up (see Common tasks).
Protocols a realm speaks¶
A single realm exposes multiple protocol surfaces at once — you don't pick one at realm creation:
| Role | Endpoint (per realm) | Docs |
|---|---|---|
| OIDC / OAuth 2.1 provider | https://<host>/realms/<realm> — discovery at /.well-known/openid-configuration |
OIDC clients |
| SAML 2.0 Identity Provider | https://<host>/realms/<realm>/saml/idp/metadata |
SAML relying parties |
| Federation broker (inbound) | brokers upstream OIDC/SAML/LDAP/eID logins into this realm | Federation & eIDs |
| Workload identity federation | keyless token exchange for Kubernetes/CI JWTs | Workload identity |
| Agent / NHI delegation | RFC 8693 on-behalf-of token exchange | Agents |
An Application is the protocol-agnostic parent that can own an OIDC client and a SAML relying party together, sharing one subject-claim mapping and login flow across both.
Note
Because the issuer URL contains the realm name, the realm name is effectively part of every OIDC token's iss claim and the SAML IdP entity ID. Choose stable, URL-safe realm names.
What a realm isolates¶
Everything below is scoped to one realm and never spans realms:
- Identities — human users & credentials (Users), AI agents / non-human identities (Agents), and workload identities (Workload identity).
- Applications — the protocol-agnostic parent, plus its OIDC clients (OIDC clients) and SAML relying parties (SAML relying parties).
- Authorization model — realm & client roles (Roles), hierarchical groups (Groups), client scopes & claim mappers (Client scopes & claims), and fine-grained admin RBAC (Admin roles).
- Organizations (B2B) — member companies with their own domains and identity providers (Organizations).
- Federation — brokered identity providers and eID connectors (DigiD, eHerkenning, eIDAS) (Federation & eIDs).
- Authentication — per-realm login flows, MFA, passkeys, device push, and risk-based policy (Authentication).
- Signing keys / JWKS — each realm has its own rotating key set (Realm keys).
- Sessions & SSO — unified SSO sessions with per-realm idle/max/remember-me policy (Sessions).
- Branding & login theming — per-realm login appearance (Login theming).
- Integrations — SCIM provisioning (SCIM), and notification providers (Notifications).
- Audit & privacy — audit events on stdout for your audit tool (Events & audit) and GDPR/privacy configuration (GDPR).
In the console¶
The realm switcher at the top of the admin console shows the realm you are working in. A master console lists the realms of the server and has a Create realm button next to the switcher; a tenant console shows only its own realm and cannot create one. Realm-wide configuration lives under Manage as Realm settings, Login theme, Realm keys and Notifications; the day-to-day objects inside a realm (applications, users, groups, roles, sessions) are the other items under Manage.
Watch: the realm screens¶
Common tasks¶
- Create a realm — on a master console (a master administrator on a master host), click Create realm next to the realm switcher. Enter a Realm id (1-100 letters, digits,
.,_or-, starting with a letter or digit; it is part of every address of the realm and cannot be changed later) and a Display name, and click Create realm. The new realm starts with the default settings and gets what every new realm gets: the built-in browser flow, an admin role and user, the default roles, thehelix-consoleandhelix-cliclients and its own signing keys. It joins the realm switcher and opens on its Realm settings. Its admin user has a random password nobody knows: set it, or add the realm's own administrators, on its Users page. Other routes:- Over the API.
POST /admin/realmswith{realmId, displayName}(see below). - Import under a new realm id. Send a realm document (or a realm archive) to
POST /admin/realms/{newRealm}/import, signed in as a master-realm administrator. If the realm does not exist yet, the import creates it first and then fills it. See Import / export & migration. - Realm-config folder at start-up. Put one
<realm>.jsonor.yamlfile per realm in the folder set byHELIX_REALMS_LOCATION(default/realms). The file name is the realm id. A realm that already exists is left alone unless you setHELIX_REALMS_ON_CONFLICTtooverwrite. See the drop-in folder.
- Over the API.
- Switch realms — on a master console, use the realm switcher; every Manage screen then operates on the selected realm.
- Register an application — add an Application and attach an OIDC client, a SAML relying party, or both; they share the app's subject claim and login flow.
- Configure tokens & sessions — in Manage → Realm settings, adjust access/refresh token lifetimes and the session idle/max/remember-me policies (see Realm settings).
- Brand the login page — in Manage → Login theme, set the realm's login appearance (logo, colors, copy).
- Manage signing keys — rotate or inspect the realm's keys in Manage → Realm keys.
- Export / import a realm — capture the realm's full configuration — across every domain above — as a portable document and apply it to another environment, with secrets carried as
${ENV}placeholders. An upload does not fill them from the server's environment: the secrets stay unset and the console lists them, so set them afterwards. Only the realm-config folder fills them at start-up (Import / export & migration).
There is no realm delete
Helix has no realm-delete operation, in the console or the admin API. If an operator removes a realm's realm_config row directly in the database, a trigger deletes that realm's EU Digital Identity Wallet pepper, verifier access keys, in-flight wallet transactions and trusted list sources with it (see When a realm is deleted); it does not remove the realm's other data.
Disabling a realm¶
Switch Enabled off in Realm settings (or PUT /admin/realms/{realm}/settings with "enabled": false) to take
a realm out of service without deleting anything:
- Refused: the authorization endpoint, login and every sign-in page (a
403page in English and Dutch), federation brokers, registration and the account console, the SAML IdP (SSO and SLO); token issuance and refresh, PAR, device authorization, CIBA and dynamic client registration answer403 {"error":"access_denied"}; userinfo answers401withWWW-Authenticate: Bearer error="invalid_token"; introspection answers{"active":false}for every token. - Still served: discovery (
/.well-known/…), the JWKS, the SAML IdP metadata, token revocation, logout, SCIM and the theme's public assets, so relying parties keep their configuration and pick up where they left off when the realm is enabled again. JWT access tokens issued before the realm was disabled remain cryptographically valid until they expire (keep access-token lifetimes short); a resource server that introspects sees them as inactive. - The admin API stays reachable (it is not realm-routed), so a realm administrator can switch the realm back on.
The change applies at once on the replica that saved it and within 5 seconds on the others. The master realm cannot
be disabled (400): it signs administrators in to the console. A settings update that omits enabled keeps the
realm's current state.
Danger
Treat the master realm as privileged infrastructure. Compromise of master is compromise of the whole server. Restrict who holds admin roles there and prefer per-tenant realms for application users.
Over the API¶
Realm-wide configuration is read and written through the realm's settings resource; the whole realm can be exported and imported as one document. All admin endpoints are scoped under /admin/realms/{realm} and use session + CSRF auth — see Authenticating to the API.
Note
There is no realm delete in the admin API. A new realm comes from POST /admin/realms, an import (POST /admin/realms/{newRealm}/import) or the start-up folder; the rest of the admin API operates within an existing realm.
Create a realm¶
Only a master administrator on a master host may list (GET /admin/realms) or create realms.
curl -s -b cookies.txt -X POST \
-H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
-d '{"realmId":"acme","displayName":"Acme"}' \
"$HELIX_URL/admin/realms"
201 with the new realm; 400 {message, fieldErrors} for an invalid body or a refused realm id; 409 on realmId when the realm exists; 403 for anyone else.
Read realm settings¶
{
"realmId": "master",
"displayName": "Master",
"accessTokenTtlSeconds": 3600,
"refreshTokenTtlSeconds": 5184000,
"requireMfa": false,
"passwordMinLength": 12,
"enabled": true,
"ssoSessionIdleTimeoutSeconds": 1800,
"ssoSessionMaxLifetimeSeconds": 36000,
"lockoutEnabled": false,
"maxLoginFailures": 5
}
Update the same resource with PUT (tokens, sessions, password policy, lockout, risk, branding). Refresh the CSRF token after the read, then write — see the auth guide for the helix() helper.
Export the whole realm¶
The export is a single portable document spanning every domain (clients, SAML clients, roles, scopes, identity providers, flows, organizations, applications, SCIM targets, workload identities, messaging, admin roles, groups, users, agents), with secrets replaced by ${ENV} placeholders listed under requiredEnv. It also carries the realm's key-store policy in keyCustody (never keys). Importing a sovereign realm into a new realm needs keyCustody.backendId; see Realm key custody.
Realm admin endpoints¶
Method & path (under /admin/realms/{realm}) |
Purpose |
|---|---|
GET /admin/realms · POST /admin/realms (not under a realm) |
List realms / create a realm (master administrators on a master host) |
GET /settings · PUT /settings |
Read / update realm-wide configuration |
GET /export |
Export the realm's full configuration |
POST /import |
Import a configuration document into the realm; creates the realm if the id is new |
Every object inside a realm has its own /admin/realms/{realm}/… sub-resource (applications, oidc clients, saml-clients, users, agents, roles, groups, identity-providers, scim-targets, …). See the full API reference and Import / export & migration.
See also¶
- Applications — the protocol-agnostic app parent (OIDC + SAML)
- Agents (AI / non-human identity)
- Federation & eIDs
- Import / export & migration
- Realm settings
- Authentication flows