Single Sign-On (SSO) #

Enterprise Single Sign-On lets your team sign into eCardWidget with your existing identity provider (IdP). This is an Enterprise-plan feature.

SSO is about login. If what you want is your employee list flowing into ECW automatically (for birthdays, anniversaries, recognition), that's Directory Sync — a separate, independent feature with several methods (SCIM, API, Zapier, spreadsheet). You can set up either one without the other, or both together.

SSO vs. Directory Sync — two independent channels #

SSO (OIDC) Directory Sync
Purpose Login — people sign into ECW with your IdP Provisioning — keep the team-member directory in sync
Who it affects Admin/owner login users Team members (the people celebrated/managed; they have no ECW login)
How Browser redirect, SP-initiated OIDC SCIM push from your IdP, REST API, Zapier, or spreadsheet
Required Enterprise plan + verified domain Depends on method — SCIM needs Enterprise + verified domain; SSO is not required

ECW is a downstream consumer of identity. Your IdP is the source of truth — ECW never writes back to it. Both channels are receive-only from your directory's perspective.

Pick what you need. The setup wizard (Settings → SSO & Directory Sync) asks whether you want SSO, SCIM, or both. SCIM-only setup skips the OIDC configuration entirely (just a display name + your email domain, then domain verification) — ideal when you only want the directory synced and don't need SSO login.

What ECW supports (and doesn't) #

  • OpenID Connect only. ECW is an OIDC relying party using the authorization-code flow with PKCE (S256), SP-initiated. SAML is not supported — if your IdP catalog offers a "SAML/SSO app" wrapper, choose the OpenID Connect protocol and SP-initiated mode.
  • Signing algorithm: ID tokens must be signed RS256. RS384/PS256/ES*/EdDSA are rejected.
  • Scopes requested: openid email profile (fixed — you don't configure these in ECW).
  • The email claim is load-bearing. ECW signs a user in by the email claim in the ID token, and it must be on the domain you register (see domain matching).

Which platforms can be your IdP? #

Platform SSO with ECW?
Okta ✅ Yes — dedicated guide
Microsoft Entra ID (Azure AD) ✅ Yes — dedicated guide
Google Workspace ✅ Yes — dedicated guide
Auth0, Ping (PingOne/PingFederate), OneLogin, JumpCloud, Keycloak, SAP Cloud Identity, Oracle OCI IAM ✅ Standards-compliant OIDC — use the generic OIDC guide
Rippling ⚠️ Rippling is also an identity provider. If your plan lets you add a custom OIDC app, the generic OIDC guide applies; if you only see SAML custom apps, contact us
ADP, Workday, UKG, BambooHR, Gusto, Paylocity, … (HR platforms) ❌ Not as a sign-in provider — see below

The 4-question test for any provider not listed — if all four are "yes," it works with ECW via the generic OIDC guide, no ECW-side changes needed:

  1. Can an admin register a custom OIDC web app with ECW's two redirect URIs?
  2. Is there a public /.well-known/openid-configuration whose issuer matches the tokens?
  3. Are ID tokens signed RS256?
  4. Does the ID token carry an email claim on your verified domain?

HR platforms are not sign-in providers #

ADP, Workday, UKG and similar HR systems are the source of employee identity, not a sign-in authority — they don't act as an OIDC identity provider for apps you register yourself (they fail question 1 above). Sign-in-wise, connect ECW to the IdP your HR platform feeds — almost always Entra ID, Okta, or Google Workspace.

If your actual goal is getting your employee roster into ECW (the usual ask), you don't need SSO at all — see Directory Sync for every option, including the HR-platform → IdP → SCIM chain and direct API/Zapier/spreadsheet methods.

Setup at a glance #

  1. Register an OIDC app in your IdP (redirect URIs below). Copy the Client ID, Client Secret, and your OIDC discovery URL.
  2. In ECW: Settings → SSO & Directory Sync → Set up SSO → pick your provider → paste the three values → Save & Create SSO.
  3. Verify your email domain via a DNS-TXT record (SSO login is inactive until verified).
  4. Test Connection, then sign in from an incognito window.
  5. (Optional) Enable SCIM for automatic provisioning, and/or Require SSO to disable password login.

Redirect / callback URIs (add both to your IdP; adjust host for staging/dev):

https://app.ecardwidget.com/v2/api/sso/callback
https://app.ecardwidget.com/v2/api/pub/sender/ssoCallback

The first handles dashboard (admin) sign-in. The second handles SSO sign-in inside the eCard widget (sender verification / team-directory sending) — if it's missing, dashboard SSO works but widget sign-in fails at your IdP with a redirect-URI mismatch error.

Using a custom eCard domain (e.g. ecard.yourcompany.com)? Also register https://<your-ecard-domain>/v2/api/pub/sender/ssoCallback. Widget sign-ins currently use the app.ecardwidget.com callback even on custom-domain pages, but registering the custom-domain variant as well is harmless and future-proofs your setup.

The email claim matters #

ECW resolves the signing-in user by the email claim in the ID token and requires it to match the email domain you register (e.g. yourcompany.com). If the token's email is missing, or on a different domain, the login is rejected with sso_error=domain_mismatch.

  • ECW reads the email claim directly — it does not fall back to upn or preferred_username.
  • Make sure the email scope is granted (it's in the standard set ECW requests) and that your IdP actually populates an email address for each user. Entra in particular needs the email attribute populated or the optional claim configured — see Entra ID.
  • email_verified is honored only if your IdP sends it; providers that omit it (e.g. Entra) are fine.

Domain verification (DNS-TXT) #

After saving the config, click Verify Domain. ECW generates a token you publish as a TXT record:
Record name _ecw-domain-verify.yourcompany.com
Type TXT
Value ecw-domain-verify=<token ECW shows you>

Wait 5–15 minutes for DNS propagation, then click Check Now. SSO login stays disabled until the domain shows Verified — this proves you control the domain before ECW trusts logins for it.

Enforcing SSO (optional) #

Toggling Require SSO for sign-in disables password login for users on your domain. This is a high-impact action: ECW always asks for a fresh admin one-time passcode (OTP) before enabling it, and warns you that password login will be blocked. Turning it back off does not require an OTP. The account owner always retains a recovery path if SSO ever becomes unavailable.

Who can configure it #

  • Enterprise plan is required for all SSO/SCIM configuration actions (non-Enterprise callers get 403).
  • The account owner performs setup. Cooperators (delegated admins) can view SSO status and run Test Connection, but cannot make SSO configuration changes.

Next: pick your provider — Okta · Microsoft Entra ID · Google Workspace · Generic OIDC — or head to Directory Sync if syncing your team is the goal.

← PreviousJavaScript APINext →Okta SSO
Documentation
Getting Started