PD-26 — Plan d'implémentation¶

1. Découpage en composants¶

1.1 Composants backend (NestJS)¶

1.2 Composants Keycloak (infra)¶

1.3 Configuration¶

2. Flux techniques¶

2.1 Flux N1 — Découverte OIDC (startup)¶

┌─────────────────┐     ┌────────────────────┐     ┌──────────┐
│ NestJS Bootstrap│────▶│OidcDiscoveryService│────▶│ Keycloak │
└─────────────────┘     └────────────────────┘     └──────────┘
        │                        │                      │
        │                        │ GET /.well-known/    │
        │                        │ openid-configuration │
        │                        │◀─────────────────────│
        │                        │                      │
        │                        │ GET /protocol/       │
        │                        │ openid-connect/certs │
        │                        │◀─────────────────────│
        │                        │                      │
        │  JWKS cached           │                      │
        │◀───────────────────────│                      │
        │                        │                      │
        │  Health: READY         │                      │

2.2 Flux N3 — Appel API protégé¶

┌────────┐     ┌────────────┐     ┌──────────────────┐     ┌───────────────────┐
│ Client │────▶│JwtAuthGuard│────▶│JwtValidationSvc  │────▶│AuthorizationSvc   │
└────────┘     └────────────┘     └──────────────────┘     └───────────────────┘
     │              │                     │                        │
     │ Bearer JWT   │                     │                        │
     │─────────────▶│                     │                        │
     │              │ validate(token)     │                        │
     │              │────────────────────▶│                        │
     │              │                     │                        │
     │              │                     │ 1. Decode header       │
     │              │                     │ 2. Check alg ∈ RS256   │
     │              │                     │ 3. Verify signature    │
     │              │                     │ 4. Check iss           │
     │              │                     │ 5. Check aud           │
     │              │                     │ 6. Check exp/nbf/iat   │
     │              │                     │ 7. Check required      │
     │              │                     │    claims              │
     │              │                     │                        │
     │              │ payload             │                        │
     │              │◀────────────────────│                        │
     │              │                     │                        │
     │              │ authorize(payload, route)                    │
     │              │─────────────────────────────────────────────▶│
     │              │                     │                        │
     │              │                     │     Check authz.roles  │
     │              │                     │     Check authz.scopes │
     │              │                     │     Apply AND/OR rule  │
     │              │                     │                        │
     │              │ granted/denied      │                        │
     │◀─────────────│◀────────────────────────────────────────────│

2.3 Flux N5 — Rotation des clés (JWKS refresh)¶

┌─────────────────────┐     ┌──────────┐
│OidcDiscoveryService │────▶│ Keycloak │
└─────────────────────┘     └──────────┘
        │                        │
        │ (periodic or on-demand)│
        │ GET /certs             │
        │───────────────────────▶│
        │                        │
        │ new JWKS               │
        │◀───────────────────────│
        │                        │
        │ Update cache           │
        │ Invalidate old kids    │

2.4 Flux Fail-Closed JWKS/Discovery (INV-08, CA-11, TC-NOM-11)¶

Objectif : En cas d'indisponibilité JWKS/Discovery, le système DOIT : 1. Rejeter tout nouveau token (fail-closed) 2. Exposer un signal d'état dégradé observable

┌─────────────────────┐     ┌──────────┐     ┌─────────────────┐
│OidcDiscoveryService │────▶│ Keycloak │     │AuthHealthIndicator│
└─────────────────────┘     └──────────┘     └─────────────────┘
        │                        │                    │
        │ GET /certs (refresh)   │                    │
        │───────────────────────▶│                    │
        │                        │                    │
        │ ❌ Timeout / 5xx       │                    │
        │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│                    │
        │                        │                    │
        │ jwksAvailable = false  │                    │
        │────────────────────────────────────────────▶│
        │                        │                    │
        │                        │    isHealthy()     │
        │                        │    ───────────────▶│
        │                        │                    │
        │                        │    { status: 'down',
        │                        │      oidc: 'unavailable' }
        │                        │    ◀───────────────│

Mécanisme détaillé :

Points d'observation (TC-NOM-11) :

