Browser sign-in with OpenID Connect: core (5/7)

docs/oidc/.gitignore

@@ -0,0 +1 @@
+.env

docs/oidc/docker-compose.yml

@@ -0,0 +1,92 @@
+# TEST ENVIRONMENT ONLY. Placeholder credentials, plain http, no persistence guarantees.
+# Never use this file for a real installation. Guide: docs/oidc-resource-server.md
+#
+#   docker compose -f docs/oidc/docker-compose.yml up -d
+#
+# Required variables (a .env file next to this file, example in docs/oidc-resource-server.md section 10):
+#   KC_ADMIN_USER, KC_ADMIN_PASSWORD, ZITADEL_DB_PASSWORD, ZITADEL_MASTERKEY (32 chars), ZITADEL_ADMIN_PASSWORD
+# Optional: GRANDNODE_PROJECT_ID (Zitadel project id, for the claim target)
+# Ports are bound to 127.0.0.1 only.
+#
+# Keycloak 26.8.0  http://localhost:8080   admin user: KC_ADMIN_USER / KC_ADMIN_PASSWORD
+# Zitadel  v4.19.4 http://localhost:8081   admin: zitadel-admin@zitadel.localhost / ZITADEL_ADMIN_PASSWORD
+#
+# Use exactly these public URLs as OidcResourceServer:Authority and in the browser - the token issuer is built from them
+# (Keycloak: http://localhost:8080/realms/<realm>, Zitadel: http://localhost:8081).
+
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.8.0
+    # resource-indicators and cimd are experimental features in Keycloak 26.8
+    command: start-dev --features=resource-indicators,cimd
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_ADMIN_USER:?set KC_ADMIN_USER}
+      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD:?set KC_ADMIN_PASSWORD}
+    ports:
+      - "127.0.0.1:8080:8080"
+
+  zitadel-db:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: ${ZITADEL_DB_PASSWORD:?set ZITADEL_DB_PASSWORD}
+      POSTGRES_DB: zitadel
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d zitadel"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    volumes:
+      - zitadel-db-data:/var/lib/postgresql/data
+
+  zitadel:
+    # latest stable release at the time of writing (2026-10-08)
+    image: ghcr.io/zitadel/zitadel:v4.19.4
+    command: start-from-init --masterkeyFromEnv --tlsMode disabled
+    depends_on:
+      zitadel-db:
+        condition: service_healthy
+    environment:
+      # exactly 32 characters, cannot be changed after the first start
+      ZITADEL_MASTERKEY: ${ZITADEL_MASTERKEY:?set ZITADEL_MASTERKEY (32 characters)}
+      ZITADEL_DATABASE_POSTGRES_HOST: zitadel-db
+      ZITADEL_DATABASE_POSTGRES_PORT: 5432
+      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: ${ZITADEL_DB_PASSWORD:?set ZITADEL_DB_PASSWORD}
+      ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE: disable
+      ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: postgres
+      ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: ${ZITADEL_DB_PASSWORD:?set ZITADEL_DB_PASSWORD}
+      ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
+      # the public address: issuer = http://localhost:8081
+      ZITADEL_EXTERNALDOMAIN: localhost
+      ZITADEL_EXTERNALPORT: 8081
+      ZITADEL_EXTERNALSECURE: "false"
+      # use the login UI built into the zitadel container (the default in v4 is a separate "zitadel-login" container
+      # behind a reverse proxy, see https://github.com/zitadel/zitadel/tree/main/deploy/compose)
+      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: "false"
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: zitadel-admin
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: ${ZITADEL_ADMIN_PASSWORD:?set ZITADEL_ADMIN_PASSWORD}
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "false"
+      # TEST ONLY - restores SSRF exposure of Actions targets; do not copy to production.
+      # Targets on private addresses are refused by default; the e-mail target below lives in this network
+      ZITADEL_HTTPCLIENT_DENYLIST: "169.254.0.0/16"
+    ports:
+      - "127.0.0.1:8081:8080"
+
+  # Zitadel Actions v2 target that adds email, email_verified and scope to access tokens
+  # (endpoint for the target: http://zitadel-email-target:8090/)
+  zitadel-email-target:
+    image: node:22-alpine
+    command: node /app/zitadel-email-target.js
+    environment:
+      PORT: 8090
+      GRANDNODE_SCOPE: grandnode.api
+      # project role key and the id of the GrandNode project (set in .env after creating the project in Zitadel)
+      GRANDNODE_ROLE: grandnode.api
+      GRANDNODE_PROJECT_ID: ${GRANDNODE_PROJECT_ID:-}
+    volumes:
+      - ./zitadel-email-target.js:/app/zitadel-email-target.js:ro
+
+volumes:
+  zitadel-db-data:

