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 #

Microsoft Entra admin center → Identity → Applications → App registrations → New registration.
Name: eCardWidget.
Supported account types: Accounts in this organizational directory only (single tenant).

Redirect URI — platform Web:

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

Register, then from Overview copy the Application (client) ID (the GUID — not the internal APP00… number) and the Directory (tenant) ID.
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.
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:

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

2. Connect Entra in ECW #

Sign in as the account owner → Settings → SSO & Directory Sync → Set up SSO.
Provider: choose Microsoft Entra ID → Continue.
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
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.

Test Connection — confirm the checks pass end-to-end.
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. In ECW: SCIM tab → Enable SCIM → Save & Generate SCIM Token (copy it — shown once). Then in Entra's Provisioning 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 and configure your assignment scope. 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.