Comportement fail-closed : 1. Si jwksAvailable === false → JwtAuthGuard retourne immédiatement HTTP 503 2. Le health check passe en status: 'error' 3. La metric auth_oidc_jwks_available passe à 0 4. Les logs émettent { error: 'jwks_unavailable', ts } (conforme liste blanche)

2.5 Isolation Realm/Tenant (INV-07, CA-09, TC-NOM-09)¶

Objectif : Garantir l'isolation des environnements par realm et tenant, conformément aux politiques REALM_POLICY et TENANT_POLICY (Spec §12).

2.5.1 Paramètres contractuels (Spec §12, §16)¶

2.5.2 Configuration¶

// src/config/oidc.config.ts
export const oidcConfig = {
  issuer: process.env.OIDC_ISSUER, // https://auth.probatiovault.prod/realms/pv-prod
  expectedRealm: extractRealmFromIssuer(process.env.OIDC_ISSUER), // pv-prod
  tenantClaim: 'tenant', // Nom du claim tenant (contractuel)
  allowedTenants: process.env.ALLOWED_TENANTS?.split(',') || [], // Liste optionnelle
};

2.5.3 Mécanisme de validation¶

┌────────┐     ┌──────────────────┐
│ Token  │────▶│JwtValidationSvc  │
└────────┘     └──────────────────┘
     │               │
     │ iss claim     │ 1. Vérifier iss === OIDC_ISSUER
     │───────────────▶│    (inclut validation realm implicite)
     │               │
     │ tenant claim  │ 2. Extraire tenant du token
     │───────────────▶│
     │               │ 3. Vérifier tenant non null/vide
     │               │
     │               │ 4. Si ALLOWED_TENANTS défini :
     │               │    vérifier tenant ∈ ALLOWED_TENANTS
     │               │
     │               │ 5. Stocker tenant dans contexte
     │               │    pour audit/RLS

Méthodes implémentées :

2.5.4 Contrôles cross-realm/tenant¶

2.5.5 Points d'observation (TC-NOM-09)¶

2.5.6 Hypothèse technique ajoutée¶

2.6 Politique de Log/Audit Normative (INV-04, CA-10, TC-NOM-10, TC-NEG-04)¶

Objectif : Garantir que les logs d'authentification/autorisation respectent une liste blanche fermée de champs autorisés, sans fuite de données sensibles (tokens, secrets, claims non listés).

2.6.1 Paramètres contractuels (Spec §14)¶

Champs interdits (blacklist stricte) :

Champs autorisés (whitelist fermée) :

2.6.2 Architecture du mécanisme¶

┌────────────┐     ┌─────────────────────┐     ┌────────────────┐
│  Request   │────▶│ AuthAuditInterceptor│────▶│    Logger      │
└────────────┘     └─────────────────────┘     └────────────────┘
      │                     │                         │
      │                     │ 1. Extraire contexte    │
      │                     │    (requestId, route)   │
      │                     │                         │
      │                     │ 2. Si authentifié :     │
      │                     │    extraire claims      │
      │                     │    autorisés seulement  │
      │                     │                         │
      │                     │ 3. Sanitize :           │
      │                     │    - Supprimer headers  │
      │                     │      Authorization      │
      │                     │    - Filtrer claims     │
      │                     │                         │
      │                     │ 4. Construire entry     │
      │                     │    conforme whitelist   │
      │                     │                         │
      │                     │ emit(auditEntry)        │
      │                     │────────────────────────▶│

2.6.3 Implémentation AuthAuditInterceptor¶

// src/modules/auth/interceptors/auth-audit.interceptor.ts

@Injectable()
export class AuthAuditInterceptor implements NestInterceptor {
  // Liste blanche fermée - AUCUN autre champ ne doit être loggé
  private static readonly ALLOWED_FIELDS = [
    'requestId', 'sub', 'tenant', 'issuer', 'audience',
    'clientId', 'error', 'route', 'ts'
  ] as const;

  // Patterns à détecter et rejeter
  private static readonly FORBIDDEN_PATTERNS = [
    /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/, // JWT
    /^Bearer\s+/i,  // Authorization header
  ];

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const startTime = Date.now();

