feat(auth): migrate dotAuth (OAuth/OIDC + SAML) from plugin to core

[swicken]

Closes #35555

Supersedes #35421 (same branch; could not be reopened).

Proposed Changes

Migrates the OAuth 2.0 / OIDC provider from the legacy dotOAuth plugin into core, adds SAML support as a first-class protocol alongside OAuth, introduces a headless token-exchange flow for front-end SPAs, and replaces the old dotsaml-config / dotOAuth app-key editors with a unified dotAuth portlet under Settings.

---

Backend (dotCMS/src)

REST API — /v1/dotauth

• Full CRUD for per-host dotAuth configs (DotAuthResource, DTOs, wired into DotRestApplication).
• Config bundle import/export endpoints (encrypted Apps export file, dotAuth-only filter on import).
• OIDC discovery proxy — fetches .well-known/openid-configuration and returns parsed issuer, endpoints, JWKS URI, and signing algorithms.
• Session-ref revocation endpoint (flushes the dotAuth sessionRef cache).

Protocol layer

• DotAuthProtocol enum + ProtocolHandler strategy interface.
• OAuthProtocolHandler — extracted from the legacy plugin; hardened OIDC iss check, alg validation, session binding.
• SamlProtocolHandler — new; own secret-key set, metadata endpoint, custom attribute mapping.
• Dual-key read/write/delete with case-insensitive host-id lookup; key rename dotOAuth → dotAuth.

Headless token exchange

• OAuth exchange endpoint (/v1/dotauth/exchange) — accepts an authorization code from an SPA, validates against the OIDC provider, provisions or resolves the user, and returns a dotCMS session-ref bearer token.
• DotAuthSession model + cache for session-ref tokens; DotAuthSessionCredentialProcessor wired into the filter chain.
• BuildRolesStrategy — configurable role sync (merge / replace / none) on each login.

Security hardening

• SSRF DNS-rebinding prevention on the OIDC discovery proxy (shared OAuthSsrfGuard).
• 60s clock-skew tolerance + fail-closed replay-fingerprint check on OIDC id_token.
• Admin-only guard on session-ref revocation.
• No OIDC validation details leaked in error responses.
• OAuth callback URL auto-derived from request (no user-supplied redirect target).
• Response size limits and redirect sanitization on the OAuth callback.

Portlet registration

• Startup task (Task260420AddDotAuthPortletToMenu) registers the dotAuth portlet in the Settings layout.
• portlet.xml registration; /apps/dotsaml-config redirects to the dotAuth portlet; dotsaml-config hidden from the Apps grid.

---

Frontend (core-web)

libs/portlets/dot-auth (new Nx library)

• Data-access service, discriminated-union models on protocol, list + config SignalStores.
• List view — protocol column, composed status tag, per-host CRUD.
• SSO config page — protocol toggle (OAuth / SAML), OIDC discovery auto-fill, SAML fieldsets (metadata URL/fetch, custom attributes, SP keypair auto-generation, metadata download), auto-provision and role-sync strategy controls.
• Headless config page — separated from SSO; system-level headless security settings with own app key.
• Config bundle import/export UI.
• Shell, routes, and i18n keys.

Modernization

• PrimeNG migration (p-inputSwitch → p-toggleswitch, pTextarea + TextareaModule), Tailwind v4 var-shorthand normalization.
• Components aligned with ANGULAR_STANDARDS (signals, @if/@for, OnPush).
• Regenerated OpenAPI client.

---

Testing

• Backend: JUnit 5 unit tests for DotAuthResource, protocol handlers, exchange guard paths, role-strategy, OIDC claim validation, SSRF guard, mapper round-trips.
• Frontend: Spectator specs for list component, edit dialog, SignalStores, SAML + protocol-switch paths, mapper round-trips.

---

Rollback notes

The startup task inserts a dotAuth portlet entry into cms_layouts_portlets and shifts existing portlet order values. On rollback to N−1 this entry becomes orphaned. Manual cleanup required:

