diff --git a/.claude/settings.json b/.claude/settings.json
index df0088f..22066f1 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -16,6 +16,12 @@
       "Bash(git push origin feature/*)",
       "Bash(git push -u origin fix/*)",
       "Bash(git push origin fix/*)",
+      "Bash(git push -u origin feat/*)",
+      "Bash(git push origin feat/*)",
+      "Bash(git push -u origin docs/*)",
+      "Bash(git push origin docs/*)",
+      "Bash(git push -u origin chore/*)",
+      "Bash(git push origin chore/*)",
       "Bash(gh pr create*)",
       "Bash(ls*)",
       "Bash(find . -name*)",
diff --git a/.env.example b/.env.example
index 5a96904..9b1842f 100644
--- a/.env.example
+++ b/.env.example
@@ -65,12 +65,49 @@ API_BASE_URL=http://api:3200
 # SSO_OKTA_DISPLAY_NAME=Okta                                 # optional (button)
 # SSO_OKTA_ICON_KEY=okta                                     # optional (icon)
 #
-# Signs the short-lived OIDC transaction & logout-hint cookies. Falls back to
-# JWT_REFRESH_SECRET if unset; set a dedicated value in production.
+# Signs the short-lived OIDC/SAML transaction & logout-hint cookies. Falls back
+# to JWT_REFRESH_SECRET if unset; set a dedicated value in production.
 # SSO_STATE_SECRET=
 # Dev-only escape hatch to allow http/loopback issuers. NEVER enable in prod.
+# (Cloud-metadata / link-local / 0.0.0.0 stay blocked even when this is true.)
 # SSO_ALLOW_INSECURE_ISSUERS=false
 
+# ── SSO / SAML 2.0 (optional, legacy tenants) ───────────────────────────────
+# The gateway acts as a SAML Service Provider (SP-initiated only) for IdPs that
+# don't speak OIDC (ADFS, Shibboleth, Okta-SAML, Azure AD SAML). Leave ALL of
+# these unset to keep SAML disabled (zero regression). Declare a provider by
+# setting <NAME>_ENTRY_POINT; <NAME> becomes the provider id (lowercased), used
+# in /api/v1/auth/sso/<name>/login and must NOT collide with an OIDC id.
+# A declared-but-incomplete provider fails the gateway fast at boot.
+#
+# Onboard the IdP with the SP metadata: GET /api/v1/auth/sso/<name>/metadata
+# (public, no private material). The ACS / CALLBACK_URL must match EXACTLY.
+#
+# _IDP_CERT is the IdP's PUBLIC x509 cert (PEM). It is NOT a secret, but the
+# gateway rejects it at boot if expired, RSA <2048-bit, or sha1. For rotation,
+# put both certs separated by ';' during the overlap window.
+#
+# _ALLOWED_DOMAINS is MANDATORY: SAML assertions are trusted as email-verified,
+# so this allowlist is the ONLY cross-tenant account-takeover boundary. Without
+# it the gateway refuses to start.
+#
+# SAML_ACME_ENTRY_POINT=https://idp.acme.example/sso/saml         # IdP SSO URL (https)
+# SAML_ACME_IDP_ISSUER=https://idp.acme.example/metadata          # IdP entityID
+# SAML_ACME_IDP_CERT=-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----
+# SAML_ACME_CALLBACK_URL=https://app.example.com/api/v1/auth/sso/acme/callback  # ACS (exact)
+# SAML_ACME_ALLOWED_DOMAINS=acme.com,acme.io                      # REQUIRED (csv)
+# SAML_ACME_SP_ISSUER=https://app.example.com                     # optional (default: callback origin)
+# SAML_ACME_EMAIL_ATTRIBUTE=email                                 # optional (default)
+# SAML_ACME_GROUPS_ATTRIBUTE=groups                               # optional (default)
+# SAML_ACME_PERMISSION_MAP=admins:ADMIN;staff:WRITE_SOME_ENTITY,READ_SOME_ENTITY  # optional
+# SAML_ACME_SIGNATURE_ALGORITHM=sha256                            # optional (sha256|sha512; sha1 disabled)
+# SAML_ACME_LOGOUT_URL=https://idp.acme.example/slo               # optional (best-effort SLO)
+# SAML_ACME_DECRYPTION_PVK=                                       # optional SECRET (encrypted assertions); gateway only
+# SAML_ACME_FORCE_AUTHN=false                                     # optional (re-auth at the IdP)
+# SAML_ACME_DISABLE_REQUESTED_AUTHN_CONTEXT=true                  # optional (legacy IdP compat)
+# SAML_ACME_DISPLAY_NAME=Acme SSO                                 # optional (button)
+# SAML_ACME_ICON_KEY=acme                                         # optional (icon)
+
 # Auth rate limiting (anti brute-force / credential stuffing). Login is keyed by
 # IP+email and only counts failed attempts.
 LOGIN_RATE_WINDOW_MS=900000
diff --git a/AGENTS.md b/AGENTS.md
index 9efd0e0..9cd31fc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -200,5 +200,10 @@ These are the cross-cutting invariants. Layer-specific rules live in each packag
   The scripts encode the right flags, configs and order; raw tooling drifts from
   them. If a needed task has no script, add one to `package.json` rather than
   documenting a bare command.
+- **Never regenerate `package-lock.json` wholesale** (`npm install` with a stale
+  `node_modules` can silently drop the peer-installed `@rspack/core` subtree, which
+  breaks `npm ci` in CI with `EUSAGE`). When adding a dependency, keep the lockfile
+  diff limited to the new package's entries, and validate with `npm run verify:lock`
+  (a dry-run `npm ci`) before pushing.
 - When you implement or change something significant, update the relevant `AGENTS.md`
   in the same change so it stays accurate.
