feat(server): improve oidc compatibility (#14686)

fix #13938 fix #14683 fix #14532 #### PR Dependency Tree * **PR #14686** 👈 This tree was auto-generated by [Charcoal](https://github.com/danerwilliams/charcoal)  ## Summary by CodeRabbit * **New Features** * Flexible OIDC claim mapping for email/name, automatic OIDC discovery retry with exponential backoff, and explicit OAuth flow modes (popup vs redirect) propagated through the auth flow. * **Bug Fixes** * Stricter OIDC email validation, clearer error messages listing attempted claim candidates, and improved callback redirect handling for various flow scenarios. * **Tests** * Added unit tests covering OIDC behaviors, backoff scheduler/promise utilities, and frontend OAuth flow parsing/redirect logic.
2026-07-17 01:56:27 +08:00 · 2026-03-20 04:02:37 +08:00
parent 1ffb8c922c
commit 16a8f17717
9 changed files with 807 additions and 77 deletions
@@ -1,9 +1,10 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
 import { createRemoteJWKSet, type JWTPayload, jwtVerify } from 'jose';
 import { omit } from 'lodash-es';
 import { z } from 'zod';

 import {
+  ExponentialBackoffScheduler,
  InvalidAuthState,
  InvalidOauthResponse,
  URLHelper,
@@ -35,7 +36,7 @@ const OIDCUserInfoSchema = z
  .object({
    sub: z.string(),
    preferred_username: z.string().optional(),
-    email: z.string().email(),
+    email: z.string().optional(),
    name: z.string().optional(),
    email_verified: z
      .union([z.boolean(), z.enum(['true', 'false', '1', '0', 'yes', 'no'])])
@@ -44,6 +45,8 @@ const OIDCUserInfoSchema = z
  })
  .passthrough();

+const OIDCEmailSchema = z.string().email();
+
 const OIDCConfigurationSchema = z.object({
  authorization_endpoint: z.string().url(),
  token_endpoint: z.string().url(),
@@ -54,16 +57,28 @@ const OIDCConfigurationSchema = z.object({

 type OIDCConfiguration = z.infer<typeof OIDCConfigurationSchema>;

+const OIDC_DISCOVERY_INITIAL_RETRY_DELAY = 1000;
+const OIDC_DISCOVERY_MAX_RETRY_DELAY = 60_000;
+
@Injectable()
-export class OIDCProvider extends OAuthProvider {
+export class OIDCProvider extends OAuthProvider implements OnModuleDestroy {
  override provider = OAuthProviderName.OIDC;
  #endpoints: OIDCConfiguration | null = null;
  #jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+  readonly #retryScheduler = new ExponentialBackoffScheduler({
+    baseDelayMs: OIDC_DISCOVERY_INITIAL_RETRY_DELAY,
+    maxDelayMs: OIDC_DISCOVERY_MAX_RETRY_DELAY,
+  });
+  #validationGeneration = 0;

  constructor(private readonly url: URLHelper) {
    super();
  }

+  onModuleDestroy() {
+    this.#retryScheduler.clear();
+  }
+
  override get requiresPkce() {
    return true;
  }
@@ -87,58 +102,109 @@ export class OIDCProvider extends OAuthProvider {
  }

  protected override setup() {
-    const validate = async () => {
-      this.#endpoints = null;
-      this.#jwks = null;
+    const generation = ++this.#validationGeneration;
+    this.#retryScheduler.clear();

-      if (super.configured) {
-        const config = this.config as OAuthOIDCProviderConfig;
-        if (!config.issuer) {
-          this.logger.error('Missing OIDC issuer configuration');
-          super.setup();
-          return;
-        }
-
-        try {
-          const res = await fetch(
-            `${config.issuer}/.well-known/openid-configuration`,
-            {
-              method: 'GET',
-              headers: { Accept: 'application/json' },
-            }
-          );
-
-          if (res.ok) {
-            const configuration = OIDCConfigurationSchema.parse(
-              await res.json()
-            );
-            if (
-              this.normalizeIssuer(config.issuer) !==
-              this.normalizeIssuer(configuration.issuer)
-            ) {
-              this.logger.error(
-                `OIDC issuer mismatch, expected ${config.issuer}, got ${configuration.issuer}`
-              );
-            } else {
-              this.#endpoints = configuration;
-              this.#jwks = createRemoteJWKSet(new URL(configuration.jwks_uri));
-            }
-          } else {
-            this.logger.error(`Invalid OIDC issuer ${config.issuer}`);
-          }
-        } catch (e) {
-          this.logger.error('Failed to validate OIDC configuration', e);
-        }
-      }
-
-      super.setup();
-    };
-
-    validate().catch(() => {
+    this.validateAndSync(generation).catch(() => {
      /* noop */
    });
  }

+  private async validateAndSync(generation: number) {
+    if (generation !== this.#validationGeneration) {
+      return;
+    }
+
+    if (!super.configured) {
+      this.resetState();
+      this.#retryScheduler.reset();
+      super.setup();
+      return;
+    }
+
+    const config = this.config as OAuthOIDCProviderConfig;
+    if (!config.issuer) {
+      this.logger.error('Missing OIDC issuer configuration');
+      this.resetState();
+      this.#retryScheduler.reset();
+      super.setup();
+      return;
+    }
+
+    try {
+      const res = await fetch(
+        `${config.issuer}/.well-known/openid-configuration`,
+        {
+          method: 'GET',
+          headers: { Accept: 'application/json' },
+        }
+      );
+
+      if (generation !== this.#validationGeneration) {
+        return;
+      }
+
+      if (!res.ok) {
+        this.logger.error(`Invalid OIDC issuer ${config.issuer}`);
+        this.onValidationFailure(generation);
+        return;
+      }
+
+      const configuration = OIDCConfigurationSchema.parse(await res.json());
+      if (
+        this.normalizeIssuer(config.issuer) !==
+        this.normalizeIssuer(configuration.issuer)
+      ) {
+        this.logger.error(
+          `OIDC issuer mismatch, expected ${config.issuer}, got ${configuration.issuer}`
+        );
+        this.onValidationFailure(generation);
+        return;
+      }
+
+      this.#endpoints = configuration;
+      this.#jwks = createRemoteJWKSet(new URL(configuration.jwks_uri));
+      this.#retryScheduler.reset();
+      super.setup();
+    } catch (e) {
+      if (generation !== this.#validationGeneration) {
+        return;
+      }
+      this.logger.error('Failed to validate OIDC configuration', e);
+      this.onValidationFailure(generation);
+    }
+  }
+
+  private onValidationFailure(generation: number) {
+    this.resetState();
+    super.setup();
+    this.scheduleRetry(generation);
+  }
+
+  private scheduleRetry(generation: number) {
+    if (generation !== this.#validationGeneration) {
+      return;
+    }
+
+    const delay = this.#retryScheduler.schedule(() => {
+      this.validateAndSync(generation).catch(() => {
+        /* noop */
+      });
+    });
+    if (delay === null) {
+      return;
+    }
+
+    this.logger.warn(
+      `OIDC discovery validation failed, retrying in ${delay}ms`
+    );
+  }
+
+  private resetState() {
+    this.#endpoints = null;
+    this.#jwks = null;
+  }
+
  getAuthUrl(state: string): string {
    const parsedState = this.parseStatePayload(state);
    const nonce = parsedState?.state ?? state;
@@ -291,6 +357,68 @@ export class OIDCProvider extends OAuthProvider {
    return undefined;
  }

+  private claimCandidates(
+    configuredClaim: string | undefined,
+    defaultClaim: string
+  ) {
+    if (typeof configuredClaim === 'string' && configuredClaim.length > 0) {
+      return [configuredClaim];
+    }
+    return [defaultClaim];
+  }
+
+  private formatClaimCandidates(claims: string[]) {
+    return claims.map(claim => `"${claim}"`).join(', ');
+  }
+
+  private resolveStringClaim(
+    claims: string[],
+    ...sources: Array<Record<string, unknown>>
+  ) {
+    for (const claim of claims) {
+      for (const source of sources) {
+        const value = this.extractString(source[claim]);
+        if (value) {
+          return value;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  private resolveBooleanClaim(
+    claims: string[],
+    ...sources: Array<Record<string, unknown>>
+  ) {
+    for (const claim of claims) {
+      for (const source of sources) {
+        const value = this.extractBoolean(source[claim]);
+        if (value !== undefined) {
+          return value;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  private resolveEmailClaim(
+    claims: string[],
+    ...sources: Array<Record<string, unknown>>
+  ) {
+    for (const claim of claims) {
+      for (const source of sources) {
+        const value = this.extractString(source[claim]);
+        if (value && OIDCEmailSchema.safeParse(value).success) {
+          return value;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
  async getUser(tokens: Tokens, state: OAuthState): Promise<OAuthAccount> {
    if (!tokens.idToken) {
      throw new InvalidOauthResponse({
@@ -315,6 +443,8 @@ export class OIDCProvider extends OAuthProvider {
      { treatServerErrorAsInvalid: true }
    );
    const user = OIDCUserInfoSchema.parse(rawUser);
+    const userClaims = user as Record<string, unknown>;
+    const idTokenClaimsRecord = idTokenClaims as Record<string, unknown>;

    if (!user.sub || !idTokenClaims.sub) {
      throw new InvalidOauthResponse({
@@ -327,22 +457,29 @@ export class OIDCProvider extends OAuthProvider {
    }

    const args = this.config.args ?? {};
+    const idClaims = this.claimCandidates(args.claim_id, 'sub');
+    const emailClaims = this.claimCandidates(args.claim_email, 'email');
+    const nameClaims = this.claimCandidates(args.claim_name, 'name');
+    const emailVerifiedClaims = this.claimCandidates(
+      args.claim_email_verified,
+      'email_verified'
+    );

-    const claimsMap = {
-      id: args.claim_id || 'sub',
-      email: args.claim_email || 'email',
-      name: args.claim_name || 'name',
-      emailVerified: args.claim_email_verified || 'email_verified',
-    };
-
-    const accountId =
-      this.extractString(user[claimsMap.id]) ?? idTokenClaims.sub;
-    const email =
-      this.extractString(user[claimsMap.email]) ||
-      this.extractString(idTokenClaims.email);
-    const emailVerified =
-      this.extractBoolean(user[claimsMap.emailVerified]) ??
-      this.extractBoolean(idTokenClaims.email_verified);
+    const accountId = this.resolveStringClaim(
+      idClaims,
+      userClaims,
+      idTokenClaimsRecord
+    );
+    const email = this.resolveEmailClaim(
+      emailClaims,
+      userClaims,
+      idTokenClaimsRecord
+    );
+    const emailVerified = this.resolveBooleanClaim(
+      emailVerifiedClaims,
+      userClaims,
+      idTokenClaimsRecord
+    );

    if (!accountId) {
      throw new InvalidOauthResponse({
@@ -352,7 +489,7 @@ export class OIDCProvider extends OAuthProvider {

    if (!email) {
      throw new InvalidOauthResponse({
-        reason: 'Missing required claim for email',
+        reason: `Missing valid email claim in OIDC response. Tried userinfo and ID token claims: ${this.formatClaimCandidates(emailClaims)}`,
      });
    }

@@ -367,9 +504,11 @@ export class OIDCProvider extends OAuthProvider {
      email,
    };

-    const name =
-      this.extractString(user[claimsMap.name]) ||
-      this.extractString(idTokenClaims.name);
+    const name = this.resolveStringClaim(
+      nameClaims,
+      userClaims,
+      idTokenClaimsRecord
+    );
    if (name) {
      account.name = name;
    }