DELETE FROM cms_layouts_portlets WHERE portlet_id = 'dotAuth';

A CDN purge of the Angular admin bundle may also be needed if a caching proxy is in front of the admin UI.

---

Checklist

• Tests — backend unit + frontend Spectator coverage across all major paths
• Translations — i18n keys for dotAuth labels, protocols, fieldsets, and error states
• Security — SSRF prevention, OIDC hardening (clock skew, replay), no leaked validation details, admin-only endpoints, no hardcoded secrets

Stats

126 files changed, ~16k LOC added

[semgrep-code-dotcms-test]

Legal Risk

The following dependencies were released under a license that
has been flagged by your organization for consideration.

Recommendation

While merging is not directly blocked, it's best to pause and consider what it means to use this license before continuing. If you are unsure, reach out to your security team or Semgrep admin to address this issue.

GPL-2.0

• node-forge 1.4.0

MPL-2.0

• axe-core 4.11.2
• dompurify 3.3.3
• lightningcss-android-arm64 1.31.1
• lightningcss-darwin-arm64 1.31.1
• lightningcss-darwin-x64 1.31.1
• lightningcss-freebsd-x64 1.31.1
• lightningcss-linux-arm-gnueabihf 1.31.1
• lightningcss-linux-arm64-gnu 1.31.1
• lightningcss-linux-arm64-musl 1.31.1
• lightningcss-linux-x64-gnu 1.31.1
• lightningcss-linux-x64-musl 1.31.1
• lightningcss-win32-arm64-msvc 1.31.1
• lightningcss-win32-x64-msvc 1.31.1
• lightningcss 1.31.1

[github-actions]

🤖 Bedrock Review — deepseek.v3.2

[🟡 Medium] core-web/apps/dotcms-ui/src/app/portlets/dot-apps/dot-apps-import-export-dialog/store/dot-apps-import-export-dialog.store.ts:65 — _importSuccessSubject is exposed as a public property (store._importSuccessSubject). This breaks encapsulation and allows external code to call next()/complete()/error() on the subject, which is an internal implementation detail. It should be kept private.

[🟡 Medium] core-web/apps/dotcms-ui/src/app/portlets/dot-apps/dot-apps-import-export-dialog/store/dot-apps-import-export-dialog.store.ts:77 — Method openExport signature changed to accept DotApp | null. The comment on line 88 says "the store handles null to mean 'all apps'", but the store method's logic for handling null is not shown in the diff. Ensure the backend API call correctly handles a null app key for a full export.

[🟡 Medium] core-web/apps/dotcms-ui/src/app/portlets/dot-apps/dot-apps-list/dot-apps-list.component.ts:154 — The filterApps method subscribes but does not handle errors. If the dotAppsService.get call fails, the error will be uncaught, potentially breaking the UI. Add error handling (e.g., log and reset state).

[🟡 Medium] core-web/libs/data-access/src/lib/dot-auth/dot-auth.service.ts:99 — downloadSamlMetadata uses window.open without any user interaction context (called from a component). Browsers may block this as a pop-up. Consider triggering this from a direct user action (like a button click) or use a safer method.

[🟡 Medium] core-web/libs/data-access/src/lib/dot-auth/dot-auth.service.ts:112 — exportBundle returns a Promise but the rest of the service methods return Observable. This creates an inconsistent API pattern. Consider aligning it to return an Observable for consistency, or ensure the mixed pattern is documented and intentional.

[🟠 High] core-web/libs/data-access/src/lib/dot-auth/dot-auth.service.ts:130 — importBundle constructs a FormData with a JSON string under key "json". The backend endpoint /api/v1/dotauth/import likely expects the password as a form field, not a JSON string. This could cause a server-side parsing error. Verify the expected request format matches the backend.

