Implement SAML (Single Sign-On) Support

[sangalo20]

Implement SAML (Single Sign-On) Support

What?

We need to develop SAML 2.0 (Single Sign-On) support within the Nexus Framework, allowing it to act as a SAML Service Provider (SP).

Currently, Nexus supports OAuth 2.0, OIDC, API Keys, Basic Auth, and custom static credentials. Adding SAML support will enable Nexus to seamlessly integrate with enterprise Identity Providers (IdPs) that rely on XML-based assertions for authentication.

Why?

1. Enterprise Adoption: Many large organizations and enterprises still rely heavily on SAML for Single Sign-On (SSO) across their applications. To drive adoption in these environments, Nexus must support SAML natively.
2. Unified Identity Management: The core value proposition of Nexus is providing a single, cohesive layer to manage all types of identity and credentials. Lacking SAML means an incomplete solution for enterprise identity.
3. Frictionless Integration: By acting as a SAML SP, Nexus will handle the complexity of generating AuthnRequests and validating cryptographic XML assertions, allowing developers to integrate enterprise SSO without writing bespoke, complex SAML logic.

Sample Approach (The "How")

1. Data Model Extension: Update the Nexus Broker's data models to support a new saml value in the AuthType enums. Extend the provider_profiles table to store SAML-specific metadata, such as the IdP's SSO URL, Entity ID, and public X.509 certificates used for validating signatures.
2. SAML Library Integration: Introduce a robust, production-ready Go SAML library (e.g., github.com/crewjam/saml) into the nexus-broker service to handle XML parsing, signature generation, and validation.
3. Login Handler Implementation (/saml/login): Analogous to the OAuth consent flow, build a handler that generates a SAML AuthnRequest and redirects the user's browser to the enterprise IdP for authentication.
4. Assertion Consumer Service (ACS) Handler (/saml/acs): Develop an endpoint to receive the HTTP POST containing the SAML Response from the IdP. This handler must rigorously validate the XML signature, check assertion conditions (e.g., NotOnOrAfter), extract user identity and attributes, and finalize the creation of a Nexus Connection.
5. State & Security Management: Ensure SAML RelayState is securely generated, signed, and validated (similar to OIDC state) to prevent CSRF and binding attacks.

Where to Begin

1. Research SAML 2.0: Familiarize yourself with the SAML 2.0 Web Browser SSO Profile, specifically the roles of the Identity Provider (IdP) and Service Provider (SP), and the structure of AuthnRequest and Response XML documents.
2. Evaluate Libraries: Review and select an appropriate Go SAML library (like crewjam/saml) that meets security and maintainability standards.
3. Extend the Data Model: Begin by updating nexus-broker/internal/models/constants.go to include saml and craft a database migration to add necessary columns to provider_profiles.
4. Build a Proof of Concept: Create a basic SP implementation within nexus-broker that can successfully generate an AuthnRequest and validate a test assertion from a mock IdP (like a local Keycloak instance or a developer Okta tenant).
5. Integrate into Nexus Flows: Wire the successful SAML authentication into the existing Nexus Connection creation lifecycle, ensuring it issues and encrypts tokens consistently with OAuth/OIDC flows.