    return next.handle().pipe(
      tap({
        next: () => this.logSuccess(request, startTime),
        error: (err) => this.logError(request, err, startTime),
      }),
    );
  }

  private buildAuditEntry(request: Request, error?: string): AuditEntry {
    const user = request.user; // Populated by JwtAuthGuard

    return this.sanitize({
      requestId: request.id,
      sub: user?.sub,
      tenant: user?.tenant,
      issuer: user?.iss,
      audience: user?.aud,
      clientId: user?.clientId,
      error: error,
      route: request.path,
      ts: new Date().toISOString(),
    });
  }

  private sanitize(entry: Record<string, unknown>): AuditEntry {
    const sanitized: AuditEntry = {};

    for (const [key, value] of Object.entries(entry)) {
      // 1. Rejeter si champ non autorisé
      if (!AuthAuditInterceptor.ALLOWED_FIELDS.includes(key)) {
        continue; // Silently drop
      }

      // 2. Rejeter si valeur contient pattern interdit
      if (typeof value === 'string') {
        for (const pattern of AuthAuditInterceptor.FORBIDDEN_PATTERNS) {
          if (pattern.test(value)) {
            throw new Error(`Forbidden pattern detected in audit field: ${key}`);
          }
        }
      }

      sanitized[key] = value;
    }

    return sanitized;
  }
}

2.6.4 Règles de granularité (Spec §14)¶

2.6.5 Points d'observation (TC-NOM-10, TC-NEG-04)¶

TC-NOM-10 : Vérification non-fuite standard

TC-NEG-04 : Test adversarial injection

2.6.6 Configuration et validation startup¶

// src/config/audit.config.ts
export const auditConfig = {
  // Liste normative - ne pas modifier sans revue sécurité
  allowedFields: ['requestId', 'sub', 'tenant', 'issuer', 'audience', 'clientId', 'error', 'route', 'ts'],

  // Validation au démarrage
  validateConfig(): void {
    // Vérifier que la liste correspond exactement à la spec
    const specFields = new Set(['requestId', 'sub', 'tenant', 'issuer', 'audience', 'clientId', 'error', 'route', 'ts']);
    const configFields = new Set(this.allowedFields);

    if (!setsEqual(specFields, configFields)) {
      throw new Error('Audit config does not match spec §14 whitelist');
    }
  }
};

2.6.7 Hypothèses techniques ajoutées¶

2.7 Claims Normatifs et Modèle HYBRID (INV-09, INV-10, INV-11, CA-07, CA-08, TC-NOM-07/08/12)¶

Objectif : Définir les structures normatives des claims requis et le modèle d'autorisation HYBRID avec règles AND/OR déterministes.

2.7.1 Claims requis (Spec §11, §16)¶

JWT_REQUIRED_CLAIMS (liste fermée contractuelle) :

2.7.2 Structure du claim authz (Spec §16)¶

// src/modules/auth/dto/authz-claim.dto.ts

/**
 * Structure normative du claim authz (AUTHORIZATION_MODEL = HYBRID)
 * Spec §16 : JWT_ROLE_CLAIM = authz.roles, JWT_SCOPE_CLAIM = authz.scopes
 */
export interface AuthzClaim {
  /**
   * Rôles applicatifs (RBAC)
   * Chemin JWT : authz.roles
   * Type : string[] (peut être vide si scopes présents)
   */
  roles?: string[];

  /**
   * Scopes OAuth2
   * Chemin JWT : authz.scopes
   * Type : string[] (peut être vide si roles présents)
   */
  scopes?: string[];
}

/**
 * DTO complet du payload JWT validé
 */
export interface JwtPayloadDto {
  sub: string;
  iss: string;
  aud: string | string[];
  exp: number;
  iat: number;
  tenant: string;
  authz: AuthzClaim;
}

2.7.3 Validation des claims requis (INV-09, CA-07)¶

// src/modules/auth/services/jwt-validation.service.ts

@Injectable()
export class JwtValidationService {
  // Claims requis selon Spec §16
  private static readonly REQUIRED_CLAIMS: (keyof JwtPayloadDto)[] = [
    'sub', 'iss', 'aud', 'exp', 'iat', 'tenant', 'authz'
  ];

