SSO & Directory Sync #

Enterprise Single Sign-On lets your team sign into eCardWidget with your existing identity provider (IdP), and SCIM provisioning keeps your team-member directory in sync automatically. This is an Enterprise-plan feature.

Okta · Microsoft Entra ID · Google Workspace · Any OIDC provider
SCIM provisioning & attribute mapping
Troubleshooting

How it works — two independent channels #

	SSO (OIDC)	SCIM 2.0
Purpose	Login — people sign into ECW with your IdP	Provisioning — push directory members into ECW
Direction	Browser redirect, SP-initiated	IdP pushes create/update/deactivate to ECW
Who it affects	Admin/owner login users	Team members (the people celebrated/managed; they have no ECW login)
Required	Enterprise plan + verified domain	SSO configured first, then enable SCIM

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.

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).

Setup at a glance #

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

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

https://app.ecardwidget.com/v2/api/sso/callback

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 — then set up SCIM provisioning.