14.1 Store and plugin setup

1. Run nopCommerce on one stable HTTPS origin. Never mix localhost and a tunnel in the same flow. OIDC callbacks and SAML ACS are browser redirects/POSTs; some cloud IdPs still reject localhost as a registered URL — use ngrok / Cloudflare / staging when required (especially Entra SAML).
2. Install and enable nopStation SSO.
3. Open nopStation → SSO → Configure:
   • Enable SSO.
   • Leave Disable default login off while debugging (local form + SSO buttons). Turn it on for SSO-only (hides password form and redirects /login to the default provider).
   • Enable Emergency local admin login.
   • Set Public Base URL exactly as browsers and the IdP will see it (no trailing slash mismatch).
4. Open SSO → Identity providers → Add new.
5. After save, note Provider Id from the Edit URL (/Admin/SSO/Edit/{id}). Callbacks use that id.
6. Copy the Redirect URI / ACS / Entity ID shown on the Edit page into the IdP app registration.

14.2 Recommended settings for first tests

14.3 Verification checklist

After each IdP is configured:

1. Incognito → {PublicBaseUrl}/en/login → SSO button visible.
2. Click provider → IdP login page opens.
3. Sign in with test user → land on storefront authenticated (/en/customer/info or configured post-login path). Audit success alone is not enough — confirm the browser session on the same host as Public Base URL.
4. Admin → SSO → Links shows identity (provider + subject + email).
5. Admin → SSO → Audit shows sso.signin_succeeded.
6. Logout → session ends; optional IdP SLO if configured.
7. Fail closed: wrong client secret / wrong ACS → audit reason code, no silent admin elevation.

14.4 Emergency admin access

1. Sign out of storefront.
2. Open /login?returnUrl=%2FAdmin.
3. Local email/password for an Administrator must still work when emergency login is enabled.

14.5 Add a provider: shared nopCommerce steps

1. Admin login (emergency if needed): /login?returnUrl=%2FAdmin.
2. Configuration → Local plugins → ensure SSO is installed & enabled.
3. nopStation → SSO → Configure → save Public Base URL + emergency login.
4. nopStation → SSO → Identity providers → Add new:
   • Name (button label), e.g. Entra OIDC.
   • Preset (see sections below).
   • Protocol if not filled by preset.
   • Audience = Storefront.
5. Save once to get provider id, then reopen Edit.
6. Fill IdP fields (discovery fetch when available).
7. Paste client secret / IdP certificate.
8. Enable provider → Save.
9. Run the verification checklist (14.3).

Microsoft Entra ID / Azure AD / Office 365 (Preset: EntraId, OIDC)

Replace {providerId} in every URL below with your provider id (shown in the Edit page URL after the first save).

OIDC setup

A. Access Entra ID

1. Open Microsoft Entra admin center.
2. Sign in with your Microsoft account.
3. Go to Manage tenants and select your existing Default Directory.
4. No new tenant is required for testing.

B. Register the SSO application

1. Navigate to Entra ID → App registrations → New registration.
2. Application name: nopStation SSO (or any label you prefer).
3. Supported account types: Single tenant only – Default Directory.
4. Redirect URI platform: Web.
5. Enter the plugin OIDC callback from the provider Edit page (Redirect URI, read-only):

{PublicBaseUrl}/sso/oidc/callback/{providerId}

Example (testing): https://localhost:{port}/sso/oidc/callback/12

(If you use a Cloudflare/ngrok public URL, use that host instead of localhost — it must match Public Base URL on /Admin/SSO/Configure.)

6. Click Register.

C. Get application credentials

1. From the app Overview, copy:
   • Application (client) ID
   • Directory (tenant) ID
2. Navigate to Certificates & secrets → New client secret. Create a secret and copy its Value immediately (shown once).
3. openid profile email are OIDC scopes on the plugin authorize request—not Microsoft Graph API permissions. Do not add them in the Graph permissions blade. Add Graph permissions (e.g. User.Read or group APIs) only if you configure Graph-based overage/enrichment that actually calls Graph.
4. Token configuration (optional): add optional claims email, family_name, given_name, upn as needed.

D. Create a test user

1. Navigate to Entra ID → Users → New user.
2. Create a dedicated test user in your tenant (e.g. sso.tester@{yourtenant}.onmicrosoft.com).
3. Set the required password and complete any required first-login / MFA steps.

E. Map Entra values → /Admin/SSO/Edit/{providerId} (e.g. /Admin/SSO/Edit/12)

Also on /Admin/SSO/Configure:

F. Test user steps

1. Incognito → {PublicBaseUrl}/en/login → continue with nopStation SSO (or your provider name).
2. Sign in as the Entra test user.
3. Confirm customer created/linked under /Admin/SSO/Links.
4. Confirm /Admin/SSO/Audit shows success (filter by Customer email if needed).

G. SAML

Use the Microsoft Entra ID SAML guide (same Entra tenant; separate Enterprise application + plugin provider with Protocol Saml2).