  validateRequiredClaims(payload: Record<string, unknown>): JwtPayloadDto {
    for (const claim of JwtValidationService.REQUIRED_CLAIMS) {
      if (payload[claim] === undefined || payload[claim] === null) {
        throw new UnauthorizedException({
          error: 'claim_missing',
          claim: claim,
          message: `Required claim '${claim}' is missing`,
        });
      }
    }

    // Validation spécifique authz (INV-10)
    const authz = payload.authz as AuthzClaim;
    if (!authz || typeof authz !== 'object') {
      throw new UnauthorizedException({
        error: 'claim_invalid',
        claim: 'authz',
        message: 'Claim authz must be an object',
      });
    }

    // HYBRID : au moins roles OU scopes doit être présent et non vide
    const hasRoles = Array.isArray(authz.roles) && authz.roles.length > 0;
    const hasScopes = Array.isArray(authz.scopes) && authz.scopes.length > 0;

    if (!hasRoles && !hasScopes) {
      throw new UnauthorizedException({
        error: 'authz_empty',
        message: 'HYBRID model requires at least roles or scopes',
      });
    }

    return payload as JwtPayloadDto;
  }
}

2.7.4 Modèle HYBRID et règles AND/OR (INV-10, INV-11, CA-08)¶

AUTHORIZATION_MODEL = HYBRID (Spec §16) : - Combine rôles applicatifs (authz.roles) ET scopes OAuth2 (authz.scopes) - Chaque route déclare explicitement ses exigences via décorateurs - Les règles AND/OR sont déclarées, jamais implicites

Décorateurs d'autorisation :

// src/modules/auth/decorators/roles.decorator.ts
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

// src/modules/auth/decorators/scopes.decorator.ts
export const Scopes = (...scopes: string[]) => SetMetadata('scopes', scopes);

// src/modules/auth/decorators/auth-rule.decorator.ts
export enum AuthRule {
  AND = 'AND',  // Tous les rôles ET tous les scopes requis
  OR = 'OR',    // Au moins un rôle OU un scope suffit
}
export const AuthorizationRule = (rule: AuthRule) => SetMetadata('authRule', rule);

Exemples de déclaration de routes :

// Route exigeant un rôle spécifique (règle implicite : rôle seul suffit)
@Get('documents')
@Roles('document:read')
async listDocuments() { }

// Route exigeant un scope spécifique
@Post('documents')
@Scopes('documents:write')
async createDocument() { }

// Route HYBRID avec règle AND (rôle ET scope requis)
@Delete('documents/:id')
@Roles('admin')
@Scopes('documents:delete')
@AuthorizationRule(AuthRule.AND)
async deleteDocument() { }

// Route HYBRID avec règle OR (rôle OU scope suffit)
@Get('documents/:id')
@Roles('document:read', 'admin')
@Scopes('documents:read')
@AuthorizationRule(AuthRule.OR)
async getDocument() { }

2.7.5 Implémentation des Guards (INV-11)¶

// src/modules/auth/guards/authorization.guard.ts

@Injectable()
export class AuthorizationGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler()) || [];
    const requiredScopes = this.reflector.get<string[]>('scopes', context.getHandler()) || [];
    const authRule = this.reflector.get<AuthRule>('authRule', context.getHandler());

    // Si aucune exigence déclarée → accès libre (authentification seule)
    if (requiredRoles.length === 0 && requiredScopes.length === 0) {
      return true;
    }

    const request = context.switchToHttp().getRequest();
    const user: JwtPayloadDto = request.user;
    const userRoles = user.authz?.roles || [];
    const userScopes = user.authz?.scopes || [];

    // Déterminer la règle (défaut selon ce qui est déclaré)
    const effectiveRule = this.determineRule(authRule, requiredRoles, requiredScopes);

    const rolesMatch = this.checkRoles(requiredRoles, userRoles);
    const scopesMatch = this.checkScopes(requiredScopes, userScopes);

    let granted: boolean;
    if (effectiveRule === AuthRule.AND) {
      // AND : tous les rôles ET tous les scopes requis
      granted = rolesMatch && scopesMatch;
    } else {
      // OR : au moins un rôle OU un scope suffit
      granted = rolesMatch || scopesMatch;
    }

    if (!granted) {
      throw new ForbiddenException({
        error: 'access_denied',
        required: { roles: requiredRoles, scopes: requiredScopes, rule: effectiveRule },
        provided: { roles: userRoles, scopes: userScopes },
      });
    }

    return true;
  }

  private determineRule(
    declaredRule: AuthRule | undefined,
    requiredRoles: string[],
    requiredScopes: string[]
  ): AuthRule {
    // Si règle explicitement déclarée → l'utiliser
    if (declaredRule) return declaredRule;

    // Sinon, déduire selon ce qui est requis :
    // - Rôles seuls ou scopes seuls → pas de combinaison, retourne OR par défaut
    // - Les deux déclarés sans règle → erreur de configuration
    if (requiredRoles.length > 0 && requiredScopes.length > 0) {
      throw new Error(
        'Configuration error: both roles and scopes declared without explicit AuthorizationRule (AND/OR)'
      );
    }

    return AuthRule.OR; // Défaut pour rôle seul ou scope seul
  }

  private checkRoles(required: string[], provided: string[]): boolean {
    if (required.length === 0) return true;
    return required.every(role => provided.includes(role));
  }

  private checkScopes(required: string[], provided: string[]): boolean {
    if (required.length === 0) return true;
    return required.every(scope => provided.includes(scope));
  }
}