docs/oidc/zitadel-email-target.js

@@ -0,0 +1,63 @@
+// Zitadel Actions v2 target for the "preaccesstoken" function (test environment helper, Node 18+, no dependencies).
+//
+// Zitadel puts neither `email`/`email_verified` nor a `scope` claim into JWT access tokens. The GrandNode resource
+// server links a user on first use by the verified e-mail address and checks RequiredScopes, so this target appends:
+//   email, email_verified - from the payload Zitadel sends (userinfo, falling back to the human user)
+//   scope                 - GRANDNODE_SCOPE (default "grandnode.api") ONLY when the user is entitled: the user has a
+//                           project role GRANDNODE_ROLE (default "grandnode.api") in the project GRANDNODE_PROJECT_ID
+//                           (user_grants of the payload). Not entitled: no scope claim, so GrandNode answers 403.
+//                           Zitadel sends user_grants only when the project has "Assert Roles on Authentication"
+//                           on (or the client requests urn:zitadel:iam:org:projects:roles).
+// ID tokens never pass through this function, so they never carry the scope.
+// GRANDNODE_PROJECT_ID is required; without it no scope is ever added.
+// Zitadel calls it as a "Call" target (the response is used): see docs/oidc-resource-server.md.
+// Listens on PORT (default 8090). Signature verification (ZITADEL-Signature header) is NOT done: test use only.
+const http = require('node:http');
+
+const scope = process.env.GRANDNODE_SCOPE || 'grandnode.api';
+const role = process.env.GRANDNODE_ROLE || 'grandnode.api';
+const projectId = process.env.GRANDNODE_PROJECT_ID || '';
+const port = Number(process.env.PORT || 8090);
+
+function isEntitled(payload) {
+  if (!projectId) return false;
+  const grants = Array.isArray(payload.user_grants) ? payload.user_grants : [];
+  return grants.some((g) => g && (g.projectId === projectId || g.project_id === projectId) &&
+    Array.isArray(g.roles) && g.roles.includes(role));
+}
+
+function claimsFor(payload) {
+  const info = payload.userinfo || {};
+  const human = (payload.user && payload.user.human) || {};
+  const email = info.email || (human.email && (human.email.email || human.email)) || '';
+  // Zitadel v4 sends user.human.email as a string and the flag as user.human.is_email_verified
+  const verifiedRaw = info.email_verified !== undefined
+    ? info.email_verified
+    : human.is_email_verified ?? (human.email && (human.email.is_verified ?? human.email.isVerified));
+  const claims = [];
+  if (isEntitled(payload)) claims.push({ key: 'scope', value: scope });
+  if (typeof email === 'string' && email) {
+    claims.push({ key: 'email', value: email });
+    claims.push({ key: 'email_verified', value: verifiedRaw === true });
+  }
+  return { append_claims: claims };
+}
+
+if (require.main === module) {
+  http.createServer((req, res) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try {
+        const payload = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(claimsFor(payload)));
+      } catch (e) {
+        res.writeHead(400);
+        res.end();
+      }
+    });
+  }).listen(port, () => console.log(`zitadel-email-target listening on ${port}`));
+}
+
+module.exports = { claimsFor };

src/Business/Grand.Business.Authentication/Services/OidcCustomerResolver.cs

