Generic OIDC provider setup #

Any standards-compliant OpenID Connect provider works with eCardWidget — OneLogin, Ping Identity, JumpCloud, Auth0, Keycloak, Authentik, and others. Choose OIDC (Generic) in the setup wizard.

If your source of truth is LDAP/Active Directory on-prem, front it with an OIDC layer (Authentik, Keycloak, Okta, Entra) and connect that. ECW does not federate LDAP directly.

Requirements ECW places on your IdP #

1. Register the app in your IdP #

1. Create an OIDC / Web application.
2. Redirect URI: https://app.ecardwidget.com/v2/api/sso/callback.
3. Ensure the app returns an email claim (and that it's on your organization's domain — see note below). Request/allow the email and profile scopes.
4. Copy the Client ID, Client Secret, and the provider's discovery URL.

2. The discovery URL must match the issuer exactly #

ECW validates (per RFC 8414) that your discovery URL is exactly:

<issuer>/.well-known/openid-configuration

where <issuer> is the iss value the document advertises. If the two don't line up, ECW rejects the config. Use the provider's canonical discovery URL — don't hand-assemble one against a different host or path.

3. Connect in ECW #

1. Settings → SSO & Directory Sync → Set up SSO → OIDC (Generic) → Continue.
2. Fill in Provider name, Email domain, OIDC discovery URL, Client ID, Client Secret → Save & Create SSO.
3. Verify Domain (DNS-TXT _ecw-domain-verify.yourcompany.com = ecw-domain-verify=<token>), run Test Connection, then sign in from an incognito window.

The email claim requirement #

ECW resolves the signing-in user by the email claim and requires it to be on your registered domain. It reads email directly — it does not fall back to preferred_username or upn. If your IdP puts the address elsewhere, add an email claim mapping in the IdP so the ID token carries a domain-matching email. A missing/mismatched email surfaces as sso_error=domain_mismatch.

SCIM (optional) #

If your IdP supports SCIM 2.0 provisioning, enable SCIM in ECW and paste the token. Which URL to use depends on how your connector treats the endpoint:

• Appends /Users itself (Okta-style) → use the SCIM Base URL …/v2/api/scim/v2.
• Wants the full collection URL (Entra/Google-style) → use the SCIM Users Endpoint URL …/v2/api/scim/v2/Users.

ECW's SCIM tab shows both, labelled. See SCIM provisioning & attribute mapping.

More: Troubleshooting.