2.7.6 Points d'observation (TC-NOM-07, TC-NOM-08, TC-NOM-12)¶

TC-NOM-07 : Claims requis manquants

TC-NOM-08 : Autorisation accordée (HYBRID)

TC-NOM-12 : Autorisation refusée (HYBRID)

2.7.7 Configuration normative¶

// src/config/auth.config.ts
export const authConfig = {
  // Modèle d'autorisation (Spec §16)
  authorizationModel: 'HYBRID' as const,

  // Chemins des claims d'autorisation
  roleClaim: 'authz.roles',
  scopeClaim: 'authz.scopes',

  // Claims requis (Spec §16)
  requiredClaims: ['sub', 'iss', 'aud', 'exp', 'iat', 'tenant', 'authz'],

  // Validation au démarrage
  validateConfig(): void {
    if (this.authorizationModel !== 'HYBRID') {
      throw new Error('Only HYBRID authorization model is supported (Spec §16)');
    }
  }
};

2.7.8 Hypothèses techniques ajoutées¶

2bis. Diagrammes Mermaid¶

2bis.1 Graphe de dépendances des composants¶

graph TD
    subgraph "AuthModule"
        JwtAuthGuard["JwtAuthGuard<br/>(jwt-auth.guard.ts)"]
        RolesGuard["RolesGuard<br/>(roles.guard.ts)"]
        ScopesGuard["ScopesGuard<br/>(scopes.guard.ts)"]
        AuthorizationGuard["AuthorizationGuard<br/>(authorization.guard.ts)"]
        JwtValidationService["JwtValidationService<br/>(jwt-validation.service.ts)"]
        OidcDiscoveryService["OidcDiscoveryService<br/>(oidc-discovery.service.ts)"]
        AuthorizationService["AuthorizationService<br/>(authorization.service.ts)"]
        AuthAuditInterceptor["AuthAuditInterceptor<br/>(auth-audit.interceptor.ts)"]
        AuthHealthIndicator["AuthHealthIndicator<br/>(auth-health.indicator.ts)"]
    end

    subgraph "Configuration"
        OidcConfig["oidc.config.ts"]
        AuthConfig["auth.config.ts"]
        AuditConfig["audit.config.ts"]
    end

    subgraph "Externe"
        Keycloak["Keycloak<br/>(IdP — PD-235)"]
    end

    JwtAuthGuard -->|"validate(token)"| JwtValidationService
    JwtAuthGuard -->|"jwksAvailable?"| OidcDiscoveryService
    RolesGuard -->|"checkRoles()"| AuthorizationService
    ScopesGuard -->|"checkScopes()"| AuthorizationService
    AuthorizationGuard -->|"canActivate()"| AuthorizationService
    JwtValidationService -->|"getKey(kid)"| OidcDiscoveryService
    OidcDiscoveryService -->|"GET /.well-known/<br/>openid-configuration"| Keycloak
    OidcDiscoveryService -->|"GET /certs (JWKS)"| Keycloak
    AuthHealthIndicator -->|"jwksAvailable"| OidcDiscoveryService
    JwtValidationService -->|"issuer, audiences, algos"| OidcConfig
    AuthorizationGuard -->|"authorizationModel,<br/>roleClaim, scopeClaim"| AuthConfig
    AuthAuditInterceptor -->|"allowedFields"| AuditConfig

    style Keycloak fill:#f9f,stroke:#333,stroke-width:2px
    style JwtAuthGuard fill:#bbf,stroke:#333
    style JwtValidationService fill:#bbf,stroke:#333
    style OidcDiscoveryService fill:#bbf,stroke:#333