[🟡 Medium] core-web/libs/portlets/dot-auth/src/lib/dot-auth-config/components/dot-auth-headless-section.component.ts:69 — toggleIdp toggles expansion based on index, but if an IdP is removed, the indices shift, which could cause the wrong IdP to be expanded. Consider tracking expansion by a stable ID (like idp.id) instead of index.

[🟡 Medium] core-web/libs/portlets/dot-auth/src/lib/dot-auth-config/components/dot-auth-oidc-connection.component.ts:33 — isSecretStored checks for hardcoded '****' and DOT_AUTH_HIDDEN_SECRET_MASK. This logic is duplicated from the backend secret masking. Ensure the mask value is synchronized and documented as a constant shared with the backend to avoid drift.

[🟡 Medium] core-web/libs/portlets/dot-auth/src/lib/dot-auth-config/components/dot-auth-oidc-connection.component.ts:41 — error method accesses this.errors()[oidc.${field}]. The error mapping relies on a dotted path convention. Ensure the parent component provides errors in exactly this format, or this could fail silently.

[🟡 Medium] core-web/libs/portlets/dot-auth/src/lib/dot-auth-config/components/dot-auth-provisioning.component.html (line not in diff) — The template uses [ngModel] and (ngModelChange) but the corresponding component logic (onChange) is not shown in the diff. Ensure the component has the necessary method to handle the change events emitted by the template.

---

