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:

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

   (Add one for each environment you'll sign in from.)
5. Sign-out redirect URIs: https://app.ecardwidget.com/.
6. Assignments: assign the people who should have access.
7. Save, then copy the Client ID and Client Secret.

Your OIDC discovery URL is:

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

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

4. Test the connection and sign in #

1. Click Test Connection — you should see each check (discovery reachable, JWKS keys, endpoints) pass.
2. 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.