Skip to content

Healthcare Users ​

Manage Keycloak users that participate in SMART on FHIR flows. Users created here get Keycloak accounts and can optionally be linked to FHIR Person/Practitioner resources and external identity providers.

API Endpoints ​

MethodPathSummary
GET/admin/healthcare-users/List Healthcare Users
POST/admin/healthcare-users/Create Healthcare User
GET/admin/healthcare-users/:userIdGet Healthcare User
PUT/admin/healthcare-users/:userIdUpdate Healthcare User
DELETE/admin/healthcare-users/:userIdDelete Healthcare User
POST/admin/healthcare-users/:userId/client-roles/:clientIdAdd Client Roles to User
DELETE/admin/healthcare-users/:userId/client-roles/:clientId/:roleNameRemove Client Role from User
GET/admin/healthcare-users/:userId/federated-identitiesList Federated Identities
POST/admin/healthcare-users/:userId/federated-identities/:providerLink Federated Identity
DELETE/admin/healthcare-users/:userId/federated-identities/:providerUnlink Federated Identity
POST/admin/healthcare-users/:userId/realm-rolesAdd Realm Roles to User
DELETE/admin/healthcare-users/:userId/realm-roles/:roleNameRemove Realm Role from User

Creating a User ​

Required fields:

  • Username -- Keycloak login name
  • First name / Last name
  • Email -- used for password resets and notifications
  • Enabled -- whether the account is active immediately
  • Credentials -- initial password (can be marked temporary)

Optional fields:

  • Attributes -- key-value pairs stored on the Keycloak user (e.g., fhirUser, department)
  • Realm roles -- assign roles like clinician, admin, etc.
  • Groups -- Keycloak group membership

A user can be linked to external identity providers (SAML, OIDC, LDAP). This allows them to log in via those providers while maintaining a single Keycloak identity.

Use the federated-identities endpoints to:

  • List which providers a user is linked to
  • Link a new provider (requires the external user ID and username)
  • Unlink a provider

Launch Contexts ​

Launch context is resolved during each authorization rather than stored on the user; see Launch Context. The fhirUser attribute is the one context value kept on the user, and it decides which FHIR resource the user acts as.

Roles ​

Roles are managed separately via /admin/roles/:

MethodPathDescription
GET/admin/roles/List all realm roles
POST/admin/roles/Create role
GET/admin/roles/:roleNameGet role details
PUT/admin/roles/:roleNameUpdate role
DELETE/admin/roles/:roleNameDelete role
GET/admin/roles/clients/:clientIdList client-specific roles

Organizations ​

Users can be members of organizations (Keycloak Organizations feature):

MethodPathDescription
GET/admin/organizations/List organizations
POST/admin/organizations/Create organization
GET/admin/organizations/:orgId/membersList members
POST/admin/organizations/:orgId/membersAdd member
DELETE/admin/organizations/:orgId/members/:userIdRemove member

Organizations support per-org branding overrides via the /:orgId/branding endpoints.

User Federation (LDAP) ​

The Users page carries a User Federation sub-tab for LDAP directory connections, which imports and synchronizes users from an enterprise directory (Active Directory, OpenLDAP, and similar) into Keycloak rather than managing them here.

See User Federation for provider configuration, sync operations, and attribute mapping.

Proxy Smart — Healthcare Interoperability Platform