Users¶

Users are the accounts in a realm — their credentials, attributes, roles, and lifecycle are managed here.

What it is¶

A user belongs to exactly one realm. Users sign in with username or email, and credentials are protected with Argon2id password hashing. HelixIAM enforces a configurable password policy, keeps password history to prevent reuse, and runs a HIBP breach check to reject known-compromised passwords.

Other capabilities:

Required actions — a framework for pending steps a user must complete at next login (e.g. update password, verify email, configure OTP).
Per-user roles — direct role assignments in addition to roles inherited from groups.
Credentials management — list, reset, and remove a user's credentials.
Admin impersonation — start a session as the user for support and debugging.
Bulk import — load many users at once.
GDPR — export or delete a user's personal data on request.

Note

Login accepts either username or email. Email is supported as a user attribute; make sure your subject-claim choice (see Scopes & claims) reflects how downstream apps identify users.

In the console¶

Users live under Manage → Users & access → Users. Users are always shown by their username, never by a raw subject id.

Open Manage → Users & access → Users, then click Create.
Set the username and email, add any attributes, and save.
From the user's Credentials tab, set a password (subject to policy, history, and the HIBP check) or send a reset.
Under Required actions, add a step the user must complete at next login (e.g. configure OTP).
From the Roles tab, assign realm or client roles directly — or add the user to a group that already holds them.
Use Import to load a batch of users at once, Impersonate to reproduce an issue as the user, and GDPR to export or erase their data.
Resend verification email (shown while the address is not verified) queues a new verification link; delivery is asynchronous.
Sign out everywhere (on the user and on its Sessions tab, confirmed) ends every session of the user and shows what was ended.
Verified attributes lists the attributes a wallet step-up kept on the profile (names, source, times) and can delete one or all of them (confirmed; audited).

Warning

Admin impersonation creates a real session as the user and is a sensitive operation. Impersonation and credential resets are recorded in the audit log — restrict who can perform them.

Citizen service numbers (BSN)

Users who signed in with DigiD have an opaque username (digid-…) and show their BSN masked, *****1234, in the list and on the details page (search matches the last four digits). Reveal full number needs the reveal-bsn permission and is recorded in the audit log. See DigiD: how the BSN is handled.

Danger

GDPR delete is irreversible and removes the user's personal data. Export first if you may need a record.

Over the API¶

All user management is available under /admin/realms/{realm}/users. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List users¶

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/users"

[
  {
    "realmId": "acme",
    "userId": "684db0eb-4afe-44f9-ad16-37a64f3496ea",
    "username": "alice",
    "email": "[email protected]",
    "enabled": true,
    "locked": false,
    "mfaEnabled": false,
    "roles": [],
    "attributes": {},
    "createdAt": 1783339573376
  }
]

Create a user¶

# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/users" >/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 \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"username":"alice","email":"[email protected]","enabled":true}' \
  "$HELIX_URL/admin/realms/$REALM/users"

{
  "realmId": "acme",
  "userId": "684db0eb-4afe-44f9-ad16-37a64f3496ea",
  "username": "alice",
  "email": "[email protected]",
  "enabled": true,
  "locked": false,
  "mfaEnabled": false,
  "roles": [],
  "attributes": {},
  "createdAt": 1783339573376
}

Set a password, assign a role, delete¶

Use the returned userId for subsequent calls:

# Set (or reset) the password — enforced against policy, history, and HIBP
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"newPassword":"S3cure-passphrase!"}' \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea/password"

# Assign a realm role (by its roleId, from GET /admin/realms/{realm}/roles)
ROLE_ID=$(curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/roles" | jq -r '.[] | select(.name == "billing-admin") | .roleId')
curl -s -b cookies.txt -X POST \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d "{\"roleId\":\"$ROLE_ID\"}" \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea/roles"

# Delete the user — returns 204 No Content
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea"

Full endpoint set¶

Method & path (under `/admin/realms/{realm}`)	Purpose
`GET /users` · `POST /users`	List / create users
`GET` · `PUT` · `DELETE /users/{userId}`	Read / update / delete a user
`POST /users/import`	Bulk import
`GET /users/{userId}/credentials` · `DELETE .../credentials/{type}/{id}`	List / remove credentials
`PUT /users/{userId}/password`	Set password
`GET` · `POST /users/{userId}/roles`	User role mappings
`GET` · `PUT /users/{userId}/required-actions`	Required actions
`POST /users/{userId}/impersonate`	Start impersonation
`POST /users/{userId}/send-verification-email`	Resend the verification email (`429` when too many were sent)
`DELETE /users/{userId}/sessions`	Sign the user out everywhere
`GET` · `DELETE /users/{userId}/verified-attributes` · `POST .../verified-attributes/reveal`	Wallet-verified attributes kept on the profile (`DELETE` takes `?name=` for one; values only with `reveal-bsn`)
`GET /users/{userId}/gdpr/export` · `GET /users/{userId}/gdpr/consents` · `DELETE /users/{userId}/gdpr`	GDPR export / consents / erase

See the API reference for the complete schema of every field.