Skip to content

Realm settings

Tune each realm's tokens, sessions, sign-in policy and security from a single tabbed configuration page.

What it is

A realm is a fully isolated tenant in HelixIAM — its own users, clients, keys and policy. The Realm settings screen is where you shape how that tenant behaves at runtime. Settings are scoped to the realm: changing one realm never affects another.

The page is organised into tabs:

  • General — display name, issuer URL and Realm enabled.
  • Tokens & sessions — token lifetimes, the signing algorithm, SSO session policy (idle timeout, maximum lifetime, remember-me) and concurrent-session limits.
  • Login — sign-in options (emailed link, verified email), the sign-in identity, Require MFA, password length and password policy, and CAPTCHA.
  • Registration — whether this realm accepts self-service sign-ups, and where a new user goes afterwards.
  • Organizations — email domains no organization may claim.
  • Account console — what users may do in the account console.
  • Branding — the sign-in branding, read-only here; it is edited on Login theme.
  • Threat protection — brute-force protection (account lockout) and the adaptive risk policy.
  • Security — the realm's security profile (for example FAPI 2.0).
  • Logging — audit events and temporary debug logging.
  • Endpoints — the realm's OIDC discovery and protocol endpoints, to copy.

The languages of the sign-in pages are set on Login theme (Layout & texts → Languages), not here. The RFC 8707 resource allow-list is per client, under Resource indicators (RFC 8707) on the client's Advanced tab.

45 seconds, no sound. Change the display name, token and session settings, sign-in options, self-registration and what users may do in the account console, then save. Recorded on the current release in a test realm.

In the console

  1. Open Realm settings (under Manage).
  2. Pick a tab and edit the fields.
  3. Click Save — changes apply to new sessions and token requests immediately. Discard drops unsaved changes.

Tokens & sessions

Field Effect
Access token TTL (seconds) How long an access token is valid.
Refresh token TTL (seconds) How long a refresh token is valid; must be longer than the access token TTL.
Reuse refresh tokens The same refresh token can be exchanged more than once.
Idle timeout (seconds) An SSO session ends after this period of inactivity.
Maximum session lifetime (seconds) Hard cap on a session's age regardless of activity.
Remember me · Remember-me lifetime (seconds) Lets returning users keep a longer-lived session from the login page.
Max concurrent sessions · Evict oldest session Limit of active sessions per user (0 = unlimited), and whether the oldest is signed out or the new sign-in refused.

These policies are enforced across every application in the realm and underpin silent SSO and re-authentication prompts. The Signing section on this tab sets the realm's token signing algorithm (see Realm keys).

Registration

Field Effect
Allow self-registration Lets people create their own account for this realm at /register.

Self-registration only runs when both switches agree: the platform-wide USER_REGISTRATION_ENABLED environment variable (Configuration) and this realm's Allow self-registration toggle. If either one is off, the realm's /register page shows a "registration closed" panel and no sign-up is accepted.

When it's on, /register uses the same per-realm login branding as the sign-in page — logo, colours, welcome text and custom CSS. The fields on the sign-up form, and which of them are required, are not set here: they come from the realm's claim catalogue. See Self-registration fields.

