Docs: OIDC resource server guide, Keycloak and Zitadel test environment (4/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.Core/Interfaces/Authentication/IJwtBearerAuthenticationService.cs

@@ -2,7 +2,7 @@
 
 namespace Grand.Business.Core.Interfaces.Authentication;
 
-[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider")]
+[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider (docs/oidc-resource-server.md)")]
 public interface IJwtBearerAuthenticationService
 {
     /// <summary>

src/Business/Grand.Business.Core/Interfaces/Customers/IUserApiService.cs

@@ -3,7 +3,7 @@
 
 namespace Grand.Business.Core.Interfaces.Customers;
 
-[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider")]
+[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider (docs/oidc-resource-server.md)")]
 public interface IUserApiService
 {
     /// <summary>

src/Core/Grand.Domain/Customers/UserApi.cs

@@ -1,6 +1,6 @@
 namespace Grand.Domain.Customers;
 
-[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider")]
+[Obsolete("API users with a shared SecretKey are deprecated - configure OidcResourceServer and use access tokens of your identity provider (docs/oidc-resource-server.md)")]
 public class UserApi : BaseEntity
 {
     public string Email { get; set; }

src/Core/Grand.Infrastructure/Configuration/OidcProtectedResource.cs

@@ -11,7 +11,7 @@ public class OidcProtectedResource
     /// <summary>Path prefix, matched case-insensitively on a segment boundary ("/api" covers "/api/x", not "/apix")</summary>
     public string PathPrefix { get; set; }
 
-    /// <summary>Canonical resource URI (RFC 8707); empty = the request's base URL + PathPrefix</summary>
+    /// <summary>Canonical resource URI (RFC 8707); empty = the Store URL of the request's store + PathPrefix</summary>
     public string Resource { get; set; }
 
     /// <summary>Additional accepted "aud" values, for providers that do not put the resource URI there</summary>

src/Web/Grand.Web/App_Data/appsettings.json

@@ -229,7 +229,7 @@
   //api for admin
   //when enabled (Development environment only), API documentation (Scalar) is available at: https://your-domain/scalar/v1
   //locally: https://localhost:44350/scalar/v1
-  //DEPRECATED: API users with tokens signed by SecretKey. Prefer OidcResourceServer; this keeps working until it is
+  //DEPRECATED: API users with tokens signed by SecretKey. Prefer OidcResourceServer (docs/oidc-resource-server.md); this keeps working until it is
   //removed in a future major version.
   "BackendAPI": {
     "Enabled": true,
@@ -243,7 +243,7 @@
     "ExpiryInMinutes": 1440
   },
   //OAuth 2.1 resource server: accept access tokens issued by an external OpenID Connect provider on protected
-  //resources (APIs, integrations, plugin endpoints)
+  //resources (APIs, integrations, plugin endpoints). See docs/oidc-resource-server.md.
   "OidcResourceServer": {
     "Enabled": false,
     //issuer of the identity provider; discovery document at {Authority}/.well-known/openid-configuration