Skip to content

User Federation ​

User Federation manages LDAP directory connections for importing and synchronizing users into Keycloak. This is found as a sub-tab within the Users admin page.

Accessing ​

Navigate to Users in the admin sidebar, then select the User Federation tab.

Provider List ​

Each configured LDAP provider shows its name and connection URL, its enabled state, how many users it has imported, and when it last synced.

Adding an LDAP Provider ​

Click Add Provider to configure a new LDAP connection:

FieldDescription
NameDisplay name for the federation provider
VendorLDAP vendor (Active Directory, OpenLDAP, Red Hat DS, etc.)
Connection URLLDAP server URL (ldap:// or ldaps://)
Bind DNDistinguished name for binding to LDAP
Bind CredentialPassword for the bind DN
Users DNBase DN for user searches
User Object ClassesLDAP object classes for user entries
Edit ModeHow Keycloak writes back to LDAP (READ_ONLY, WRITABLE, UNSYNCED)
Search ScopeLDAP search scope (ONE_LEVEL or SUBTREE)
PaginationEnable LDAP pagination for large directories
Import UsersWhether to import users into Keycloak's local database
Sync RegistrationsSync newly registered Keycloak users back to LDAP

Connection Testing ​

Two checks are available before saving, and they fail differently: Test Connection covers network reachability and the TLS handshake, while Test Authentication goes further and confirms the bind DN and credential are accepted. A connection that passes the first and fails the second is a credential problem, not a network one.

Synchronization ​

A full sync imports every user matching the filter; a changed-users sync imports only those modified since the last run, which is the one to schedule on a large directory. Two teardown actions differ in an important way: Remove Imported deletes the users that came from this provider, while Unlink Users keeps them in Keycloak and only severs the federation link.

Mapper Configuration ​

Attribute mappers control which LDAP attributes reach the Keycloak user, listed per provider as directory attribute → user attribute with the mapper's type and synchronization direction.

Mappers decide which directory attributes reach the Keycloak user, which makes them a prerequisite for SMART launches: a directory user without the fhirUser attribute cannot be resolved to a FHIR resource.

Open Mappers on a provider card to list its mappers as directory attribute → user attribute, add one (the form is built from the properties Keycloak reports for the chosen mapper type, so it adapts to the LDAP vendor), or delete one. The card itself shows a summary chip: the mapper count, or a warning when nothing writes fhirUser.

Unlike identity providers, there is no provisioning action here. The directory attribute holding the FHIR reference is deployment-specific -- it may be fhirUser, an employee number, or a vendor-specific OID -- so the dialog reports the gap and leaves the source attribute to the admin rather than guessing.

API Endpoints ​

MethodPathSummary
GET/admin/user-federation/List LDAP Federations
POST/admin/user-federation/Create LDAP Federation
GET/admin/user-federation/:idGet LDAP Federation
PUT/admin/user-federation/:idUpdate LDAP Federation
DELETE/admin/user-federation/:idDelete LDAP Federation
GET/admin/user-federation/:id/mapper-typesList LDAP Mapper Types
GET/admin/user-federation/:id/mappersList LDAP Mappers
POST/admin/user-federation/:id/mappersCreate LDAP Mapper
PUT/admin/user-federation/:id/mappers/:mapperIdUpdate LDAP Mapper
DELETE/admin/user-federation/:id/mappers/:mapperIdDelete LDAP Mapper
POST/admin/user-federation/:id/remove-importedRemove Imported Users
POST/admin/user-federation/:id/syncSync LDAP Users
POST/admin/user-federation/:id/unlinkUnlink Federated Users
GET/admin/user-federation/countGet User Federation Count
POST/admin/user-federation/test-authenticationTest LDAP Authentication
POST/admin/user-federation/test-connectionTest LDAP Connection

Proxy Smart — Healthcare Interoperability Platform