Security Identity Providers Reference

Configure external identity providers (LDAP and OIDC) for HTML5 and Rich Client operator login.

Home → Technical Reference → Platform Modules Reference → Security Module Reference → Security Designer UI Reference → Identity Providers

Security Identity Providers (Reference): configure external authentication mechanisms — LDAP directory servers and OpenID Connect (OIDC) identity providers — that the runtime consults to resolve a user's identity at login time. Each row in this table is a pluggable authentication mechanism.

Identity Providers provide:

• LDAP and Active Directory authentication (RFC 4511) — replaces the legacy single-server SecurityEnableLDAP configuration.

• OpenID Connect (OIDC) authentication for HTML5, WPF Rich Client, and Smart Client operator login.

• Per-provider DefaultPolicy that maps the authenticated user to one of the solution's Permission Groups.

• Diagnostic counters and last-error tracking, surfaced at runtime via @Security.IdentityProvider.<Name>.

• Zero-modification path for PIV and smartcard authentication — configure an OIDC row pointing at a PIV-aware IdP.

Architectural Principle: IdP Identifies; the Platform Manages

An identity provider's only job is to answer who is logging in. Once identity is resolved, every downstream concern — session lifetime, Permission Group binding, password and e-sign policies, audit trail, runtime authority — stays with the platform's existing Security machinery.

What an IdP row configures: how to validate credentials against an external system, and which Permission Group the resolved user receives.

What an IdP row does NOT configure:

• Silent-login or kiosked auto-login — scripted at the customer's LogOn Display CodeBehind via @Client.LogOnSSOAsync(providerName). The IdP table holds how to validate credentials, not which credentials to silently submit.

• Session minting or browser session state — owned by the platform's HTTP layer. The OIDC callback handler resolves identity, and the platform binds the operator session internally.

• Multi-factor authentication, conditional access, device posture, anomalous-login detection — IdP-delivered. The IdP enforces these; the platform receives the resolved identity after the IdP applied them.

• Audit and compliance posture — Workspace-scoped. See Security Module Reference for the audit story per Workspace.

The benefit of this layering: every audit, permission, e-sign, session-timeout, and password-policy mechanism continues to work unchanged regardless of which IdP a user signed in through. Customers swap IdPs without touching their Permission Groups, Policies, or Displays.

Configuration Properties

Access at Security → Identity Providers.

The discriminator column is AuthType (specific to this table), not the generic Type column reused across many tables — same every-column-unique discipline as SecuritySecrets.SecretType.

AuthOptions: Packed Configuration

AuthOptions is a Key=Value;Key=Value packed string. The Designer's edit dialog presents named fields per AuthType and writes the packed form on save; you only handle the packed string directly when scripting or inspecting.

LDAP keys

Example LDAP AuthOptions:

Server=ldaps://ad.corp.local:636;DefaultPolicy=Operators

OIDC keys

In the Designer, SSL is the SSL checkbox of the Identity Provider edit dialog — checked by default. A row saved before this option existed carries no SSL key and is treated as true, so upgraded solutions stay HTTPS-mandatory with no edit.

Example OIDC AuthOptions:

Authority=https://keycloak.corp.local/realms/factory;ClientId=fwx-runtime;ClientSecretRef=/secret:KeycloakClientSecret;RedirectUri=https://factory.corp.local/oidc/callback;Scopes=openid,profile,email,groups;UsernameClaim=preferred_username;GroupsClaim=groups;DefaultPolicy=Operators;SSL=true

Authentication Flows

A single AuthType=OIDC row serves every client path — the configuration is identical for all of them; the platform handles the differences transparently.

OIDC sign-in has one entry point on every client: @Client.LogOnSSOAsync(providerName), called from the LogOn Display CodeBehind. The platform owns the whole round-trip — opening the IdP, validating the token, resolving the identity and binding the runtime session. No token handling is written in the solution.

