Identity Providers

Let people sign in with an account they already have — HelixIAM brokers the login, provisions the user automatically, and keeps you in control of every attribute.

What it is

HelixIAM acts as an identity broker. Instead of holding a credential itself, the realm delegates authentication to a trusted external source — another OpenID Connect or SAML 2.0 provider, an LDAP/Active Directory directory, a social login, one of the built-in EU electronic IDs (DigiD, eHerkenning, eIDAS), or an EU Digital Identity Wallet through the OpenID4VP verifier (Beta; Digital Credentials API and verify-only are Preview). When a user returns from the upstream source, Helix takes over the session.

The broker model gives you three things out of the box:

• Just-in-time (JIT) provisioning — the first time someone logs in through a provider, Helix creates the local user automatically from the upstream identity, so there is no pre-registration step.
• Account linking — an incoming federated identity can be linked to an existing local account, so one person keeps one Helix identity across multiple login methods.
• Configurable mappers — per provider, you map upstream claims/attributes onto Helix user attributes and roles (see Mappers), so downstream applications see a consistent profile regardless of where the user authenticated.

Every provider is one record with the same shape: a stable alias, a protocol that selects the broker (oidc, saml, ldap, an eID scheme, or eudi-wallet), and a flat config map of protocol-specific settings. Providers are scoped per realm — two realms may use the same alias — and are loaded and refreshed from the store at runtime, so adding or reconfiguring a provider takes effect without redeploying anything. A write refreshes its own realm at once; with several replicas, the others pick the change up within helix.federation.store.poll-interval-seconds (default 10). Both need HELIX_FEDERATION_STORE_ENABLED, which defaults to true.

Federated single logout (SLO) propagates a Helix logout back to the upstream provider where the protocol supports it, so ending a session ends it everywhere.

In the console

Providers live under the Federation & eIDs section. Each realm manages its own set.

1. Open Federation & eIDs → Identity providers to see every provider configured in the realm.
2. Click Add identity provider to launch the wizard, then choose the provider type — the fields adapt to the protocol you pick (see the sibling pages: OIDC & social, SAML, LDAP/AD, DigiD, eHerkenning, eIDAS, EU Digital Identity Wallet).
3. Provide the connection details for the upstream source — endpoints or metadata, client/SP credentials, and trust material as the protocol requires.
4. Define mappers on the provider's Mappers tab to translate the upstream identity into Helix user attributes and roles.
5. Decide account linking behaviour for returning users and confirm JIT provisioning for first-time logins.
6. Optionally enable federated SLO so logout propagates upstream, then save. The provider is picked up on the next registry refresh and appears on the realm's sign-in options.

Tip

Providers are always shown by their display name in the console and on the login page — the raw alias is only the stable key used in URLs and the API.

Over the API

All provider management lives under /admin/realms/{realm}/identity-providers. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List providers

Each entry echoes its alias, protocol, displayName, enabled flag, and the protocol-specific config map.

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

[
  { "realmId": "acme", "alias": "google",       "protocol": "oidc", "displayName": "Google",         "enabled": true },
  { "realmId": "acme", "alias": "partner-saml", "protocol": "saml", "displayName": "Partner Corp",   "enabled": true },
  { "realmId": "acme", "alias": "digid",        "protocol": "digid","displayName": "DigiD",          "enabled": true }
]

Create a provider

POST the provider record. The alias and protocol are required; config carries the protocol-specific settings — see each sibling page for the keys that protocol reads.

# 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/identity-providers" >/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 '{
        "alias": "google",
        "protocol": "oidc",
        "displayName": "Google",
        "enabled": true,
        "config": { "clientId": "…", "clientSecret": "…" }
      }' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers"

{
  "realmId": "acme",
  "alias": "google",
  "protocol": "oidc",
  "displayName": "Google",
  "enabled": true,
  "config": { "clientId": "…", "clientSecretSet": true }
}

Secrets are write-only

The admin API never returns a provider's secrets — the OIDC clientSecret, the eID SP private keys (spDecryptionPrivateKey, spSigningPrivateKey), the LDAP bind password (bindPassword, bindPw, bindCredential) and the wallet's keys. Each comes back as a "<key>Set": true|false flag instead. Secrets are stored encrypted at rest, and realm exports mask them.

On a write (POST or PUT):

You send	Effect
the secret absent, null or blank	the stored secret is kept
a value	the stored secret is replaced
"clear<Key>": "true" (e.g. "clearClientSecret": "true") without a value	the stored secret is removed
a value and its clear flag	400

So a PUT that only changes displayName can leave clientSecret out. A sync script or Terraform provider must not compare secrets it reads back: there are none to read. See the upgrade guide.

For the eID schemes (eid, digid, eherkenning, eidas) the SP signing, mutual-TLS and decryption keys can also be generated inside an HSM/KMS and then never leave it; see Key custody: eID SP keys.

Update or delete a provider

The alias is the key for every subsequent call:

# Update — PUT the full desired state
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{ "alias": "google", "protocol": "oidc", "displayName": "Google Workspace", "enabled": true, "config": { "clientId": "…", "clientSecret": "…" } }' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers/google"

# Delete — returns 204 No Content
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/$REALM/identity-providers/google"

Deleting a provider removes its links

Deleting an identity provider also deletes every federated link to it (audited as IDP_LINKS_REMOVED). A provider created later under the same alias — possibly pointing at another IdP — never signs the old linked users in; they sign in another way or are provisioned anew. Changing or deleting a provider administrators sign in through, or a BSN-authoritative one, needs the corresponding admin permissions (realm-admin for a BSN-authoritative provider).

Full endpoint set

Method & path (under /admin/realms/{realm})	Purpose
GET /identity-providers · POST /identity-providers	List / create providers
GET · PUT · DELETE /identity-providers/{alias}	Read / update / delete a provider
POST /user-federation/{alias}/sync	Import / refresh directory users (LDAP/AD — see LDAP)

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

See also

• OIDC & social brokers · SAML broker · LDAP / Active Directory
• EU eIDs: DigiD · eHerkenning · eIDAS · EU Digital Identity Wallet (Beta; DC API/verify-only Preview)
• Users & credentials — how JIT-provisioned users appear and are managed
• Authentication flows — where a broker step fits in the sign-in journey
• API reference