Post-registration redirect. The Registration tab also sets where a new user goes after signing up (postRegistrationRedirectUrl, an absolute http(s) URL; the console checks it before sending and shows the server's origin refusal on the field).

Login

The Login tab has the sections Sign-in options, Sign-in identity, Login security (Require MFA, Days a new account may skip MFA setup, Minimum password length), Password policy and CAPTCHA. See Password policy & lockout for the password and CAPTCHA fields.

Switches with their own endpoints, saved after the realm settings and only when changed:

Field Effect Endpoint
Sign in with an emailed link the magic-link sign-in /settings/magic-link ({"enabled": …})
Require a verified email address users must verify their email address /settings/verify-email ({"enabled": …})
Days a new account may skip MFA setup 0–90 days a user may skip MFA enrolment, next to Require MFA (only skipGraceDays is sent) /settings/mfa

Threat protection

Brute-force protection (Enable lockout, Max login failures, Failure reset window (seconds), Permanent lockout, Lockout duration (seconds)) and Adaptive risk policy (thresholds and the action per risk level). See Password policy & lockout and Risk-based authentication.

Account console

What users may do in the account console:

Field Effect
Authenticator removal users may remove their own MFA devices (default on)
Data export users may export their personal data (default on)
Account deletion users may delete their own account (default off)
Self-editable profile attributes the profile attributes users may edit themselves (Edit details in the account console); reserved claims are refused

/settings/account-console holds allowAuthenticatorRemoval, allowDataExport and allowAccountDeletion; /settings/self-editable-attributes holds {"attributes": [...]}. When a save stored the settings but a switch was refused, the console says what was saved and what was not, with the reason.

Branding

The five branding fields of the settings object (logoUrl, primaryColor, backgroundColor, welcomeText, customCss) are part of the realm theme: the tab shows them read-only, with a link to Login theming.

Organizations

The Organizations tab holds Blocked domains: a list of email domains, separated by commas, semicolons, new lines or spaces, that no organization may claim in this realm (at most 500). Entries are normalised (lower case, internationalised names as punycode) and an invalid entry is refused with a message naming it. A listed domain also blocks its subdomains. Public suffixes and the built-in public email providers (for example gmail.com, outlook.com, hotmail.com, yahoo.com, icloud.com, proton.me) are always refused and need not be listed. The list applies when a domain is added or verified; it does not remove a domain an organization has already verified. The console shows the entries with their Unicode names (for example bücher.example); the API stores and returns punycode.

In the API the list is the field organizationBlockedDomains of the settings object. It is one string, not a JSON array (an array is refused with 400 "Request body is malformed"), with the entries separated by commas, semicolons, new lines or spaces; the response returns them comma-separated in punycode:

{ "organizationBlockedDomains": "contoso.com,tailspin-toys.com" }

Realm import in overwrite mode

Importing an export that has no organization settings in overwrite mode clears this list, because overwrite replaces the realm's settings wholesale. Set it again afterwards.

Over the API

Most fields of the General, Tokens & sessions, Login, Registration, Organizations, Branding and Threat protection tabs are one RealmSettingsDto resource under /admin/realms/{realm}/settings; the switches listed under Login and the account-console settings have their own endpoints. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

Read the settings

The response carries the full realm configuration — session policy, password rules, lockout, CAPTCHA, adaptive-risk thresholds and branding — in one object (abridged here):

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/settings"
{
  "realmId": "acme",
  "displayName": "Acme",
  "issuer": null,
  "accessTokenTtlSeconds": 3600,
  "refreshTokenTtlSeconds": 5184000,
  "reuseRefreshTokens": false,
  "requireMfa": false,
  "ssoSessionIdleTimeoutSeconds": 1800,
  "ssoSessionMaxLifetimeSeconds": 36000,
  "rememberMe": false,
  "rememberMeLifetimeSeconds": 2592000,
  "lockoutEnabled": false,
  "maxLoginFailures": 5,
  "lockoutDurationSeconds": 900,
  "passwordMinLength": 12,
  "breachedPasswordCheck": false,
  "captchaProvider": "none",
  "maxConcurrentSessions": 0,
  "riskPolicyEnabled": false,
  "riskMediumThreshold": 40,
  "riskHighThreshold": 70,
  "logoUrl": null,
  "primaryColor": null,
  "backgroundColor": null,
  "welcomeText": null,
  "customCss": null,
  "registrationEnabled": true
}

Update the settings

Submit the full settings object (a PUT replaces it). Refresh CSRF after the read:

# Refresh CSRF after any GET, then PUT (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/settings" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "displayName": "Acme",
        "ssoSessionIdleTimeoutSeconds": 900,
        "rememberMe": true,
        "lockoutEnabled": true,
        "maxLoginFailures": 10,
        "breachedPasswordCheck": true,
        "registrationEnabled": true
      }' \
  "$HELIX_URL/admin/realms/$REALM/settings"

The response echoes the updated RealmSettingsDto.

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /settings · PUT /settings Read / replace the full realm settings object
GET · PUT /settings/magic-link Sign-in with an emailed link
GET · PUT /settings/verify-email Require a verified email address
GET · PUT /settings/mfa Require MFA, skip-grace days (0–90)
GET · PUT /settings/registration Post-registration redirect URL
GET · PUT /settings/account-console Account console permissions
GET · PUT /settings/self-editable-attributes Profile attributes users may edit

See also