Credential Synchronization
Credential Synchronization automatically turns users from Database Provider, LDAP Active Directory, API Authentication Provider, and OIDC Provider (Keycloak only) sources into Credential records, either on a schedule or on manual trigger. This keeps credentials centrally up to date from the external source instead of being created manually for each provider.
Sync Profile
Each identity provider (Database Provider, LDAP Active Directory, API Authentication Provider, OIDC Provider) has a separate Sync Profile (or, for OIDC, Synchronization) tab in its edit screen. The common fields in this tab are:
| Field | Description |
|---|---|
| Enable Synchronization | When enabled, credentials are synchronized from this source according to the configured schedule. When disabled, neither the scheduled nor the manual synchronization runs. |
| Cron Expression | A Quartz cron expression that determines how often synchronization runs (e.g. 0 0 2 * * ?). If left empty, synchronization can only be triggered manually from the Synchronization screen. |
| Deactivation Mode | The action applied to credentials whose corresponding user is no longer present in the source on the last run: • Disable (recoverable) — the credential is disabled but its record is kept. This is the default. • Delete (irreversible) — the credential is permanently deleted. • None (keep as is) — no action is taken; drift is accepted. |
Provider-specific additional fields are described below.
LDAP Active Directory
| Field | Description |
|---|---|
| Root OU DN | The root DN of the OU (Organizational Unit) tree to synchronize. Example: OU=Users,DC=acme,DC=corp |
LDAP synchronization synchronizes not only users but also the organization tree the users belong to. The OIDC (Keycloak) source can also synchronize the group tree in addition to users when Synchronize Groups is enabled. The remaining sources (Database, API) synchronize users only.
Database Provider
| Field | Description |
|---|---|
| User List Query | A parameterless SELECT statement that returns the users to synchronize. The returned columns must use the following aliases: username (required), email, full_name. Example: select login as username, mail as email, display_name as full_name from users |
API Authentication Provider
| Field | Description |
|---|---|
| User List URL | The endpoint that returns the list of users to synchronize. |
| HTTP Method | The HTTP method used when calling the user list endpoint. |
| Timeout | The request is terminated after this many seconds. |
| Request Body | An optional request body sent to the user list endpoint (for POST/PUT). |
| Request Headers | Optional HTTP headers sent with the user list request (e.g. Authorization). |
| Users Array JSON Path | The JSON Path expression to the user array in the response. Default: $ |
| Username JSON Path | The JSON Path expression to the username within a user item. Required. |
| Email JSON Path | The JSON Path expression to the email within a user item. |
| Full Name JSON Path | The JSON Path expression to the full name within a user item. |
OIDC Provider (Keycloak)
Available only when the provider's Vendor is Keycloak — see OIDC Provider for the full field reference.
| Field | Description |
|---|---|
| Realm | The Keycloak realm to synchronize from. |
| Admin API Base URL | The base URL of the Keycloak Admin REST API. |
| Sync Client ID | The service-account client used to call the Admin API. Requires, at minimum, the view-users and query-groups realm-management roles — see Keycloak Service Account Roles. |
| Sync Page Size | The page size used when paging through Keycloak's user list. Default: 250. |
| Synchronize Groups | When enabled, the realm's group tree is also synchronized as Credential organizations. |
| Role Sync Source | Realm Roles, Client Roles, or Groups — which Keycloak role assignment becomes the synchronized user's roles. |
Unlike the other three sources, users synchronized from Keycloak are passwordless — the password stays with Keycloak, and authentication is verified through the OIDC Authentication policy's token validation, not through a stored password. See Password Model and Username Contract.
Synchronization Status and History
The screen opened from Identity > Providers > Synchronization lists LDAP, Database, API, and OIDC sources in separate tabs. Each row shows:
| Field | Description |
|---|---|
| Name | The name of the identity provider. |
| Type | The source type (LDAP / Database / API / OIDC). |
| Schedule | The configured cron expression. |
| Status | The job status: Scheduled, Running, Paused, Blocked, Complete, Error, or Undefined (never run). |
| Last Synchronized | The completion time of the last run. |
| Upserted, Deactivated, Skipped, Errors | The record counts processed on the last run. |
The Synchronize Now button on this screen triggers synchronization for the corresponding source immediately, without waiting for its schedule.
Synchronize Now cannot be run for a source whose synchronization is disabled (the Enable Synchronization field is off).
Synchronize Now is also reachable from an individual synchronized record's own detail screen — the Synchronization tab/section on a credential or organization — for users with identity management permission. Triggering it there runs the same synchronization for the record's entire source provider, not only that one record.
Run History
Beyond the last-run snapshot in the table above, Apinizer keeps a permanent record of every synchronization run. A Synchronization History card appears at the bottom of two screens:
- The Identity > Providers > Synchronization screen described above — the card here lists runs from every source in the current project, with a Source column identifying which provider each row belongs to.
- Each provider's own view screen (LDAP Active Directory, Database Provider, API Authentication Provider, OIDC Provider) — the same card, scoped to that source only, without the Source column.
Both surfaces show the same columns, paged from the server (10 / 20 / 50 rows per page):
| Column | Description |
|---|---|
| Source | The provider's name and type. Shown only on the project-wide Synchronization screen. |
| Started | The run's start time. |
| Duration | How long the run took. |
| Trigger | Scheduled or Manual; for a manual run, the triggering administrator's username is shown underneath. |
| Result | Success, Warning, or Failed — see below. |
| Upserted, Deactivated, Skipped, Errors | The record counts processed by this run. |
| Reason | A translated explanation of the result. |
Every run is recorded — including a run that failed outright and a run that was rejected during pre-checks before synchronization could even start (for example, a missing connection or a required field left empty). The run an administrator is looking for is often the one that didn't work.
A Warning result means the run finished without error, but the source returned zero users. To keep a transient source outage from causing a mass deactivation, this run's deactivation/reconciliation step is skipped entirely — no credential is upserted, deactivated, or skipped-and-counted for it. Check the source's user filter, base DN, or query settings.
The source name recorded in history is a snapshot taken at the time the run executed — if the provider is later renamed or deleted, its history rows keep the name they had when the run happened.
Retention
History records are not deleted automatically. An administrator can turn on automatic cleanup for the Identity Synchronization History entry on the Application Log Cleanup Tasks screen; while it stays off (the default), no history record is ever removed regardless of age.
Audit Attribution
When a synchronization run changes a credential, the resulting entry in Audit Records shows its Principal as sync:<SOURCE_TYPE>:<source name> (for example sync:LDAP:corp-ad or sync:OIDC:keycloak-prod) instead of the generic SYSTEM — so a synchronization-driven change can be told apart from one made by a person, and traced back to the source that made it. The administrator who manually triggered the run is not part of this value; that name appears in the Trigger column of the Run History table instead.
Behavior and Safety Notes
- If a manually created (non-sync-managed) credential's username also exists in the source, synchronization does not overwrite that record; an administrator must resolve the conflict.
- If a credential is already managed by another source (for example LDAP), a different source (for example Database) does not take it over.
- If the same username already exists in another project, synchronization does not create a new credential with that username in a different project.
- If the user list cannot be fetched from the source (connection error, etc.) or the source returns zero users, the deactivation step for that run is skipped so that a transient source outage cannot cause a mass deactivation.
Related Pages
For provider connection settings, see Database Provider, LDAP Active Directory, API Authentication Provider, and OIDC Provider. For the synchronized records, see Credentials.