2bis.2 Diagramme de séquence — Appel API protégé (multi-service)¶

sequenceDiagram
    participant Client
    participant JwtAuthGuard
    participant OidcDiscoverySvc as OidcDiscoveryService
    participant JwtValidationSvc as JwtValidationService
    participant AuthorizationGuard
    participant AuthAuditInterceptor
    participant Keycloak
    participant Controller

    Note over Client,Controller: Flux N3 — Requête API avec Bearer JWT

    Client->>+JwtAuthGuard: GET /documents (Bearer JWT)

    JwtAuthGuard->>OidcDiscoverySvc: jwksAvailable?
    alt JWKS indisponible (INV-08)
        OidcDiscoverySvc-->>JwtAuthGuard: false
        JwtAuthGuard-->>Client: HTTP 503 Service Unavailable
    end
    OidcDiscoverySvc-->>JwtAuthGuard: true

    JwtAuthGuard->>+JwtValidationSvc: validate(token)

    JwtValidationSvc->>JwtValidationSvc: 1. validateAlgorithm(header.alg)
    Note right of JwtValidationSvc: alg ∈ RS256 (INV-02, CA-06)

    JwtValidationSvc->>OidcDiscoverySvc: getKey(header.kid)
    OidcDiscoverySvc-->>JwtValidationSvc: publicKey (JWKS cache)

    JwtValidationSvc->>JwtValidationSvc: 2. verifySignature(token, key)
    Note right of JwtValidationSvc: INV-02, CA-02

    JwtValidationSvc->>JwtValidationSvc: 3. validateIssuer(payload.iss)
    Note right of JwtValidationSvc: iss === OIDC_ISSUER (INV-07, CA-03)

    JwtValidationSvc->>JwtValidationSvc: 4. validateAudience(payload.aud)
    Note right of JwtValidationSvc: aud ∩ ALLOWED ≠ ∅ (CA-04)

    JwtValidationSvc->>JwtValidationSvc: 5. validateDates(exp, nbf, iat)
    Note right of JwtValidationSvc: ±120s clock skew (CA-05)

    JwtValidationSvc->>JwtValidationSvc: 6. validateRequiredClaims(payload)
    Note right of JwtValidationSvc: sub, tenant, authz (INV-09)

    JwtValidationSvc->>JwtValidationSvc: 7. validateTenant(payload.tenant)
    Note right of JwtValidationSvc: INV-07, CA-09

    JwtValidationSvc-->>-JwtAuthGuard: JwtPayloadDto (validated)

    JwtAuthGuard->>JwtAuthGuard: request.user = payload

    JwtAuthGuard->>+AuthorizationGuard: canActivate(context)
    AuthorizationGuard->>AuthorizationGuard: Lire @Roles, @Scopes, @AuthorizationRule
    AuthorizationGuard->>AuthorizationGuard: Evaluer AND/OR (INV-10, INV-11)

    alt Accès refusé
        AuthorizationGuard-->>Client: HTTP 403 Forbidden
    end

    AuthorizationGuard-->>-JwtAuthGuard: granted
    JwtAuthGuard-->>-Controller: next()

    Controller-->>Client: HTTP 200 (response)

    AuthAuditInterceptor->>AuthAuditInterceptor: sanitize(auditEntry)
    Note right of AuthAuditInterceptor: Whitelist fermée (INV-04)
    AuthAuditInterceptor->>AuthAuditInterceptor: emit({ requestId, sub, tenant, route, ts })

2bis.3 Diagramme de séquence — Découverte OIDC et rotation JWKS¶

