Microsoft Entra ID (Azure AD) SSO setup #

Connect Microsoft Entra ID to eCardWidget over OpenID Connect. Entra has a few provider-specific gotchas — the callouts below are the difference between a clean first login and a confusing failure.

Register this as an OpenID Connect app, not SAML. ECW uses OIDC (authorization-code flow), SP-initiated. If your process routes through a "SAML/SSO application" catalog item, set the protocol to OpenID Connect and the mode to SP-initiated.

1. Register the app in Entra #

1. Microsoft Entra admin center → Identity → Applications → App registrations → New registration.

2. Name: eCardWidget.

3. Supported account types: Accounts in this organizational directory only (single tenant).

4. Redirect URI — platform Web. Add both URIs (Entra rejects any sign-in whose redirect URI isn't registered, with error AADSTS50011):

   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 itself (sender verification / team-directory sending). If you skip the second, dashboard SSO works but clicking Sign in inside a widget fails on the Microsoft error page.

5. Register, then from Overview copy the Application (client) ID (the GUID — not the internal APP00… number) and the Directory (tenant) ID.

6. Certificates & secrets → New client secret → copy the Value (not the Secret ID). Choose the longest lifetime allowed.

   ⚠️ Entra manages the secret's expiry, not ECW. When it lapses, SSO logins stop until you create a new secret in Entra and paste it into ECW. Note the expiry date somewhere you'll see it.

7. Implicit grant / hybrid: leave Access tokens and ID tokens unchecked — ECW uses the authorization-code flow, not implicit.

API permissions — what's actually needed #

ECW does not call Microsoft Graph, so User.Read is not required. The only scopes ECW uses are the standard OIDC ones: openid, profile, email.

⚠️ If your tenant blocks user consent (common in large orgs), those scopes still need admin consent or the first login fails with AADSTS65001 "user or administrator has not consented." To pre-empt it: API permissions → Add a permission → Microsoft Graph → Delegated → openid, profile, email → Grant admin consent. You can skip User.Read.

⭐ Add the email optional claim (prevents the most common failure) #

ECW signs users in by the email claim and requires it to match your registered domain. Entra only includes email in the token when the user's mail attribute is populated — if it's absent, ECW rejects the login as sso_error=domain_mismatch (a confusing error for a missing claim).

To make it reliable:

1. App registration → Token configuration → Add optional claim → Token type: ID → email → Add.
2. Confirm your users' primary email is on the domain you'll register in ECW (e.g. @hitachienergy.com).

2. Connect Entra in ECW #

1. Sign in as the account owner → Settings → SSO & Directory Sync → Set up SSO.
2. Provider: choose Microsoft Entra ID → Continue.
3. Fill in:
   • Provider name: Microsoft Entra ID
   • Email domain: yourcompany.com
   • OIDC discovery URL — use the tenant-specific v2.0 endpoint:

     https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration
     

     ⚠️ Must be the tenant-specific v2.0 URL. Do not use /common or a v1.0 endpoint — the issuer won't match and login fails with sso_error=invalid_issuer.

   • OIDC client ID: the Application (client) ID (GUID)
   • OIDC client secret: the secret Value
4. Click Save & Create SSO. ECW auto-discovers and validates the rest of your Entra endpoints.

3. Verify your email domain #

Click Verify Domain, then publish the DNS record ECW gives you:

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

Wait 5–15 min → Check Now. SSO login is inactive until it shows Verified.

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 support@ecardwidget.com 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. (Enabling may ask for an admin OTP.)
2. Test Connection — confirm the checks pass end-to-end.
3. In a fresh incognito window: https://app.ecardwidget.com/main/login → enter a test user's email → Continue with SSO → authenticate at Microsoft → land in the ECW dashboard.

The user's name comes from the standard profile scope, so no extra name-claim setup is needed.

5. (Optional) SCIM provisioning from Entra #

Entra supports SCIM 2.0 natively — but not on the App Registration you created for SSO. Entra only offers the Provisioning configuration on Enterprise Applications, and custom App Registrations don't get that blade. So SCIM needs its own small, provisioning-only app:

Create the provisioning app: Entra admin center → Enterprise applications → New application → Create your own application → choose "Integrate any other application you don't find in the gallery (Non-gallery)" → name it e.g. eCardWidget Provisioning. This app does no sign-in — no redirect URIs, no SAML, no OIDC config. It exists solely to push directory changes to ECW, and it sits alongside (not instead of) your SSO App Registration. If your team went looking for Provisioning on the OIDC app and found nothing configurable — this is why.

In ECW: SCIM tab → Enable SCIM → Save & Generate SCIM Token (copy it — shown once). Then in the provisioning app's Provisioning → Automatic settings:

• Tenant URL — use ECW's SCIM Users Endpoint URL (the full endpoint, with /Users):

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

  Entra uses the full Users endpoint (unlike Okta, which takes the base URL and appends /Users itself). ECW's SCIM tab shows both URLs labelled for exactly this reason — copy the Users Endpoint one for Entra.

• Secret token: the ECW SCIM token.
• Test connection → should pass. Set Provisioning Status → On, then under Users and groups assign who should sync — Entra only provisions assigned users/groups, and the first cycle can take up to ~40 minutes. Default attribute mappings work for most cases; to customize, see SCIM provisioning & attribute mapping.

6. (Optional) Require SSO #

Toggle Require SSO for sign-in to disable password login for your domain (fresh admin OTP required; the owner keeps a recovery path).

Troubleshooting (Entra) #

Symptom	Fix
AADSTS50011 Reply URL mismatch	Redirect URI in Entra ≠ the ECW host. Add the exact URI under Authentication → Web.
AADSTS65001 not consented	Grant admin consent for openid/profile/email (see above).
sso_error=invalid_issuer	Discovery URL isn't the tenant-specific v2.0 endpoint. Fix the <tenant ID> / /v2.0/ path; don't use /common.
sso_error=domain_mismatch	Token has no email, or it's on another domain. Add the email optional claim and confirm the user's mail attribute is on your registered domain.
SCIM connection fails	Use the Users Endpoint URL (…/scim/v2/Users) as the Tenant URL, not the base.

More: Troubleshooting.