_{Run: #27967632129 · tokens: in: 22400 · out: 934 · total: 23334}

[claude]

Claude finished @swicken's task in 3m 2s —— View job

---

Pull Request Unsafe to Rollback!!!

---

Category: H-1 — One-Way Data Migration on cms_layouts_portlets

• Risk Level: 🟡 MEDIUM
• Why it's unsafe: Task260420AddDotAuthPortletToMenu performs two writes that persist after rollback to N-1: (1) it INSERTs a new dotAuth row into cms_layouts_portlets, which becomes an orphaned row on N-1 (N-1 has no dotAuth portlet and will ignore it, but the row stays); (2) it UPDATEs every portlet whose portlet_order ≥ appsOrder + 1 by incrementing the order by 1 — this is a one-way transformation on existing rows. On rollback to N-1, the shifted portlet_order values persist, so portlets that were after the apps entry appear at +1 from their pre-migration positions. Neither write can be automatically undone by reverting the binary.
• Code that makes it unsafe:
  • File: dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260420AddDotAuthPortletToMenu.java
  • Lines 57–61 (the permanent portlet_order shift):

    private static final String SQL_SHIFT_ORDER =
            "UPDATE cms_layouts_portlets SET portlet_order = portlet_order + 1 "
            + "WHERE layout_id = ? AND portlet_order >= ?";

  • Lines 60–63 (the INSERT that becomes orphaned on rollback):

    private static final String SQL_INSERT =
            "INSERT INTO cms_layouts_portlets(id, layout_id, portlet_id, portlet_order) "
            + "VALUES (?, ?, ?, ?)";

• Alternative: The PR already documents the orphaned row cleanup SQL (DELETE FROM cms_layouts_portlets WHERE portlet_id = 'dotAuth'). The portlet_order shift is NOT addressed — on rollback the admin Settings menu portlets remain shifted by 1 position from their pre-migration values. To make this fully safe, the task should record the pre-migration portlet_order values or use a reversible approach (no separate manual step is currently documented for the order shift).

---

Category: H-8 — New VTL Viewtools Added to toolbox.xml

• Risk Level: 🟢 LOW
• Why it's unsafe: Two new viewtools are registered in WEB-INF/toolbox.xml — $oauth (OAuthTool) and $oauthToken (OAuthTokenTool). N-1 does not have these keys in its toolbox. Any Velocity template (stored in the DB or theme filesystem) that adopts $oauth.isConfigured() or $oauthToken.getAccessToken() during the N release cycle will fail to resolve after rollback, rendering the affected template block blank or erroring. No core dotCMS VTL templates are co-migrated in this PR's diff, so the risk is conditional on customer templates adopting these new keys.
• Code that makes it unsafe:
  • File: dotCMS/src/main/webapp/WEB-INF/toolbox.xml
  • Lines 340–349:

    <tool>
        <key>oauth</key>
        <scope>request</scope>
        <class>com.dotcms.auth.providers.oauth.viewtool.OAuthTool</class>
    </tool>
    <tool>
        <key>oauthToken</key>
        <scope>request</scope>
        <class>com.dotcms.auth.providers.oauth.viewtool.OAuthTokenTool</class>
    </tool>

• Alternative: No change needed in this PR since no templates are co-migrated. Document in release notes that any customer template using $oauth or $oauthToken will fail on rollback to N-1 and must be reverted alongside the binary.

[claude]

Pull Request Unsafe to Rollback!!!

---

Category: H-1 — One-Way Data Migration on cms_layouts_portlets

• Risk Level: 🟡 MEDIUM
• Why it's unsafe: Task260420AddDotAuthPortletToMenu performs two writes that persist after rollback to N-1: (1) it INSERTs a new dotAuth row into cms_layouts_portlets, which becomes an orphaned row on N-1 (N-1 has no dotAuth portlet and will ignore it, but the row stays); (2) it UPDATEs every portlet whose portlet_order ≥ appsOrder + 1 by incrementing the order by 1 — this is a one-way transformation on existing rows. On rollback to N-1, the shifted portlet_order values persist, so portlets that were after the apps entry appear at +1 from their pre-migration positions. Neither write can be automatically undone by reverting the binary.
• Code that makes it unsafe:
  • File: dotCMS/src/main/java/com/dotmarketing/startup/runonce/Task260420AddDotAuthPortletToMenu.java
  • Lines 57–61 (the permanent portlet_order shift):

    private static final String SQL_SHIFT_ORDER =
            "UPDATE cms_layouts_portlets SET portlet_order = portlet_order + 1 "
            + "WHERE layout_id = ? AND portlet_order >= ?";

  • Lines 60–63 (the INSERT that becomes orphaned on rollback):

    private static final String SQL_INSERT =
            "INSERT INTO cms_layouts_portlets(id, layout_id, portlet_id, portlet_order) "
            + "VALUES (?, ?, ?, ?)";

• Alternative: The PR already documents the orphaned row cleanup SQL (DELETE FROM cms_layouts_portlets WHERE portlet_id = 'dotAuth'). The portlet_order shift is NOT addressed — on rollback the admin Settings menu portlets remain shifted by 1 position from their pre-migration values. To make this fully safe, the task should record the pre-migration portlet_order values or use a reversible approach (no separate manual step is currently documented for the order shift).

---

Category: H-8 — New VTL Viewtools Added to toolbox.xml

• Risk Level: 🟢 LOW
• Why it's unsafe: Two new viewtools are registered in WEB-INF/toolbox.xml — $oauth (OAuthTool) and $oauthToken (OAuthTokenTool). N-1 does not have these keys in its toolbox. Any Velocity template (stored in the DB or theme filesystem) that adopts $oauth.isConfigured() or $oauthToken.getAccessToken() during the N release cycle will fail to resolve after rollback, rendering the affected template block blank or erroring. No core dotCMS VTL templates are co-migrated in this PR's diff, so the risk is conditional on customer templates adopting these new keys.
• Code that makes it unsafe:
  • File: dotCMS/src/main/webapp/WEB-INF/toolbox.xml
  • Lines 340–349:

    <tool>
        <key>oauth</key>
        <scope>request</scope>
        <class>com.dotcms.auth.providers.oauth.viewtool.OAuthTool</class>
    </tool>
    <tool>
        <key>oauthToken</key>
        <scope>request</scope>
        <class>com.dotcms.auth.providers.oauth.viewtool.OAuthTokenTool</class>
    </tool>

• Alternative: No change needed in this PR since no templates are co-migrated. Document in release notes that any customer template using $oauth or $oauthToken will fail on rollback to N-1 and must be reverted alongside the binary.