sequenceDiagram
    participant NestJS as NestJS Bootstrap
    participant OidcDiscoverySvc as OidcDiscoveryService
    participant HealthIndicator as AuthHealthIndicator
    participant Keycloak

    Note over NestJS,Keycloak: Flux N1 — Startup + Flux N5 — Rotation JWKS

    rect rgb(230, 245, 255)
        Note over NestJS,Keycloak: Phase startup
        NestJS->>+OidcDiscoverySvc: onModuleInit()
        OidcDiscoverySvc->>Keycloak: GET /.well-known/openid-configuration
        Keycloak-->>OidcDiscoverySvc: discovery document
        OidcDiscoverySvc->>Keycloak: GET /protocol/openid-connect/certs
        Keycloak-->>OidcDiscoverySvc: JWKS (clés publiques)
        OidcDiscoverySvc->>OidcDiscoverySvc: Cache JWKS (jwksAvailable = true)
        OidcDiscoverySvc-->>-NestJS: READY
    end

    rect rgb(255, 245, 230)
        Note over OidcDiscoverySvc,Keycloak: Phase rotation périodique
        loop Toutes les N secondes (TTL)
            OidcDiscoverySvc->>Keycloak: GET /certs (refresh)
            alt Keycloak disponible
                Keycloak-->>OidcDiscoverySvc: new JWKS
                OidcDiscoverySvc->>OidcDiscoverySvc: Update cache, invalidate old kids
            else Keycloak indisponible (INV-08)
                Keycloak-->>OidcDiscoverySvc: Timeout / 5xx
                OidcDiscoverySvc->>OidcDiscoverySvc: Retry backoff (3 tentatives, max 30s)
                OidcDiscoverySvc->>OidcDiscoverySvc: jwksAvailable = false
                OidcDiscoverySvc->>HealthIndicator: signal dégradé
                HealthIndicator->>HealthIndicator: status: down, oidc: unavailable
                Note over HealthIndicator: GET /health → 503<br/>metric auth_oidc_jwks_available = 0
            end
        end
    end

3. Mapping invariants → mécanismes¶

Note PD-235 : Les invariants INV-02 (validation dates), INV-05/09 (claims requis) et INV-08 (fail-closed) couvrent également les cas délégués par PD-235 (infra IdP) — voir §5bis pour le mapping détaillé des tests TC-PD235-*.

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

5bis. Mapping tests PD-235 délégués → mécanismes backend¶

Les tests suivants sont délégués par PD-235 (infra IdP) au backend PD-26 (consumer). Ils assurent la traçabilité de la dépendance et la clôture des cas d'erreur côté consumer.

Traçabilité de la délégation :

6. Gestion des erreurs¶

7. Impacts sécurité¶

7.1 Risques identifiés¶

7.2 Journalisation sécurisée¶

Champs autorisés (liste blanche fermée) : - requestId - sub - tenant - issuer - audience - clientId - error (code uniquement) - route - ts (horodatage)

Champs interdits : - Token complet (access/refresh/id) - Header Authorization - Secrets/signatures - Claims sensibles non listés - Payload JWT en clair

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

9.1 Risques techniques¶

9.2 Dette technique acceptée¶

9.3 Pièges d'implémentation¶

• Alg=none : TOUJOURS vérifier que l'algorithme est dans la liste autorisée AVANT la vérification de signature
• Audience array : aud peut être string ou array selon le token
• Clock skew : Appliquer JWT_CLOCK_SKEW_MAX = 120s (Spec §16) dans les DEUX sens : exp > now - 120s ET nbf < now + 120s ET iat ≤ now + 120s
• Claims nested : authz.roles est un path, pas un claim de premier niveau
• Logging : Ne JAMAIS logger request.headers.authorization

10. Hors périmètre¶

• Fédération SSO (Google, Microsoft, FranceConnect, SAML)
• MFA (TOTP, WebAuthn, SMS)
• Gestion cycle de vie identités (KYC, eIDAS)
• Politiques RGPD détaillées
• Rotation secrets applicatifs
• Cache distribué JWKS
• Révocation de tokens
• Refresh tokens côté backend

Références¶

• Epic : PD-182 — AUTH
• JIRA : PD-26
• Repos : backend / infra
• Spécification : PD-26-specification.md
• Tests : PD-26-tests.md
• Dépendance : PD-235 (IdP Keycloak infra) — tests délégués au backend : TC-ERR-01/03, TC-NEG-02/04