// LogOn Display CodeBehind - same call on HTML5, Rich Client and Smart Client
int rc = await @Client.LogOnSSOAsync("CorpEntraID");
if (rc != 0)
    @Client.UI.ShowMessageBox("SSO sign-in failed: " + rc);

The providerName argument is the Name of the Identity Provider row. On Rich Client and Smart Client it may be omitted when the solution has exactly one Active OIDC row, in which case the platform picks it; on the HTML5 Web Client the name is always required.

HTML5 (Web browser)

1. Operator opens the LogOn Display in a browser.

2. Operator clicks the Sign in with SSO button and picks an Identity Provider from the dropdown.

3. The Display CodeBehind calls @Client.LogOnSSOAsync("<Name>"). The platform opens the IdP in a popup window and keeps the client tab — and everything the operator had open in it — alive.

4. Operator authenticates in the popup (password, MFA, PIV, WebAuthn — whatever the IdP enforces).

5. The IdP returns to /oidc/callback. The platform validates the token, resolves identity, closes the popup, and binds the runtime session.

6. @Security.CurrentUser updates and the normal operator displays open.

Popup blocked. If the browser refuses the popup, the platform falls back to running the flow in the current tab. The sign-in still completes, but the client reloads on return, so the operator lands back on the startup Display instead of the one they were on. Allowing popups for the runtime URL avoids this.

Deployment requirement. RedirectUri must share its origin — scheme, host and port — with the URL the HTML5 client is served from. http://localhost:3201 and http://127.0.0.1:3201 are different origins: with that mismatch the operator authenticates successfully at the IdP and still ends up not signed in.

WPF Rich Client and Smart Client (OIDC Native-Flow SSO)

The same call, adapted per RFC 8252 (OAuth 2.0 for Native Apps): the client opens the operator's system browser (not an embedded WebView — enterprise IdPs reject those) and listens on a loopback HTTP endpoint for the redirect.

1. Operator clicks Sign in with SSO on the Rich Client LogOn Display, and the CodeBehind calls @Client.LogOnSSOAsync("<Name>").

2. The client opens the system default browser at the IdP, with the redirect pointed at its own loopback endpoint (PKCE-protected).

3. Operator authenticates against the IdP in the system browser.

4. The IdP redirect lands on the loopback endpoint the client is listening on; the platform validates the token, resolves identity, and binds the session.

5. The call returns 0 and @Security.CurrentUser reflects the signed-in operator.

Native flow is available on Rich Client and Smart Client (Windows + WPF). It is not available, and not needed, on the HTML5 Web Client, which already has a browser.

LDAP

LDAP rows have no callback flow. The user types username and password into the LogOn Display; the platform forwards the credentials to the configured LDAP Server; on success the resolved user receives the row's DefaultPolicy (or a matched Permission Group).

Configuration Examples

Active Directory via LDAP

Microsoft Entra ID (Azure AD) via OIDC

1. Register an application in Entra ID; note the Application (client) ID and Directory (tenant) ID.

2. Add a Web redirect URI: https://factory.corp.local/oidc/callback.

3. Generate a client secret; store it in Security → Secrets as EntraIDClientSecret.

4. In Security → Identity Providers, create a row:

Keycloak (self-hosted) via OIDC

1. In Keycloak, create a realm (e.g., factory).

2. Create a client fwx-runtime with client authentication on, redirect URI https://factory.corp.local/oidc/callback.

3. Copy the generated client secret; store it in Security → Secrets as KeycloakClientSecret.

4. In Security → Identity Providers, create a row pointing at the Keycloak realm:

