Okta SSO setup #

Connect Okta to eCardWidget over OpenID Connect. This covers login (OIDC); for automatic team-member provisioning see SCIM provisioning.

Prerequisites: Enterprise plan, and you'll verify your email domain via DNS during setup. A free Okta Integrator/Developer tenant (developer.okta.com/signup) is enough to test the full flow, including SCIM.

1. Create the OIDC app in Okta #

1. Admin Console → Applications → Create App Integration.

2. Sign-in method: OIDC – OpenID Connect. Application type: Web Application. Next.

3. App name: eCardWidget.

4. Sign-in redirect URIs — add both:

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

   The first is dashboard (admin) sign-in; the second is SSO sign-in inside the eCard widget (sender verification / team-directory sending) — without it, widget sign-in fails with a redirect-URI mismatch. (Add a pair for each environment you'll sign in from.)

5. Sign-out redirect URIs: https://app.ecardwidget.com/.

6. Assignments — don't skip this. Okta offers three options here:

   • Allow everyone in your organization to access
   • Limit access to selected groups
   • Skip group assignment for now

   Pick one of the first two. If you choose Skip group assignment for now, no one is assigned to the app, so sign-in will fail after setup even though everything else looks correct — a confusing state to debug. (You can always change assignments later under the app's Assignments tab.)

7. Save, then copy the Client ID and Client Secret.

You can skip these sections if Okta shows them — eCardWidget doesn't use them: Proof of Possession, Grant Type (the default Authorization Code is what we use), and Trusted Origins. Leave them at their defaults and move on.

Your OIDC discovery URL is:

https://<YOUR-OKTA-TENANT>.okta.com/.well-known/openid-configuration

What's my Okta tenant? Your tenant (also called your Okta org or Okta domain) is your organization's unique Okta URL — e.g. acme.okta.com or acme.oktapreview.com. To find it: sign in to the Okta Admin Console, click your profile/avatar (top-right), and copy the value shown under your email — or just copy it from your browser's address bar. Drop that in place of <YOUR-OKTA-TENANT> above.

2. Connect Okta in ECW #

1. Sign in as the account owner → Settings → SSO & Directory Sync → Set up SSO.
2. Provider: choose Okta → Continue.
3. Fill in:
   • Provider name: Okta
   • Email domain: the domain your Okta users' emails use (e.g. yourcompany.com)
   • OIDC discovery URL: from above
   • OIDC client ID / client secret: from step 1
4. Click Save & Create SSO. ECW fetches and caches your Okta endpoints (authorize, token, JWKS) automatically — no other URLs to enter.

Enabling SSO may prompt for an admin OTP (emailed to the owner). Enter it to proceed.

3. Verify your email domain #

1. Click Verify Domain to generate a token.

2. Publish it as a DNS record:

   Record name	Type	Value
   _ecw-domain-verify.yourcompany.com	TXT	ecw-domain-verify=<token>

3. Wait 5–15 min, then Check Now. Domain should show Verified. (SSO login is inactive until this succeeds.)

   If the domain still isn't verified after waiting, DNS changes can take longer to propagate — give it up to an hour and click Check Now again. If it still won't verify, email [email protected] and we'll help you check the record.

4. Enable SSO, then test and sign in #

1. Turn on SSO. In Settings → SSO & Directory Sync, toggle Enable SSO. Verifying the domain does not switch login on by itself — this toggle is what activates the Continue with SSO option for your domain. (Enabling may ask for an admin OTP.)
2. Click Test Connection — you should see each check (discovery reachable, JWKS keys, endpoints) pass.
3. In a fresh incognito window, go to https://app.ecardwidget.com/main/login, enter a test user's email on the verified domain, and choose Continue with SSO. You should be redirected to Okta and land back in the ECW dashboard.

5. (Optional) Enable SCIM provisioning #

Okta can automatically create/update/deactivate ECW team members. In ECW, open the SCIM tab → Enable SCIM → Save & Generate SCIM Token (copy it — shown once). Then in Okta:

• Provisioning → Integration → SCIM connector base URL: use the SCIM Base URL ECW shows —

  https://app.ecardwidget.com/v2/api/scim/v2
  

  Do not add /Users — Okta appends it. (Pasting .../Users here is the classic cause of "Invalid user ID.")
• Authentication Mode: HTTP Header / OAuth Bearer Token → paste the ECW SCIM token.
• Test API Credentials → expect "verified successfully."
• Provisioning → To App: enable Create Users, Update User Attributes, Deactivate Users. Leave Sync Password OFF (ECW team members have no login).

Full details and attribute mapping: SCIM provisioning.

6. (Optional) Require SSO #

Once login works, toggle Require SSO for sign-in to disable password login for your domain. This asks for a fresh admin OTP and warns you before applying.

Troubleshooting (Okta) #

Symptom	Fix
sso_error=invalid_audience	Okta app audience must be the client_id (default). Check Sign On settings.
sso_error=invalid_signature	JWKS clock-skew/rotation. ECW caches Okta's JWKS ~15 min; wait or click Test Connection (cache-busting).
sso_error=replay_detected	A token was replayed (e.g. browser Back after login). Open a new tab.
sso_error=domain_mismatch	The token's email isn't on your registered domain, or has no email. Confirm the user's Okta email is on yourcompany.com.
SCIM "Invalid user ID"	You pasted the base URL with /Users. Remove the suffix.

More: Troubleshooting.