SAML setup (Enterprise application)

Use this when testing Microsoft SAML SSO (Enterprise application → Single sign-on → SAML), not the OIDC app registration described in Microsoft Entra ID OIDC.

Replace {providerId} with your provider id after you create or import the provider.

A. Prerequisites (plugin)

1. Admin → nopStation → SSO → Configure:
   • Enable SSO = Yes
   • Public Base URL = tunnel origin (no trailing slash), e.g. https://your-tunnel.trycloudflare.com
   • Keep Emergency local admin login on while testing
2. Confirm the tunnel forwards to your store (e.g. https://localhost:{port}).
3. Decide how to create the provider (B1 or B2).

B1. Create provider manually (Add new)

1. SSO → Identity providers → Add new.
2. Set:

3. Save once → note provider id from /Admin/SSO/Edit/{providerId}.
4. Copy the read-only URLs shown on Edit (they use Public base URL + id):

5. Continue with C (Entra app), then D (paste Entra → plugin).

B2. Import IdP from metadata (recommended when you already have Entra SAML app)

On SSO → Identity providers, click Import IdP from metadata.

Dialog tip (same as admin): Provide a federation metadata URL and/or paste EntityDescriptor XML. When both are set, XML is used. Preferred entity ID selects one IdP from multi-entity metadata.

Import creates a SAML 2 draft with Issuer, IdP entity ID, SAML SSO endpoint, SLO, and IdP signing certificate.

Then on Edit:

1. Set Name = Microsoft SAML SSO
2. Set Provider preset = Entra Id (applies Microsoft claim URIs)
3. Set Public base URL = tunnel; Save
4. Set JIT / Linking = Automatic; Enabled = On; Save
5. Confirm Validation = Ready / valid
6. Copy the read-only ACS / Entity ID / Login / SLO URLs into Entra (C)

C. Create / configure Entra Enterprise application (SAML)

1. Open Microsoft Entra admin center → your tenant.
2. Identity → Applications → Enterprise applications → New application → Create your own application.
3. Name: e.g. nopStation SAML → Integrate any other application you don’t find in the gallery (Non-gallery) → Create.
4. Open the app → Single sign-on → SAML.
5. Under Basic SAML Configuration → Edit, enter plugin values from Edit (B1/B2):

Example (tunnel + provider id 12):

• Identifier: https://your-tunnel.trycloudflare.com/sso/saml/metadata/12

• Reply URL: https://your-tunnel.trycloudflare.com/sso/saml/acs/12

• Sign on URL: https://your-tunnel.trycloudflare.com/sso/login/12

• Logout URL: https://your-tunnel.trycloudflare.com/sso/saml/slo/12

6. Save Basic SAML Configuration.
7. Attributes & Claims (defaults are usually enough for Entra preset):

8. SAML Certificates:
   • Status Active
   • Download Certificate (Base64) (public only — never a private key)
   • Copy App Federation Metadata Url
9. Set up {App name} (right side): copy Login URL, Azure AD Identifier, Logout URL, and metadata URL for the plugin if you did not use Import.

D. Map Entra → /Admin/SSO/Edit/{providerId} (required IdP fields)

If Import (B2) already filled endpoints + cert, only confirm Public base URL, preset, JIT, Enabled. Otherwise fill:

Entra preset claim defaults (normally leave as-is after choosing Preset Entra Id):

Leave empty for first login: Domain / Group allow lists, role mapping, SP signing/decryption certs (unless Entra requires signed AuthnRequests or encrypted assertions).

Do not put plugin ACS/Entity ID values that still say localhost into Entra if Public base URL is the tunnel (or the reverse). After changing Public base URL, Save and re-copy the read-only URLs into Entra.

E. Test user

1. Entra → Users → New user (or use an existing cloud user with a mailbox / UPN).
2. Assign the user to the Enterprise application (Users and groups → Add user/group).
3. Complete password / MFA prompts in a normal browser first if required.

F. Test login

1. Open the store on the same host as Public base URL (tunnel URL in the address bar).
2. Incognito → /en/login → Microsoft SAML SSO (or open Sign on URL).
3. Sign in at Microsoft → return to store authenticated.
4. Confirm SSO → Linked identities and SSO → Audit (sso.signin_succeeded).
5. Optional: sign out and confirm SLO if Logout URL is configured on both sides.

G. SAML checklist / common failures

Azure AD B2C (Preset: EntraId, OIDC)

B2C is not a separate plugin preset — use Preset EntraId + Protocol Oidc with B2C policy discovery (*.b2clogin.com). Do not reuse a workforce Entra (login.microsoftonline.com) issuer for a B2C app.

Trial: Azure subscription → create an Azure AD B2C tenant (or use an existing one). Create a local B2C test user under Users.

A. User flow + app registration

1. B2C tenant → User flows → New user flow → Sign up and sign in (e.g. B2C_1_signupsignin). Recommended attributes: Email Address, Display Name, Given Name, Surname.
2. Under the flow → Application claims: enable Email Addresses, Given Name, Surname, User’s Object ID (and Display Name if needed).
3. App registrations → New registration (in the B2C tenant, not the workforce directory):
   • Supported account types: Accounts in any identity provider or organizational directory (for authenticating users with user flows).
   • Redirect URI (Web): {PublicBaseUrl}/sso/oidc/callback/{providerId} (exact; create the plugin provider first to get {providerId}).
4. Certificates & secrets → new client secret → copy once.
5. Optional: under Authentication, add front-channel logout URL later if testing RP logout (B2C end_session support varies by policy).

B. Plugin (/Admin/SSO/Edit/{id})

C. Test

1. Incognito → {PublicBaseUrl}/sso/login/{providerId} or storefront Continue with ….
2. Complete B2C sign-up / sign-in → confirm Links + Audit + customer email.

D. Limitations and notes (B2C)

• No dedicated B2C preset logo path — catalog may say Azure AD B2C but preset id is still EntraId.
• B2C SAML via custom policies is advanced; prefer OIDC user flows for testing. For SAML use Entra workforce SAML or Generic.
• Social IdPs inside B2C (Google/Facebook) still return through the B2C issuer — configure claims on the user flow, not on Google Cloud.

Okta (Preset: Okta) — OIDC and SAML

Trial: developer.okta.com/signup/ (Integrator Free Plan / Developer). Create a test user under Directory → People. Assign that user to every Okta app you create.

A. OIDC — Okta Web app

1. Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
2. Grant type: Authorization Code (PKCE on is fine for confidential web apps in this plugin).
3. Sign-in redirect URIs (exact, no trailing slash, no /en/): {PublicBaseUrl}/sso/oidc/callback/{providerId} (example: https://your-tunnel.trycloudflare.com/sso/oidc/callback/12).
4. Sign-out redirect URIs (optional): {PublicBaseUrl}/
5. Assignments → assign your test user (missing assignment → access_denied).
6. Copy Client ID, Client secret, and org domain (integrator-….okta.com or dev-xxxxx.okta.com).
7. Prefer the default custom authorization server for testing: Issuer https://{domain}/oauth2/default, Discovery https://{domain}/oauth2/default/.well-known/openid-configuration. Org issuer https://{domain} is different — pin whichever discovery returns as issuer.

B. OIDC — Authorization Server access policy (required)

If authorize returns 400 / Policy evaluation failed / access_denied with no matching policy:

1. Security → API → Authorization Servers → default → Access Policies.
2. Add Policy (e.g. nopStation OIDC Policy) → Assign to your OIDC client (or All clients) → Active.
3. Add Rule (e.g. Allow Authorization Code):
   • Grant type: Authorization Code
   • User: Any user assigned to the app (or your test user/group)
   • Scopes: Any scopes while testing (later lock to openid profile email)
   • Access: Allowed
4. Ensure no higher-priority Deny rule blocks the client.

App Assignments and AS Access Policy are separate — both must allow the user/client.

C. OIDC — plugin (/Admin/SSO/Edit/{id})

D. OIDC test

1. Incognito → {PublicBaseUrl}/sso/login/{providerId} or /en/login → Continue with Okta… (storefront returnUrl, not /Admin/... unless Audience = Both).
2. Confirm Links + Audit after success.

E. SAML — Okta app

Create a separate SAML 2.0 app (do not reuse the OIDC client).

1. Applications → Create App Integration → SAML 2.0.
2. In Okta SAML Settings (where you configure the SP):

3. Attribute statements (Sign On) — required for JIT customer create:

4. Assignments → test user.
5. User authentication (testing): prefer Password only / Any one factor. Any two factors often breaks the Okta Sign-In widget (“The page has timed out”) and causes a redirect loop back to /sso/login/{id}.
6. Open Sign On → Metadata details (or View SAML setup instructions) and copy:

F. SAML — plugin (/Admin/SSO/Edit/{id})

Recommended: paste Okta Metadata URL into Federation metadata URL → Import IdP from metadata (fills Issuer, SSO endpoint, IdP cert).

Register back into Okta: ACS + Audience from the plugin Edit page (read-only Assertion consumer URL / Entity ID).

G. SAML test

1. Incognito → {PublicBaseUrl}/sso/login/{providerId} only (or storefront SSO button with non-Admin returnUrl).
2. Complete Okta username/password without refreshing the Okta page if it warns about timeout.
3. Confirm customer created/linked + Audit.

H. SAML checklist / common errors

Auth0 (Preset: Auth0) — OIDC (primary) / SAML

Trial: auth0.com/signup → Free plan (no card required for basic testing) → create tenant + Database connection + a test user (User Management → Users → Create User, connection typically Username-Password-Authentication). Enable that connection on the application.

Copy direction (both protocols):

There is no Auth0 application type named “SAML App”. Create a Regular Web Application, then either configure OIDC under Settings or enable Addons → SAML2 Web App for SAML. Client ID / Client Secret are OIDC only — they are not substitutes for SAML issuer, SSO URL, or certificate.

A. OIDC — Regular Web Application (Auth0 Settings)

1. Applications → Create Application → Regular Web Application → Create (e.g. nopCommerce SSO).
2. Settings → Application URIs (use values from the plugin Edit page after Save — do not guess paths):

3. Copy Domain, Client ID, Client Secret from Basic Information into the plugin (keep the secret server-side only).
4. Advanced Settings → OAuth: OIDC Conformant On (default on modern tenants).
5. Connections: enable the Database (or social) connection that contains your test user.
6. RP-initiated logout: tenant Settings → Advanced → Login and Logout — enable RP-Initiated Logout End Session Endpoint Discovery if discovery lacks end_session_endpoint (tenants created before ~Nov 2023).

B. OIDC — plugin (/Admin/SSO/Edit/{id})

After Save, copy the plugin’s Callback URL back into Auth0 Allowed Callback URLs if you had not already.

C. OIDC test / errors

1. Incognito → {PublicBaseUrl}/sso/login/{providerId} → Auth0 Universal Login → Links + Audit. (Optional: Auth0 app Quickstart / Auth0 CLI login to confirm the tenant before plugin wiring.)

D. SAML — Auth0 as IdP (Addons → SAML2 Web App)

Reuse the same Regular Web Application (or create another). Open the application → Addons tab → SAML2 Web App → Settings. Putting the ACS under the main app Allowed Callback URLs alone does not enable SAML assertion issuance — the add-on must be enabled and configured.

1. Plugin first: Add new → Protocol Saml2 → Preset Auth0 → Save → copy read-only Assertion consumer URL (ACS), Entity ID, and note SSO login URL (start URL only).
2. Auth0 add-on Settings:

3. Attribute mappings (addon JSON / mappings UI) — align with plugin claim fields:

4. Enable / Save the add-on → open the Usage tab → copy IdP Login URL, Issuer, signing certificate, and/or metadata URL/XML into the plugin (Import IdP preferred when available).
5. Assign / authorize the Database connection for that application.

SSO login URL ({PublicBaseUrl}/sso/login/{providerId}) is where the shopper starts SSO on nopCommerce. It is not Auth0’s Application Callback URL and must not be pasted into Audience.

E. SAML — plugin

F. Limitations and notes (Auth0)

• No default groups/roles/company/tenant → Dynamic B2B needs Auth0 Actions + claim field names.
• Custom domains change discovery host — always Fetch after domain change.
• SAML addon attribute names vary; verify with a SAML tracer / Audit if JIT fails.
• Auth0 as SAML SP (enterprise connection inbound) is out of scope for this guide — here Auth0 is the IdP.
• Tunnel URL churn: update ACS, Audience, Allowed Callback URLs, and plugin Public base URL / Entity ID together when the public host changes.

Google OIDC (Preset: GoogleWorkspace, OIDC)

OIDC setup

A. Google account / Cloud project

1. This section is Google OIDC only (Google Cloud OAuth Web client). It does not create a Google Admin custom SAML app — that is Google Workspace SAML and needs a Workspace/Cloud Identity admin.
2. OIDC can use a consumer Google account or a Workspace user. With consent External + Testing, add the account as a Test user.
3. Open Google Cloud Console and select (or create) your project:

console.cloud.google.com/

4. Open Google Auth Platform → Clients:

console.cloud.google.com/auth/clients

B. OAuth consent screen

1. Google Auth Platform → Branding / Audience (consent screen).
2. User type:
   • Internal — only when the Cloud project is tied to an eligible Workspace/Cloud Identity org; users must be in that org. Does not enable Admin Console SAML.
   • External — while Testing, only listed test users (can include personal Gmail). Does not create a Workspace org or SAML app.
3. App name: e.g. nopStation SSO.
4. Add developer contact email; save.
5. If External + Testing: Audience → Test users → Add users. Untested accounts get Access blocked.

C. Create OAuth client

1. Clients → Create client (or Create OAuth client).
2. Application type: Web application.
3. Name: e.g. nopStation SSO.
4. Authorized redirect URIs → Add URI — must match the plugin Redirect URI exactly:

{PublicBaseUrl}/sso/oidc/callback/{providerId}

Examples:

• Local: https://localhost:{port}/sso/oidc/callback/12

• Tunnel: https://your-tunnel.trycloudflare.com/sso/oidc/callback/12

Copy the read-only Redirect URI from /Admin/SSO/Edit/{providerId} after the provider exists (save once to get an id).

5. Create → copy Client ID and Client secret immediately (secret is shown once).
6. Clients list: console.cloud.google.com/auth/clients

D. Test user

1. Workspace: Admin console → Directory → Users → Add user, or use an existing org user.
2. External/Testing: add that email under consent Test users.
3. Complete any first-login / 2-Step Verification prompts in a normal browser before SSO testing.

E. Map Google values → /Admin/SSO/Edit/{providerId}

Create provider: Add new → Protocol Oidc → Preset Google Workspace (claims/discovery hints fill automatically). Then:

Also on /Admin/SSO/Configure: enable SSO; Public Base URL must match the host used in Google redirect and in the browser.

F. Test

1. Open the store on the same host as Public base URL (tunnel or localhost — not mixed).
2. Incognito → /en/login → Continue with Google workspace SSO.
3. Sign in as a consent test user / Workspace user.
4. Confirm /Admin/SSO/Links and /Admin/SSO/Audit (sso.signin_succeeded) and /en/customer/info shows the signed-in customer.
5. If Error 400: redirect_uri_mismatch: Google client URI ≠ plugin Redirect URI (check provider id and host).
6. If audit success but UI still looks logged out: you started SSO on a different host than Public base URL; use one host only (the plugin redirects to the Public base URL when the hosts differ).

SAML setup (Google Admin custom SAML app)

Use this when testing Google Admin → custom SAML app (not Google Cloud OAuth / Google OIDC). Aligns with Google: Set up your own custom SAML app and plugin preset Google Workspace + Protocol Saml2.

A. Plugin — create provider first (get ACS / Entity ID)

1. nopStation → SSO → Configure: Enable SSO; set Public Base URL; keep emergency local admin on.
2. SSO → Identity providers → Add new:

3. Save → note {providerId} from /Admin/SSO/Edit/{providerId}.
4. Copy read-only URLs:

Leave Service provider entity ID blank unless you need a custom SP Entity ID (blank → metadata Entity ID above).

B. Google Admin — Add custom SAML app (wizard order)

1. Open Google Admin → Apps → Web and mobile apps.
2. Add app → Add custom SAML app.
3. App details: name e.g. nopStation SSO (optional icon) → Continue.
4. Google Identity Provider details (do this before SP fields):
   • Download IdP metadata (XML file) — Google does not publish a stable public federation metadata URL for custom apps.
   • Or copy SSO URL, Entity ID, and download Certificate (X.509, public only).
5. Continue.
6. Service provider details:

7. Continue → Attribute mapping (App attributes are case-sensitive; match SAML Google preset):

Optional groups: map Group membership → set plugin Groups claim to the same App attribute name.

8. Finish.
9. Open the app → User access → turn ON for Everyone, or the test OU / group / user.

If access is Off, Google shows app_not_configured_for_user (403) — not a plugin bug.

C. Plugin — map Google IdP → /Admin/SSO/Edit/{providerId}

Option A (recommended): Import IdP from metadata → paste the downloaded XML into Federation metadata XML (leave URL empty). Preferred entity ID = Google’s IdP Entity ID if the file has multiple entities.

Option B: Paste manually:

SAML Google Workspace preset defaults (normally leave after choosing preset):

D. Test user & login

1. Ensure the Workspace user exists (Directory → Users) and has User access to the SAML app.
2. Complete first-login / 2SV in a normal browser if required.
3. Incognito → {PublicBaseUrl}/en/login → Google Workspace SAML (or open SSO login URL).
4. Sign in at Google → return authenticated.
5. Confirm SSO → Links, SSO → Audit (sso.signin_succeeded), and /en/customer/info.
6. Optional IdP-initiated: Google app launcher — enable Allow IdP-initiated on the plugin only if you need that path; re-test issuer/audience.

E. Checklist / common failures

Keycloak (Preset: Keycloak) — OIDC (primary) / SAML — a free option for local testing

Install (Docker):

docker run -d --name keycloak -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Bash syntax shown; in PowerShell replace the trailing \ with a backtick (`). Recent Keycloak releases use KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD; the older KEYCLOAK_ADMIN variables are deprecated. The admin / admin credentials are for local testing only.

Open http://localhost:8080 → admin / admin. Create realm nopstation. Create a user (email + password, Email verified = On, Temporary = Off).

A. OIDC client

1. Clients → Create client → OpenID Connect → Client ID nop-sso.
2. Client authentication On (confidential). Standard flow On.
3. Valid redirect URIs: {PublicBaseUrl}/sso/oidc/callback/{providerId}
4. Web origins: {PublicBaseUrl} or +
5. Credentials → copy Client secret.
6. Protocol mappers (recommended):
   • Email, given name, family name (usually present via default scopes).
   • Group Membership → Token Claim Name groups (for group allow lists).
   • Roles: preset Roles claim is realm_access.roles (dotted path supported). Or map a flat roles claim and set the plugin field to match.

B. OIDC — plugin

C. OIDC test

Incognito → /en/login → Keycloak → Links + Audit.

D. SAML client (separate from OIDC)

1. Plugin first: Saml2 + Keycloak → Save → copy ACS + Entity ID.
2. Keycloak Clients → Create → Client type SAML → Client ID = plugin Entity ID (exact).
3. Login settings: Valid redirect URIs / Assertion Consumer Service POST URL = {PublicBaseUrl}/sso/saml/acs/{providerId} (ACS, never /sso/login/{id}).
4. NameID format: email (or username if you map email via attributes).
5. Client scopes / mappers: add attribute mappers so assertion contains:

6. Realm → Realm settings → Endpoints → SAML 2.0 Identity Provider metadata → plugin Federation metadata URL → Import IdP (or paste SSO URL + realm signing cert).
7. If Keycloak requires signed AuthnRequests: enable Sign AuthnRequests on the plugin and upload SP signing cert/key; import SP metadata into the Keycloak client.

E. SAML — plugin

F. Limitations and notes (Keycloak)

• Roles claim default OIDC is realm_access.roles (dotted path). Client roles under resource_access.{client}.roles need a manual Roles claim path.
• Prefer Group Membership mapper named groups for allow lists.
• HTTP Keycloak + HTTPS store can break cookies / mixed content; use the same scheme for both, or tunnel both.
• start-dev is for testing only — not a production Keycloak topology.

OneLogin (Preset: OneLogin) — OIDC / SAML

Trial: www.onelogin.com/developer-signup (or vendor trial). Create an Active user under Users and assign that user to each app you test (OIDC and SAML are separate apps).

Common pitfalls: OIDC access_denied (user not assigned), invalid_client (secret / Basic vs POST), SAML Access Denied (/access_denied?id=… — user not assigned), ACS set to /sso/login causing loops, and missing email attributes → customer_creation_failed.

A. OIDC app (OneLogin Admin)

1. Applications → Add App → OpenId Connect (OIDC) → Save.
2. Configuration tab:
   • Login Url = {PublicBaseUrl}/sso/login/{providerId} (not the store homepage — portal launch must hit SP start so a state transaction exists).
   • Redirect URI's = {PublicBaseUrl}/sso/oidc/callback/{providerId} (HTTPS; exact match to plugin Redirect URI).
   • Post Logout Redirect URIs = {PublicBaseUrl}/ (optional).
3. SSO tab:
   • Enable OpenID Connect = On.
   • Copy Client ID, Client Secret, Issuer URL = https://{subdomain}.onelogin.com/oidc/2.
   • Application Type = Web.
   • Token Endpoint Authentication Method = POST (recommended for this plugin) or Basic — must match plugin Client authentication.
   • Open Well-known Configuration to confirm authorization_endpoint / token_endpoint under /oidc/2/.
4. Users tab (or Access via Role): assign the test user to this app. Without assignment → access_denied / End-user does not have access to this application (often with no OneLogin password page if a session already exists).
5. Token timeout (Access / Refresh minutes): optional. This plugin uses the access token only at login (UserInfo); it does not refresh tokens or tie the nopCommerce cookie to access-token lifetime. Leave defaults.

B. OIDC — plugin (/Admin/SSO/Edit/{id})

C. Test

1. Browse the store on the same host as Public base URL (do not mix localhost and tunnel).
2. Incognito → {PublicBaseUrl}/en/login or {PublicBaseUrl}/sso/login/{providerId}.
3. Confirm Links + Audit (sso.signin_succeeded) and /en/customer/info.

D. SAML — choose the connector

In Applications → Add App, search for SAML. For nopStation:

Avoid SAML 1.1 connectors and vendor-specific apps (Adobe, DocuSign, ChatGPT, etc.).

E. SAML — OneLogin Configuration tab (SP settings from the plugin)

Create the plugin provider first (Protocol Saml2, Preset OneLogin) so Edit shows read-only URLs, then paste into OneLogin Configuration:

Example (provider id 12, Cloudflare tunnel):

• Audience = https://….trycloudflare.com/sso/saml/metadata/12
• ACS / Recipient = https://….trycloudflare.com/sso/saml/acs/12
• Login URL = https://….trycloudflare.com/sso/login/12

F. SAML — OneLogin SSO tab (IdP values → plugin)

Recommended: paste Issuer URL into plugin Federation metadata URL → Import IdP from metadata (fills Issuer, SSO endpoint, cert). Leave Preferred entity ID blank. Allow private-network metadata URL = Off for public OneLogin hosts. Federation metadata XML = only if URL import fails.

Manual plugin fields if not importing:

G. SAML — assign user (required)

OneLogin returns Access Denied / https://{subdomain}.onelogin.com/access_denied?id={appId} when the user is not assigned to this SAML app.

1. Ensure an Active user exists under directory Users.
2. Prefer assignment from the user side when the app Users tab has no Add button:
   • Users → open test user → Applications → + / Add App → select this SAML connector → Save.
3. Or Applications → Access → attach a role that includes the user.
4. Confirm the user → Applications list shows the SAML app.

H. SAML — Parameters (email for JIT)

On Parameters, map NameID / email (or User.Email) so the assertion includes a usable mailbox. Missing email → plugin customer_creation_failed.

I. SAML test

1. Incognito → {PublicBaseUrl}/sso/login/{providerId} (or ?forceSso=true after a cooldown page).
2. Sign in as the assigned OneLogin user.
3. Do not refresh a timed-out OneLogin page — restart from /sso/login/{id}.
4. Confirm Links + Audit and /en/customer/info.

J. common errors (OIDC + SAML checklist)

K. Limitations and notes

• Claim name mismatch on SAML (User.* vs short names) — always check Parameters.
• Groups often require extra Parameters; empty groups → allow-list deny.
• Custom domain changes discovery host — always Fetch after change.
• SCIM is separate from SAML login; use a SCIM+SAML connector only when testing provisioning.

PingOne / PingFederate (Preset: Ping)

Trial: www.pingidentity.com/en/try-ping.html (PingOne). Prefer PingOne OIDC for cloud trials; PingFederate needs a test or evaluation VM. Preset Ping is dual-protocol (OIDC default).

A. PingOne OIDC

1. Create a Worker / population + test user; assign the user to the application.
2. Applications → Add → OIDC Web App (or OIDC + Authorization Code).
3. Redirect URIs = {PublicBaseUrl}/sso/oidc/callback/{providerId}.
4. Enable Authorization Code; create/copy Client Secret.
5. Open Configuration / URLs and copy discovery exactly:

https://auth.pingone.{region}/{envId}/as/.well-known/openid-configuration

6. Issuer shape: https://auth.pingone.{region}/{envId}/as
7. Attribute / resource scopes: ensure email (and profile names) are released to the token / UserInfo.

B. OIDC — plugin

C. PingFederate / PingOne SAML

1. Plugin first: Saml2 + Ping → copy ACS + Entity ID.
2. Create SAML SP connection; ACS = plugin ACS (POST); Entity ID = plugin Entity ID.
3. Prefer IdP metadata export → plugin Import IdP, or paste Issuer + SSO URL + signing cert.
4. Attribute contract — confirm against the assertion. Ping SAML preset defaults:

5. Enable Sign AuthnRequests + upload SP signing cert/key when Ping requires signed requests.
6. Assign the test user / group to the SP connection.

D. Test / errors

E. Limitations and notes

• PAR / DPoP / PingOne advanced OAuth features are not used (authorization code + optional PKCE only).
• end_session is often …/as/signoff — register post-logout URL on Ping when testing RP logout.
• PingFederate attribute contracts are highly custom — treat presets as hints, not guarantees.

ADFS (Preset: Adfs, SAML only)

Test setup: Windows Server with AD DS + AD FS (Azure VM is fine). Create [email protected]. No public SaaS trial. Preset Adfs appears only for Protocol Saml2.

A. Relying Party Trust (SAML)

1. Plugin first: Saml2 + Adfs → Save → copy Entity ID + ACS.
2. AD FS Management → Relying Party Trusts → Add.
3. Identifier = plugin Entity ID ({PublicBaseUrl}/sso/saml/metadata/{providerId} or custom SP Entity ID).
4. Endpoint: SAML Assertion Consumer → POST → {PublicBaseUrl}/sso/saml/acs/{providerId} (never /sso/login/{id}).
5. Optional: SAML Logout endpoints if testing SLO.
6. Issuance transform rules must emit claim types that match the Adfs preset (Microsoft URIs), or change plugin claim fields to match your rules:

FriendlyName short names also resolve (plugin indexes Name and FriendlyName).

7. Export Token-signing certificate (Base64) → plugin IdP signing certificate (or import metadata).
8. Federation metadata: https://{adfs-host}/FederationMetadata/2007-06/FederationMetadata.xml → Import IdP. If private CA / TLS fails, download XML on the ADFS host and paste XML.

B. Plugin

C. OIDC on ADFS

Only if the farm exposes OIDC (newer AD FS + Application Groups). There is no Adfs+OIDC preset — use Generic + OIDC with the farm discovery URL. Most setups should stay on SAML.

D. Test / errors

E. Limitations and notes

• WS-Federation unsupported — SAML 2.0 or OIDC only.
• Response signing vs assertion signing policies must match what the plugin validates.
• ADFS claim rules (LDAP rules) are the most common source of setup problems — inspect one assertion to confirm the claim types.

JumpCloud (Preset: JumpCloud) — SAML (default) / OIDC

Trial: jumpcloud.com/ → Admin Portal. Create a user; bind the user to the SSO app. Use the correct regional admin URL if the org is not US-hosted.

A. Custom SAML

1. Plugin first: Saml2 + JumpCloud → copy Entity ID + ACS.
2. Access → SSO Applications → + Add New Application → Custom Application → Configure SSO with SAML.
3. Display label → Save → Configure.
4. SP Entity ID = plugin Entity ID; ACS URL = {PublicBaseUrl}/sso/saml/acs/{providerId}.
5. Optional: upload SP metadata from {PublicBaseUrl}/sso/saml/metadata/{providerId}.
6. Attribute mapping (matches JumpCloud SAML preset): email, firstname, lastname, username; groups often memberOf or custom — set plugin Groups claim to match.
7. Download IdP certificate / metadata → plugin Import IdP or paste cert + SSO URL + Issuer (IdP Entity ID).
8. Bind user / group to the application (missing bind → JumpCloud access error).

B. SAML — plugin

C. OIDC (Preset JumpCloud, Protocol Oidc)

1. Add Custom Application → Configure SSO with OIDC (separate app from SAML).
2. Redirect URIs = {PublicBaseUrl}/sso/oidc/callback/{providerId}.
3. Client Authentication = Client Secret POST (or None + keep plugin Require PKCE On).
4. Login URL (optional) = {PublicBaseUrl}/sso/login/{providerId} for User Portal.
5. Subject Claim in JumpCloud: default JumpCloud User ID → plugin Subject claim sub.
6. Copy Client ID, Client Secret, Discovery URL from the SSO tab (often https://oauth.id.jumpcloud.com/.well-known/openid-configuration — confirm in console).
7. Plugin: Protocol Oidc, Preset JumpCloud → Fetch discovery → paste credentials. Username claim preset = email.

D. Test / errors

E. Limitations and notes

• Group attribute naming varies by app template.
• JumpCloud SCIM provisioning is configured separately from SSO login.

Salesforce as IdP (Preset: Generic, SAML)

Trial: developer.salesforce.com/signup → Developer Edition. There is no dedicated Salesforce SSOPreset — catalog entry maps to Generic.

A. Enable Salesforce Identity Provider

1. Setup → Identity → Identity Provider → Enable; download the IdP certificate.
2. Note the Salesforce IdP Entity ID / SSO URL from the Identity Provider page (or metadata).

B. Connected App (Service Provider)

1. Plugin first: Protocol Saml2, Preset Generic, catalog Salesforce or Custom IDP → Save → copy ACS + Entity ID.
2. Setup → App Manager → New Connected App (or Enable IdP for an existing Connected App):
   • Entity ID = plugin Entity ID
   • ACS URL = {PublicBaseUrl}/sso/saml/acs/{providerId} (HTTP-POST)
   • Subject Type / NameID: Email or Federation ID (align with plugin Subject / Email claims)
3. Map custom attributes so the assertion includes a mailbox the plugin can read (email, or set Email claim to the Salesforce attribute Name).
4. Profiles / Permission Sets: grant the Connected App to the test user.

C. Plugin

D. Test / errors

E. Limitations and notes

• Salesforce as SP (Salesforce login via external IdP) is a different product surface — this section is Salesforce as IdP only.
• OIDC via Salesforce is uncommon for this plugin path; prefer SAML Generic.

Generic / Custom IDP and catalog vendors

Use for Shibboleth, ForgeRock/OpenAM, CyberArk, SiteMinder, FusionAuth, SimpleSAMLphp, Duo SSO, WSO2, Gluu, SURFconext, ClassLink, Absorb LMS, WordPress-as-IdP, Salesforce (section 27), and any other provider without a dedicated preset. (JumpCloud OIDC now has a first-class dual preset — prefer JumpCloud OIDC over Generic.)

A. OIDC

1. Obtain Client ID, Client Secret, discovery URL (or Auth / Token / JWKS / Issuer manually).
2. Plugin: Protocol Oidc, Preset Generic → Discovery → Fetch OIDC discovery.
3. Pin Issuer to discovery issuer; set Email / Username / Groups from a decoded ID token.
4. Allowlist redirect URI exactly; match Client Secret Post vs Basic vs None+PKCE.
5. PKCE S256 is sent when Require PKCE is On — IdP must accept code_challenge.
6. Confidential client (secret) or Private Key JWT / None+PKCE as configured — no silent public-client fallback beyond those options.
7. Nested claims: dotted paths work (e.g. realm_access.roles). Arrays such as B2C-style emails resolve to the first usable mailbox.

B. SAML

1. Protocol Saml2, Preset Generic.
2. Prefer Import IdP from federation metadata (URL or XML). If URL fails (BOM, TLS, auth wall), paste XML.
3. On IdP: register SP Entity ID + ACS (+ SLO) from plugin SP URLs / SP metadata. ACS must be /sso/saml/acs/{id} — never /sso/login/{id}.
4. Attribute Name and FriendlyName both resolve — Shibboleth long URIs or short FriendlyNames work.
5. NameID format: align EmailAddress / Persistent / Transient with IdP; Transient needs a stable Subject claim mapping plus a separate Email attribute for JIT.
6. Encrypted assertions: upload SP decryption cert/key; signed AuthnRequests: upload SP signing cert/key.

C. Generic checklist

• Validation = Ready (replace all {placeholder} hints before enable)
• Login → Links + Audit success
• Email claim present for JIT (or NameID email-shaped)
• Groups claim if Dynamic B2B / allow lists used
• Optional: logout (OIDC end_session or SAML SLO), IdP-initiated (Allow IdP-initiated On)

D. Limitations and notes

• Catalog logo ≠ verified integration.
• Artifact binding, SOAP SLO, WS-Fed, PAR, DPoP, JWE — not supported.
• Object-valued UserInfo JSON properties are retained as raw JSON for dotted paths; non-scalar nested objects are not JIT fields by themselves.