A Keycloak instance running on plain HTTP for development (http://localhost:8080/realms/factory) additionally needs SSL=false — uncheck SSL in the edit dialog. Re-check it before the solution reaches production.

Auth0 via OIDC

1. In the Auth0 dashboard, create a Regular Web Application; note the Domain, Client ID, and Client Secret.

2. Add an Allowed Callback URL: https://factory.corp.local/oidc/callback.

3. Store the client secret in Security → Secrets as Auth0ClientSecret.

4. If group-to-Permission Group mapping is needed, add a roles claim to the ID token via an Auth0 Action (Auth0 does not emit a groups claim by default).

5. In Security → Identity Providers, create a row:

login.gov via OIDC

login.gov is the U.S. federal single sign-on service. Two operational specifics distinguish it from a typical OIDC IdP: client authentication is by signed JWT assertion (private_key_jwt), not a shared client secret, and the IdP does not emit a groups claim — every authenticated user receives the row's DefaultPolicy.

1. Register the FrameworX deployment in the login.gov partner dashboard (sandbox: https://idp.int.identitysandbox.gov; production: https://secure.login.gov). Upload the public key of the JWT signing certificate FrameworX will use for client assertion.

2. Note the assigned Client ID and select the IAL / AAL level appropriate to the deployment (IAL1 / AAL1 for basic identity; IAL2 / AAL2 when verified identity and MFA are required).

3. Add the redirect URI https://factory.corp.local/oidc/callback in the partner dashboard.

4. Store the JWT signing key reference in Security → Secrets as LoginGovSigningKey — resolved server-side at client-assertion time.

5. In Security → Identity Providers, create a row:

login.gov does not pass group claims, so omit GroupsClaim — every authenticated user falls through to the row's DefaultPolicy (typically Operators). Use the sandbox Authority (https://idp.int.identitysandbox.gov) for development; switch to https://secure.login.gov for production.

PIV and smartcard authentication

PIV is delivered through an OIDC IdP that supports certificate-based authentication (Entra ID with CBA, AD FS with smartcard, login.gov, or any OIDC-compliant IdP fronting a PIV PKI). Configure an AuthType=OIDC row pointing at the PIV-aware IdP — no special FrameworX configuration is needed. The IdP enforces the PIV cert; FrameworX receives the resolved identity.

Group Claim to Permission Group Mapping

When the OIDC IdP includes a groups claim in the ID token (per the GroupsClaim configuration), FrameworX iterates each group name in order and matches it case-exactly against the names of SecurityPermissions groups in the solution.

The first match wins. If no group name matches, the row's DefaultPolicy applies. If DefaultPolicy is empty, the platform's default behavior applies.

Practical mapping pattern: name your Permission Groups in FrameworX to match the IdP's group names exactly. Customers commonly create groups in their IdP named Operators, Engineers, Supervisors to match Permission Groups of the same names; then no per-provider mapping configuration is needed.

LDAP-side group mapping follows the same rule against the LDAP user's group memberships.

Runtime Diagnostic Properties

Each Identity Provider exposes runtime metrics readable from scripts and Display CodeBehind via @Security.IdentityProvider.<Name>:

These properties are runtime-only — they reset to zero on module restart. They do not persist across solution reload. Use them to drive an operator status panel showing IdP health.

Migration from Pre-10.1.5

Solutions upgraded from pre-10.1.5 automatically migrate the legacy LDAP configuration:

• The SecurityEnableLDAP and SecurityLDAPServer columns on the pre-10.1.5 SecurityRuntimeSettings table are read, then materialized as a single AuthType=LDAP, Active=true row in SecurityIdentityProviders with AuthOptions = "Server=<old-server>;DefaultPolicy=AD;".

• The legacy columns are then dropped from SecurityRuntimeSettings.

• Migration runs once on first open of the solution under 10.1.5+.

No script or Display change is needed to keep LDAP login working post-upgrade — the runtime CheckUser LDAP branch now reads the new table and produces identical behavior. Customers wanting to add OIDC providers add rows alongside the migrated LDAP row.

Common Mistakes

See Also

• Security Module Reference — complete security documentation.

• Security Secrets Reference — used by ClientSecretRef for OIDC client secrets.

• Security Permissions Reference — the Permission Groups that group claims and DefaultPolicy map to.

• Security Policies Reference — session timeout, password rules, e-sign — applied post-identity-resolution regardless of IdP.

In this section...