Skip to content

Organization admin guide

This guide is for the people who administer one customer organization (for example the IT or HR staff of Acme BV). You sign in to the same console as the realm's operators, but you see, and can change, only your own organization.

Watch: Sign in as an organization admin

43 seconds, no sound. Sign in as an organization admin, add a domain, open the invitation form and look at Roles and SCIM. Recorded on the current release.

Signing in

Your realm admin gave you the Org admin role (or another organization role with org:* permissions) in your organization. Open the console of your realm and sign in with your normal account. The console asks the server what you administer (GET /admin/realms/{realm}/me/scope) and shows an Organization console limited to your organization; if you administer several, you can switch between them. The console is English only.

Reachability

If the operator restricts the console to certain hosts (for example a VPN-only console), you reach it on a host they added for customers. See Console reachability for customer organization admins.

You can only act inside your own organization and your own realm. Nothing you do reaches another organization, realm-level clients, roles, identity providers or settings.

Tabs and permissions

Each tab appears only when you hold its permission. The server checks the permission on every request, whatever the console shows.

Tab Permission to see and change it What you do there
Overview org:view The organization's name, status and settings (changing settings needs org:policies)
Members org:members (read-only with org:view) Change members' roles and managers, remove members
Invitations org:invitations Invite by email, resend, revoke
Structure org:units Unit tree (department, team, group) and the org chart
Roles org:roles Organization roles and their permissions
Domains org:domains Claim and verify email domains
SSO org:sso The organization's own identity providers (OIDC or SAML)
Policies org:policies MFA, password and session rules, auto-join, single sign-on only
SCIM org:scim Tokens for your own provisioning client
Branding org:branding Sign-in name, logo, colour and theme

Who sees email addresses

Holders of org:view see member email addresses in the member list and the org chart. Among the organization admin routes, only holders of org:view see them; tokens never carry them. The console needs them because invitations and domain rules work on email addresses. Members and the org chart show a member's full name, else their username, else their email address, never an id; a member with none of these appears as "Unnamed user". The member list is in name order.

Day-to-day tasks

Claim and verify a domain

  1. Domains → Add domain, enter acme-bv.example.com.
  2. Copy the record shown: name _helixiam-challenge.acme-bv.example.com, type TXT, value helixiam-verify=<token>.
  3. Publish it at your DNS provider, wait for DNS to update, then click Verify.

Public email providers (such as gmail.com) and public suffixes cannot be claimed, and neither can any domain the realm operator blocked. A domain another organization of this realm has verified answers "taken" (409). Verified domains are re-checked daily; if the record is gone for three checks in a row the domain returns to pending and stops routing your people to your identity provider and stops auto-join. Keep the TXT record in place.

curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"domain":"acme-bv.example.com"}' \
  "$HELIX_URL/admin/realms/acme/organizations/$ORG/domains"
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/acme/organizations/$ORG/domains/$DOMAIN/verify"

Connect your identity provider

SSO → Add provider: choose OIDC or SAML (the console offers only those two) and enter the settings from your IdP. Secrets are write-only; leave a secret blank when editing to keep it. The provider works only for your verified domains: an assertion for an email outside them is refused. After you add and enable it, people with a verified-domain email are sent to it at sign-in. Users who sign in through it for the first time become members. The provider's Trust email and Trust AMR settings are set by a realm administrator: a change to them from you is refused (403), and saving the provider without them keeps their current values.

With Single sign-on only on (Policies tab), password, passkey and one-time-code sign-in is refused for your domain's users and your members. This needs at least one enabled OIDC or SAML provider of yours; the server refuses the setting otherwise, and refuses to remove the last such provider while it is on. Realm administrators are exempt so the operator cannot be locked out; you are not exempt. The refusal comes before the password is checked and is the same for an address no account has, so it tells nobody whether a colleague has an account.

Invite people

Invitations → Invite: enter the email and choose roles. You can only offer roles whose permissions you hold yourself. The person gets a single-use link, valid for the number of days in your settings (1 to 30, default 7). They sign in or register with that same email address: an account with another verified address cannot accept, and the email tells them the link is personal. Someone who registers from the link has their address verified by it and joins at once; an existing account whose address is not verified yet verifies it first (the page offers the verification email). At most 200 invitations may be pending; Resend replaces the link, Revoke ends it. Invitations go out by email: until the realm operator sets up an email provider, inviting fails with "This realm cannot send email yet" (409 email-not-configured).

Sending is limited to 5 invitations an hour to one address (sends and resends together), 100 an hour per inviter and 300 an hour per organization; past that the console says to try again later (429 invitation-rate-limited). A role you invite someone with is granted at the strength it had when you sent or resent the invitation: if it gained permissions since, it is granted only while you (or whoever resent it last) still hold them.

Roles, members and units

  • Create a role with only the permissions it needs. Org admin is built in and cannot be changed or deleted.
  • A member's roles can come from direct grants and from the units they are in (a unit grants its roles to its members and to the members of its sub-units).
  • Set a manager for a member from Members; the Structure tab shows the org chart.
  • Your own row in Members offers no Remove: leaving is not an administrator action on yourself.
  • Up to 8 levels of units and 1000 units per organization.

Provision with SCIM

SCIM → Create token: the token is shown once. Configure your provisioning client with base URL https://<host>/realms/<realm>/scim/v2 and Authorization: Bearer <token>. See SCIM. SCIM cannot deactivate or remove a member who holds an organization permission (for example an Org admin), take them out of a unit that grants one, or delete such a unit. An organization admin or a realm admin removes them in the console.

Policies

You can require MFA for your members, limit which methods count, raise the minimum password length and history, and shorten the idle and maximum session times. Each value must be at least as strict as the realm's; the console shows the realm's value, and the server refuses a weaker one (400). Your MFA and session policy applies to sign-ins where your organization is the active one.

What you cannot do (by design)

  • Grant what you do not hold. Giving a member a role, or putting permissions in a role or a unit, is refused (403) unless you hold every permission involved.
  • Take away what you do not hold. Removing permissions from a role, deleting a role, or removing a role from a member, is refused (403) when it would take away permissions you lack. This stops a smaller admin from pushing a stronger one out.
  • Remove the last Org admin. The last member holding the Org admin role cannot lose it or be removed (409).
  • Add arbitrary realm users. People join your organization by invitation, SCIM, a verified domain (auto-join) or your identity provider. Adding an existing realm user directly by id is for realm administrators only.
  • See or change realm-level objects. Realm roles, clients, realm identity providers and realm settings are not reachable.

Every change you make is written to the audit log with the realm, your organization and you as actor.

Over the API

The console uses the same API, so everything above is scriptable with the same permissions: see the endpoint table.

See also