diff --git a/README.md b/README.md
index 609aca2..20bb395 100644
--- a/README.md
+++ b/README.md
@@ -751,7 +751,7 @@ En producción, aplicar el SQL manualmente sobre la DB.
 ### Roadmap
 
 - [x] SSO/OIDC en el gateway para clientes enterprise (Okta, Azure AD, Auth0) — ver [docs/SECURITY.md → Federación OIDC](docs/SECURITY.md#federación-oidc-sso-okta--azure-ad--auth0)
-- [ ] SAML para tenants legacy
+- [x] SAML 2.0 para tenants legacy — ver [docs/SECURITY.md → Federación SAML 2.0](docs/SECURITY.md#federación-saml-20-tenants-legacy)
 - [ ] SCIM 2.0 para aprovisionamiento masivo
 - [ ] Multi-tenancy en CRUDs
 - [ ] Tests e2e completos (Playwright)
diff --git a/apps/front/src/app/libs/auth/services/sso.service.spec.ts b/apps/front/src/app/libs/auth/services/sso.service.spec.ts
index 661c6ee..d469bef 100644
--- a/apps/front/src/app/libs/auth/services/sso.service.spec.ts
+++ b/apps/front/src/app/libs/auth/services/sso.service.spec.ts
@@ -4,6 +4,7 @@ import {
   HttpTestingController,
 } from '@angular/common/http/testing';
 import { firstValueFrom } from 'rxjs';
+import { SsoProviderPublicDTO } from '@dto';
 import { SsoService, SSO_CALLBACK_PATH } from './sso.service';
 import { AUTH_CONFIGURATION } from '../auth.constants';
 
@@ -35,6 +36,31 @@ describe('SsoService', () => {
     expect(await promise).toEqual([{ id: 'okta', displayName: 'Okta' }]);
   });
 
+  it('returns mixed OIDC and SAML providers preserving the protocol field', async () => {
+    const mixed: SsoProviderPublicDTO[] = [
+      { id: 'okta', displayName: 'Okta', protocol: 'oidc' },
+      { id: 'adfs', displayName: 'ADFS', protocol: 'saml' },
+      { id: 'legacy', displayName: 'Legacy' }, // no protocol — defaults to oidc on the backend
+      {
+        id: 'saml-corp',
+        displayName: 'Corp SSO',
+        protocol: 'saml',
+        iconKey: 'corp-logo',
+      },
+    ];
+    const promise = firstValueFrom(service.getProviders());
+    const req = httpMock.expectOne('http://localhost:3200/auth/sso/providers');
+    req.flush(mixed);
+    const result = await promise;
+    // Typed as SsoProviderPublicDTO[] — no runtime coercion needed
+    expect(result).toHaveLength(4);
+    expect(result[0].protocol).toBe('oidc');
+    expect(result[1].protocol).toBe('saml');
+    expect(result[2].protocol).toBeUndefined(); // optional — absent means oidc by convention
+    expect(result[3].protocol).toBe('saml');
+    expect(result[3].iconKey).toBe('corp-logo');
+  });
+
   it('builds a login url with an encoded same-site returnTo', () => {
     expect(service.buildLoginUrl('okta')).toBe(
       `http://localhost:3200/auth/sso/okta/login?returnTo=${encodeURIComponent(
diff --git a/apps/front/src/app/pages/login/login.component.html b/apps/front/src/app/pages/login/login.component.html
index 4e5d83d..7f10359 100644
--- a/apps/front/src/app/pages/login/login.component.html
+++ b/apps/front/src/app/pages/login/login.component.html
@@ -102,7 +102,13 @@ <h5 class="card-title">{{ 'login.title' | transloco }}</h5>
                   type="button"
                   class="btn btn-outline-secondary w-100 mb-2"
                   (click)="loginWithSso(provider.id)"
+                  [attr.data-testid]="'sso-btn-' + provider.id"
                 >
+                  @if (!provider.iconKey && provider.protocol === 'saml') {
+                    <span class="visually-hidden" data-testid="saml-badge">{{
+                      'login.sso.samlBadge' | transloco
+                    }}</span>
+                  }
                   {{
                     'login.sso.continueWith'
                       | transloco: { provider: provider.displayName }
diff --git a/apps/front/src/app/pages/login/login.component.spec.ts b/apps/front/src/app/pages/login/login.component.spec.ts
index 83870b8..15cf426 100644
--- a/apps/front/src/app/pages/login/login.component.spec.ts
+++ b/apps/front/src/app/pages/login/login.component.spec.ts
@@ -1,7 +1,8 @@
-import { TestBed } from '@angular/core/testing';
+import { TestBed, ComponentFixture } from '@angular/core/testing';
 import { ActivatedRoute, Router } from '@angular/router';
-import { TranslocoService } from '@jsverse/transloco';
+import { TranslocoTestingModule } from '@jsverse/transloco';
 import { of, throwError } from 'rxjs';
+import { SsoProviderPublicDTO } from '@dto';
 import LoginComponent from './login.component';
 import { AuthService } from '@front/app/libs/auth/services/auth.service';
 import { SsoService } from '@front/app/libs/auth/services/sso.service';
@@ -10,10 +11,27 @@ describe('LoginComponent (SSO integration)', () => {
   const getProviders = vi.fn();
   const ssoLogin = vi.fn();
 
-  const setup = (hasSsoError = false) => {
+  const setup = (
+    hasSsoError = false,
+  ): { cmp: LoginComponent; fixture: ComponentFixture<LoginComponent> } => {
     TestBed.resetTestingModule();
     TestBed.configureTestingModule({
-      imports: [LoginComponent],
+      imports: [
+        LoginComponent,
+        // Real (test) transloco wiring so the template's transloco pipe
+        // renders; missing keys fall back to the key itself.
+        TranslocoTestingModule.forRoot({
+          langs: {
+            en: {
+              login: {
+                sso: { continueWith: 'Continue with {{provider}}' },
+              },
+            },
+          },
+          translocoConfig: { availableLangs: ['en'], defaultLang: 'en' },
+          preloadLangs: true,
+        }),
+      ],
       providers: [
         { provide: SsoService, useValue: { getProviders, login: ssoLogin } },
         { provide: AuthService, useValue: { login: vi.fn() } },
@@ -31,49 +49,129 @@ describe('LoginComponent (SSO integration)', () => {
             },
           },
         },
-        {
-          provide: TranslocoService,
-          useValue: { translate: (k: string) => k },
-        },
       ],
     });
-    return TestBed.createComponent(LoginComponent).componentInstance;
+    const fixture = TestBed.createComponent(LoginComponent);
+    return { cmp: fixture.componentInstance, fixture };
   };
 
   beforeEach(() => vi.clearAllMocks());
 
   it('renders a button per configured provider', () => {
     getProviders.mockReturnValue(of([{ id: 'okta', displayName: 'Okta' }]));
-    const cmp = setup();
+    const { cmp } = setup();
     cmp.ngOnInit();
     expect(cmp.providers()).toEqual([{ id: 'okta', displayName: 'Okta' }]);
   });
 
   it('shows no providers when none are configured', () => {
     getProviders.mockReturnValue(of([]));
-    const cmp = setup();
+    const { cmp } = setup();
     cmp.ngOnInit();
     expect(cmp.providers()).toEqual([]);
   });
 
   it('falls back to empty providers if the request fails', () => {
     getProviders.mockReturnValue(throwError(() => new Error('boom')));
-    const cmp = setup();
+    const { cmp } = setup();
     cmp.ngOnInit();
     expect(cmp.providers()).toEqual([]);
   });
 
   it('surfaces a generic error when the gateway flags sso_error', () => {
     getProviders.mockReturnValue(of([]));
-    const cmp = setup(true);
+    const { cmp } = setup(true);
     cmp.ngOnInit();
     expect(cmp.error).toEqual(['login.sso.error']);
   });
 
   it('starts the federated flow via the SSO service', () => {
     getProviders.mockReturnValue(of([]));
-    const cmp = setup();
+    const { cmp } = setup();
     cmp.loginWithSso('okta');
     expect(ssoLogin).toHaveBeenCalledWith('okta');
   });
+
+  it('renders one button per provider in a mixed OIDC+SAML list', () => {
+    const mixed: SsoProviderPublicDTO[] = [
+      { id: 'okta', displayName: 'Okta', protocol: 'oidc' },
+      { id: 'adfs', displayName: 'ADFS', protocol: 'saml' },
+      { id: 'legacy', displayName: 'Legacy Corp' },
+    ];
+    getProviders.mockReturnValue(of(mixed));
+    const { cmp } = setup();
+    cmp.ngOnInit();
+    expect(cmp.providers()).toHaveLength(3);
+    expect(cmp.providers()[1].protocol).toBe('saml');
+  });
+
+  it('shows the SAML badge for a provider with protocol=saml and no iconKey', () => {
+    const samlProvider: SsoProviderPublicDTO = {
+      id: 'adfs',
+      displayName: 'ADFS',
+      protocol: 'saml',
+    };
+    getProviders.mockReturnValue(of([samlProvider]));
+    const { cmp, fixture } = setup();
+    cmp.ngOnInit();
+    fixture.detectChanges();
+    const badge: HTMLElement | null = fixture.nativeElement.querySelector(
+      '[data-testid="saml-badge"]',
+    );
+    expect(badge).not.toBeNull();
+  });
+
+  it('does not show the SAML badge when a SAML provider has an iconKey', () => {
+    const samlWithIcon: SsoProviderPublicDTO = {
+      id: 'adfs',
+      displayName: 'ADFS',
+      protocol: 'saml',
+      iconKey: 'adfs-logo',
+    };
+    getProviders.mockReturnValue(of([samlWithIcon]));
+    const { cmp, fixture } = setup();
+    cmp.ngOnInit();
+    fixture.detectChanges();
+    const badge: HTMLElement | null = fixture.nativeElement.querySelector(
+      '[data-testid="saml-badge"]',
+    );
+    expect(badge).toBeNull();
+  });
+
+  it('does not show the SAML badge for an OIDC provider', () => {
+    const oidcProvider: SsoProviderPublicDTO = {
+      id: 'okta',
+      displayName: 'Okta',
+      protocol: 'oidc',
+    };
+    getProviders.mockReturnValue(of([oidcProvider]));
+    const { cmp, fixture } = setup();
+    cmp.ngOnInit();
+    fixture.detectChanges();
+    const badge: HTMLElement | null = fixture.nativeElement.querySelector(
+      '[data-testid="saml-badge"]',
+    );
+    expect(badge).toBeNull();
+  });
+
+  it('renders displayName as text — a malicious displayName does not inject elements', () => {
+    const xssProvider: SsoProviderPublicDTO = {
+      id: 'evil',
+      displayName: '<script>alert(1)</script>Evil Corp',
+      protocol: 'saml',
+    };
+    getProviders.mockReturnValue(of([xssProvider]));
+    const { cmp, fixture } = setup();
+    cmp.ngOnInit();
+    fixture.detectChanges();
+    // No <script> element must exist inside the rendered component
+    const scripts = fixture.nativeElement.querySelectorAll('script');
+    expect(scripts.length).toBe(0);
+    // The literal text (encoded by Angular interpolation) is present as text content
+    const btn: HTMLButtonElement = fixture.nativeElement.querySelector(
+      '[data-testid="sso-btn-evil"]',
+    );
+    expect(btn).not.toBeNull();
+    expect(btn.textContent).toContain('Evil Corp');
+  });
 });
diff --git a/apps/front/src/assets/i18n/ca.json b/apps/front/src/assets/i18n/ca.json
index 5f35e14..ad6a6a6 100644
--- a/apps/front/src/assets/i18n/ca.json
+++ b/apps/front/src/assets/i18n/ca.json
@@ -26,7 +26,8 @@
     "sso": {
       "or": "o continua amb",
       "continueWith": "Continua amb {{provider}}",
-      "error": "L'inici de sessió únic ha fallat. Torna-ho a provar."
+      "error": "L'inici de sessió únic ha fallat. Torna-ho a provar.",
+      "samlBadge": "SSO Empresarial"
     }
   },
   "unauthorized": {
diff --git a/apps/front/src/assets/i18n/en.json b/apps/front/src/assets/i18n/en.json
index e53f7df..106e293 100644
--- a/apps/front/src/assets/i18n/en.json
+++ b/apps/front/src/assets/i18n/en.json
@@ -26,7 +26,8 @@
     "sso": {
       "or": "or continue with",
       "continueWith": "Continue with {{provider}}",
-      "error": "Single sign-on failed. Please try again."
+      "error": "Single sign-on failed. Please try again.",
+      "samlBadge": "Enterprise SSO"
     }
   },
   "unauthorized": {
diff --git a/apps/front/src/assets/i18n/es.json b/apps/front/src/assets/i18n/es.json
index 112a56d..f47b31f 100644
--- a/apps/front/src/assets/i18n/es.json
+++ b/apps/front/src/assets/i18n/es.json
@@ -26,7 +26,8 @@
     "sso": {
       "or": "o continúa con",
       "continueWith": "Continuar con {{provider}}",
-      "error": "El inicio de sesión único ha fallado. Inténtalo de nuevo."
+      "error": "El inicio de sesión único ha fallado. Inténtalo de nuevo.",
+      "samlBadge": "SSO Empresarial"
     }
   },
   "unauthorized": {
diff --git a/apps/gateway/AGENTS.md b/apps/gateway/AGENTS.md
index e5ac490..64b798c 100644
--- a/apps/gateway/AGENTS.md
+++ b/apps/gateway/AGENTS.md
@@ -31,6 +31,26 @@ the internal API on the same private network.
    migrating the monorepo to `moduleResolution: nodenext`. Full design & threat
    model: `docs/SECURITY.md` → "Federación OIDC". With zero providers configured
    the gateway behaves exactly as before.
+5. **SAML 2.0 Service Provider (SSO)** (`src/sso/saml-*.ts`,
+   `src/controllers/saml.controller.ts`): optional **SP-initiated** federated
+   login for legacy IdPs (ADFS/Shibboleth/Okta-SAML/Azure-SAML), via
+   `@node-saml/node-saml`. The OIDC routes dispatch by `protocol` through the
+   **federated registry** (`src/sso/federated-registry.ts`), so login/logout
+   share the OIDC paths; SAML adds `POST /:provider/callback` (ACS, route-scoped
+   `urlencoded` parser, 256 KB cap), `GET /:provider/metadata` (public SP
+   metadata, no private material) and `GET|POST /:provider/logout/callback`
+   (SLO). It **reuses** the OIDC `/internal/federated/resolve` endpoint (scope
+   `FEDERATED_IDENTITY`) with `provider`=id and `subject`=NameID, and issues the
+   **same** local session via `respondWithTokens`. Hardening that must NOT be
+   relaxed: `wantAssertionsSigned` + `wantAuthnResponseSigned` (both literal
+   `true`), `validateInResponseTo: always` (IdP-initiated rejected by design),
+   audience pinned to the SP entityID, `Issuer` pinned to `idpIssuer` (mix-up),
+   signatures verified only against the registry's pinned certs, `transient`
+   NameID rejected, and **`SAML_<NAME>_ALLOWED_DOMAINS` is mandatory** (the ACS
+   stamps `emailVerified: true`, so the domain allowlist is the sole
+   cross-tenant account-takeover boundary). Full threat model:
+   `docs/SECURITY.md` → "Federación SAML 2.0". Zero `SAML_*` providers → SAML
+   disabled, no behavior change.
 
 ## Request flow (must stay intact)
 
@@ -66,16 +86,17 @@ browser ──/api/*──▶ nginx ──proxy_pass──▶ gateway
 
 ## Env vars
 
-| Var                          | Purpose                                                                                                   |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `GATEWAY_PORT`               | Listen port (default 3100)                                                                                |
-| `API_BASE_URL`               | Upstream API base (default `http://api:3200`)                                                             |
-| `INTERNAL_JWT_PRIVATE_KEY`   | EdDSA private key for signing internal tokens (PEM)                                                       |
-| `CORS_ORIGIN`                | Comma-separated allowed origins                                                                           |
-| `JWT_REFRESH_REMEMBER_DAYS`  | "remember me" refresh lifetime in days (default 30)                                                       |
-| `SSO_<NAME>_*`               | OIDC provider config (issuer/client_id/secret/redirect_uri/…); see `.env.example`. Secrets live ONLY here |
-| `SSO_STATE_SECRET`           | Signs the OIDC transaction & logout-hint cookies (falls back to `JWT_REFRESH_SECRET`)                     |
-| `SSO_ALLOW_INSECURE_ISSUERS` | Dev-only: allow http/loopback issuers. Never enable in production                                         |
+| Var                          | Purpose                                                                                                                                                                                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GATEWAY_PORT`               | Listen port (default 3100)                                                                                                                                                                             |
+| `API_BASE_URL`               | Upstream API base (default `http://api:3200`)                                                                                                                                                          |
+| `INTERNAL_JWT_PRIVATE_KEY`   | EdDSA private key for signing internal tokens (PEM)                                                                                                                                                    |
+| `CORS_ORIGIN`                | Comma-separated allowed origins                                                                                                                                                                        |
+| `JWT_REFRESH_REMEMBER_DAYS`  | "remember me" refresh lifetime in days (default 30)                                                                                                                                                    |
+| `SSO_<NAME>_*`               | OIDC provider config (issuer/client_id/secret/redirect_uri/…); see `.env.example`. Secrets live ONLY here                                                                                              |
+| `SAML_<NAME>_*`              | SAML provider config (entry_point/idp_issuer/idp_cert/callback_url/**allowed_domains** required, …); see `.env.example`. `_ALLOWED_DOMAINS` is mandatory; `_DECRYPTION_PVK` is a secret kept ONLY here |
+| `SSO_STATE_SECRET`           | Signs the OIDC **and SAML** transaction & logout-hint cookies (falls back to `JWT_REFRESH_SECRET`)                                                                                                     |
+| `SSO_ALLOW_INSECURE_ISSUERS` | Dev-only: allow http/loopback issuers (OIDC & SAML). Never enable in production; metadata/link-local/0.0.0.0 stay blocked regardless                                                                   |
 
 **SSO hard rule:** federated login still ends in the standard local session — the
 api keeps trusting only the internal EdDSA JWT, never an IdP token. Client secrets
@@ -90,5 +111,10 @@ the security-critical units. Run: `npm run test:gateway`.
 End-to-end specs (`*.e2e.spec.ts`) spin up a **real mock OIDC provider**
 (`oauth2-mock-server`) and exercise the full SSO handshake (discovery, PKCE,
 state, nonce, ID-token JWKS validation) plus an attack case (tampered state →
-rejection). They are excluded from the unit suite (port binding / real HTTP) and
-run with `npm run test:e2e`.
+rejection). For SAML, `saml-flow.e2e.spec.ts` stands up a throwaway self-signed
+test IdP that signs real Responses/Assertions (`xml-crypto`) and runs the happy
+path plus a 14-case attack suite (unsigned/partial-signature, rogue-key, XSW,
+NameID comment injection, replay, IdP-initiated, InResponseTo mismatch, wrong
+audience, expired, mix-up issuer, domain outside allowlist, external RelayState,
+transient NameID). The api boundary is mocked, so no Postgres/network. They are
+excluded from the unit suite and run with `npm run test:e2e`.
diff --git a/apps/gateway/src/controllers/saml.controller.spec.ts b/apps/gateway/src/controllers/saml.controller.spec.ts
new file mode 100644
index 0000000..70c289e
--- /dev/null
+++ b/apps/gateway/src/controllers/saml.controller.spec.ts
@@ -0,0 +1,580 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@gateway/sso/federated-registry', () => ({
+  getFederatedProvider: vi.fn(),
+}));
+vi.mock('@gateway/sso/saml-client', () => ({
+  generateSamlRequestId: vi.fn(() => '_feedfacefeedfacefeedfacefeedface'),
+  getSamlClient: vi.fn(),
+}));
+vi.mock('@gateway/sso/saml-transaction.service', () => ({
+  setSamlTransactionCookie: vi.fn(),
+  readSamlTransaction: vi.fn(),
+  clearSamlTransactionCookie: vi.fn(),
+}));
+vi.mock('@gateway/sso/saml-logout.service', () => ({
+  setSamlLogoutHintCookie: vi.fn(),
+}));
+vi.mock('@gateway/clients/api.client', () => ({
+  ApiClient: { resolveFederatedUser: vi.fn() },
+}));
+vi.mock('@gateway/middleware/auth.middleware', () => ({
+  respondWithTokens: vi.fn(),
+}));
+
+import { Permission } from '@dto';
+import { ApiClient } from '@gateway/clients/api.client';
+import { respondWithTokens } from '@gateway/middleware/auth.middleware';
+import { getFederatedProvider } from '@gateway/sso/federated-registry';
+import { getSamlClient } from '@gateway/sso/saml-client';
+import { setSamlLogoutHintCookie } from '@gateway/sso/saml-logout.service';
+import {
+  clearSamlTransactionCookie,
+  readSamlTransaction,
+  setSamlTransactionCookie,
+} from '@gateway/sso/saml-transaction.service';
+import samlController from './saml.controller';
+
+const samlConfig = {
+  id: 'acme',
+  displayName: 'Acme',
+  entryPoint: 'https://idp.acme.example/sso',
+  issuer: 'https://app.example.com',
+  emailAttribute: 'email',
+  groupsAttribute: 'groups',
+  permissionMap: [
+    { claim: 'admins', permissions: [Permission.WRITE_SOME_ENTITY] },
+  ],
+  // Mandatory domain allowlist — the ACS stamps emailVerified:true, so this is
+  // the cross-tenant account-takeover boundary.
+  allowedDomains: ['acme.com'],
+  decryptionPvk: 'SUPER-SECRET-KEY-MATERIAL',
+};
+
+const PERSISTENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+const TRANSIENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient';
+
+const mkRes = () => {
+  const res = {} as Record<string, ReturnType<typeof vi.fn>>;
+  res.status = vi.fn(() => res);
+  res.json = vi.fn(() => res);
+  res.redirect = vi.fn();
+  res.cookie = vi.fn();
+  res.type = vi.fn(() => res);
+  res.send = vi.fn(() => res);
+  return res as never;
+};
+
+const samlInstance = {
+  getAuthorizeUrlAsync: vi.fn(
+    async () => 'https://idp.acme.example/sso?SAMLRequest=abc',
+  ),
+  generateServiceProviderMetadata: vi.fn(
+    () => '<EntityDescriptor entityID="https://app.example.com"/>',
+  ),
+  validatePostResponseAsync: vi.fn(),
+  getLogoutUrlAsync: vi.fn(
+    async () => 'https://idp.acme.example/slo?SAMLRequest=xyz',
+  ),
+  validateRedirectAsync: vi.fn(async () => ({
+    profile: null,
+    loggedOut: true,
+  })),
+};
+
+const goodTx = {
+  provider: 'acme',
+  requestId: '_feedfacefeedfacefeedfacefeedface',
+  returnTo: '/dashboard',
+};
+
+const goodProfile = {
+  issuer: 'https://idp.acme.example/metadata',
+  nameID: 'persistent-subject-123',
+  nameIDFormat: PERSISTENT,
+  inResponseTo: goodTx.requestId,
+  sessionIndex: 'sess-1',
+  email: 'user@acme.com',
+  groups: ['admins'],
+};
+
+// samlConfig must declare the IdP issuer the ACS pins against.
+Object.assign(samlConfig, { idpIssuer: 'https://idp.acme.example/metadata' });
+
+describe('SamlController', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(getSamlClient).mockReturnValue(samlInstance as never);
+    vi.mocked(getFederatedProvider).mockReturnValue({
+      protocol: 'saml',
+      config: samlConfig,
+    } as never);
+  });
+
+  describe('login', () => {
+    it('404s for an unknown provider without echoing the param', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
+      const res = mkRes() as never as {
+        status: ReturnType<typeof vi.fn>;
+        json: ReturnType<typeof vi.fn>;
+      };
+      await samlController.login(
+        {
+          params: { provider: '<script>alert(1)</script>' },
+          query: {},
+        } as never,
+        res as never,
+      );
+      expect(res.status).toHaveBeenCalledWith(404);
+      expect(JSON.stringify(res.json.mock.calls)).not.toContain('<script>');
+      expect(setSamlTransactionCookie).not.toHaveBeenCalled();
+    });
+
+    it('404s when the provider exists but is OIDC', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'oidc',
+        config: { id: 'okta' },
+      } as never);
+      const res = mkRes() as never as { status: ReturnType<typeof vi.fn> };
+      await samlController.login(
+        { params: { provider: 'okta' }, query: {} } as never,
+        res as never,
+      );
+      expect(res.status).toHaveBeenCalledWith(404);
+    });
+
+    it('stores the transaction (cookie, not RelayState) and redirects', async () => {
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.login(
+        {
+          params: { provider: 'acme' },
+          query: { returnTo: '/dashboard' },
+        } as never,
+        res as never,
+      );
+      expect(getSamlClient).toHaveBeenCalledWith(
+        'acme',
+        '_feedfacefeedfacefeedfacefeedface',
+      );
+      expect(setSamlTransactionCookie).toHaveBeenCalledWith(
+        res,
+        expect.objectContaining({
+          provider: 'acme',
+          requestId: '_feedfacefeedfacefeedfacefeedface',
+          returnTo: '/dashboard',
+        }),
+      );
+      // RelayState must be empty — returnTo travels only in the signed cookie.
+      expect(samlInstance.getAuthorizeUrlAsync).toHaveBeenCalledWith(
+        '',
+        undefined,
+        {},
+      );
+      expect(res.redirect).toHaveBeenCalledWith(
+        'https://idp.acme.example/sso?SAMLRequest=abc',
+      );
+    });
+
+    it.each(['https://evil.com', '//evil.com', '/\\evil.com'])(
+      'neutralises malicious returnTo %s to "/"',
+      async (returnTo) => {
+        const res = mkRes();
+        await samlController.login(
+          { params: { provider: 'acme' }, query: { returnTo } } as never,
+          res,
+        );
+        expect(setSamlTransactionCookie).toHaveBeenCalledWith(
+          res,
+          expect.objectContaining({ returnTo: '/' }),
+        );
+      },
+    );
+
+    it('redirects to the generic error page when the client throws', async () => {
+      samlInstance.getAuthorizeUrlAsync.mockRejectedValueOnce(
+        new Error('boom'),
+      );
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.login(
+        { params: { provider: 'acme' }, query: {} } as never,
+        res as never,
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+  });
+
+  describe('callback (ACS)', () => {
+    const mkReq = (body = { SAMLResponse: 'b64' }) =>
+      ({ params: { provider: 'acme' }, body }) as never;
+
+    beforeEach(() => {
+      vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      vi.mocked(readSamlTransaction).mockReturnValue(goodTx);
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: { ...goodProfile },
+        loggedOut: false,
+      });
+      vi.mocked(ApiClient.resolveFederatedUser).mockResolvedValue({
+        id: 7,
+        email: 'user@acme.com',
+        permissions: [Permission.READ_SOME_ENTITY],
+      } as never);
+    });
+
+    it('happy path: validates, resolves, issues tokens, sets SLO hint, redirects', async () => {
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+
+      expect(clearSamlTransactionCookie).toHaveBeenCalled(); // single-use
+      expect(ApiClient.resolveFederatedUser).toHaveBeenCalledWith(
+        {
+          provider: 'acme',
+          subject: 'persistent-subject-123',
+          email: 'user@acme.com',
+          emailVerified: true,
+          suggestedPermissions: [Permission.WRITE_SOME_ENTITY],
+        },
+        expect.any(String),
+      );
+      expect(respondWithTokens).toHaveBeenCalledWith(
+        expect.anything(),
+        {
+          id: 7,
+          email: 'user@acme.com',
+          permissions: [Permission.READ_SOME_ENTITY],
+        },
+        expect.objectContaining({ issueRefreshCookie: true }),
+      );
+      expect(setSamlLogoutHintCookie).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          provider: 'acme',
+          nameId: 'persistent-subject-123',
+          sessionIndex: 'sess-1',
+        }),
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/dashboard');
+    });
+
+    it('rejects without a transaction cookie (IdP-initiated blocked)', async () => {
+      vi.mocked(readSamlTransaction).mockReturnValue(null);
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(samlInstance.validatePostResponseAsync).not.toHaveBeenCalled();
+      expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('rejects a transaction bound to a different provider (mix-up)', async () => {
+      vi.mocked(readSamlTransaction).mockReturnValue({
+        ...goodTx,
+        provider: 'other',
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(samlInstance.validatePostResponseAsync).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('rejects a response whose Issuer is a different IdP (mix-up)', async () => {
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: { ...goodProfile, issuer: 'https://evil-idp.example/meta' },
+        loggedOut: false,
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('rejects an InResponseTo that does not match the transaction', async () => {
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: { ...goodProfile, inResponseTo: '_someoneelses' },
+        loggedOut: false,
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('rejects a transient NameID (unstable identifier)', async () => {
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: { ...goodProfile, nameIDFormat: TRANSIENT },
+        loggedOut: false,
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('rejects an invalid signature (validate throws) without leaking detail', async () => {
+      samlInstance.validatePostResponseAsync.mockRejectedValue(
+        new Error('Invalid signature <xml>secret</xml>'),
+      );
+      const res = mkRes() as never as {
+        redirect: ReturnType<typeof vi.fn>;
+        json: ReturnType<typeof vi.fn>;
+      };
+      await samlController.callback(mkReq(), res as never);
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+      expect(res.json).not.toHaveBeenCalled();
+    });
+
+    it('rejects an email outside the domain allowlist (cross-tenant containment)', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: { ...samlConfig, allowedDomains: ['acme.com'] },
+      } as never);
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: { ...goodProfile, email: 'victim@othertenant.com' },
+        loggedOut: false,
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('accepts an allowlisted email and rejects malformed/hostile emails', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: { ...samlConfig, allowedDomains: ['acme.com'] },
+      } as never);
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(res.redirect).toHaveBeenCalledWith('/dashboard');
+
+      for (const email of ['not-an-email', 'a@b<script>.com', '']) {
+        vi.mocked(ApiClient.resolveFederatedUser).mockClear();
+        samlInstance.validatePostResponseAsync.mockResolvedValue({
+          profile: { ...goodProfile, email },
+          loggedOut: false,
+        });
+        const res2 = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+        await samlController.callback(mkReq(), res2 as never);
+        expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+        expect(res2.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+      }
+    });
+
+    it('falls back to the NameID as email only for the emailAddress format', async () => {
+      samlInstance.validatePostResponseAsync.mockResolvedValue({
+        profile: {
+          ...goodProfile,
+          email: undefined,
+          nameID: 'User@Acme.com',
+          nameIDFormat:
+            'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+        },
+        loggedOut: false,
+      });
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(ApiClient.resolveFederatedUser).toHaveBeenCalledWith(
+        expect.objectContaining({ email: 'user@acme.com' }),
+        expect.any(String),
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/dashboard');
+    });
+
+    it('issues no half-session when the api resolve fails', async () => {
+      vi.mocked(ApiClient.resolveFederatedUser).mockRejectedValue(
+        new Error('api down'),
+      );
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(respondWithTokens).not.toHaveBeenCalled();
+      expect(setSamlLogoutHintCookie).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('404s for an unknown provider', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
+      const res = mkRes() as never as { status: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(res.status).toHaveBeenCalledWith(404);
+    });
+
+    it('sets no SLO hint when token issuance itself fails', async () => {
+      vi.mocked(respondWithTokens).mockRejectedValueOnce(new Error('boom'));
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.callback(mkReq(), res as never);
+      expect(setSamlLogoutHintCookie).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/login?sso_error=1');
+    });
+
+    it('clears the transaction cookie even on rejection paths (single-use)', async () => {
+      vi.mocked(readSamlTransaction).mockReturnValue(null);
+      const res = mkRes();
+      await samlController.callback(mkReq(), res);
+      expect(clearSamlTransactionCookie).toHaveBeenCalledWith(res);
+    });
+  });
+
+  describe('sloRedirectUrl', () => {
+    const hint = {
+      provider: 'acme',
+      nameId: 'persistent-subject-123',
+      sessionIndex: 'sess-1',
+    };
+
+    it('returns null when the provider is unknown, OIDC, or has no logoutUrl', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
+      expect(await samlController.sloRedirectUrl(hint, '/')).toBeNull();
+
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'oidc',
+        config: { id: 'acme' },
+      } as never);
+      expect(await samlController.sloRedirectUrl(hint, '/')).toBeNull();
+
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: { ...samlConfig, logoutUrl: undefined },
+      } as never);
+      expect(await samlController.sloRedirectUrl(hint, '/')).toBeNull();
+    });
+
+    it('builds the IdP SLO URL with the hint identity and a vetted RelayState', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: {
+          ...samlConfig,
+          idpIssuer: 'https://idp.acme.example/metadata',
+          logoutUrl: 'https://idp.acme.example/slo',
+        },
+      } as never);
+      const url = await samlController.sloRedirectUrl(
+        hint,
+        'https://evil.com/phish', // must be neutralised to '/'
+      );
+      expect(url).toBe('https://idp.acme.example/slo?SAMLRequest=xyz');
+      expect(samlInstance.getLogoutUrlAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          nameID: 'persistent-subject-123',
+          sessionIndex: 'sess-1',
+        }),
+        '/', // RelayState sanitised by safeReturnTo
+        {},
+      );
+    });
+
+    it('returns null (best-effort) when URL generation throws', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: { ...samlConfig, logoutUrl: 'https://idp.acme.example/slo' },
+      } as never);
+      samlInstance.getLogoutUrlAsync.mockRejectedValueOnce(new Error('down'));
+      expect(await samlController.sloRedirectUrl(hint, '/')).toBeNull();
+    });
+  });
+
+  describe('logoutCallback', () => {
+    it('lands on a vetted local path, neutralising external RelayState', async () => {
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.logoutCallback(
+        {
+          method: 'GET',
+          params: { provider: 'acme' },
+          query: { SAMLResponse: 'b64', RelayState: 'https://evil.com' },
+          originalUrl: '/api/v1/auth/sso/acme/logout/callback?SAMLResponse=b64',
+        } as never,
+        res as never,
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/');
+    });
+
+    it('an invalid LogoutResponse never breaks the landing', async () => {
+      samlInstance.validateRedirectAsync.mockRejectedValueOnce(
+        new Error('bad signature'),
+      );
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.logoutCallback(
+        {
+          method: 'GET',
+          params: { provider: 'acme' },
+          query: { SAMLResponse: 'b64', RelayState: '/login' },
+          originalUrl: '/x?SAMLResponse=b64',
+        } as never,
+        res as never,
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/login');
+    });
+
+    it('lands locally even for an unknown provider (no validation possible)', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.logoutCallback(
+        {
+          method: 'GET',
+          params: { provider: 'ghost' },
+          query: {},
+          originalUrl: '/x',
+        } as never,
+        res as never,
+      );
+      expect(res.redirect).toHaveBeenCalledWith('/login');
+    });
+
+    it('validates POST-binding LogoutResponses through the post validator', async () => {
+      const res = mkRes() as never as { redirect: ReturnType<typeof vi.fn> };
+      await samlController.logoutCallback(
+        {
+          method: 'POST',
+          params: { provider: 'acme' },
+          query: {},
+          body: { SAMLResponse: 'b64', RelayState: '/done' },
+          originalUrl: '/x',
+        } as never,
+        res as never,
+      );
+      expect(samlInstance.validatePostResponseAsync).toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/done');
+    });
+  });
+
+  describe('metadata', () => {
+    it('404s for unknown or OIDC providers', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
+      const res = mkRes() as never as { status: ReturnType<typeof vi.fn> };
+      samlController.metadata(
+        { params: { provider: 'ghost' } } as never,
+        res as never,
+      );
+      expect(res.status).toHaveBeenCalledWith(404);
+
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'oidc',
+        config: { id: 'okta' },
+      } as never);
+      const res2 = mkRes() as never as { status: ReturnType<typeof vi.fn> };
+      samlController.metadata(
+        { params: { provider: 'okta' } } as never,
+        res2 as never,
+      );
+      expect(res2.status).toHaveBeenCalledWith(404);
+    });
+
+    it('serves SP metadata with the SAML content type and no secrets', () => {
+      const res = mkRes() as never as {
+        type: ReturnType<typeof vi.fn>;
+        send: ReturnType<typeof vi.fn>;
+      };
+      samlController.metadata(
+        { params: { provider: 'acme' } } as never,
+        res as never,
+      );
+      // Generated without certs: no signing cert, no decryption cert.
+      expect(samlInstance.generateServiceProviderMetadata).toHaveBeenCalledWith(
+        null,
+        null,
+      );
+      expect(res.type).toHaveBeenCalledWith('application/samlmetadata+xml');
+      const sent = res.send.mock.calls[0][0] as string;
+      expect(sent).toContain('EntityDescriptor');
+      expect(sent).not.toContain('SUPER-SECRET-KEY-MATERIAL');
+    });
+  });
+});
diff --git a/apps/gateway/src/controllers/saml.controller.ts b/apps/gateway/src/controllers/saml.controller.ts
new file mode 100644
index 0000000..243f45a
--- /dev/null
+++ b/apps/gateway/src/controllers/saml.controller.ts
@@ -0,0 +1,349 @@
+import HttpResponser from '@gateway/adapters/http/http.responser';
+import { ApiClient } from '@gateway/clients/api.client';
+import { respondWithTokens } from '@gateway/middleware/auth.middleware';
+import { getFederatedProvider } from '@gateway/sso/federated-registry';
+import { mapGroupsToPermissions } from '@gateway/sso/permission-mapper';
+import { generateSamlRequestId, getSamlClient } from '@gateway/sso/saml-client';
+import {
+  SamlLogoutHint,
+  setSamlLogoutHintCookie,
+} from '@gateway/sso/saml-logout.service';
+import {
+  clearSamlTransactionCookie,
+  readSamlTransaction,
+  setSamlTransactionCookie,
+} from '@gateway/sso/saml-transaction.service';
+import { safeReturnTo } from '@gateway/sso/sso-transaction.service';
+import type { Profile } from '@node-saml/node-saml';
+import { randomUUID } from 'crypto';
+import type { Request, Response } from 'express';
+
+// Where the SPA lands when SSO fails. A relative path so it can never be an
+// open redirect, and it carries no IdP error detail (avoids leakage).
+const SSO_ERROR_REDIRECT = '/login?sso_error=1';
+
+// NameID formats whose (provider, subject) link is stable across logins.
+// `transient` is rejected by design — a per-session identifier must never key
+// a federated identity. `unspecified` is also rejected: an explicit allowlist
+// fails closed; legacy IdPs should be configured to emit persistent NameIDs
+// (our AuthnRequest requests the persistent format).
+const ACCEPTED_NAMEID_FORMATS = [
+  'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+  'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+];
+
+// Pragmatic email shape check on the asserted attribute. The API re-validates
+// with zod (`z.string().email()`); this gate exists so an obviously broken or
+// hostile value never leaves the gateway. Angle brackets and control chars are
+// rejected outright (comment-injection / log-injection defense in depth).
+const isPlausibleEmail = (value: string): boolean => {
+  if (value.length === 0 || value.length > 150) return false;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) return false;
+  }
+  if (/[<>"'`\\]/.test(value)) return false;
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+};
+
+/** First string value of a (possibly multi-valued) SAML attribute. */
+const attributeAsString = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value) && typeof value[0] === 'string') return value[0];
+  return undefined;
+};
+
+/** Looks up the provider and narrows to SAML; undefined for unknown/OIDC. */
+const samlProvider = (req: Request) => {
+  const fed = getFederatedProvider(req.params.provider as string);
+  return fed?.protocol === 'saml' ? fed.config : undefined;
+};
+
+class SamlController {
+  /**
+   * SP-initiated login: mint a CSPRNG AuthnRequest id, persist it together
+   * with the vetted `returnTo` in the signed transaction cookie, and redirect
+   * to the IdP (HTTP-Redirect binding).
+   *
+   * RelayState is deliberately EMPTY: the post-login destination travels only
+   * inside the signed cookie, so a tampered RelayState can never become an
+   * open redirect.
+   */
+  login = async (req: Request, res: Response) => {
+    const config = samlProvider(req);
+    if (!config) {
+      // Generic message — never echo the :provider param (reflection/XSS).
+      return HttpResponser.errorJson(res, { message: 'Unknown provider' }, 404);
+    }
+
+    try {
+      const requestId = generateSamlRequestId();
+      const returnTo = safeReturnTo(req.query.returnTo);
+      const saml = getSamlClient(config.id, requestId);
+      const url = await saml.getAuthorizeUrlAsync('', undefined, {});
+
+      setSamlTransactionCookie(res, {
+        provider: config.id,
+        requestId,
+        returnTo,
+      });
+      return res.redirect(url);
+    } catch {
+      return res.redirect(SSO_ERROR_REDIRECT);
+    }
+  };
+
+  /**
+   * Assertion Consumer Service (HTTP-POST binding) — the security heart of
+   * the SAML flow. Validation chain (every step fail-closed, none of it
+   * disableable through env):
+   *
+   *  1. The signed transaction cookie must exist and belong to the SAME
+   *     provider that started the flow (read + cleared: single-use). Its
+   *     absence means the response is unsolicited → IdP-initiated SSO is
+   *     rejected by design.
+   *  2. node-saml (hardened in saml-client.ts) verifies: XML signature on the
+   *     Response AND the Assertion against the registry's pinned cert(s) only
+   *     (never certs embedded in the response), Status == Success,
+   *     Conditions/NotBefore/NotOnOrAfter with bounded skew, AudienceRestriction
+   *     == our SP entityID, response Issuer == configured idpIssuer (mix-up
+   *     defense), InResponseTo present in its request cache (single-use).
+   *  3. The response's InResponseTo must equal the AuthnRequest id from the
+   *     transaction cookie — binds the response to the browser that started
+   *     the flow (anti-CSRF on a route that is necessarily CSRF-exempt).
+   *  4. NameID must use a stable format (persistent/emailAddress; transient
+   *     rejected) and the asserted email must be plausible and — when
+   *     `allowedDomains` is configured — inside the tenant's domain allowlist
+   *     (cross-tenant assertion containment).
+   *
+   * `emailVerified: true` is a documented policy decision: the tenant's IdP is
+   * authoritative for its own domain, the operator configures it explicitly,
+   * and `allowedDomains` bounds the blast radius.
+   *
+   * Errors NEVER reflect IdP status/XML back to the browser (XSS/info-leak):
+   * generic redirect only, structured log keyed by an internal requestId.
+   */
+  callback = async (req: Request, res: Response) => {
+    const config = samlProvider(req);
+    if (!config) {
+      return HttpResponser.errorJson(res, { message: 'Unknown provider' }, 404);
+    }
+
+    // Single-use: read then immediately clear the transaction cookie.
+    const tx = readSamlTransaction(req);
+    clearSamlTransactionCookie(res);
+    if (!tx || tx.provider !== config.id) {
+      return res.redirect(SSO_ERROR_REDIRECT);
+    }
+
+    const requestId = randomUUID();
+    try {
+      const saml = getSamlClient(config.id);
+      const { profile, loggedOut } = await saml.validatePostResponseAsync(
+        (req.body ?? {}) as Record<string, string>,
+      );
+      if (loggedOut || !profile)
+        throw new Error('SAML: no profile in response');
+
+      // Issuer pin (mix-up defense). node-saml's `idpIssuer` option is only
+      // enforced on LogoutRequest/LogoutResponse, NOT on the login Response —
+      // so we MUST check the asserted issuer here, otherwise a response signed
+      // by a *different* configured IdP would be accepted for this provider.
+      if (profile.issuer !== config.idpIssuer) {
+        throw new Error(
+          'SAML: response Issuer does not match the configured IdP',
+        );
+      }
+
+      // InResponseTo ⇄ transaction binding (on top of node-saml's own cache).
+      if (profile.inResponseTo !== tx.requestId) {
+        throw new Error('SAML: InResponseTo does not match the transaction');
+      }
+
+      // Stable-identifier policy: reject transient (and anything not
+      // explicitly allowed). The (provider, subject) pair keys the account.
+      if (
+        !profile.nameID ||
+        !ACCEPTED_NAMEID_FORMATS.includes(profile.nameIDFormat)
+      ) {
+        throw new Error('SAML: NameID missing or non-persistent format');
+      }
+
+      const email = (
+        attributeAsString(profile[config.emailAttribute]) ??
+        (profile.nameIDFormat === ACCEPTED_NAMEID_FORMATS[1]
+          ? profile.nameID
+          : '')
+      )
+        .trim()
+        .toLowerCase();
+      if (!isPlausibleEmail(email)) {
+        throw new Error('SAML: asserted email is missing or malformed');
+      }
+
+      // Cross-tenant containment: an IdP may only assert emails inside its
+      // configured domain allowlist. This is MANDATORY (the registry fails fast
+      // when it is absent) because the ACS stamps `emailVerified: true` below —
+      // without this gate a signed assertion could claim an arbitrary email and
+      // auto-link to a pre-existing/other-tenant account (account takeover).
+      const domain = email.slice(email.lastIndexOf('@') + 1);
+      if (
+        !config.allowedDomains.length ||
+        !config.allowedDomains.includes(domain)
+      ) {
+        throw new Error('SAML: asserted email domain is not allowed');
+      }
+
+      const suggestedPermissions = mapGroupsToPermissions(
+        profile[config.groupsAttribute],
+        config.permissionMap,
+      );
+
+      const user = await ApiClient.resolveFederatedUser(
+        {
+          provider: config.id,
+          subject: profile.nameID,
+          email,
+          emailVerified: true,
+          suggestedPermissions,
+        },
+        requestId,
+      );
+
+      await respondWithTokens(
+        res,
+        { id: user.id, email: user.email, permissions: user.permissions },
+        { issueRefreshCookie: true, requestId },
+      );
+
+      // Best-effort SLO hint so logout can also end the IdP session (T-37).
+      setSamlLogoutHintCookie(res, {
+        provider: config.id,
+        nameId: profile.nameID,
+        nameIdFormat: profile.nameIDFormat,
+        sessionIndex: profile.sessionIndex,
+      });
+
+      return res.redirect(safeReturnTo(tx.returnTo));
+    } catch (err) {
+      // Internal, structured log only — NEVER the raw response or IdP status
+      // to the browser. The message may carry IdP-controlled fragments, so it
+      // is stripped of control characters and truncated (log-injection
+      // defense) before logging.
+      const reason = (err instanceof Error ? err.message : 'unknown error')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f\x7f]+/g, ' ')
+        .slice(0, 200);
+      console.warn(
+        `[SAML] ACS rejected a response (provider="${config.id}", requestId="${requestId}"): ${reason}`,
+      );
+      return res.redirect(SSO_ERROR_REDIRECT);
+    }
+  };
+
+  /**
+   * SP metadata for IdP onboarding. Public by design: it only carries the SP
+   * entityID, the ACS URL and the requested NameID format — never private
+   * keys (we neither sign AuthnRequests nor publish the decryption cert here;
+   * encrypted-assertion certs are exchanged with the IdP out-of-band).
+   */
+  metadata = (req: Request, res: Response) => {
+    const config = samlProvider(req);
+    if (!config) {
+      return HttpResponser.errorJson(res, { message: 'Unknown provider' }, 404);
+    }
+
+    try {
+      const xml = getSamlClient(config.id).generateServiceProviderMetadata(
+        null,
+        null,
+      );
+      return res.type('application/samlmetadata+xml').send(xml);
+    } catch {
+      return HttpResponser.errorJson(
+        res,
+        { message: 'Metadata unavailable' },
+        500,
+      );
+    }
+  };
+
+  /**
+   * Builds the IdP SLO redirect URL for a logout hint (HTTP-Redirect
+   * binding), or null when SLO is not possible. STRICTLY best-effort: the
+   * caller has ALWAYS revoked the local refresh family before calling this —
+   * a null/throwing result only skips the IdP round-trip, never keeps a
+   * local session alive.
+   *
+   * The LogoutRequest is unsigned: signing would require an SP private key,
+   * which this starter deliberately does not manage (documented in
+   * SECURITY.md). RelayState carries only a local relative path and is
+   * re-validated with `safeReturnTo` when the IdP lands back on the SLO
+   * callback.
+   */
+  sloRedirectUrl = async (
+    hint: SamlLogoutHint,
+    relayState: string,
+  ): Promise<string | null> => {
+    const fed = getFederatedProvider(hint.provider);
+    if (fed?.protocol !== 'saml' || !fed.config.logoutUrl) return null;
+
+    try {
+      const saml = getSamlClient(hint.provider);
+      const profile: Profile = {
+        issuer: fed.config.idpIssuer,
+        nameID: hint.nameId,
+        nameIDFormat:
+          hint.nameIdFormat ??
+          'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+        ...(hint.sessionIndex ? { sessionIndex: hint.sessionIndex } : {}),
+      };
+      return await saml.getLogoutUrlAsync(
+        profile,
+        safeReturnTo(relayState),
+        {},
+      );
+    } catch {
+      return null; // best-effort: fall back to the local redirect
+    }
+  };
+
+  /**
+   * SLO response landing (GET = HTTP-Redirect binding, POST = HTTP-POST
+   * binding). The LogoutResponse is validated when possible (signature if
+   * present, InResponseTo against the request cache); ANY failure is ignored
+   * silently — by the time the IdP sends us here the local session is already
+   * fully revoked, so a forged/broken LogoutResponse can produce no state
+   * change. We simply land the browser on a vetted local path.
+   */
+  logoutCallback = async (req: Request, res: Response) => {
+    const config = samlProvider(req);
+    const relayState =
+      (typeof req.query?.RelayState === 'string' && req.query.RelayState) ||
+      (typeof req.body?.RelayState === 'string' && req.body.RelayState) ||
+      '/login';
+
+    if (config) {
+      try {
+        const saml = getSamlClient(config.id);
+        if (req.method === 'POST') {
+          await saml.validatePostResponseAsync(
+            (req.body ?? {}) as Record<string, string>,
+          );
+        } else if (typeof req.query?.SAMLResponse === 'string') {
+          const originalQuery = req.originalUrl.split('?')[1] ?? '';
+          await saml.validateRedirectAsync(
+            req.query as Record<string, string>,
+            originalQuery,
+          );
+        }
+      } catch {
+        /* silent — no state change is possible here */
+      }
+    }
+    return res.redirect(safeReturnTo(relayState));
+  };
+}
+
+const samlController = new SamlController();
+export default samlController;
diff --git a/apps/gateway/src/controllers/sso.controller.spec.ts b/apps/gateway/src/controllers/sso.controller.spec.ts
index 49c9d3f..8259c63 100644
--- a/apps/gateway/src/controllers/sso.controller.spec.ts
+++ b/apps/gateway/src/controllers/sso.controller.spec.ts
@@ -3,7 +3,18 @@ import { Permission } from '@dto';
 
 vi.mock('@gateway/sso/provider-registry', () => ({
   getProviderConfig: vi.fn(),
+}));
+vi.mock('@gateway/sso/federated-registry', () => ({
   listPublicProviders: vi.fn(),
+  getFederatedProvider: vi.fn(),
+}));
+vi.mock('@gateway/controllers/saml.controller', () => ({
+  default: { login: vi.fn(), metadata: vi.fn(), sloRedirectUrl: vi.fn() },
+}));
+vi.mock('@gateway/sso/saml-logout.service', () => ({
+  setSamlLogoutHintCookie: vi.fn(),
+  clearSamlLogoutHintCookie: vi.fn(),
+  readSamlLogoutHint: vi.fn(),
 }));
 vi.mock('@gateway/sso/discovery', () => ({ getClient: vi.fn() }));
 vi.mock('@gateway/clients/api.client', () => ({
@@ -35,10 +46,16 @@ vi.mock('openid-client', () => ({
   },
 }));
 
+import { getProviderConfig } from '@gateway/sso/provider-registry';
 import {
-  getProviderConfig,
+  getFederatedProvider,
   listPublicProviders,
-} from '@gateway/sso/provider-registry';
+} from '@gateway/sso/federated-registry';
+import samlController from '@gateway/controllers/saml.controller';
+import {
+  clearSamlLogoutHintCookie,
+  readSamlLogoutHint,
+} from '@gateway/sso/saml-logout.service';
 import { getClient } from '@gateway/sso/discovery';
 import { ApiClient } from '@gateway/clients/api.client';
 import {
@@ -111,7 +128,7 @@ describe('SsoController', () => {
 
   describe('login', () => {
     it('404s for an unknown provider', async () => {
-      vi.mocked(getProviderConfig).mockReturnValue(undefined);
+      vi.mocked(getFederatedProvider).mockReturnValue(undefined);
       const res = mkRes();
       await ssoController.login(
         { params: { provider: 'nope' }, query: {} } as never,
@@ -121,8 +138,23 @@ describe('SsoController', () => {
       expect(setTransactionCookie).not.toHaveBeenCalled();
     });
 
+    it('dispatches SAML providers to the SAML controller', async () => {
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'saml',
+        config: { id: 'acme' },
+      } as never);
+      const res = mkRes();
+      const req = { params: { provider: 'acme' }, query: {} } as never;
+      await ssoController.login(req, res);
+      expect(samlController.login).toHaveBeenCalledWith(req, res);
+      expect(setTransactionCookie).not.toHaveBeenCalled();
+    });
+
     it('stores the transaction and redirects to the IdP with PKCE S256', async () => {
-      vi.mocked(getProviderConfig).mockReturnValue(config as never);
+      vi.mocked(getFederatedProvider).mockReturnValue({
+        protocol: 'oidc',
+        config,
+      } as never);
       const res = mkRes();
       await ssoController.login(
         {
@@ -336,5 +368,74 @@ describe('SsoController', () => {
       expect(clearRefreshCookie).toHaveBeenCalledWith(res);
       expect(res.redirect).toHaveBeenCalledWith('/bye');
     });
+
+    it('SAML session: revokes the family FIRST, then redirects to the IdP SLO', async () => {
+      vi.mocked(readLogoutHint).mockReturnValue(null);
+      vi.mocked(readSamlLogoutHint).mockReturnValue({
+        provider: 'acme',
+        nameId: 'subject-1',
+        sessionIndex: 'sess-1',
+      });
+      vi.mocked(samlController.sloRedirectUrl).mockResolvedValue(
+        'https://idp.acme.example/slo?SAMLRequest=xyz',
+      );
+      const res = mkRes();
+      await ssoController.logout({ query: {}, cookies: {} } as never, res);
+
+      // Local revocation + cookie cleanup happen before any IdP involvement.
+      expect(revokeCurrentRefreshFamily).toHaveBeenCalled();
+      expect(clearRefreshCookie).toHaveBeenCalledWith(res);
+      expect(clearSamlLogoutHintCookie).toHaveBeenCalledWith(res);
+      expect(res.redirect).toHaveBeenCalledWith(
+        'https://idp.acme.example/slo?SAMLRequest=xyz',
+      );
+    });
+
+    it('SAML session without SLO support: local logout only', async () => {
+      vi.mocked(readLogoutHint).mockReturnValue(null);
+      vi.mocked(readSamlLogoutHint).mockReturnValue({
+        provider: 'acme',
+        nameId: 'subject-1',
+      });
+      vi.mocked(samlController.sloRedirectUrl).mockResolvedValue(null);
+      const res = mkRes();
+      await ssoController.logout(
+        { query: { returnTo: '/bye' }, cookies: {} } as never,
+        res,
+      );
+      expect(revokeCurrentRefreshFamily).toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/bye');
+    });
+
+    it('stale dual hints: OIDC takes precedence, SAML SLO never runs', async () => {
+      // Should be impossible (a session is one protocol), but stale cookies
+      // could coexist: OIDC end_session wins and SAML is not contacted.
+      vi.mocked(readLogoutHint).mockReturnValue({
+        provider: 'okta',
+        idToken: 'tok',
+      });
+      vi.mocked(readSamlLogoutHint).mockReturnValue({
+        provider: 'acme',
+        nameId: 'subject-1',
+      });
+      vi.mocked(getProviderConfig).mockReturnValue(config as never);
+      const res = mkRes();
+      await ssoController.logout({ query: {}, cookies: {} } as never, res);
+      expect(res.redirect).toHaveBeenCalledWith(
+        'https://example.okta.com/logout?id_token_hint=x',
+      );
+      expect(samlController.sloRedirectUrl).not.toHaveBeenCalled();
+      // Both hint cookies are cleared regardless of which path redirects.
+      expect(clearSamlLogoutHintCookie).toHaveBeenCalledWith(res);
+    });
+
+    it('no hint of any protocol: plain local logout (no IdP round-trip)', async () => {
+      vi.mocked(readLogoutHint).mockReturnValue(null);
+      vi.mocked(readSamlLogoutHint).mockReturnValue(null);
+      const res = mkRes();
+      await ssoController.logout({ query: {}, cookies: {} } as never, res);
+      expect(samlController.sloRedirectUrl).not.toHaveBeenCalled();
+      expect(res.redirect).toHaveBeenCalledWith('/');
+    });
   });
 });
diff --git a/apps/gateway/src/controllers/sso.controller.ts b/apps/gateway/src/controllers/sso.controller.ts
index c95552a..6a5a9ed 100644
--- a/apps/gateway/src/controllers/sso.controller.ts
+++ b/apps/gateway/src/controllers/sso.controller.ts
@@ -13,9 +13,15 @@ import {
   setLogoutHintCookie,
 } from '@gateway/sso/sso-logout.service';
 import {
-  getProviderConfig,
+  clearSamlLogoutHintCookie,
+  readSamlLogoutHint,
+} from '@gateway/sso/saml-logout.service';
+import { getProviderConfig } from '@gateway/sso/provider-registry';
+import {
+  getFederatedProvider,
   listPublicProviders,
-} from '@gateway/sso/provider-registry';
+} from '@gateway/sso/federated-registry';
+import samlController from '@gateway/controllers/saml.controller';
 import {
   clearTransactionCookie,
   readTransaction,
@@ -36,15 +42,21 @@ class SsoController {
     HttpResponser.successJson(res, listPublicProviders());
 
   /**
-   * Start the Authorization Code + PKCE flow: mint state/nonce/PKCE, stash
-   * them in the signed transaction cookie, and redirect to the IdP.
+   * Unified federated login entry point: dispatches by the provider's
+   * protocol. SAML providers are handled by `saml.controller.ts`; OIDC starts
+   * the Authorization Code + PKCE flow — mint state/nonce/PKCE, stash them in
+   * the signed transaction cookie, and redirect to the IdP.
    */
   login = async (req: Request, res: Response) => {
     const providerId = req.params.provider as string;
-    const config = getProviderConfig(providerId);
-    if (!config) {
+    const fed = getFederatedProvider(providerId);
+    if (!fed) {
       return HttpResponser.errorJson(res, { message: 'Unknown provider' }, 404);
     }
+    if (fed.protocol === 'saml') {
+      return samlController.login(req, res);
+    }
+    const config = fed.config;
 
     try {
       const client = await getClient(providerId);
@@ -153,10 +165,15 @@ class SsoController {
 
   /**
    * RP-initiated logout. Always revokes the local refresh family and clears
-   * cookies FIRST (so a down IdP can never keep the local session alive), then
-   * — if the session is federated and the IdP supports end_session — redirects
-   * the browser to the provider to terminate the IdP session too. Best-effort:
-   * any IdP failure falls back to a same-site redirect.
+   * cookies FIRST (so a down IdP can never keep the local session alive),
+   * then — if the session is federated — best-effort terminates the IdP
+   * session too, dispatching by the protocol of whichever signed logout hint
+   * is present (OIDC end_session or SAML SLO). Any IdP failure falls back to
+   * a same-site redirect.
+   *
+   * IdP-initiated SLO (the IdP sending US a LogoutRequest) is out of scope —
+   * documented in SECURITY.md together with its residual risk, mirroring the
+   * OIDC back-channel-logout decision.
    */
   logout = async (req: Request, res: Response) => {
     const requestId = randomUUID();
@@ -169,6 +186,8 @@ class SsoController {
 
     const hint = readLogoutHint(req);
     clearLogoutHintCookie(res);
+    const samlHint = readSamlLogoutHint(req);
+    clearSamlLogoutHintCookie(res);
     const fallback = safeReturnTo(req.query.returnTo);
 
     if (hint) {
@@ -190,6 +209,13 @@ class SsoController {
         }
       }
     }
+
+    if (samlHint) {
+      // The local refresh family is already revoked above — this redirect is
+      // strictly best-effort and can never keep a session alive.
+      const sloUrl = await samlController.sloRedirectUrl(samlHint, fallback);
+      if (sloUrl) return res.redirect(sloUrl);
+    }
     return res.redirect(fallback);
   };
 }
diff --git a/apps/gateway/src/main.ts b/apps/gateway/src/main.ts
index 6726911..37b3234 100644
--- a/apps/gateway/src/main.ts
+++ b/apps/gateway/src/main.ts
@@ -6,6 +6,7 @@ import helmet from 'helmet';
 
 import api from './routes';
 import { validateSsoConfig } from './sso/provider-registry';
+import { validateSamlConfig } from './sso/saml-provider-registry';
 
 const parseOrigins = (raw?: string): string[] =>
   (raw ?? '')
@@ -26,6 +27,7 @@ class Main {
     // Fail-fast: a declared-but-misconfigured SSO provider must stop boot, not
     // surface at runtime. No providers configured ⇒ no-op (SSO disabled).
     validateSsoConfig();
+    validateSamlConfig();
     this.#config();
     this.#setRoutes();
     this.#app.listen(this.#port, '0.0.0.0', () => {
diff --git a/apps/gateway/src/routes/sso.routes.ts b/apps/gateway/src/routes/sso.routes.ts
index a51ecc1..0a84f86 100644
--- a/apps/gateway/src/routes/sso.routes.ts
+++ b/apps/gateway/src/routes/sso.routes.ts
@@ -1,6 +1,9 @@
+import samlController from '@gateway/controllers/saml.controller';
 import ssoController from '@gateway/controllers/sso.controller';
-import { Router } from 'express';
+import express, { Router } from 'express';
 
+// All routes here inherit the coarse per-IP authRateLimiter mounted on the
+// auth router (see auth.routes.ts) — including SAML login/metadata.
 const ssoRouter = Router();
 
 // Public list for the SPA login screen.
@@ -10,9 +13,35 @@ ssoRouter.get('/providers', ssoController.providers);
 // when federated). GET so the SPA can navigate to it (top-level redirect).
 ssoRouter.get('/logout', ssoController.logout);
 
-// OIDC Authorization Code + PKCE handshake. `:provider` is validated against
-// the registry inside the controller (no arbitrary providers).
+// Federated handshake (OIDC code+PKCE or SAML AuthnRequest — the controller
+// dispatches by protocol). `:provider` is validated against the registry
+// inside the controller (no arbitrary providers).
 ssoRouter.get('/:provider/login', ssoController.login);
 ssoRouter.get('/:provider/callback', ssoController.callback);
 
+// SAML Assertion Consumer Service (HTTP-POST binding). The urlencoded parser
+// is mounted ONLY here, with an explicit cap (encrypted responses grow, but
+// 256kb bounds XML-bomb/DoS payloads). The route is necessarily exempt from
+// cookie-based CSRF (it is a cross-site POST from the IdP) — protection comes
+// from the signed single-use transaction cookie + InResponseTo binding.
+ssoRouter.post(
+  '/:provider/callback',
+  express.urlencoded({ extended: false, limit: '256kb' }),
+  samlController.callback,
+);
+
+// SAML SLO response landing (Redirect or POST binding). Validation failures
+// are silently ignored: the local session was fully revoked before the IdP
+// round-trip started, so a forged LogoutResponse can change no state.
+ssoRouter.get('/:provider/logout/callback', samlController.logoutCallback);
+ssoRouter.post(
+  '/:provider/logout/callback',
+  express.urlencoded({ extended: false, limit: '256kb' }),
+  samlController.logoutCallback,
+);
+
+// SAML SP metadata for IdP onboarding. Public by design: entityID, ACS URL
+// and NameID format only — never secrets or private keys.
+ssoRouter.get('/:provider/metadata', samlController.metadata);
+
 export default ssoRouter;
diff --git a/apps/gateway/src/sso/federated-registry.ts b/apps/gateway/src/sso/federated-registry.ts
new file mode 100644
index 0000000..f7c0bc3
--- /dev/null
+++ b/apps/gateway/src/sso/federated-registry.ts
@@ -0,0 +1,97 @@
+import { SsoProviderPublicDTO } from '@dto';
+import { SsoProviderConfig, getAllProviderConfigs } from './provider-registry';
+import { SamlProviderConfig } from './saml-types';
+import {
+  getAllSamlProviderConfigs,
+  isSamlEnabled,
+  resetSamlRegistryCache,
+} from './saml-provider-registry';
+import { isSsoEnabled, resetRegistryCache } from './provider-registry';
+
+// Re-export so callers that previously depended on resetRegistryCache from
+// provider-registry can also reset the federated cache atomically.
+export { resetRegistryCache, resetSamlRegistryCache };
+
+/**
+ * Resets both underlying protocol caches in one call.
+ * Use in tests that mutate `process.env` or need a clean slate.
+ */
+export const resetFederatedRegistryCache = (): void => {
+  resetRegistryCache();
+  resetSamlRegistryCache();
+};
+
+// ---------------------------------------------------------------------------
+// Discriminated-union type for protocol-aware provider lookup
+// ---------------------------------------------------------------------------
+
+/** Result of {@link getFederatedProvider}: protocol-tagged config. */
+export type FederatedProvider =
+  | { protocol: 'oidc'; config: SsoProviderConfig }
+  | { protocol: 'saml'; config: SamlProviderConfig };
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the unified public metadata for all configured SSO providers
+ * (both OIDC and SAML), sorted by provider id for a stable display order.
+ *
+ * This is the single source of truth for the `/auth/sso/providers` endpoint.
+ * It MUST NOT include any secret-bearing fields (clientSecret, cert PEMs,
+ * issuer URLs, decryptionPvk, etc.) — only `id`, `displayName`, `iconKey`,
+ * and `protocol`.
+ */
+export const listPublicProviders = (): SsoProviderPublicDTO[] => {
+  const oidcProviders: SsoProviderPublicDTO[] = getAllProviderConfigs().map(
+    ({ id, displayName, iconKey }) => ({
+      id,
+      displayName,
+      iconKey,
+      protocol: 'oidc' as const,
+    }),
+  );
+
+  const samlProviders: SsoProviderPublicDTO[] = getAllSamlProviderConfigs().map(
+    ({ id, displayName, iconKey }) => ({
+      id,
+      displayName,
+      iconKey,
+      protocol: 'saml' as const,
+    }),
+  );
+
+  return [...oidcProviders, ...samlProviders].sort((a, b) =>
+    a.id.localeCompare(b.id),
+  );
+};
+
+/**
+ * Looks up a provider by id across both OIDC and SAML registries.
+ * Returns a discriminated union so callers can narrow to the correct
+ * config type without unsafe casts.
+ *
+ * Returns `undefined` when no provider with that id is registered.
+ */
+export const getFederatedProvider = (
+  id: string,
+): FederatedProvider | undefined => {
+  const oidcConfigs = getAllProviderConfigs();
+  const oidc = oidcConfigs.find((c) => c.id === id);
+  if (oidc) return { protocol: 'oidc', config: oidc };
+
+  const samlConfigs = getAllSamlProviderConfigs();
+  const saml = samlConfigs.find((c) => c.id === id);
+  if (saml) return { protocol: 'saml', config: saml };
+
+  return undefined;
+};
+
+/**
+ * Returns `true` when at least one SSO provider (OIDC or SAML) is configured.
+ * Use this to conditionally show the SSO section in the UI or enable
+ * federated-login routes.
+ */
+export const isFederationEnabled = (): boolean =>
+  isSsoEnabled() || isSamlEnabled();
diff --git a/apps/gateway/src/sso/provider-registry.spec.ts b/apps/gateway/src/sso/provider-registry.spec.ts
index 9bd0bdc..035afed 100644
--- a/apps/gateway/src/sso/provider-registry.spec.ts
+++ b/apps/gateway/src/sso/provider-registry.spec.ts
@@ -4,9 +4,12 @@ import {
   buildRegistryFromEnv,
   getProviderConfig,
   isSsoEnabled,
-  listPublicProviders,
   resetRegistryCache,
 } from './provider-registry';
+import {
+  listPublicProviders,
+  resetFederatedRegistryCache,
+} from './federated-registry';
 
 const okta = {
   SSO_OKTA_ISSUER: 'https://example.okta.com',
@@ -112,14 +115,34 @@ describe('buildRegistryFromEnv', () => {
       expect(() => buildRegistryFromEnv(okta)).not.toThrow();
     });
 
-    it('allows insecure issuers only behind the explicit dev escape hatch', () => {
-      expect(() =>
-        buildRegistryFromEnv({
-          ...okta,
-          SSO_OKTA_ISSUER: 'http://localhost:8080',
-          SSO_ALLOW_INSECURE_ISSUERS: 'true',
-        }),
-      ).not.toThrow();
+    it('allows insecure/local issuers only behind the explicit dev escape hatch', () => {
+      // Dev setups run the IdP on localhost or a private docker network.
+      for (const issuer of ['http://localhost:8080', 'https://10.1.2.3']) {
+        expect(() =>
+          buildRegistryFromEnv({
+            ...okta,
+            SSO_OKTA_ISSUER: issuer,
+            SSO_ALLOW_INSECURE_ISSUERS: 'true',
+          }),
+        ).not.toThrow();
+      }
+    });
+
+    it('blocks link-local/cloud-metadata even with the dev escape hatch', () => {
+      // Tier-1 block is unconditional — no escape hatch reaches 169.254.x.x.
+      for (const issuer of [
+        'https://169.254.169.254/meta',
+        'http://169.254.169.254/meta',
+        'https://0.0.0.0',
+      ]) {
+        expect(() =>
+          buildRegistryFromEnv({
+            ...okta,
+            SSO_OKTA_ISSUER: issuer,
+            SSO_ALLOW_INSECURE_ISSUERS: 'true',
+          }),
+        ).toThrow(/not allowed/);
+      }
     });
   });
 });
@@ -129,6 +152,7 @@ describe('public accessors (process.env-backed)', () => {
   afterEach(() => {
     process.env = { ...saved };
     resetRegistryCache();
+    resetFederatedRegistryCache();
   });
 
   it('listPublicProviders exposes only id/displayName/iconKey — no secrets', () => {
@@ -141,7 +165,12 @@ describe('public accessors (process.env-backed)', () => {
 
     const list = listPublicProviders();
     expect(list).toEqual([
-      { id: 'okta', displayName: 'Okta', iconKey: 'okta-logo' },
+      {
+        id: 'okta',
+        displayName: 'Okta',
+        iconKey: 'okta-logo',
+        protocol: 'oidc',
+      },
     ]);
     const serialised = JSON.stringify(list);
     expect(serialised).not.toContain('secret-okta');
diff --git a/apps/gateway/src/sso/provider-registry.ts b/apps/gateway/src/sso/provider-registry.ts
index 3eb5f5a..c58d8b3 100644
--- a/apps/gateway/src/sso/provider-registry.ts
+++ b/apps/gateway/src/sso/provider-registry.ts
@@ -1,9 +1,11 @@
-import { ClaimPermissionMapping, Permission, SsoProviderPublicDTO } from '@dto';
+import { ClaimPermissionMapping, Permission } from '@dto';
+// SsoProviderPublicDTO intentionally not imported here — the unified public
+// surface lives in federated-registry.ts, which owns listPublicProviders().
 
 /**
  * Full, secret-bearing configuration of one OIDC provider. Lives ONLY in the
- * gateway — never serialised to the client. Use {@link listPublicProviders}
- * for anything the browser may see.
+ * gateway — never serialised to the client. Use the federated registry's
+ * `listPublicProviders` for anything the browser may see.
  */
 export interface SsoProviderConfig {
   /** Lowercased provider key, used in `/auth/sso/:id/login`. */
@@ -23,47 +25,105 @@ export interface SsoProviderConfig {
 
 const ENV_PREFIX = /^SSO_(.+)_ISSUER$/;
 
-// Hosts that must never be reachable as an issuer: loopback, link-local
-// (incl. the 169.254.169.254 cloud metadata endpoint), and RFC1918 ranges.
-// SSRF defense — an attacker-influenced issuer must not pivot to internal hosts.
-const isBlockedHost = (host: string): boolean => {
-  const h = host.replace(/^\[|\]$/g, '').toLowerCase();
-  if (h === 'localhost' || h === '0.0.0.0' || h === '::1') return true;
+// SSRF defense, two tiers:
+// - ALWAYS blocked, even with the dev escape-hatch: link-local (incl. the
+//   169.254.169.254 cloud metadata endpoint) and 0.0.0.0/"this host". There is
+//   no legitimate federation scenario — dev included — pointing at those.
+// - Blocked unless the dev escape-hatch is active: loopback and RFC1918
+//   ranges. Dev setups legitimately run the IdP on localhost or a private
+//   docker network; production must never set SSO_ALLOW_INSECURE_ISSUERS.
+const parseIpv4 = (h: string): [number, number] | null => {
   const ipv4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
-  if (!ipv4) return false;
-  const [a, b] = [Number(ipv4[1]), Number(ipv4[2])];
-  if (a === 127 || a === 10 || a === 0) return true; // loopback / private / this-host
+  return ipv4 ? [Number(ipv4[1]), Number(ipv4[2])] : null;
+};
+
+const isAlwaysBlockedHost = (host: string): boolean => {
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+  if (h === '0.0.0.0') return true;
+  const ip = parseIpv4(h);
+  if (!ip) return false;
+  const [a, b] = ip;
+  if (a === 0) return true; // "this host"
   if (a === 169 && b === 254) return true; // link-local + cloud metadata
+  return false;
+};
+
+const isPrivateHost = (host: string): boolean => {
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+  if (h === 'localhost' || h === '::1') return true;
+  const ip = parseIpv4(h);
+  if (!ip) return false;
+  const [a, b] = ip;
+  if (a === 127 || a === 10) return true; // loopback / private
   if (a === 192 && b === 168) return true; // private
   if (a === 172 && b >= 16 && b <= 31) return true; // private
   return false;
 };
 
-const assertSafeIssuer = (
+/**
+ * SSRF guard for any federation URL (OIDC issuer, SAML entryPoint, logoutUrl…).
+ * Enforces https and blocks loopback/RFC1918 destinations, except when the dev
+ * escape-hatch (`SSO_ALLOW_INSECURE_ISSUERS=true`) is active — dev setups run
+ * IdPs on localhost/private networks. Link-local (cloud metadata) and 0.0.0.0
+ * are blocked UNCONDITIONALLY: the escape hatch never opens those.
+ *
+ * @param providerId  Provider id included in error messages (never the URL value).
+ * @param url         The URL to validate.
+ * @param allowInsecure  Set to true only in dev (`SSO_ALLOW_INSECURE_ISSUERS=true`).
+ * @param label       Human-readable field name for the error message (e.g. "issuer",
+ *                    "entryPoint", "logoutUrl").
+ */
+export const assertSafeFederationUrl = (
   providerId: string,
-  issuer: string,
+  url: string,
   allowInsecure: boolean,
+  label = 'url',
 ): void => {
-  let url: URL;
+  let parsed: URL;
   try {
-    url = new URL(issuer);
+    parsed = new URL(url);
   } catch {
-    throw new Error(`SSO provider "${providerId}" has a malformed issuer URL`);
+    throw new Error(
+      `SSO provider "${providerId}" has a malformed ${label} URL`,
+    );
+  }
+  // Tier 1 — unconditional: cloud-metadata/link-local/0.0.0.0 are never a
+  // legitimate federation target, not even in dev.
+  if (isAlwaysBlockedHost(parsed.hostname)) {
+    throw new Error(
+      `SSO provider "${providerId}" ${label} host is not allowed (link-local/metadata)`,
+    );
   }
-  if (url.protocol !== 'https:') {
-    if (allowInsecure && url.protocol === 'http:') return;
+  if (parsed.protocol !== 'https:') {
+    if (allowInsecure && parsed.protocol === 'http:') return;
     throw new Error(
-      `SSO provider "${providerId}" issuer must use https (got ${url.protocol})`,
+      `SSO provider "${providerId}" ${label} must use https (got ${parsed.protocol})`,
     );
   }
-  if (!allowInsecure && isBlockedHost(url.hostname)) {
+  // Tier 2 — loopback/RFC1918: blocked unless the explicit dev escape hatch.
+  if (!allowInsecure && isPrivateHost(parsed.hostname)) {
     throw new Error(
-      `SSO provider "${providerId}" issuer host is not allowed (loopback/link-local/private)`,
+      `SSO provider "${providerId}" ${label} host is not allowed (loopback/link-local/private)`,
     );
   }
 };
 
-const parsePermissionMap = (
+// Internal alias kept for backward-compatibility within this module.
+const assertSafeIssuer = (
+  providerId: string,
+  issuer: string,
+  allowInsecure: boolean,
+): void => assertSafeFederationUrl(providerId, issuer, allowInsecure, 'issuer');
+
+/**
+ * Parses a raw permission-map string (`claim:PERM1,PERM2;…`) into structured
+ * mappings. Unknown permissions and malformed entries are a fatal misconfiguration
+ * — this function throws so they are caught at boot, never granted silently.
+ *
+ * @param providerId  Included in error messages; must not contain secret material.
+ * @param raw         The raw env-var value, or `undefined` when the var is absent.
+ */
+export const parsePermissionMap = (
   providerId: string,
   raw: string | undefined,
 ): ClaimPermissionMapping[] => {
@@ -182,11 +242,3 @@ export const getProviderConfig = (id: string): SsoProviderConfig | undefined =>
   registry().get(id);
 
 export const isSsoEnabled = (): boolean => registry().size > 0;
-
-/** Secret-free provider metadata for the browser (login buttons). */
-export const listPublicProviders = (): SsoProviderPublicDTO[] =>
-  getAllProviderConfigs().map(({ id, displayName, iconKey }) => ({
-    id,
-    displayName,
-    iconKey,
-  }));
diff --git a/apps/gateway/src/sso/saml-client.spec.ts b/apps/gateway/src/sso/saml-client.spec.ts
new file mode 100644
index 0000000..7240741
--- /dev/null
+++ b/apps/gateway/src/sso/saml-client.spec.ts
@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ValidateInResponseTo } from '@node-saml/node-saml';
+import {
+  generateSamlRequestId,
+  getSamlClient,
+  resetSamlClientCaches,
+} from './saml-client';
+import { getSamlProviderConfig } from './saml-provider-registry';
+import type { SamlProviderConfig } from './saml-types';
+
+vi.mock('./saml-provider-registry', () => ({
+  getSamlProviderConfig: vi.fn(),
+}));
+
+const baseConfig: SamlProviderConfig = {
+  id: 'acme',
+  displayName: 'Acme',
+  entryPoint: 'https://idp.acme.example/sso',
+  issuer: 'https://app.example.com',
+  idpIssuer: 'https://idp.acme.example/metadata',
+  idpCertPems: ['-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----'],
+  callbackUrl: 'https://app.example.com/api/v1/auth/sso/acme/callback',
+  signatureAlgorithm: 'sha256',
+  wantAssertionsSigned: true,
+  groupsAttribute: 'groups',
+  emailAttribute: 'email',
+  permissionMap: [],
+};
+
+describe('generateSamlRequestId', () => {
+  it('produces unique, CSPRNG, xsd:ID-safe identifiers', () => {
+    const ids = new Set(
+      Array.from({ length: 100 }, () => generateSamlRequestId()),
+    );
+    expect(ids.size).toBe(100);
+    for (const id of ids) expect(id).toMatch(/^_[0-9a-f]{32}$/);
+  });
+});
+
+describe('getSamlClient', () => {
+  beforeEach(() => {
+    vi.mocked(getSamlProviderConfig).mockReturnValue(baseConfig);
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+    resetSamlClientCaches();
+  });
+
+  it('throws for an unknown provider', () => {
+    vi.mocked(getSamlProviderConfig).mockReturnValue(undefined);
+    expect(() => getSamlClient('ghost')).toThrow(/Unknown SAML provider/);
+  });
+
+  it('builds a hardened instance — none of the invariants relaxed', () => {
+    const saml = getSamlClient('acme');
+    const options = saml.options;
+    expect(options.wantAssertionsSigned).toBe(true);
+    expect(options.wantAuthnResponseSigned).toBe(true);
+    expect(options.validateInResponseTo).toBe(ValidateInResponseTo.always);
+    expect(options.audience).toBe(baseConfig.issuer);
+    expect(options.idpIssuer).toBe(baseConfig.idpIssuer);
+    expect(options.idpCert).toEqual(baseConfig.idpCertPems);
+    expect(options.signatureAlgorithm).toBe('sha256');
+    expect(options.digestAlgorithm).toBe('sha256');
+    expect(options.acceptedClockSkewMs).toBeLessThanOrEqual(30_000);
+    expect(options.maxAssertionAgeMs).toBeLessThanOrEqual(10 * 60_000);
+    expect(options.identifierFormat).toBe(
+      'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+    );
+    expect(options.forceAuthn).toBe(false);
+    expect(options.disableRequestedAuthnContext).toBe(true);
+  });
+
+  it('honours per-provider forceAuthn / disableRequestedAuthnContext', () => {
+    vi.mocked(getSamlProviderConfig).mockReturnValue({
+      ...baseConfig,
+      forceAuthn: true,
+      disableRequestedAuthnContext: false,
+    });
+    const options = getSamlClient('acme').options;
+    expect(options.forceAuthn).toBe(true);
+    expect(options.disableRequestedAuthnContext).toBe(false);
+  });
+
+  it('injects the provided request id as the AuthnRequest ID generator', () => {
+    const saml = getSamlClient('acme', '_feedfacefeedfacefeedfacefeedface');
+    expect(saml.options.generateUniqueId()).toBe(
+      '_feedfacefeedfacefeedfacefeedface',
+    );
+  });
+
+  it('shares one request-id cache across instances of the same provider', async () => {
+    const a = getSamlClient('acme', '_id1');
+    const b = getSamlClient('acme');
+    await a.options.cacheProvider.saveAsync('_id1', 'ts');
+    expect(await b.options.cacheProvider.getAsync('_id1')).toBe('ts');
+    // Different provider → different cache.
+    vi.mocked(getSamlProviderConfig).mockReturnValue({
+      ...baseConfig,
+      id: 'other',
+    });
+    const c = getSamlClient('other');
+    expect(await c.options.cacheProvider.getAsync('_id1')).toBeNull();
+  });
+
+  it('generates a real redirect URL: deflate+base64 SAMLRequest with our ID', async () => {
+    const { inflateRawSync } = await import('node:zlib');
+    const requestId = generateSamlRequestId();
+    const saml = getSamlClient('acme', requestId);
+    const url = new URL(await saml.getAuthorizeUrlAsync('', undefined, {}));
+
+    expect(url.origin + url.pathname).toBe(baseConfig.entryPoint);
+    const raw = url.searchParams.get('SAMLRequest');
+    expect(raw).toBeTruthy();
+    const xml = inflateRawSync(Buffer.from(raw as string, 'base64')).toString(
+      'utf8',
+    );
+    expect(xml).toContain(`ID="${requestId}"`);
+    expect(xml).toContain(`Destination="${baseConfig.entryPoint}"`);
+    expect(xml).toContain(baseConfig.issuer); // SP entityID as Issuer
+    expect(xml).toContain(
+      'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+    );
+    expect(xml).not.toContain('ForceAuthn'); // off by default
+    // RelayState empty → not in the query at all.
+    expect(url.searchParams.get('RelayState')).toBeFalsy();
+  });
+
+  it('request-id cache entries are single-use via removeAsync', async () => {
+    const saml = getSamlClient('acme');
+    const cache = saml.options.cacheProvider;
+    await cache.saveAsync('_x', 'ts');
+    expect(await cache.removeAsync('_x')).toBe('_x');
+    expect(await cache.getAsync('_x')).toBeNull();
+    expect(await cache.removeAsync('_x')).toBeNull();
+  });
+});
diff --git a/apps/gateway/src/sso/saml-client.ts b/apps/gateway/src/sso/saml-client.ts
new file mode 100644
index 0000000..ce48e4a
--- /dev/null
+++ b/apps/gateway/src/sso/saml-client.ts
@@ -0,0 +1,151 @@
+import { randomBytes } from 'node:crypto';
+import {
+  CacheItem,
+  CacheProvider,
+  SAML,
+  ValidateInResponseTo,
+} from '@node-saml/node-saml';
+import { getSamlProviderConfig } from './saml-provider-registry';
+
+/**
+ * Hard validation bounds. Constants by design — none of these can be relaxed
+ * through env configuration:
+ * - 30s of clock skew is enough for NTP-synced IdPs; anything larger widens
+ *   the replay window.
+ * - 10 minutes is a hard ceiling on assertion age regardless of what the
+ *   assertion's own Conditions say (defense in depth against lax IdPs).
+ */
+const ACCEPTED_CLOCK_SKEW_MS = 30_000;
+const MAX_ASSERTION_AGE_MS = 10 * 60_000;
+
+/**
+ * InResponseTo bookkeeping: node-saml stores the AuthnRequest id when the
+ * request is generated and consumes it when the matching response arrives.
+ * The TTL mirrors the transaction-cookie TTL (5 min) plus slack, and the
+ * entry cap bounds memory so a flood of /login requests cannot OOM the
+ * gateway (oldest entries are evicted first).
+ */
+const REQUEST_ID_TTL_MS = 10 * 60_000;
+const REQUEST_CACHE_MAX_ENTRIES = 10_000;
+
+/**
+ * Minimal FIFO-bounded, TTL-expiring cache provider for node-saml.
+ * The library's own InMemoryCacheProvider is not exported from the package
+ * root and has no entry cap; this one is interface-compatible and bounded.
+ * NOTE: in-memory state means InResponseTo validation is per-instance; the
+ * signed transaction cookie (which also carries the request id) is what keeps
+ * the flow stateless across gateway replicas.
+ */
+class BoundedCacheProvider implements CacheProvider {
+  private readonly entries = new Map<
+    string,
+    { value: string; createdAt: number }
+  >();
+
+  async saveAsync(key: string, value: string): Promise<CacheItem | null> {
+    this.pruneExpired();
+    if (this.entries.size >= REQUEST_CACHE_MAX_ENTRIES) {
+      // FIFO eviction: Map preserves insertion order.
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined) this.entries.delete(oldest);
+    }
+    const createdAt = Date.now();
+    this.entries.set(key, { value, createdAt });
+    return { createdAt, value };
+  }
+
+  async getAsync(key: string): Promise<string | null> {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    if (Date.now() - entry.createdAt > REQUEST_ID_TTL_MS) {
+      this.entries.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async removeAsync(key: string | null): Promise<string | null> {
+    if (key === null || !this.entries.has(key)) return null;
+    this.entries.delete(key);
+    return key;
+  }
+
+  private pruneExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.entries) {
+      if (now - entry.createdAt > REQUEST_ID_TTL_MS) this.entries.delete(key);
+    }
+  }
+}
+
+// One shared cache per provider so the SAML instance that generates the
+// AuthnRequest and the one that validates the response agree on request ids.
+const requestCaches = new Map<string, BoundedCacheProvider>();
+
+const cacheFor = (providerId: string): BoundedCacheProvider => {
+  let cache = requestCaches.get(providerId);
+  if (!cache) {
+    cache = new BoundedCacheProvider();
+    requestCaches.set(providerId, cache);
+  }
+  return cache;
+};
+
+/**
+ * CSPRNG AuthnRequest id. Prefixed with `_` because an xsd:ID must not start
+ * with a digit. 128 bits of entropy — unguessable by construction.
+ */
+export const generateSamlRequestId = (): string =>
+  `_${randomBytes(16).toString('hex')}`;
+
+/**
+ * Builds a hardened node-saml instance for one provider. Instances are cheap
+ * (no I/O in the constructor) and are built per call so a per-request
+ * `generateUniqueId` can inject the request id we store in the signed
+ * transaction cookie.
+ *
+ * Security invariants — NONE of these is env-configurable:
+ * - `wantAssertionsSigned` + `wantAuthnResponseSigned`: both the Response and
+ *   the Assertion must carry a valid signature (anti partial-signing).
+ * - signatures verified ONLY against the registry's pinned IdP cert(s) —
+ *   never against certificates embedded in the response (trust bypass).
+ * - `audience`: AudienceRestriction must equal our SP entityID.
+ * - `idpIssuer`: the response Issuer must match the configured IdP
+ *   (multi-IdP mix-up defense).
+ * - `validateInResponseTo: always`: unsolicited (IdP-initiated) responses are
+ *   rejected by design.
+ * - persistent NameID format requested; transient is rejected at the ACS.
+ */
+export const getSamlClient = (providerId: string, requestId?: string): SAML => {
+  const config = getSamlProviderConfig(providerId);
+  if (!config) throw new Error(`Unknown SAML provider: ${providerId}`);
+
+  return new SAML({
+    issuer: config.issuer,
+    callbackUrl: config.callbackUrl,
+    entryPoint: config.entryPoint,
+    idpCert: config.idpCertPems,
+    idpIssuer: config.idpIssuer,
+    audience: config.issuer,
+    wantAssertionsSigned: true,
+    wantAuthnResponseSigned: true,
+    signatureAlgorithm: config.signatureAlgorithm,
+    digestAlgorithm: config.signatureAlgorithm,
+    acceptedClockSkewMs: ACCEPTED_CLOCK_SKEW_MS,
+    maxAssertionAgeMs: MAX_ASSERTION_AGE_MS,
+    validateInResponseTo: ValidateInResponseTo.always,
+    requestIdExpirationPeriodMs: REQUEST_ID_TTL_MS,
+    cacheProvider: cacheFor(providerId),
+    identifierFormat: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+    forceAuthn: config.forceAuthn ?? false,
+    disableRequestedAuthnContext: config.disableRequestedAuthnContext ?? true,
+    ...(config.decryptionPvk ? { decryptionPvk: config.decryptionPvk } : {}),
+    ...(config.logoutUrl ? { logoutUrl: config.logoutUrl } : {}),
+    ...(requestId ? { generateUniqueId: () => requestId } : {}),
+  });
+};
+
+/** Clears the per-provider request-id caches — for tests. */
+export const resetSamlClientCaches = (): void => {
+  requestCaches.clear();
+};
diff --git a/apps/gateway/src/sso/saml-flow.e2e.spec.ts b/apps/gateway/src/sso/saml-flow.e2e.spec.ts
new file mode 100644
index 0000000..af34cd3
--- /dev/null
+++ b/apps/gateway/src/sso/saml-flow.e2e.spec.ts
@@ -0,0 +1,426 @@
+import cookieParser from 'cookie-parser';
+import express, { type Express } from 'express';
+import { SignedXml } from 'xml-crypto';
+import { generateKeyPairSync, X509Certificate } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import request from 'supertest';
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Permission } from '@dto';
+
+// The api boundary is mocked so this e2e needs no Postgres/api: it exercises
+// the REAL SAML SP of the gateway (AuthnRequest generation, full POST-binding
+// Response validation via @node-saml/node-saml, transaction cookie binding,
+// InResponseTo, NameID policy, domain allowlist) against XML we sign here with
+// a throwaway test IdP key — plus a full attack suite. No external network.
+vi.mock('@gateway/clients/api.client', () => ({
+  ApiClient: {
+    resolveFederatedUser: vi.fn().mockResolvedValue({
+      id: 42,
+      email: 'alice@corp.com',
+      permissions: [Permission.WRITE_SOME_ENTITY],
+    }),
+    recordRefresh: vi.fn().mockResolvedValue({ recorded: true }),
+  },
+}));
+
+import { ApiClient } from '@gateway/clients/api.client';
+import authRouter from '@gateway/routes/auth.routes';
+import { resetSamlClientCaches } from '@gateway/sso/saml-client';
+import { resetSamlRegistryCache } from '@gateway/sso/saml-provider-registry';
+
+const SP_ENTITY = 'https://app.example.com';
+const IDP_ISSUER = 'https://idp.e2e.example/metadata';
+const IDP_ENTRY = 'https://idp.e2e.example/sso';
+const ACS = 'https://app.example.com/api/v1/auth/sso/test/callback';
+
+const SAML_NS = 'urn:oasis:names:tc:SAML:2.0:assertion';
+const SAMLP_NS = 'urn:oasis:names:tc:SAML:2.0:protocol';
+const PERSISTENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+
+// --- Throwaway test IdP key + self-signed cert (generated at suite start,
+//     never persisted, never reused outside this spec). -----------------------
+let IDP_KEY = '';
+let IDP_CERT = '';
+// A second, unrelated key — used to forge signatures the SP must reject.
+let ROGUE_KEY = '';
+
+const makeSelfSignedCert = (): { key: string; cert: string } => {
+  const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const keyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string;
+  const dir = mkdtempSync(join(tmpdir(), 'saml-e2e-'));
+  const keyPath = join(dir, 'k.pem');
+  const certPath = join(dir, 'c.pem');
+  writeFileSync(keyPath, keyPem);
+  // openssl is available on the dev/CI image; build a long-lived x509.
+  execFileSync('openssl', [
+    'req',
+    '-x509',
+    '-new',
+    '-key',
+    keyPath,
+    '-out',
+    certPath,
+    '-days',
+    '27000',
+    '-subj',
+    '/CN=e2e-test-idp',
+    '-sha256',
+  ]);
+  const cert = new X509Certificate(
+    execFileSync('cat', [certPath]).toString(),
+  ).toString();
+  return { key: keyPem, cert };
+};
+
+let app: Express;
+
+// --- Minimal SAML IdP harness: builds and signs Responses/Assertions. --------
+interface BuildOpts {
+  requestId: string;
+  nameId?: string;
+  nameIdFormat?: string;
+  email?: string;
+  groups?: string[];
+  audience?: string;
+  issuer?: string;
+  notOnOrAfter?: string;
+  signAssertion?: boolean;
+  signResponse?: boolean;
+  signKey?: string;
+  signCert?: string;
+  // XSW: inject a second, unsigned assertion alongside the signed one.
+  xswSecondAssertion?: boolean;
+  // comment injection in the NameID (CVE-2017-11427 class).
+  nameIdComment?: boolean;
+}
+
+const iso = (offsetMs = 0) => new Date(Date.now() + offsetMs).toISOString();
+let idCounter = 0;
+const uid = (p: string) => `_${p}${(idCounter += 1)}${'0'.repeat(20)}`;
+
+const signElement = (
+  xml: string,
+  refId: string,
+  key: string,
+  cert: string,
+): string => {
+  const sig = new SignedXml({ privateKey: key, publicCert: cert });
+  sig.signatureAlgorithm = 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256';
+  sig.canonicalizationAlgorithm = 'http://www.w3.org/2001/10/xml-exc-c14n#';
+  sig.addReference({
+    xpath: `//*[@ID='${refId}']`,
+    transforms: [
+      'http://www.w3.org/2000/09/xmldsig#enveloped-signature',
+      'http://www.w3.org/2001/10/xml-exc-c14n#',
+    ],
+    digestAlgorithm: 'http://www.w3.org/2001/04/xmlenc#sha256',
+  });
+  sig.computeSignature(xml, {
+    location: {
+      reference: `//*[@ID='${refId}']/*[local-name()='Issuer']`,
+      action: 'after',
+    },
+  });
+  return sig.getSignedXml();
+};
+
+const buildAssertion = (o: BuildOpts, assertionId: string): string => {
+  const nameId = o.nameIdComment
+    ? `alice@corp.com<!---->.evil.com`
+    : (o.nameId ?? 'persistent-user-123');
+  const after = o.notOnOrAfter ?? iso(5 * 60_000);
+  const audience = o.audience ?? SP_ENTITY;
+  const issuer = o.issuer ?? IDP_ISSUER;
+  const email = o.email ?? 'alice@corp.com';
+  const groups = o.groups ?? ['admins'];
+  return (
+    `<saml:Assertion xmlns:saml="${SAML_NS}" ID="${assertionId}" Version="2.0" IssueInstant="${iso()}">` +
+    `<saml:Issuer>${issuer}</saml:Issuer>` +
+    `<saml:Subject><saml:NameID Format="${o.nameIdFormat ?? PERSISTENT}">${nameId}</saml:NameID>` +
+    `<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">` +
+    `<saml:SubjectConfirmationData NotOnOrAfter="${after}" Recipient="${ACS}" InResponseTo="${o.requestId}"/>` +
+    `</saml:SubjectConfirmation></saml:Subject>` +
+    `<saml:Conditions NotBefore="${iso(-60_000)}" NotOnOrAfter="${after}">` +
+    `<saml:AudienceRestriction><saml:Audience>${audience}</saml:Audience></saml:AudienceRestriction>` +
+    `</saml:Conditions>` +
+    `<saml:AuthnStatement AuthnInstant="${iso()}" SessionIndex="sess-e2e">` +
+    `<saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef></saml:AuthnContext>` +
+    `</saml:AuthnStatement>` +
+    `<saml:AttributeStatement>` +
+    `<saml:Attribute Name="email"><saml:AttributeValue>${email}</saml:AttributeValue></saml:Attribute>` +
+    `<saml:Attribute Name="groups">${groups
+      .map((g) => `<saml:AttributeValue>${g}</saml:AttributeValue>`)
+      .join('')}</saml:Attribute>` +
+    `</saml:AttributeStatement></saml:Assertion>`
+  );
+};
+
+/** Builds a base64 SAMLResponse per the options, signing as requested. */
+const buildResponse = (o: BuildOpts): string => {
+  const signAssertion = o.signAssertion ?? true;
+  const signResponse = o.signResponse ?? true;
+  const key = o.signKey ?? IDP_KEY;
+  const cert = o.signCert ?? IDP_CERT;
+  const responseId = uid('resp');
+  const assertionId = uid('assn');
+
+  let assertion = buildAssertion(o, assertionId);
+  if (signAssertion) assertion = signElement(assertion, assertionId, key, cert);
+
+  // XSW: prepend a forged unsigned assertion with attacker NameID, keeping the
+  // legitimately-signed one elsewhere in the tree.
+  const forged = o.xswSecondAssertion
+    ? buildAssertion({ ...o, nameId: 'attacker-evil' }, uid('forged'))
+    : '';
+
+  let response =
+    `<samlp:Response xmlns:samlp="${SAMLP_NS}" xmlns:saml="${SAML_NS}" ID="${responseId}" Version="2.0" IssueInstant="${iso()}" Destination="${ACS}" InResponseTo="${o.requestId}">` +
+    `<saml:Issuer>${o.issuer ?? IDP_ISSUER}</saml:Issuer>` +
+    `<samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>` +
+    forged +
+    assertion +
+    `</samlp:Response>`;
+
+  if (signResponse) response = signElement(response, responseId, key, cert);
+  return Buffer.from(response).toString('base64');
+};
+
+const cookieHeader = (setCookie: string[] | undefined): string =>
+  (setCookie ?? []).map((c) => c.split(';')[0]).join('; ');
+
+const buildApp = (): Express => {
+  const a = express();
+  a.use(cookieParser());
+  a.use('/api/v1/auth', authRouter);
+  return a;
+};
+
+/** Start login, returning the AuthnRequest id and the transaction cookie. */
+const startLogin = async (): Promise<{ requestId: string; cookie: string }> => {
+  const res = await request(app).get(
+    '/api/v1/auth/sso/test/login?returnTo=/dashboard',
+  );
+  expect(res.status).toBe(302);
+  const url = new URL(res.headers.location);
+  const raw = url.searchParams.get('SAMLRequest') as string;
+  const { inflateRawSync } = await import('node:zlib');
+  const xml = inflateRawSync(Buffer.from(raw, 'base64')).toString('utf8');
+  const requestId = /ID="([^"]+)"/.exec(xml)?.[1] as string;
+  return { requestId, cookie: cookieHeader(res.headers['set-cookie']) };
+};
+
+const postToAcs = (samlResponse: string, cookie: string) =>
+  request(app)
+    .post('/api/v1/auth/sso/test/callback')
+    .set('Cookie', cookie)
+    .type('form')
+    .send({ SAMLResponse: samlResponse });
+
+describe('SAML SP flow (e2e against a self-signed test IdP)', () => {
+  beforeAll(() => {
+    const idp = makeSelfSignedCert();
+    IDP_KEY = idp.key;
+    IDP_CERT = idp.cert;
+    ROGUE_KEY = makeSelfSignedCert().key;
+
+    process.env.SSO_ALLOW_INSECURE_ISSUERS = 'true'; // https public host anyway
+    process.env.SAML_TEST_ENTRY_POINT = IDP_ENTRY;
+    process.env.SAML_TEST_IDP_ISSUER = IDP_ISSUER;
+    process.env.SAML_TEST_IDP_CERT = IDP_CERT.replace(/\n/g, '\\n');
+    process.env.SAML_TEST_CALLBACK_URL = ACS;
+    process.env.SAML_TEST_SP_ISSUER = SP_ENTITY;
+    process.env.SAML_TEST_PERMISSION_MAP = 'admins:WRITE_SOME_ENTITY';
+    process.env.SAML_TEST_ALLOWED_DOMAINS = 'corp.com';
+    process.env.SSO_STATE_SECRET = 'e2e-state-secret';
+    process.env.JWT_ACCESS_SECRET = 'e2e-access-secret';
+    process.env.JWT_REFRESH_SECRET = 'e2e-refresh-secret';
+
+    resetSamlRegistryCache();
+    resetSamlClientCaches();
+    app = buildApp();
+  });
+
+  beforeEach(() => vi.clearAllMocks());
+
+  it('happy path: login → signed Response at the ACS issues the local session', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(buildResponse({ requestId }), cookie);
+
+    expect(res.status).toBe(302);
+    expect(res.headers.location).toBe('/dashboard');
+    expect(res.headers['authorization']).toBeTruthy();
+    expect(cookieHeader(res.headers['set-cookie'])).toContain('refreshToken=');
+    expect(ApiClient.resolveFederatedUser).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: 'test',
+        subject: 'persistent-user-123',
+        email: 'alice@corp.com',
+        emailVerified: true,
+        suggestedPermissions: [Permission.WRITE_SOME_ENTITY],
+      }),
+      expect.any(String),
+    );
+  });
+
+  // --- Attack suite: every case must end in rejection with no session. -------
+  const expectRejected = (res: {
+    status: number;
+    headers: Record<string, unknown>;
+  }) => {
+    expect(res.status).toBe(302);
+    expect(res.headers['location']).toBe('/login?sso_error=1');
+    expect(cookieHeader(res.headers['set-cookie'] as string[])).not.toContain(
+      'refreshToken=',
+    );
+    expect(ApiClient.resolveFederatedUser).not.toHaveBeenCalled();
+  };
+
+  it('attack 1: unsigned response and assertion → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, signAssertion: false, signResponse: false }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 2: signed response but UNSIGNED assertion → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, signAssertion: false, signResponse: true }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 3: signature forged with a different (rogue) key → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, signKey: ROGUE_KEY, signCert: IDP_CERT }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 4: XML Signature Wrapping — forged assertion + valid signed one → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, xswSecondAssertion: true }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 5: comment injection in the NameID → no privilege/identity confusion', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, nameIdComment: true }),
+      cookie,
+    );
+    // Either the library strips the comment (subject = full value, still a
+    // corp.com identity) or it rejects. What must NEVER happen is resolving as
+    // a different identity than the signed one. Assert no escalation to a bare
+    // "alice@corp.com" subject that drops the suffix.
+    if (res.headers.location === '/dashboard') {
+      const arg = vi.mocked(ApiClient.resolveFederatedUser).mock.calls[0][0];
+      expect(arg.subject).not.toBe('alice@corp.com');
+    } else {
+      expectRejected(res);
+    }
+  });
+
+  it('attack 6: replay — the same valid Response twice → second rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const body = buildResponse({ requestId });
+    const first = await postToAcs(body, cookie);
+    expect(first.headers.location).toBe('/dashboard');
+    vi.clearAllMocks();
+    // Reuse the (now single-use-consumed) transaction cookie + same response.
+    const second = await postToAcs(body, cookie);
+    expectRejected(second);
+  });
+
+  it('attack 7: no transaction cookie (IdP-initiated) → rejected', async () => {
+    const { requestId } = await startLogin();
+    const res = await postToAcs(buildResponse({ requestId }), '');
+    expectRejected(res);
+  });
+
+  it('attack 8: InResponseTo of a different transaction → rejected', async () => {
+    const { cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId: '_someone-elses-request-000000000' }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 9: AudienceRestriction for another SP → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, audience: 'https://other-sp.example' }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 10: expired assertion (NotOnOrAfter in the past) → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, notOnOrAfter: iso(-10 * 60_000) }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 11: Issuer of a different IdP (mix-up) → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, issuer: 'https://evil-idp.example/metadata' }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 12: email domain outside the allowlist → rejected', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({ requestId, email: 'victim@othertenant.com' }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+
+  it('attack 13: RelayState with an external URL is NEVER followed', async () => {
+    const { requestId, cookie } = await startLogin();
+    // A hostile IdP (or a MitM on the POST) sets RelayState to an external
+    // origin. The final redirect must come from the signed transaction cookie
+    // (returnTo=/dashboard), never from RelayState.
+    const res = await request(app)
+      .post('/api/v1/auth/sso/test/callback')
+      .set('Cookie', cookie)
+      .type('form')
+      .send({
+        SAMLResponse: buildResponse({ requestId }),
+        RelayState: 'https://evil.example/phish',
+      });
+    expect(res.status).toBe(302);
+    expect(res.headers.location).toBe('/dashboard');
+  });
+
+  it('attack 14: transient NameID format → rejected (unstable identity)', async () => {
+    const { requestId, cookie } = await startLogin();
+    const res = await postToAcs(
+      buildResponse({
+        requestId,
+        nameIdFormat: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
+        nameId: '_one-time-opaque-handle',
+      }),
+      cookie,
+    );
+    expectRejected(res);
+  });
+});
diff --git a/apps/gateway/src/sso/saml-logout.service.ts b/apps/gateway/src/sso/saml-logout.service.ts
new file mode 100644
index 0000000..f69fde2
--- /dev/null
+++ b/apps/gateway/src/sso/saml-logout.service.ts
@@ -0,0 +1,74 @@
+import type { CookieOptions, Request, Response } from 'express';
+import jwt, { JwtPayload } from 'jsonwebtoken';
+
+/**
+ * Minimal, integrity-protected hint needed to drive SAML Single Logout —
+ * the SAML twin of {@link SsoLogoutHint} in `sso-logout.service.ts`. It
+ * carries the provider plus the `NameID`/`SessionIndex` the IdP needs in the
+ * LogoutRequest. Signed (HS256) and HttpOnly: a forged hint must never be
+ * able to point the logout flow at an attacker-chosen provider or identity.
+ * Best-effort: if missing/expired, logout still revokes the local session.
+ */
+export interface SamlLogoutHint {
+  provider: string;
+  nameId: string;
+  nameIdFormat?: string;
+  sessionIndex?: string;
+}
+
+const COOKIE = 'saml_logout';
+const TYP = 'saml_logout';
+const TTL_SECONDS = 8 * 60 * 60; // align with the default (non-remember) session
+
+const secret = (): string =>
+  process.env.SSO_STATE_SECRET ?? process.env.JWT_REFRESH_SECRET ?? '';
+
+const cookieOptions = (maxAgeMs?: number): CookieOptions => {
+  const options: CookieOptions = {
+    httpOnly: true,
+    path: '/',
+    sameSite: 'lax',
+    secure: process.env.NODE_ENV === 'production',
+  };
+  if (maxAgeMs !== undefined) options.maxAge = maxAgeMs;
+  return options;
+};
+
+interface SamlLogoutPayload extends JwtPayload, SamlLogoutHint {
+  typ: typeof TYP;
+}
+
+export const setSamlLogoutHintCookie = (
+  res: Response,
+  hint: SamlLogoutHint,
+): void => {
+  if (!secret()) return; // best-effort; without a secret we simply skip the hint
+  const token = jwt.sign({ ...hint, typ: TYP }, secret(), {
+    algorithm: 'HS256',
+    expiresIn: TTL_SECONDS,
+  });
+  res.cookie(COOKIE, token, cookieOptions(TTL_SECONDS * 1000));
+};
+
+export const readSamlLogoutHint = (req: Request): SamlLogoutHint | null => {
+  const token = req.cookies?.[COOKIE];
+  if (!token || !secret()) return null;
+  try {
+    const decoded = jwt.verify(token, secret(), {
+      algorithms: ['HS256'],
+    }) as SamlLogoutPayload;
+    if (decoded.typ !== TYP) return null;
+    return {
+      provider: decoded.provider,
+      nameId: decoded.nameId,
+      nameIdFormat: decoded.nameIdFormat,
+      sessionIndex: decoded.sessionIndex,
+    };
+  } catch {
+    return null;
+  }
+};
+
+export const clearSamlLogoutHintCookie = (res: Response): void => {
+  res.clearCookie(COOKIE, cookieOptions());
+};
diff --git a/apps/gateway/src/sso/saml-provider-registry.spec.ts b/apps/gateway/src/sso/saml-provider-registry.spec.ts
new file mode 100644
index 0000000..38ab35b
--- /dev/null
+++ b/apps/gateway/src/sso/saml-provider-registry.spec.ts
@@ -0,0 +1,424 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Permission } from '@dto';
+import {
+  buildSamlRegistryFromEnv,
+  getSamlProviderConfig,
+  isSamlEnabled,
+  resetSamlRegistryCache,
+} from './saml-provider-registry';
+import { resetRegistryCache } from './provider-registry';
+import {
+  getFederatedProvider,
+  isFederationEnabled,
+  listPublicProviders,
+  resetFederatedRegistryCache,
+} from './federated-registry';
+
+// ---------------------------------------------------------------------------
+// Test-only X.509 fixtures. Self-signed throwaway certs generated exclusively
+// for this spec — the private keys were discarded and are not reused anywhere.
+// ---------------------------------------------------------------------------
+
+// RSA-2048, CN=test-idp-valid, expires 2100-05-14.
+const VALID_CERT = `-----BEGIN CERTIFICATE-----
+MIICsDCCAZgCCQDZWwknp3ogYzANBgkqhkiG9w0BAQsFADAZMRcwFQYDVQQDDA50
+ZXN0LWlkcC12YWxpZDAgFw0yNjA2MTEwODE2MTRaGA8yMTAwMDUxNDA4MTYxNFow
+GTEXMBUGA1UEAwwOdGVzdC1pZHAtdmFsaWQwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQCyVQEMEZSUOzo0xgDLU8EF2I5bFPCzfEPinC/BlYa3RCo0fnWN
+r4ZPEfExEMU7nDos+K6i4mApA0vYCdkY+jFA0yB4OKYLMTKd4n29t2PAqkevLu/R
+r5sZ+0bVe28+ciDzMNcG/B4JCJncCy+QWn8xdcf8LNg5bCOWLeOMAbZkDepuAIW2
+72grFEtcFH/x3UIBiVRw8Uu8U45SJkL/cQnkJDAteJ1ELoRL+2U2DuH5xn2C4jiJ
+D87Sq2MpkLml+YmeXi440g1362iDyROWvRqKI8fGvG4stXKKuqcoKy708JSdHKfs
+FvmB4wXGwzBuoy0g2xy63KICNzimbcKCjfJfAgMBAAEwDQYJKoZIhvcNAQELBQAD
+ggEBAGrPTol7VQM4SMa1lLsasJwVW9fo7+09g27EZB+nh0B2kd3nNvAJRRM5GJDe
+1o/pXAnBxp/tzQZvI8slUPFDDMYXXT4K5MKsrF3emOeT3UIQK5Uff1cRU9OG71mo
+7Zukzb03OcJg8bodq0ZNWk7PjhLScyNMUQpWUJHpgDyglFWGplcmLzDNrh8e1r1g
+s+qRBG+cf9/8cvuybkIKbnj6h0jNC6mPXfBp3ZVVWLZyNVrTJDENyYl6FLB3hKix
+gevtFdPJ/xebLkJaqvRe0ibT4Zt+JtNmvHHI+/uBrLOPv2DCkhmeteR6hyofubhb
+5UPyV34+IaicTy7s3W7E1BKe+vQ=
+-----END CERTIFICATE-----`;
+
+// RSA-1024 (intentionally weak), CN=test-idp-weak, expires 2100-05-14.
+const WEAK_CERT = `-----BEGIN CERTIFICATE-----
+MIIBqTCCARICCQD/4XvlccaiGzANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA10
+ZXN0LWlkcC13ZWFrMCAXDTI2MDYxMTA4MTYxNFoYDzIxMDAwNTE0MDgxNjE0WjAY
+MRYwFAYDVQQDDA10ZXN0LWlkcC13ZWFrMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB
+iQKBgQDlihgn9fviMnDEU/yJzVKTdZKWZJajp8f2FGVfiziuhkZk0f77WX2GZPn/
+FQ6deO85vxccksirrgU/lNpDgCCZDhGsRMOzMK/KAwpy+bSe2YcrG1QOt0r9WrmT
+gkP5h1NHydtpWs+truO5lSMCffJFRFaBjXQsF6GhRDMJXH05zQIDAQABMA0GCSqG
+SIb3DQEBCwUAA4GBAN3sAfSDjFw7k8x6q4iC4dkwGZchgNWZLcGwB8JoYuCPUxXM
+ZZ994nOU7W1GiUhDi5w3xob8EBt24F1WfUmWAf7IxW1z+xpiMcvnO/SA/0kBPowv
+FdFXrjAK84R5ZC5JqboXOy9hX6dl61G8EEv0eMjxmZB8GY/maQ01fWVUnOI+
+-----END CERTIFICATE-----`;
+
+// RSA-2048, CN=test-idp-expired, expires 2026-07-11. Used with fake timers to
+// exercise both the "expires soon" warning and the "expired" rejection paths.
+const SHORT_LIVED_CERT = `-----BEGIN CERTIFICATE-----
+MIICsjCCAZoCCQDH15vWUmOnXTANBgkqhkiG9w0BAQsFADAbMRkwFwYDVQQDDBB0
+ZXN0LWlkcC1leHBpcmVkMB4XDTI2MDYxMTA4MTYxNFoXDTI2MDcxMTA4MTYxNFow
+GzEZMBcGA1UEAwwQdGVzdC1pZHAtZXhwaXJlZDCCASIwDQYJKoZIhvcNAQEBBQAD
+ggEPADCCAQoCggEBAMijQeLeLTYq8dUmhVlMdEQcWmVimqaBvvHw8pqIERoybYGJ
+kAF0BYkibRSpp5RImwKfDQ8wpJm7zZ2NKjhxUqingv+98CMpee5V9ScEJw2NFpr2
+83pP34ebC9k3WZIUXVSukpMPJ8Exc5nzBxDQB5WO34Z28lG4oSHsXi2zUpgBDyWX
+T217rNJGF3+bVrMqq2fK/DTuZHD1gDmzYhPdmiDG38OpP+BmxgqEU/35d4AYYV32
+HbDX9z31wW2SWePJT2BJia0s6MQfx6hphur+uys/gH6hDGOgEsZgJhsV5Q0rBeMw
+yWnxiJPqAU6vRa+EvkFxXipeDxIXNEMFGuztsJkCAwEAATANBgkqhkiG9w0BAQsF
+AAOCAQEAl9GB9G+okid+Uxsz2ffkYhcCc74OIglgfJW6nj3SndIPz+YdLIypUTUi
+R7K4hByEYLSkqsOzW6BPO70/pjSO8/fBMHZAGii3+/C9vO+NtcWGiJma/Q0cMmpo
+yomznNgGfQ7cyOk6NU7/XMhUaYg+Imz79AHifpb3ICobtPVbpXJl2wLmKa1V6QBY
+3VSwcKj312u5TiuabgeRjNQ88WjMjpvf2LN2asqNh+dE3mI+R/MqpS1Z2BZFG3lp
+3CvBa7d8l9QBZPz9vYZF6nGOmHND5Mm3SnAy4bjo5bybYcEZPxgaA2nJlhYF2Nvt
+DLWV7xOOxFpksznY/IbJU4aoyPbeCA==
+-----END CERTIFICATE-----`;
+
+const acme = {
+  SAML_ACME_ENTRY_POINT: 'https://idp.acme.example/sso/saml',
+  SAML_ACME_IDP_ISSUER: 'https://idp.acme.example/metadata',
+  SAML_ACME_IDP_CERT: VALID_CERT,
+  SAML_ACME_CALLBACK_URL:
+    'https://app.example.com/api/v1/auth/sso/acme/callback',
+  // Mandatory: SAML stamps emailVerified:true, so a domain allowlist is the
+  // sole cross-tenant account-takeover boundary.
+  SAML_ACME_ALLOWED_DOMAINS: 'acme.example',
+};
+
+const oktaOidc = {
+  SSO_OKTA_ISSUER: 'https://example.okta.com',
+  SSO_OKTA_CLIENT_ID: 'client-okta',
+  SSO_OKTA_CLIENT_SECRET: 'secret-okta',
+  SSO_OKTA_REDIRECT_URI:
+    'https://app.example.com/api/v1/auth/sso/okta/callback',
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
+
+describe('buildSamlRegistryFromEnv', () => {
+  it('returns an empty registry when no provider is declared (SAML off)', () => {
+    expect(buildSamlRegistryFromEnv({}).size).toBe(0);
+  });
+
+  it('parses a provider with defaults applied', () => {
+    const reg = buildSamlRegistryFromEnv(acme);
+    const cfg = reg.get('acme');
+    expect(cfg).toBeDefined();
+    expect(cfg?.displayName).toBe('Acme');
+    expect(cfg?.entryPoint).toBe(acme.SAML_ACME_ENTRY_POINT);
+    expect(cfg?.idpIssuer).toBe(acme.SAML_ACME_IDP_ISSUER);
+    // SP entityID defaults to the origin of the callback URL.
+    expect(cfg?.issuer).toBe('https://app.example.com');
+    expect(cfg?.emailAttribute).toBe('email');
+    expect(cfg?.groupsAttribute).toBe('groups');
+    expect(cfg?.signatureAlgorithm).toBe('sha256');
+    expect(cfg?.wantAssertionsSigned).toBe(true);
+    expect(cfg?.idpCertPems).toHaveLength(1);
+    expect(cfg?.allowedDomains).toEqual(['acme.example']);
+    expect(cfg?.logoutUrl).toBeUndefined();
+    expect(cfg?.decryptionPvk).toBeUndefined();
+    expect(cfg?.forceAuthn).toBe(false);
+    expect(cfg?.disableRequestedAuthnContext).toBe(true);
+  });
+
+  it('honours every optional override', () => {
+    const reg = buildSamlRegistryFromEnv({
+      ...acme,
+      SAML_ACME_SP_ISSUER: 'https://app.example.com/saml/metadata',
+      SAML_ACME_DISPLAY_NAME: 'Acme Corp',
+      SAML_ACME_ICON_KEY: 'acme-logo',
+      SAML_ACME_EMAIL_ATTRIBUTE: 'mail',
+      SAML_ACME_GROUPS_ATTRIBUTE: 'memberOf',
+      SAML_ACME_SIGNATURE_ALGORITHM: 'sha512',
+      SAML_ACME_LOGOUT_URL: 'https://idp.acme.example/slo',
+      SAML_ACME_ALLOWED_DOMAINS: ' @Acme.com , corp.io ',
+      SAML_ACME_PERMISSION_MAP: 'admins:ADMIN;viewers:READ_SOME_ENTITY',
+      SAML_ACME_DECRYPTION_PVK: 'test-placeholder-not-a-real-key',
+      SAML_ACME_FORCE_AUTHN: 'true',
+      SAML_ACME_DISABLE_REQUESTED_AUTHN_CONTEXT: 'false',
+    });
+    const cfg = reg.get('acme');
+    expect(cfg?.issuer).toBe('https://app.example.com/saml/metadata');
+    expect(cfg?.displayName).toBe('Acme Corp');
+    expect(cfg?.iconKey).toBe('acme-logo');
+    expect(cfg?.emailAttribute).toBe('mail');
+    expect(cfg?.groupsAttribute).toBe('memberOf');
+    expect(cfg?.signatureAlgorithm).toBe('sha512');
+    expect(cfg?.logoutUrl).toBe('https://idp.acme.example/slo');
+    expect(cfg?.allowedDomains).toEqual(['acme.com', 'corp.io']);
+    expect(cfg?.permissionMap).toEqual([
+      { claim: 'admins', permissions: [Permission.ADMIN] },
+      { claim: 'viewers', permissions: [Permission.READ_SOME_ENTITY] },
+    ]);
+    expect(cfg?.decryptionPvk).toBe('test-placeholder-not-a-real-key');
+    expect(cfg?.forceAuthn).toBe(true);
+    expect(cfg?.disableRequestedAuthnContext).toBe(false);
+  });
+
+  it.each([
+    'IDP_ISSUER',
+    'IDP_CERT',
+    'CALLBACK_URL',
+    'ALLOWED_DOMAINS',
+  ] as const)('fails fast when a declared provider is missing %s', (key) => {
+    const env: NodeJS.ProcessEnv = { ...acme };
+    delete env[`SAML_ACME_${key}`];
+    expect(() => buildSamlRegistryFromEnv(env)).toThrow(
+      new RegExp(`missing required env SAML_ACME_${key}`),
+    );
+  });
+
+  it('fails fast when ALLOWED_DOMAINS is present but empty/whitespace', () => {
+    expect(() =>
+      buildSamlRegistryFromEnv({
+        ...acme,
+        SAML_ACME_ALLOWED_DOMAINS: ' , @ , ',
+      }),
+    ).toThrow(/missing required env SAML_ACME_ALLOWED_DOMAINS/);
+  });
+
+  it('rejects an invalid signature algorithm (sha1 is disabled)', () => {
+    expect(() =>
+      buildSamlRegistryFromEnv({
+        ...acme,
+        SAML_ACME_SIGNATURE_ALGORITHM: 'sha1',
+      }),
+    ).toThrow(/Only "sha256" and "sha512" are accepted/);
+  });
+
+  it('fails fast on a malformed permission map (never grants silently)', () => {
+    expect(() =>
+      buildSamlRegistryFromEnv({
+        ...acme,
+        SAML_ACME_PERMISSION_MAP: 'x:SUPERUSER',
+      }),
+    ).toThrow(/unknown permission "SUPERUSER"/);
+  });
+
+  describe('certificate validation', () => {
+    it('rejects an unparseable certificate without echoing its content', () => {
+      let message = '';
+      try {
+        buildSamlRegistryFromEnv({
+          ...acme,
+          SAML_ACME_IDP_CERT: 'bm90LWEtY2VydA==',
+        });
+      } catch (e) {
+        message = (e as Error).message;
+      }
+      expect(message).toMatch(/unparseable IdP certificate/);
+      expect(message).not.toContain('bm90LWEtY2VydA');
+    });
+
+    it('rejects an expired certificate', () => {
+      vi.useFakeTimers();
+      // 2026-08-01: SHORT_LIVED_CERT (validTo 2026-07-11) is expired.
+      vi.setSystemTime(new Date('2026-08-01T00:00:00Z'));
+      expect(() =>
+        buildSamlRegistryFromEnv({
+          ...acme,
+          SAML_ACME_IDP_CERT: SHORT_LIVED_CERT,
+        }),
+      ).toThrow(/certificate has expired/);
+    });
+
+    it('warns (but accepts) a certificate expiring in <30 days', () => {
+      vi.useFakeTimers();
+      // 2026-06-15: SHORT_LIVED_CERT expires 2026-07-11 → 26 days left.
+      vi.setSystemTime(new Date('2026-06-15T00:00:00Z'));
+      const warn = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => undefined);
+      const reg = buildSamlRegistryFromEnv({
+        ...acme,
+        SAML_ACME_IDP_CERT: SHORT_LIVED_CERT,
+      });
+      expect(reg.get('acme')?.idpCertPems).toHaveLength(1);
+      expect(warn).toHaveBeenCalledOnce();
+      expect(warn.mock.calls[0][0]).not.toContain('BEGIN CERTIFICATE');
+    });
+
+    it('rejects an RSA key smaller than 2048 bits', () => {
+      expect(() =>
+        buildSamlRegistryFromEnv({ ...acme, SAML_ACME_IDP_CERT: WEAK_CERT }),
+      ).toThrow(/RSA key smaller than 2048 bits/);
+    });
+
+    it('supports multi-cert rotation via the ";" separator', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-06-15T00:00:00Z'));
+      vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      const reg = buildSamlRegistryFromEnv({
+        ...acme,
+        SAML_ACME_IDP_CERT: `${VALID_CERT};${SHORT_LIVED_CERT}`,
+      });
+      expect(reg.get('acme')?.idpCertPems).toHaveLength(2);
+    });
+
+    it('normalises bare base64 (no PEM armour) and literal \\n escapes', () => {
+      const bare = VALID_CERT.replace(
+        /-----(BEGIN|END) CERTIFICATE-----/g,
+        '',
+      ).replace(/\s/g, '');
+      const escaped = VALID_CERT.replace(/\n/g, '\\n');
+      for (const variant of [bare, escaped]) {
+        const reg = buildSamlRegistryFromEnv({
+          ...acme,
+          SAML_ACME_IDP_CERT: variant,
+        });
+        const pems = reg.get('acme')?.idpCertPems ?? [];
+        expect(pems).toHaveLength(1);
+        expect(pems[0]).toMatch(/^-----BEGIN CERTIFICATE-----\n/);
+      }
+    });
+  });
+
+  describe('id collisions across protocols', () => {
+    it('rejects a SAML provider whose id collides with an OIDC provider', () => {
+      expect(() =>
+        buildSamlRegistryFromEnv({
+          ...oktaOidc,
+          SAML_OKTA_ENTRY_POINT: 'https://idp.okta.example/sso',
+          SAML_OKTA_IDP_ISSUER: 'https://idp.okta.example/metadata',
+          SAML_OKTA_IDP_CERT: VALID_CERT,
+          SAML_OKTA_CALLBACK_URL: 'https://app.example.com/cb',
+        }),
+      ).toThrow(/collides with an existing OIDC provider/);
+    });
+  });
+
+  describe('SSRF / federation-URL hardening', () => {
+    it('rejects a non-https entryPoint', () => {
+      expect(() =>
+        buildSamlRegistryFromEnv({
+          ...acme,
+          SAML_ACME_ENTRY_POINT: 'http://idp.acme.example/sso',
+        }),
+      ).toThrow(/must use https/);
+    });
+
+    it('rejects loopback, link-local and RFC1918 entryPoints', () => {
+      for (const host of [
+        'https://localhost/sso',
+        'https://169.254.169.254/sso',
+        'https://10.1.2.3/sso',
+        'https://192.168.0.5/sso',
+      ]) {
+        expect(() =>
+          buildSamlRegistryFromEnv({ ...acme, SAML_ACME_ENTRY_POINT: host }),
+        ).toThrow(/not allowed/);
+      }
+    });
+
+    it('applies the same guard to the optional logoutUrl', () => {
+      expect(() =>
+        buildSamlRegistryFromEnv({
+          ...acme,
+          SAML_ACME_LOGOUT_URL: 'https://169.254.169.254/slo',
+        }),
+      ).toThrow(/not allowed/);
+    });
+
+    it('allows insecure/local entryPoints only behind the explicit dev escape hatch', () => {
+      // Dev setups run the IdP on localhost or a private docker network.
+      for (const entryPoint of [
+        'http://localhost:8443/sso',
+        'https://10.1.2.3/sso',
+      ]) {
+        expect(() =>
+          buildSamlRegistryFromEnv({
+            ...acme,
+            SAML_ACME_ENTRY_POINT: entryPoint,
+            SSO_ALLOW_INSECURE_ISSUERS: 'true',
+          }),
+        ).not.toThrow();
+      }
+    });
+
+    it('blocks link-local/cloud-metadata even with the dev escape hatch', () => {
+      // Tier-1 block is unconditional — no escape hatch reaches 169.254.x.x.
+      for (const entryPoint of [
+        'https://169.254.169.254/sso',
+        'http://169.254.169.254/sso',
+        'https://0.0.0.0/sso',
+      ]) {
+        expect(() =>
+          buildSamlRegistryFromEnv({
+            ...acme,
+            SAML_ACME_ENTRY_POINT: entryPoint,
+            SSO_ALLOW_INSECURE_ISSUERS: 'true',
+          }),
+        ).toThrow(/not allowed/);
+      }
+    });
+  });
+});
+
+describe('federated registry (process.env-backed)', () => {
+  const saved = { ...process.env };
+  afterEach(() => {
+    process.env = { ...saved };
+    resetRegistryCache();
+    resetSamlRegistryCache();
+    resetFederatedRegistryCache();
+  });
+
+  const configureMixedEnv = () => {
+    Object.assign(process.env, oktaOidc, acme);
+    resetRegistryCache();
+    resetSamlRegistryCache();
+  };
+
+  it('lists OIDC and SAML providers mixed, protocol-tagged and id-sorted', () => {
+    configureMixedEnv();
+    expect(listPublicProviders()).toEqual([
+      { id: 'acme', displayName: 'Acme', iconKey: undefined, protocol: 'saml' },
+      {
+        id: 'okta',
+        displayName: 'Okta',
+        iconKey: undefined,
+        protocol: 'oidc',
+      },
+    ]);
+  });
+
+  it('never leaks certificates or secrets through the public list', () => {
+    configureMixedEnv();
+    const serialised = JSON.stringify(listPublicProviders());
+    expect(serialised).not.toContain('CERTIFICATE');
+    expect(serialised).not.toContain('secret-okta');
+    expect(serialised).not.toContain('idp.acme.example');
+  });
+
+  it('getFederatedProvider discriminates protocols and misses safely', () => {
+    configureMixedEnv();
+    const saml = getFederatedProvider('acme');
+    expect(saml?.protocol).toBe('saml');
+    if (saml?.protocol === 'saml') {
+      expect(saml.config.entryPoint).toBe(acme.SAML_ACME_ENTRY_POINT);
+    }
+    const oidc = getFederatedProvider('okta');
+    expect(oidc?.protocol).toBe('oidc');
+    if (oidc?.protocol === 'oidc') {
+      expect(oidc.config.clientId).toBe('client-okta');
+    }
+    expect(getFederatedProvider('ghost')).toBeUndefined();
+  });
+
+  it('reports federation enabled when either protocol has providers', () => {
+    for (const k of Object.keys(process.env)) {
+      if (k.startsWith('SSO_') || k.startsWith('SAML_')) delete process.env[k];
+    }
+    resetRegistryCache();
+    resetSamlRegistryCache();
+    expect(isFederationEnabled()).toBe(false);
+    expect(isSamlEnabled()).toBe(false);
+
+    Object.assign(process.env, acme);
+    resetRegistryCache();
+    resetSamlRegistryCache();
+    expect(isFederationEnabled()).toBe(true);
+    expect(isSamlEnabled()).toBe(true);
+    expect(getSamlProviderConfig('acme')?.idpCertPems).toHaveLength(1);
+  });
+});
diff --git a/apps/gateway/src/sso/saml-provider-registry.ts b/apps/gateway/src/sso/saml-provider-registry.ts
new file mode 100644
index 0000000..92b4771
--- /dev/null
+++ b/apps/gateway/src/sso/saml-provider-registry.ts
@@ -0,0 +1,337 @@
+import { X509Certificate } from 'node:crypto';
+import { ClaimPermissionMapping } from '@dto';
+import { SamlProviderConfig } from './saml-types';
+import {
+  assertSafeFederationUrl,
+  buildRegistryFromEnv,
+  parsePermissionMap,
+} from './provider-registry';
+
+// Detects a SAML provider declaration by its ENTRY_POINT variable.
+// id = lowercased capture group, e.g. SAML_OKTA_ENTRY_POINT → "okta".
+const SAML_ENV_PREFIX = /^SAML_(.+)_ENTRY_POINT$/;
+
+// How many days before expiry to emit a warning about a cert that is
+// about to expire. 30 days gives operators time to rotate without downtime.
+const CERT_WARN_DAYS = 30;
+
+const titleCase = (name: string): string =>
+  name.charAt(0).toUpperCase() + name.slice(1).toLowerCase();
+
+// ---------------------------------------------------------------------------
+// Certificate normalisation and validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalises a single raw certificate string into a PEM-encoded DER block:
+ * - Converts literal `\n` escape sequences to real newlines.
+ * - If the value is base64 without PEM armour, wraps it in BEGIN/END headers.
+ * Returns the normalised PEM string.
+ *
+ * Security note: this function MUST NOT log or propagate the cert content
+ * in error messages — it only includes the provider id.
+ */
+const normaliseCertPem = (raw: string): string => {
+  // Replace literal backslash-n sequences with real newlines.
+  const unescaped = raw.replace(/\\n/g, '\n').trim();
+
+  if (unescaped.startsWith('-----BEGIN')) {
+    // Already PEM-armoured — return as-is (normalised whitespace).
+    return unescaped;
+  }
+
+  // Assume base64 DER without headers; wrap in standard PEM armour.
+  // Strip any whitespace that might have been present in the env var.
+  const stripped = unescaped.replace(/\s/g, '');
+  const lines = stripped.match(/.{1,64}/g)?.join('\n') ?? stripped;
+  return `-----BEGIN CERTIFICATE-----\n${lines}\n-----END CERTIFICATE-----`;
+};
+
+/**
+ * Parses and validates one X.509 certificate PEM for a SAML provider.
+ * Throws on parse errors or key weakness. Warns (without logging the cert)
+ * when the cert is close to expiry.
+ *
+ * @param providerId  Used in error/warn messages — never the cert content.
+ * @param pem         PEM string (already normalised by {@link normaliseCertPem}).
+ */
+const validateCert = (providerId: string, pem: string): void => {
+  let cert: X509Certificate;
+  try {
+    cert = new X509Certificate(pem);
+  } catch {
+    // Do NOT include pem content — it may contain sensitive material or
+    // garbage that could be used in a log-injection attack.
+    throw new Error(
+      `SAML provider "${providerId}" has an unparseable IdP certificate`,
+    );
+  }
+
+  const now = Date.now();
+  const validTo = new Date(cert.validTo).getTime();
+
+  if (validTo < now) {
+    throw new Error(
+      `SAML provider "${providerId}" IdP certificate has expired (validTo: ${cert.validTo})`,
+    );
+  }
+
+  const warnThreshold = now + CERT_WARN_DAYS * 24 * 60 * 60 * 1000;
+  if (validTo < warnThreshold) {
+    // Warning only — expired certs above already throw.
+    console.warn(
+      `[SAML] Provider "${providerId}": IdP certificate expires in less than ${CERT_WARN_DAYS} days (${cert.validTo}). Rotate it before it expires.`,
+    );
+  }
+
+  // Enforce a minimum RSA key size. EC/Ed25519/Ed448 keys do not have a modulus
+  // and are accepted unconditionally (their strength is not measured in bits).
+  const pubKey = cert.publicKey;
+  if (
+    pubKey.asymmetricKeyType === 'rsa' ||
+    pubKey.asymmetricKeyType === 'rsa-pss'
+  ) {
+    const modulusLength = pubKey.asymmetricKeyDetails?.modulusLength;
+    if (modulusLength !== undefined && modulusLength < 2048) {
+      throw new Error(
+        `SAML provider "${providerId}" IdP certificate uses an RSA key smaller than 2048 bits`,
+      );
+    }
+  }
+};
+
+/**
+ * Splits a semicolon-separated cert string, normalises each entry, validates
+ * each cert independently, and returns the array of PEM strings.
+ * Fails fast on the first invalid cert.
+ */
+const parseIdpCerts = (providerId: string, rawCerts: string): string[] => {
+  const entries = rawCerts
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  if (entries.length === 0) {
+    throw new Error(
+      `SAML provider "${providerId}" SAML_${providerId.toUpperCase()}_IDP_CERT is empty`,
+    );
+  }
+
+  return entries.map((raw) => {
+    const pem = normaliseCertPem(raw);
+    validateCert(providerId, pem);
+    return pem;
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Required / optional env helpers
+// ---------------------------------------------------------------------------
+
+const requiredSaml = (
+  env: NodeJS.ProcessEnv,
+  providerId: string,
+  rawName: string,
+  key: string,
+): string => {
+  const varName = `SAML_${rawName}_${key}`;
+  const value = env[varName];
+  if (!value || !value.trim()) {
+    throw new Error(
+      `SAML provider "${providerId}" is missing required env ${varName}`,
+    );
+  }
+  return value.trim();
+};
+
+// ---------------------------------------------------------------------------
+// Core builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure builder: parses and validates every SAML provider declared in the given
+ * env object. Throws (fail-fast) on any misconfiguration. Zero providers is
+ * valid — SAML simply off. Exported for unit-testing with an explicit env.
+ *
+ * Provider detection: any `SAML_<NAME>_ENTRY_POINT` variable declares a
+ * provider; `NAME` is lowercased to produce the provider id (the primary key
+ * stored in `federated_identity.provider`).
+ *
+ * Id collision: a SAML provider id must not collide with any OIDC provider id
+ * declared in the SAME env (same id → same `federated_identity.provider` key →
+ * accounts would be mixed across protocols). The builder derives the OIDC id
+ * set from the env it receives, so the check is pure and deterministic.
+ * SAML↔SAML collisions cannot occur because each `SAML_<NAME>_ENTRY_POINT`
+ * key is unique by construction of a `Map`.
+ *
+ * Security notes:
+ * - Cert PEMs and `_DECRYPTION_PVK` are cryptographic secrets; they MUST NOT
+ *   appear in error messages, logs, or serialised responses.
+ * - Only variable names and provider ids are included in error messages.
+ */
+export const buildSamlRegistryFromEnv = (
+  env: NodeJS.ProcessEnv,
+): Map<string, SamlProviderConfig> => {
+  const allowInsecure = env.SSO_ALLOW_INSECURE_ISSUERS === 'true';
+  const samlRegistry = new Map<string, SamlProviderConfig>();
+
+  // OIDC ids declared in the SAME env — pure, deterministic collision source.
+  // Cheap to rebuild; at boot validateSsoConfig() has already vetted this env.
+  const oidcIds = new Set(buildRegistryFromEnv(env).keys());
+
+  for (const key of Object.keys(env)) {
+    const match = key.match(SAML_ENV_PREFIX);
+    if (!match) continue;
+    const rawName = match[1]; // e.g. "OKTA", "AZUREAD"
+    const id = rawName.toLowerCase(); // e.g. "okta", "azuread"
+
+    // Collision check: the id must not already be claimed by an OIDC provider.
+    if (oidcIds.has(id)) {
+      throw new Error(
+        `SAML provider "${id}" collides with an existing OIDC provider of the same id. ` +
+          `Provider ids must be globally unique across all SSO protocols.`,
+      );
+    }
+
+    // Parse required fields.
+    const entryPoint = requiredSaml(env, id, rawName, 'ENTRY_POINT');
+    assertSafeFederationUrl(id, entryPoint, allowInsecure, 'entryPoint');
+
+    const idpIssuer = requiredSaml(env, id, rawName, 'IDP_ISSUER');
+    const idpCertRaw = requiredSaml(env, id, rawName, 'IDP_CERT');
+    const callbackUrl = requiredSaml(env, id, rawName, 'CALLBACK_URL');
+
+    const idpCertPems = parseIdpCerts(id, idpCertRaw);
+
+    // SP issuer defaults to the origin of the callbackUrl. This is predictable
+    // and stable: given `https://app.example.com/saml/acme/acs`, the default
+    // SP entityID will be `https://app.example.com`. Operators can override
+    // with `SAML_<NAME>_SP_ISSUER` if their IdP registration requires a
+    // different entityID (e.g. a full metadata URL).
+    let defaultSpIssuer: string;
+    try {
+      defaultSpIssuer = new URL(callbackUrl).origin;
+    } catch {
+      throw new Error(
+        `SAML provider "${id}" has a malformed SAML_${rawName}_CALLBACK_URL`,
+      );
+    }
+    const issuer = env[`SAML_${rawName}_SP_ISSUER`]?.trim() || defaultSpIssuer;
+
+    // Optional logout URL — apply the same SSRF guard as entryPoint.
+    const logoutUrlRaw = env[`SAML_${rawName}_LOGOUT_URL`]?.trim();
+    if (logoutUrlRaw) {
+      assertSafeFederationUrl(id, logoutUrlRaw, allowInsecure, 'logoutUrl');
+    }
+
+    // Signature algorithm — only sha256 and sha512 are accepted.
+    // sha1 is intentionally excluded (cryptographically broken).
+    const sigAlgRaw =
+      env[`SAML_${rawName}_SIGNATURE_ALGORITHM`]?.trim() ?? 'sha256';
+    if (sigAlgRaw !== 'sha256' && sigAlgRaw !== 'sha512') {
+      throw new Error(
+        `SAML provider "${id}" has an invalid SAML_${rawName}_SIGNATURE_ALGORITHM: "${sigAlgRaw}". ` +
+          `Only "sha256" and "sha512" are accepted (sha1 is disabled).`,
+      );
+    }
+    const signatureAlgorithm = sigAlgRaw as 'sha256' | 'sha512';
+
+    // Allowed domains: CSV, lowercased, stripped of any leading `@`.
+    // MANDATORY for SAML: the ACS stamps `emailVerified: true` (no per-assertion
+    // verified signal exists in SAML), so this allowlist is the sole boundary
+    // that stops a signed IdP from asserting an arbitrary email and auto-linking
+    // to a pre-existing/other-tenant account. Fail fast when absent or empty.
+    const allowedDomains = (
+      env[`SAML_${rawName}_ALLOWED_DOMAINS`]?.trim() ?? ''
+    )
+      .split(',')
+      .map((d) => d.trim().toLowerCase().replace(/^@/, ''))
+      .filter(Boolean);
+    if (allowedDomains.length === 0) {
+      throw new Error(
+        `SAML provider "${id}" is missing required env SAML_${rawName}_ALLOWED_DOMAINS. ` +
+          `At least one email domain must be allowlisted: SAML assertions are trusted as ` +
+          `email-verified, so this list is the only cross-tenant account-takeover boundary.`,
+      );
+    }
+
+    // Permission map — reuse the shared parser (throws on malformed input).
+    const permissionMap: ClaimPermissionMapping[] = parsePermissionMap(
+      id,
+      env[`SAML_${rawName}_PERMISSION_MAP`],
+    );
+
+    // Decryption private key — optional; treated as a secret.
+    // Variable name logged in errors; key material never included.
+    const decryptionPvk =
+      env[`SAML_${rawName}_DECRYPTION_PVK`]?.trim() || undefined;
+
+    // forceAuthn: explicit opt-in only (default false). Instructs the IdP to
+    // re-authenticate the user even when it has an active session.
+    const forceAuthn = env[`SAML_${rawName}_FORCE_AUTHN`] === 'true';
+
+    // disableRequestedAuthnContext: default true (omit the element) for
+    // maximum IdP compat. Set the env var to 'false' to include it.
+    const disableRequestedAuthnContextRaw =
+      env[`SAML_${rawName}_DISABLE_REQUESTED_AUTHN_CONTEXT`];
+    const disableRequestedAuthnContext =
+      disableRequestedAuthnContextRaw === 'false' ? false : true;
+
+    samlRegistry.set(id, {
+      id,
+      displayName: env[`SAML_${rawName}_DISPLAY_NAME`]?.trim() || titleCase(id),
+      iconKey: env[`SAML_${rawName}_ICON_KEY`]?.trim() || undefined,
+      entryPoint,
+      issuer,
+      idpIssuer,
+      idpCertPems,
+      callbackUrl,
+      signatureAlgorithm,
+      wantAssertionsSigned: true,
+      allowedDomains,
+      groupsAttribute:
+        env[`SAML_${rawName}_GROUPS_ATTRIBUTE`]?.trim() || 'groups',
+      emailAttribute: env[`SAML_${rawName}_EMAIL_ATTRIBUTE`]?.trim() || 'email',
+      permissionMap,
+      logoutUrl: logoutUrlRaw || undefined,
+      decryptionPvk,
+      forceAuthn,
+      disableRequestedAuthnContext,
+    });
+  }
+
+  return samlRegistry;
+};
+
+// ---------------------------------------------------------------------------
+// Memoised registry (process.env-backed)
+// ---------------------------------------------------------------------------
+
+let cache: Map<string, SamlProviderConfig> | null = null;
+
+const registry = (): Map<string, SamlProviderConfig> => {
+  if (!cache) cache = buildSamlRegistryFromEnv(process.env);
+  return cache;
+};
+
+/** Clears the memoised SAML registry — for tests that mutate `process.env`. */
+export const resetSamlRegistryCache = (): void => {
+  cache = null;
+};
+
+/**
+ * Validates the SAML config at boot; throws on any misconfiguration (fail-fast).
+ * Zero providers configured is valid — SAML is simply disabled.
+ */
+export const validateSamlConfig = (): void => {
+  cache = buildSamlRegistryFromEnv(process.env);
+};
+
+export const getSamlProviderConfig = (
+  id: string,
+): SamlProviderConfig | undefined => registry().get(id);
+
+export const getAllSamlProviderConfigs = (): SamlProviderConfig[] =>
+  Array.from(registry().values());
+
+export const isSamlEnabled = (): boolean => registry().size > 0;
diff --git a/apps/gateway/src/sso/saml-transaction.service.spec.ts b/apps/gateway/src/sso/saml-transaction.service.spec.ts
new file mode 100644
index 0000000..5d637ab
--- /dev/null
+++ b/apps/gateway/src/sso/saml-transaction.service.spec.ts
@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import jwt from 'jsonwebtoken';
+import {
+  clearSamlTransactionCookie,
+  readSamlTransaction,
+  setSamlTransactionCookie,
+} from './saml-transaction.service';
+
+const SECRET = 'test-secret';
+
+const mkRes = () => {
+  const res = {} as Record<string, ReturnType<typeof vi.fn>>;
+  res.cookie = vi.fn();
+  res.clearCookie = vi.fn();
+  return res as never;
+};
+
+const tx = {
+  provider: 'acme',
+  requestId: '_feedfacefeedfacefeedfacefeedface',
+  returnTo: '/dashboard',
+};
+
+describe('saml-transaction.service', () => {
+  const saved = { ...process.env };
+  beforeEach(() => {
+    process.env.SSO_STATE_SECRET = SECRET;
+  });
+  afterEach(() => {
+    process.env = { ...saved };
+    vi.clearAllMocks();
+  });
+
+  it('set → read roundtrip preserves the transaction', () => {
+    const res = mkRes() as never as { cookie: ReturnType<typeof vi.fn> };
+    setSamlTransactionCookie(res as never, tx);
+    expect(res.cookie).toHaveBeenCalledOnce();
+    const [name, token, options] = res.cookie.mock.calls[0];
+    expect(name).toBe('saml_tx');
+    expect(options).toMatchObject({ httpOnly: true, maxAge: 5 * 60 * 1000 });
+
+    const req = { cookies: { saml_tx: token } } as never;
+    expect(readSamlTransaction(req)).toEqual(tx);
+  });
+
+  it('uses SameSite=None+Secure in production (cross-site ACS POST)', () => {
+    process.env.NODE_ENV = 'production';
+    const res = mkRes() as never as { cookie: ReturnType<typeof vi.fn> };
+    setSamlTransactionCookie(res as never, tx);
+    expect(res.cookie.mock.calls[0][2]).toMatchObject({
+      sameSite: 'none',
+      secure: true,
+      httpOnly: true,
+    });
+  });
+
+  it('throws when no signing secret is configured', () => {
+    delete process.env.SSO_STATE_SECRET;
+    delete process.env.JWT_REFRESH_SECRET;
+    expect(() => setSamlTransactionCookie(mkRes(), tx)).toThrow(
+      /secret is not configured/,
+    );
+  });
+
+  it('rejects a tampered token', () => {
+    const res = mkRes() as never as { cookie: ReturnType<typeof vi.fn> };
+    setSamlTransactionCookie(res as never, tx);
+    const token = res.cookie.mock.calls[0][1] as string;
+    const tampered = token.slice(0, -2) + 'xx';
+    expect(
+      readSamlTransaction({ cookies: { saml_tx: tampered } } as never),
+    ).toBeNull();
+  });
+
+  it('rejects a token signed with the wrong typ (no cross-cookie reuse)', () => {
+    // A valid OIDC transaction cookie must never be accepted as a SAML one.
+    const foreign = jwt.sign({ ...tx, typ: 'sso_tx' }, SECRET, {
+      algorithm: 'HS256',
+      expiresIn: 300,
+    });
+    expect(
+      readSamlTransaction({ cookies: { saml_tx: foreign } } as never),
+    ).toBeNull();
+  });
+
+  it('rejects an expired token', () => {
+    const expired = jwt.sign({ ...tx, typ: 'saml_tx' }, SECRET, {
+      algorithm: 'HS256',
+      expiresIn: -10,
+    });
+    expect(
+      readSamlTransaction({ cookies: { saml_tx: expired } } as never),
+    ).toBeNull();
+  });
+
+  it('returns null when the cookie is absent', () => {
+    expect(readSamlTransaction({ cookies: {} } as never)).toBeNull();
+  });
+
+  it('clear removes the cookie', () => {
+    const res = mkRes() as never as { clearCookie: ReturnType<typeof vi.fn> };
+    clearSamlTransactionCookie(res as never);
+    expect(res.clearCookie).toHaveBeenCalledWith(
+      'saml_tx',
+      expect.objectContaining({ httpOnly: true }),
+    );
+  });
+});
diff --git a/apps/gateway/src/sso/saml-transaction.service.ts b/apps/gateway/src/sso/saml-transaction.service.ts
new file mode 100644
index 0000000..35396ee
--- /dev/null
+++ b/apps/gateway/src/sso/saml-transaction.service.ts
@@ -0,0 +1,88 @@
+import type { CookieOptions, Request, Response } from 'express';
+import jwt, { JwtPayload } from 'jsonwebtoken';
+
+/**
+ * Short-lived, integrity-protected SAML login transaction — the SAML twin of
+ * {@link SsoTransaction} in `sso-transaction.service.ts`. It binds the browser
+ * that STARTED the flow to the ACS callback, carrying the AuthnRequest id
+ * (validated against `InResponseTo`) and the vetted post-login `returnTo`.
+ * `returnTo` ALWAYS travels here, in the signed cookie — RelayState is never
+ * trusted for the final redirect (open-redirect defense).
+ *
+ * Cookie SameSite, unlike OIDC: the ACS is a cross-site top-level POST from
+ * the IdP. `Lax` only attaches cookies to cross-site top-level GETs, so in
+ * production this cookie must be `SameSite=None; Secure` to reach the ACS.
+ * In dev (no https) `None; Secure` would be dropped by the browser, so we
+ * fall back to `Lax` — meaning the full SAML handshake against a real IdP
+ * requires https (production parity); dev coverage comes from the e2e suite
+ * which posts same-site.
+ */
+export interface SamlTransaction {
+  provider: string;
+  /** The AuthnRequest `ID` — must equal the response's `InResponseTo`. */
+  requestId: string;
+  returnTo: string;
+}
+
+const TX_COOKIE = 'saml_tx';
+const TX_TTL_SECONDS = 5 * 60; // 5 minutes — the handshake is short.
+const TX_TYP = 'saml_tx';
+
+// Same secret strategy as the OIDC transaction cookie: a dedicated
+// SSO_STATE_SECRET, falling back to the refresh secret.
+const secret = (): string =>
+  process.env.SSO_STATE_SECRET ?? process.env.JWT_REFRESH_SECRET ?? '';
+
+const cookieOptions = (maxAgeMs?: number): CookieOptions => {
+  const production = process.env.NODE_ENV === 'production';
+  const options: CookieOptions = {
+    httpOnly: true,
+    path: '/',
+    // See the interface JSDoc: None+Secure in production (cross-site POST to
+    // the ACS), Lax in dev where Secure cookies are unavailable over http.
+    sameSite: production ? 'none' : 'lax',
+    secure: production,
+  };
+  if (maxAgeMs !== undefined) options.maxAge = maxAgeMs;
+  return options;
+};
+
+interface SamlTransactionPayload extends JwtPayload, SamlTransaction {
+  typ: typeof TX_TYP;
+}
+
+export const setSamlTransactionCookie = (
+  res: Response,
+  tx: SamlTransaction,
+): void => {
+  if (!secret()) throw new Error('SSO state secret is not configured');
+  const token = jwt.sign({ ...tx, typ: TX_TYP }, secret(), {
+    algorithm: 'HS256',
+    expiresIn: TX_TTL_SECONDS,
+  });
+  res.cookie(TX_COOKIE, token, cookieOptions(TX_TTL_SECONDS * 1000));
+};
+
+/** Reads and verifies the SAML transaction cookie. Null if absent/invalid. */
+export const readSamlTransaction = (req: Request): SamlTransaction | null => {
+  const token = req.cookies?.[TX_COOKIE];
+  if (!token || !secret()) return null;
+  try {
+    const decoded = jwt.verify(token, secret(), {
+      algorithms: ['HS256'],
+    }) as SamlTransactionPayload;
+    if (decoded.typ !== TX_TYP) return null;
+    return {
+      provider: decoded.provider,
+      requestId: decoded.requestId,
+      returnTo: decoded.returnTo,
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** Clears the SAML transaction cookie — the handshake is single-use. */
+export const clearSamlTransactionCookie = (res: Response): void => {
+  res.clearCookie(TX_COOKIE, cookieOptions());
+};
diff --git a/apps/gateway/src/sso/saml-types.ts b/apps/gateway/src/sso/saml-types.ts
new file mode 100644
index 0000000..649d825
--- /dev/null
+++ b/apps/gateway/src/sso/saml-types.ts
@@ -0,0 +1,92 @@
+import { ClaimPermissionMapping } from '@dto';
+
+/**
+ * Full, secret-bearing configuration of one SAML 2.0 provider.
+ * Lives ONLY in the gateway — never serialised to the client.
+ * Use {@link SsoProviderPublicDTO} (from `@dto`) for anything the browser may see.
+ *
+ * Mirrors the shape of {@link SsoProviderConfig} (OIDC) in `provider-registry.ts`
+ * so the two registries remain structurally consistent.
+ *
+ * Security notes:
+ * - `idpCertPems` and `decryptionPvk` are cryptographic material; treat them as
+ *   secrets and keep them out of logs, responses, and error messages.
+ * - `wantAssertionsSigned` is typed as the literal `true` so the compiler prevents
+ *   any code path from weakening assertion-signing requirements.
+ * - `sha1` is not an accepted `signatureAlgorithm` value by design (broken algorithm).
+ */
+export interface SamlProviderConfig {
+  /** Lowercased provider key, used in `/auth/sso/:id/login`. */
+  id: string;
+  displayName: string;
+  iconKey?: string;
+  /** SSO URL of the IdP (HTTP-Redirect binding). */
+  entryPoint: string;
+  /** SP entityID — our service's identifier sent to the IdP. */
+  issuer: string;
+  /**
+   * EntityID of the IdP.
+   * Validated against the `Issuer` element in the SAML response to prevent
+   * mix-up attacks where a response from a different IdP is accepted.
+   */
+  idpIssuer: string;
+  /**
+   * One or more X.509 certificate(s) PEM-encoded from the IdP, used to verify
+   * response signatures. Multiple entries support certificate rotation without
+   * downtime — validation succeeds if any cert in the list matches.
+   * Must contain at least one entry.
+   */
+  idpCertPems: string[];
+  /** Assertion Consumer Service URL — must exactly match what is registered at the IdP. */
+  callbackUrl: string;
+  /**
+   * XML digital-signature algorithm for the AuthnRequest.
+   * `sha1` is intentionally excluded (cryptographically broken).
+   */
+  signatureAlgorithm: 'sha256' | 'sha512';
+  /**
+   * Require the IdP to sign individual assertions (not only the outer Response).
+   * Typed as the literal `true` — this requirement must never be relaxed.
+   */
+  wantAssertionsSigned: true;
+  /**
+   * MANDATORY allowlist of email domains accepted from this IdP (at least one
+   * entry). SAML assertions carry no per-assertion `email_verified` signal, so
+   * the gateway must stamp `emailVerified: true` for the API to resolve/link an
+   * account. This domain allowlist is therefore the ONLY cross-tenant trust
+   * boundary: it bounds which email identities a (signed) IdP may assert, and
+   * prevents a validly-signed assertion from claiming an arbitrary email that
+   * would auto-link to a pre-existing local or other-tenant account
+   * (account-takeover defense). Enforced fail-fast at boot.
+   */
+  allowedDomains: string[];
+  /** Name of the SAML attribute carrying the user's group/role memberships. */
+  groupsAttribute: string;
+  /** Name of the SAML attribute carrying the user's email address. */
+  emailAttribute: string;
+  /**
+   * Mapping from IdP group/role claim values to local permissions.
+   * Treated as a SUGGESTION by the API — the API may floor it to a minimum.
+   */
+  permissionMap: ClaimPermissionMapping[];
+  /** Optional SLO (Single Logout) endpoint of the IdP. */
+  logoutUrl?: string;
+  /**
+   * Private key (PEM) for decrypting encrypted SAML assertions.
+   * Secret — must never appear in logs, serialised responses, or error output.
+   */
+  decryptionPvk?: string;
+  /**
+   * When true, the AuthnRequest carries `ForceAuthn="true"`, which instructs
+   * the IdP to re-authenticate the user even if an active session exists.
+   * Use this for high-assurance flows (e.g. privilege elevation).
+   */
+  forceAuthn?: boolean;
+  /**
+   * When true (the default), the AuthnRequest omits `<RequestedAuthnContext>`.
+   * Set to `false` only if your IdP explicitly requires that element; most
+   * legacy IdPs fail or behave unexpectedly when it is present.
+   * Default: true (disabled for maximum IdP compatibility).
+   */
+  disableRequestedAuthnContext?: boolean;
+}
diff --git a/docs/README_eng.md b/docs/README_eng.md
index df52823..8de0435 100644
--- a/docs/README_eng.md
+++ b/docs/README_eng.md
@@ -738,7 +738,7 @@ In production, apply the SQL manually against the database.
 ### Roadmap
 
 - [x] SSO/OIDC in the gateway for enterprise customers (Okta, Azure AD, Auth0) — see [docs/SECURITY.md → Federación OIDC](SECURITY.md#federación-oidc-sso-okta--azure-ad--auth0)
-- [ ] SAML for legacy tenants
+- [x] SAML 2.0 for legacy tenants — see [docs/SECURITY.md → Federación SAML 2.0](SECURITY.md#federación-saml-20-tenants-legacy)
 - [ ] SCIM 2.0 for bulk provisioning
 - [ ] Multi-tenant CRUDs
 - [ ] Complete e2e tests (Playwright)
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 5bfe79d..6df424e 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -269,3 +269,131 @@ browser ──/auth/sso/:p/callback──▶ gateway
 3. Configurá `SSO_STATE_SECRET` (secreto dedicado en producción).
 4. `<NAME>` (en minúsculas) es el id del proveedor. El front pinta un botón por
    proveedor desde `GET /api/v1/auth/sso/providers` (solo metadatos públicos).
+
+## Federación SAML 2.0 (tenants legacy)
+
+Para IdPs corporativos que no hablan OIDC (ADFS, Shibboleth, Okta-SAML,
+Azure AD SAML), el gateway actúa como **Service Provider (SP) SAML 2.0**,
+**solo SP-initiated**. Termina en **la misma sesión local** que OIDC/local
+(access JWT + cookie refresh con familia/rotación); el API sigue confiando
+**solo** en el JWT interno EdDSA y nunca habla con el IdP. Sin proveedores
+`SAML_*` configurados, SAML está desactivado y nada cambia. Núcleo
+criptográfico: `@node-saml/node-saml` (con `xml-crypto`), endurecido en
+`apps/gateway/src/sso/saml-client.ts`.
+
+### Flujo (SP-initiated)
+
+```
+browser ──/auth/sso/:p/login──▶ gateway  (AuthnRequest id CSPRNG + returnTo
+   │                                │      → cookie tx firmada; RelayState vacío)
+   ▼                                │ 302 (HTTP-Redirect, SAMLRequest deflate+b64)
+  IdP  ◀── entryPoint (SSO URL) ────┘
+   │ login del usuario
+   ▼ 302 / auto-POST con SAMLResponse
+browser ──POST /auth/sso/:p/callback──▶ gateway (ACS, HTTP-POST binding)
+                                    │ tx cookie single-use atada al provider
+                                    │ node-saml: firma de Response Y Assertion
+                                    │   contra cert(s) PINNED del registry,
+                                    │   Status, Conditions/skew, AudienceRestriction
+                                    │ controller: Issuer==idpIssuer (mix-up),
+                                    │   InResponseTo==tx.requestId, NameID estable,
+                                    │   email plausible ∈ allowedDomains
+                                    │ grupos→permisos (sugerencia)
+                                    │ ApiClient.resolveFederatedUser → usuario local
+                                    │ respondWithTokens (sesión local estándar)
+                                    ▼ 302 a returnTo (de la cookie, allowlist same-site)
+```
+
+Metadata del SP para el onboarding del IdP:
+`GET /api/v1/auth/sso/:p/metadata` (`application/samlmetadata+xml`, público,
+sin material privado).
+
+### Modelo de amenazas y decisiones
+
+- **Solo SP-initiated**: el ACS **exige** la cookie de transacción firmada y
+  que `InResponseTo` case con el `AuthnRequest` id que la inició. Una Response
+  sin transacción (IdP-initiated) se rechaza por diseño — cierra CSRF en una
+  ruta que es necesariamente exenta de CSRF por cookie, y bloquea respuestas no
+  solicitadas.
+- **Firma exigida en Response Y Assertion** (`wantAuthnResponseSigned` +
+  `wantAssertionsSigned`, ambos literal `true`, no relajables por env), validada
+  **solo** contra los certificados pinned del registry — **nunca** contra certs
+  embebidos en la propia respuesta (trust bypass).
+- **Anti-XSW (XML Signature Wrapping)**: node-saml valida el nodo firmado
+  correcto; el e2e inyecta una aserción forjada junto a la firmada y exige
+  rechazo.
+- **Anti-XXE**: el parser de `@xmldom/xmldom` no resuelve entidades externas.
+- **NameID persistente** (o `emailAddress`); **`transient` se rechaza** — el par
+  `(provider, subject)` debe ser estable para keyear la cuenta. `unspecified`
+  también se rechaza (allowlist fail-closed).
+- **Comment injection en NameID** (clase CVE-2017-11427): mitigado por la
+  versión de `xml-crypto`/node-saml; el e2e prueba que `a@corp.com<!--x-->.evil`
+  no resuelve a una identidad distinta de la firmada.
+- **Replay**: cookie de transacción single-use (leída y borrada en todo camino)
+  - `validateInResponseTo: always` con caché acotada + re-chequeo de
+    `NotOnOrAfter` con skew ≤30s.
+- **Mix-up multi-IdP**: el `Issuer` de la Response debe ser exactamente el
+  `idpIssuer` configurado del proveedor (chequeo explícito en el controller:
+  node-saml solo aplica `idpIssuer` a mensajes de logout, no a la Response de
+  login). Cada proveedor tiene su propio cert pinned.
+- **AudienceRestriction** == entityID del SP (una aserción dirigida a otro SP se
+  rechaza).
+- **Account takeover / cross-tenant**: SAML no transporta una señal
+  `email_verified` por aserción, así que el ACS sella `emailVerified: true` (el
+  IdP del tenant es autoritativo para su dominio y lo configura el operador). Por
+  eso **`SAML_<NAME>_ALLOWED_DOMAINS` es OBLIGATORIO** (fail-fast al arranque si
+  falta): es el **único cerco** que impide que una aserción firmada asevere un
+  email arbitrario y se auto-vincule a una cuenta local/de otro tenant
+  preexistente. El email asertado debe estar dentro del allowlist o se rechaza.
+- **Escalada por atributo de grupos**: `mapGroupsToPermissions` es solo
+  _sugerencia_; el API aplica suelo de privilegio, **nunca** concede ADMIN por
+  federación y no muta los permisos de una cuenta viva.
+- **RelayState nunca se usa para el redirect final**: el `returnTo` viaja solo
+  en la cookie firmada y se re-valida con `safeReturnTo` (same-site; se rechazan
+  absolutas, `//`, `\\`, control). El e2e prueba que un `RelayState` externo no
+  se sigue.
+- **SSRF** en `entryPoint`/`logoutUrl`: solo `https`, con bloqueo de
+  loopback/link-local/metadata (169.254.169.254)/RFC1918 (mismo guard que OIDC);
+  el bloqueo de metadata/`0.0.0.0` es incondicional incluso con
+  `SSO_ALLOW_INSECURE_ISSUERS` (escape hatch solo-dev para loopback/RFC1918).
+- **Certificados**: el registry rechaza al arranque certs caducados, RSA <2048
+  bits y `sha1`; avisa si expiran en <30 días. Rotación sin downtime con
+  multi-cert (separador `;`). Las claves/certs y `_DECRYPTION_PVK` nunca aparecen
+  en logs, errores, metadata ni respuestas públicas.
+- **Sin fuga de errores/IdP**: el ACS jamás refleja `StatusMessage`/XML del IdP;
+  redirect genérico `/login?sso_error=1`; log interno con `requestId`, control
+  chars eliminados y truncado.
+- **SLO best-effort**: el logout **siempre** revoca la familia de refresh local
+  y limpia cookies **antes** de cualquier ida al IdP (un IdP caído nunca mantiene
+  viva la sesión). Si el proveedor tiene `_LOGOUT_URL` se emite un
+  `LogoutRequest` (HTTP-Redirect) con el `NameID`+`SessionIndex` del hint firmado
+  (cookie HttpOnly). El `LogoutResponse` se valida best-effort y cualquier fallo
+  se ignora: para cuando el IdP nos devuelve, la sesión local ya está revocada,
+  así que un `LogoutResponse` falsificado no produce cambio de estado.
+- **SLO IdP-initiated FUERA DE ALCANCE** en esta iteración (espejo del
+  back-channel logout de OIDC). Riesgo residual: si el logout se origina en el
+  IdP, la sesión local sigue viva hasta que expire/rote el refresh. El
+  `LogoutRequest` SP→IdP es **sin firmar** (el starter no gestiona clave privada
+  del SP); documentado y aceptado.
+
+### Alta de un IdP SAML legacy
+
+1. **Onboarding del IdP**: pasale la metadata del SP
+   (`GET /api/v1/auth/sso/<name>/metadata`) o, a mano: entityID = SP issuer,
+   **ACS exacto** (sin comodines)
+   `https://<tu-dominio>/api/v1/auth/sso/<name>/callback`, NameIDFormat
+   `persistent`.
+2. **Configurá en el entorno del gateway** (ver `.env.example`, bloque
+   `SAML_<NAME>_*`): `_ENTRY_POINT` (SSO URL del IdP), `_IDP_ISSUER` (entityID
+   del IdP), `_IDP_CERT` (PEM x509 público del IdP; multi-cert con `;` para
+   rotación), `_CALLBACK_URL` (ACS exacto) y **`_ALLOWED_DOMAINS` (obligatorio)**.
+   Opcionales: `_SP_ISSUER`, `_EMAIL_ATTRIBUTE`, `_GROUPS_ATTRIBUTE`,
+   `_PERMISSION_MAP`, `_LOGOUT_URL`, `_SIGNATURE_ALGORITHM` (sha256|sha512),
+   `_DECRYPTION_PVK`, `_FORCE_AUTHN`, `_DISABLE_REQUESTED_AUTHN_CONTEXT`,
+   `_DISPLAY_NAME`, `_ICON_KEY`.
+3. **Rotación de certificados**: durante el solape, poné ambos PEM en `_IDP_CERT`
+   separados por `;`; la validación acepta cualquiera de la lista. Quitá el viejo
+   tras la rotación.
+4. `<NAME>` (en minúsculas) es el id del proveedor (clave en
+   `federated_identity.provider`; no puede colisionar con un id OIDC). El front
+   pinta un botón por proveedor desde `GET /api/v1/auth/sso/providers`.
diff --git a/libs/rest-dto/src/lib/sso.ts b/libs/rest-dto/src/lib/sso.ts
index 909239f..403100e 100644
--- a/libs/rest-dto/src/lib/sso.ts
+++ b/libs/rest-dto/src/lib/sso.ts
@@ -1,5 +1,11 @@
 import { CreationOptional, Permission } from './rest-dto';
 
+/**
+ * Federation protocol implemented by an SSO provider.
+ * Strict literal union — never widen to `string`.
+ */
+export type SsoProtocol = 'oidc' | 'saml';
+
 /**
  * Mirrors the `federated_identity` table.
  * `subject` is the IdP-issued opaque identifier — it is internal and must not
@@ -19,14 +25,18 @@ export interface FederatedIdentityDTO {
 
 /**
  * Public metadata the frontend needs to render login buttons.
- * MUST NOT contain `clientSecret`, `issuer` internals, raw IdP claims,
- * `subject`, or any other secret/internal field.
+ * MUST NOT contain `clientSecret`, `issuer` internals, IdP URLs, certificates,
+ * entityIDs, raw IdP claims, `subject`, or any other secret/internal field.
  * `id` is the provider key used in the login URL `/auth/sso/:id/login`.
+ * `protocol` indicates the federation protocol; defaults to `'oidc'` when absent
+ * so existing clients that do not read the field continue to work correctly.
  */
 export interface SsoProviderPublicDTO {
   id: string;
   displayName: string;
   iconKey?: string;
+  /** Federation protocol of the provider. Defaults to 'oidc' when absent. */
+  protocol?: SsoProtocol;
 }
 
 /**
diff --git a/libs/rest-dto/src/lib/validation.ts b/libs/rest-dto/src/lib/validation.ts
index 86d32b7..54dc5d2 100644
--- a/libs/rest-dto/src/lib/validation.ts
+++ b/libs/rest-dto/src/lib/validation.ts
@@ -54,8 +54,15 @@ export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
 
 /**
  * Schema for the internal federated resolve/provision endpoint.
- * Called exclusively by the gateway after it has fully validated an OIDC
- * ID token. `.strict()` rejects extra keys (mass-assignment defense).
+ * Called exclusively by the gateway after it has fully validated an IdP
+ * assertion — either an OIDC ID token or a SAML 2.0 assertion.
+ * `.strict()` rejects extra keys (mass-assignment defense).
+ *
+ * `subject` covers both the OIDC `sub` claim and the SAML NameID
+ * (persistent format). The 255-char ceiling matches the `federated_identity`
+ * varchar(255) column; the SAML spec allows persistent NameIDs up to 256 chars,
+ * so any IdP that emits a 256-char NameID will be rejected at the schema layer —
+ * this is intentional and the column size should be the source of truth.
  */
 export const resolveFederatedUserSchema = z
   .object({
diff --git a/package-lock.json b/package-lock.json
index 49bdb7d..0169776 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -20,6 +20,7 @@
         "@jsverse/transloco": "^7.0.0",
         "@ng-bootstrap/ng-bootstrap": "^20.0.0",
         "@ngneat/until-destroy": "^10.0.0",
+        "@node-saml/node-saml": "5.1.0",
         "@popperjs/core": "^2.11.8",
         "axios": "^1.7.2",
         "bcrypt": "^6.0.0",
@@ -8050,6 +8051,29 @@
         "url": "https://paulmillr.com/funding/"
       }
     },
+    "node_modules/@node-saml/node-saml": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@node-saml/node-saml/-/node-saml-5.1.0.tgz",
+      "integrity": "sha512-t3cJnZ4aC7HhPZ6MGylGZULvUtBOZ6FzuUndaHGXjmIZHXnLfC/7L8a57O9Q9V7AxJGKAiRM5zu2wNm9EsvQpw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/debug": "^4.1.12",
+        "@types/qs": "^6.9.18",
+        "@types/xml-encryption": "^1.2.4",
+        "@types/xml2js": "^0.4.14",
+        "@xmldom/is-dom-node": "^1.0.1",
+        "@xmldom/xmldom": "^0.8.10",
+        "debug": "^4.4.0",
+        "xml-crypto": "^6.1.2",
+        "xml-encryption": "^3.1.0",
+        "xml2js": "^0.6.2",
+        "xmlbuilder": "^15.1.1",
+        "xpath": "^0.0.34"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/@nodelib/fs.scandir": {
       "version": "2.1.5",
       "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
@@ -12903,7 +12927,6 @@
       "version": "6.15.0",
       "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.0.tgz",
       "integrity": "sha512-JawvT8iBVWpzTrz3EGw9BTQFg3BQNmwERdKE22vlTxawwtbyUSlMppvZYKLZzB5zgACXdXxbD3m1bXaMqP/9ow==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/range-parser": {
@@ -13034,6 +13057,24 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/xml-encryption": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@types/xml-encryption/-/xml-encryption-1.2.4.tgz",
+      "integrity": "sha512-I69K/WW1Dv7j6O3jh13z0X8sLWJRXbu5xnHDl9yHzUNDUBtUoBY058eb5s+x/WG6yZC1h8aKdI2EoyEPjyEh+Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/xml2js": {
+      "version": "0.4.14",
+      "resolved": "https://registry.npmjs.org/@types/xml2js/-/xml2js-0.4.14.tgz",
+      "integrity": "sha512-4YnrRemBShWRO2QjvUin8ESA41rH+9nQGLUGZV/1IDhi3SL9OhdpNC/MrulTWuptXKwhx/aDxE7toV0f/ypIXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/yargs": {
       "version": "17.0.35",
       "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.35.tgz",
@@ -13965,6 +14006,24 @@
         }
       }
     },
+    "node_modules/@xmldom/is-dom-node": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@xmldom/is-dom-node/-/is-dom-node-1.0.1.tgz",
+      "integrity": "sha512-CJDxIgE5I0FH+ttq/Fxy6nRpxP70+e2O048EPe85J2use3XKdatVM7dDVvFNjQudd9B49NPoZ+8PG49zj4Er8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16"
+      }
+    },
+    "node_modules/@xmldom/xmldom": {
+      "version": "0.8.13",
+      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.13.tgz",
+      "integrity": "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
     "node_modules/@xtuc/ieee754": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/@xtuc/ieee754/-/ieee754-1.2.0.tgz",
@@ -26148,7 +26207,6 @@
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz",
       "integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==",
-      "dev": true,
       "license": "BlueOak-1.0.0",
       "engines": {
         "node": ">=11.0.0"
@@ -30085,6 +30143,49 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/xml-crypto": {
+      "version": "6.1.2",
+      "resolved": "https://registry.npmjs.org/xml-crypto/-/xml-crypto-6.1.2.tgz",
+      "integrity": "sha512-leBOVQdVi8FvPJrMYoum7Ici9qyxfE4kVi+AkpUoYCSXaQF4IlBm1cneTK9oAxR61LpYxTx7lNcsnBIeRpGW2w==",
+      "license": "MIT",
+      "dependencies": {
+        "@xmldom/is-dom-node": "^1.0.1",
+        "@xmldom/xmldom": "^0.8.10",
+        "xpath": "^0.0.33"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/xml-crypto/node_modules/xpath": {
+      "version": "0.0.33",
+      "resolved": "https://registry.npmjs.org/xpath/-/xpath-0.0.33.tgz",
+      "integrity": "sha512-NNXnzrkDrAzalLhIUc01jO2mOzXGXh1JwPgkihcLLzw98c0WgYDmmjSh1Kl3wzaxSVWMuA+fe0WTWOBDWCBmNA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6.0"
+      }
+    },
+    "node_modules/xml-encryption": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/xml-encryption/-/xml-encryption-3.1.0.tgz",
+      "integrity": "sha512-PV7qnYpoAMXbf1kvQkqMScLeQpjCMixddAKq9PtqVrho8HnYbBOWNfG0kA4R7zxQDo7w9kiYAyzS/ullAyO55Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@xmldom/xmldom": "^0.8.5",
+        "escape-html": "^1.0.3",
+        "xpath": "0.0.32"
+      }
+    },
+    "node_modules/xml-encryption/node_modules/xpath": {
+      "version": "0.0.32",
+      "resolved": "https://registry.npmjs.org/xpath/-/xpath-0.0.32.tgz",
+      "integrity": "sha512-rxMJhSIoiO8vXcWvSifKqhvV96GjiD5wYb8/QHdoRyQvraTpp4IEv944nhGausZZ3u7dhQXteZuZbaqfpB7uYw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6.0"
+      }
+    },
     "node_modules/xml-name-validator": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
@@ -30095,6 +30196,37 @@
         "node": ">=18"
       }
     },
+    "node_modules/xml2js": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/xml2js/-/xml2js-0.6.2.tgz",
+      "integrity": "sha512-T4rieHaC1EXcES0Kxxj4JWgaUQHDk+qwHcYOCFHfiwKz7tOVPLq7Hjq9dM1WCMhylqMEfP7hMcOIChvotiZegA==",
+      "license": "MIT",
+      "dependencies": {
+        "sax": ">=0.6.0",
+        "xmlbuilder": "~11.0.0"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/xml2js/node_modules/xmlbuilder": {
+      "version": "11.0.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-11.0.1.tgz",
+      "integrity": "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/xmlbuilder": {
+      "version": "15.1.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
+      "integrity": "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0"
+      }
+    },
     "node_modules/xmlchars": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
@@ -30102,6 +30234,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/xpath": {
+      "version": "0.0.34",
+      "resolved": "https://registry.npmjs.org/xpath/-/xpath-0.0.34.tgz",
+      "integrity": "sha512-FxF6+rkr1rNSQrhUNYrAFJpRXNzlDoMxeXN5qI84939ylEv3qqPFKa85Oxr6tDaJKqwW6KKyo2v26TSv3k6LeA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6.0"
+      }
+    },
     "node_modules/xtend": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
diff --git a/package.json b/package.json
index 24ee4d4..328c6bb 100644
--- a/package.json
+++ b/package.json
@@ -44,6 +44,7 @@
     "format:gateway": "prettier --write \"apps/gateway/**/*.{ts,js,json}\"",
     "format:libs": "prettier --write \"libs/**/*.{ts,js,json}\"",
     "format:check": "prettier --check \"**/*.{ts,js,json,html,scss,css,md}\"",
+    "verify:lock": "npm ci --dry-run",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:front": "vitest run --config apps/front/vitest.config.mts",
@@ -122,6 +123,7 @@
     "@jsverse/transloco": "^7.0.0",
     "@ng-bootstrap/ng-bootstrap": "^20.0.0",
     "@ngneat/until-destroy": "^10.0.0",
+    "@node-saml/node-saml": "5.1.0",
     "@popperjs/core": "^2.11.8",
     "axios": "^1.7.2",
     "bcrypt": "^6.0.0",