capabilities.work

Onboard a User

A 8-step recipe with Keycloak. We can help you get access.

Recipe · 8 steps

Onboard a User

with Keycloak · Cybersecurity Management

Create a user in a realm, set an initial password, and assign a realm role.

  1. Read the realm representation to confirm the realm exists and is enabled before attempting to write any users into it.
  2. Search the realm for an existing account with this username so the flow stays idempotent and never trips the 409 conflict on create.
  3. Create the enabled user account. Keycloak answers 201 with a Location header and no response body, so the UUID is resolved by the next step rather than read from this response.
  4. Resolve the user UUID by searching the realm for the username. Both the created and the pre-existing branch converge here, because every dependent Keycloak call is keyed on the UUID rather than the username.
  5. Set the account password. Marking the credential temporary forces a password change at first login, which is the expected onboarding posture.
  6. Look up the realm-level role by name to obtain the id and name pair that the role-mapping endpoint requires in its request body.
  7. Grant the resolved realm-level role to the user. The body is an array of role representations, each requiring the id and name of the role.
  8. Read the user's realm-level role mappings back to prove the grant landed before the onboarding flow reports success.
What you'll need to have ready
  • realm: The name of the realm to provision the user into (e.g. "customers").
  • username: The username for the account. Must be unique within the realm.
  • email: The email address for the account.
  • firstName: The user's given name.
  • lastName: The user's family name.
  • password: The initial password to set on the account.
  • temporaryPassword: When true the user is forced to change the password at next login. Defaults to true for onboarding.
  • roleName: The realm-level role to grant (e.g. "offline_access").
For your developer

Arazzo workflow keycloak:onboard-user, 8 operations: getRealm → getUsers → createUser → getUsers → resetUserPassword → getRole → addUserRealmRoleMappings → getUserRealmRoleMappings. Specs on APIs.io.

More recipes with Keycloak

Assign a User to a GroupAudit Group MembershipAudit a User's Effective AccessDecommission a ClientFederate an Identity ProviderApply a Realm Security BaselineInventory a RealmOffboard a UserProvision a Group HierarchyRegister a Confidential OIDC Client