@@ -7,6 +7,7 @@
 using Grand.Business.Core.Utilities.Authentication;
 using Grand.Business.Core.Utilities.Customers;
 using Grand.Data;
+using Grand.Domain.Common;
 using Grand.Domain.Customers;
 using Grand.Domain.Permissions;
 using Grand.Infrastructure.Configuration;
@@ -20,7 +21,7 @@
 namespace Grand.Business.Authentication.Services;
 
 /// <summary>
-///     Maps a validated access token to a customer: stored subject link; customer with the verified e-mail (link
+///     Maps a validated access token or a browser sign-in to a customer: stored subject link; customer with the verified e-mail (link
 ///     stored); registration with the Registered group only. Only active, registered, non-system accounts are used,
 ///     and one customer holds at most one identity (enforced by the link's identifier, see <see cref="OidcLinkId" />).
 ///     With per-store identity a subject has one link per store (plus the link of a customer of no store, valid in
@@ -107,14 +108,12 @@ public virtual async Task<OidcCustomerResult> Resolve(ClaimsPrincipal principal,
 
         //one identity per customer - a second subject with the same e-mail must not take over the account; the
         //link's identifier enforces it against concurrent requests, this check gives the answer in the normal case
-        var otherLink = await _externalAuthenticationRepository.GetOneAsync(x =>
-            x.ProviderSystemName == ProviderSystemName && x.CustomerId == customer.Id && x.ExternalIdentifier != sub);
-        if (otherLink != null)
-            return LinkedToOtherIdentity(customer, sub, otherLink);
+        if (await HasOtherLink(customer, sub))
+            return LinkedToOtherIdentity(customer, sub);
 
         var (linked, other) = await LinkOrGetWinner(customer, sub, email, storeId);
         if (other != null)
-            return LinkedToOtherIdentity(customer, sub, other);
+            return LinkedToOtherIdentity(customer, sub);
         if (linked?.Id != customer.Id)
             return await Usable(linked, sub, storeId);
 
@@ -123,6 +122,80 @@ public virtual async Task<OidcCustomerResult> Resolve(ClaimsPrincipal principal,
         return result;
     }
 
+    public virtual async Task<OidcLoginResult> ResolveForLogin(string sub, string email, bool emailVerified, string storeId)
+    {
+        if (string.IsNullOrEmpty(sub))
+            return OidcLoginResult.Refused(OidcLoginRefusal.InvalidIdentity);
+
+        var link = await GetLink(sub, storeId);
+        if (link != null)
+        {
+            var linked = await _customerService.GetCustomerById(link.CustomerId);
+            var reason = await Check(linked, sub, storeId);
+            return reason == Unusable.None ? OidcLoginResult.SignIn(linked) : OidcLoginResult.Refused(ToRefusal(reason));
+        }
+
+        if (string.IsNullOrWhiteSpace(email))
+            return OidcLoginResult.Refused(OidcLoginRefusal.InvalidIdentity);
+
+        var customer = await _customerService.GetCustomerByEmail(email,
+            _customerConfig.RegisterCustomersPerStore ? storeId : "");
+        if (customer == null)
+        {
+            var customerSettings = await _settingService.LoadSetting<CustomerSettings>(storeId);
+            if (customerSettings.UserRegistrationType == UserRegistrationType.Disabled)
+            {
+                _logger.LogWarning("Sign-in subject {Subject}: registration is disabled in store {StoreId}", sub, storeId);
+                return OidcLoginResult.Refused(OidcLoginRefusal.RegistrationDisabled);
+            }
+
+            return OidcLoginResult.RegistrationRequired();
+        }
+
+        var usable = await Check(customer, sub, storeId);
+        if (usable != Unusable.None)
+            return OidcLoginResult.Refused(ToRefusal(usable));
+
+        if (await HasOtherLink(customer, sub))
+        {
+            _logger.LogWarning("Sign-in subject {Subject}: customer {CustomerId} is linked to another identity", sub, customer.Id);
+            return OidcLoginResult.Refused(OidcLoginRefusal.LinkedToOtherIdentity);
+        }
+
+        //the first link of a back-office account, of an account protected by two-factor authentication, and of any account
+        //whose e-mail nobody verified, needs the account's password (and its second factor)
+        if (!emailVerified || await IsBackOfficeAccount(customer) || await HasTwoFactor(customer, storeId))
+            return OidcLoginResult.LinkRequired(customer);
+
+        return await LinkIdentity(customer, sub, email, storeId) switch {
+            OidcLinkResult.Linked => OidcLoginResult.SignIn(customer),
+            _ => OidcLoginResult.Refused(OidcLoginRefusal.LinkedToOtherIdentity)
+        };
+    }
+
+    public virtual async Task<OidcLinkResult> LinkIdentity(Customer customer, string sub, string email, string storeId)
+    {
+        ArgumentNullException.ThrowIfNull(customer);
+        ArgumentException.ThrowIfNullOrEmpty(sub);
+
+        //the link this store would use - with per-store identity a link of another store does not block this one
+        var existing = await GetLink(sub, storeId);
+        if (existing != null)
+            return existing.CustomerId == customer.Id ? OidcLinkResult.Linked : OidcLinkResult.SubjectLinkedToOtherCustomer;
+
+        if (await HasOtherLink(customer, sub))
+            return OidcLinkResult.CustomerLinkedToOtherSubject;
+
+        var (winner, other) = await LinkOrGetWinner(customer, sub, email ?? customer.Email ?? "", storeId);
+        if (other != null)
+            return OidcLinkResult.CustomerLinkedToOtherSubject;
+        if (winner?.Id != customer.Id)
+            return OidcLinkResult.SubjectLinkedToOtherCustomer;
+
+        _logger.LogInformation("Subject {Subject} linked to customer {CustomerId}", sub, customer.Id);
+        return OidcLinkResult.Linked;
+    }
+
     private async Task<OidcCustomerResult> Register(string sub, string email, string storeId)
     {
         if (!_config.AutoRegister)
@@ -169,7 +242,7 @@ await _customerManagerService.RegisterCustomer(new RegistrationRequest(customer,
         {
             //lost the race: drop the account just created and use the one the winner linked
             await _customerService.DeleteCustomer(customer, true);
-            return other != null ? LinkedToOtherIdentity(customer, sub, other) : await Usable(linked, sub, storeId);
+            return other != null ? LinkedToOtherIdentity(customer, sub) : await Usable(linked, sub, storeId);
         }
 
         //only after the link is stored, so the loser of a race sends no welcome message
@@ -220,10 +293,10 @@ private async Task<ExternalAuthentication> GetLink(string sub, string storeId)
     private string LinkStoreId(Customer customer) =>
         _customerConfig.RegisterCustomersPerStore ? customer.StoreId ?? "" : "";
 
-    private OidcCustomerResult LinkedToOtherIdentity(Customer customer, string sub, ExternalAuthentication otherLink)
+    private OidcCustomerResult LinkedToOtherIdentity(Customer customer, string sub)
     {
-        _logger.LogWarning("Access token subject {Subject}: customer {CustomerId} is already linked to subject {LinkedSubject}",
-            sub, customer.Id, otherLink.ExternalIdentifier);
+        _logger.LogWarning("Access token subject {Subject}: customer {CustomerId} is already linked to another subject",
+            sub, customer.Id);
         return OidcCustomerResult.Forbidden("The customer account is linked to another identity");
     }
 
@@ -281,38 +354,63 @@ public static string OidcLinkId(string customerId)
     ///     The checks every other login path applies: an active, registered, non-system account, and with per-store
     ///     identity one of the request's store (or of no store)
     /// </summary>
-    private async Task<OidcCustomerResult> Usable(Customer customer, string sub, string storeId)
+    private enum Unusable { None, Missing, Inactive, Unusable, OtherStore }
+
+    //the checks every other login path applies: an active, registered, non-system account, and with per-store
+    //identity one of the request's store (or of no store)
+    private async Task<Unusable> Check(Customer customer, string sub, string storeId)
     {
         if (customer == null)
         {
-            _logger.LogWarning("Access token subject {Subject} is linked to a customer that no longer exists", sub);
-            return OidcCustomerResult.Forbidden("The customer account no longer exists");
+            _logger.LogWarning("Subject {Subject} is linked to a customer that no longer exists", sub);
+            return Unusable.Missing;
         }
 
         if (!customer.Active || customer.Deleted)
         {
-            _logger.LogWarning("Access token subject {Subject}: customer {CustomerId} is inactive or deleted", sub, customer.Id);
-            return OidcCustomerResult.Forbidden("The customer account is inactive");
+            _logger.LogWarning("Subject {Subject}: customer {CustomerId} is inactive or deleted", sub, customer.Id);
+            return customer.Deleted ? Unusable.Unusable : Unusable.Inactive;
         }
 
         if (customer.IsSystemAccount() || !await _groupService.IsRegistered(customer))
         {
-            _logger.LogWarning("Access token subject {Subject}: customer {CustomerId} is a system or non-registered account",
-                sub, customer.Id);
-            return OidcCustomerResult.Forbidden("The customer account cannot be used");
+            _logger.LogWarning("Subject {Subject}: customer {CustomerId} is a system or non-registered account", sub, customer.Id);
+            return Unusable.Unusable;
         }
 
-        if (_customerConfig.RegisterCustomersPerStore && !string.IsNullOrEmpty(customer.StoreId) &&
-            customer.StoreId != storeId)
+        if (_customerConfig.RegisterCustomersPerStore && !string.IsNullOrEmpty(customer.StoreId) && customer.StoreId != storeId)
         {
-            _logger.LogWarning("Access token subject {Subject}: customer {CustomerId} belongs to store {CustomerStoreId}, not {StoreId}",
+            _logger.LogWarning("Subject {Subject}: customer {CustomerId} belongs to store {CustomerStoreId}, not {StoreId}",
                 sub, customer.Id, customer.StoreId, storeId);
-            return OidcCustomerResult.Forbidden("The account belongs to another store");
+            return Unusable.OtherStore;
         }
 
-        return OidcCustomerResult.Success(customer);
+        return Unusable.None;
     }
 
+    private async Task<OidcCustomerResult> Usable(Customer customer, string sub, string storeId) =>
+        await Check(customer, sub, storeId) switch {
+            Unusable.None => OidcCustomerResult.Success(customer),
+            Unusable.Missing => OidcCustomerResult.Forbidden("The customer account no longer exists"),
+            Unusable.Inactive => OidcCustomerResult.Forbidden("The customer account is inactive"),
+            Unusable.OtherStore => OidcCustomerResult.Forbidden("The account belongs to another store"),
+            _ => customer.Deleted
+                ? OidcCustomerResult.Forbidden("The customer account is inactive")
+                : OidcCustomerResult.Forbidden("The customer account cannot be used")
+        };
+
+    private static OidcLoginRefusal ToRefusal(Unusable reason) =>
+        reason == Unusable.Inactive ? OidcLoginRefusal.AccountInactive : OidcLoginRefusal.AccountUnusable;
+
+    private async Task<bool> HasOtherLink(Customer customer, string sub) =>
+        await _externalAuthenticationRepository.GetOneAsync(x =>
+            x.ProviderSystemName == ProviderSystemName && x.CustomerId == customer.Id && x.ExternalIdentifier != sub) != null;
+
+    //the same condition the password sign-in uses to ask for the second factor
+    private async Task<bool> HasTwoFactor(Customer customer, string storeId) =>
+        customer.GetUserFieldFromEntity<bool>(SystemCustomerFieldNames.TwoFactorEnabled) &&
+        (await _settingService.LoadSetting<CustomerSettings>(storeId)).TwoFactorAuthenticationEnabled;
+
     private async Task<bool> IsBackOfficeAccount(Customer customer) =>
         !string.IsNullOrEmpty(customer.VendorId) || !string.IsNullOrEmpty(customer.StaffStoreId) ||
         await _permissionService.Authorize(StandardPermission.ManageAccessAdminPanel, customer);