Chapter 3C — Enterprise SAML 2.0 Federation

SAML 2.0 Identity Provider & Service Provider Federation

Connect enterprise SAML 2.0 Identity Providers (Okta, Microsoft Entra ID, PingFederate, ADFS, OneLogin, Google Workspace) to your applications — or use SSO.ID v2 as a SAML 2.0 Identity Provider for third-party SP applications — with automated XML metadata exchange, X.509 certificate management, and HTTP-POST / HTTP-Redirect bindings.

The SAML 2.0 Story 1. SP vs. IdP Modes 2. Configuring External SAML IdPs 3. Bindings, Certs & SLO 4. SAML Endpoints & AI Prompt

Enterprise Story: Bridging Legacy SAML 2.0 into a Modern OIDC Microservice Stack

How CloudPulse Connected a Bank's ADFS / Okta SAML 2.0 Server Without Adding SAML XML Parsers to Their App

GlobalBank's InfoSec policy mandated SAML 2.0 with signed XML assertions (rsa-sha256). However, CloudPulse's modern Angular SPA and Node.js/.NET APIs were built purely around OpenID Connect (OIDC) JWT tokens.

SSO.ID v2 as Your Protocol Broker: CloudPulse configured GlobalBank's SAML 2.0 Identity Provider in /connections. When a GlobalBank employee logs in, Auth.SSO.Id sends the SAML AuthnRequest to GlobalBank, validates the signed XML SAMLResponse at https://{your-tenant}.sso.id/auth/saml/acs, maps the SAML Attribute Statements to user claims, and issues a standard RS256 OIDC JWT token back to CloudPulse's Angular SPA!

Flow Diagram Dual-Role SAML 2.0 Brokering & Protocol Translation

flowchart TD subgraph ModeA["Mode A: Enterprise IdP Federation"] OKTA["Customer IdP (Okta / Ping / ADFS)"] -->|"Signed SAML 2.0 Assertion"| ACS["SSO.ID ACS (/auth/saml/acs)"] ACS -->|"Protocol Translation"| JWT["OIDC RS256 JWT Token"] JWT --> SPA["Modern SPA / API App"] end subgraph ModeB["Mode B: SSO.ID as SAML IdP"] USER["End User"] --> LOGIN["SSO.ID Login (/auth/Saml/Login)"] LOGIN -->|"Generates XML Assertion + Signature"| SAMLAPP["Enterprise SAML SP (Salesforce / Zendesk)" ] end

Mode A: SSO.ID acts as SAML SP, translating enterprise assertions into OIDC JWTs. Mode B: SSO.ID acts as SAML IdP for legacy Service Providers.

1. Understanding SSO.ID v2's Dual SAML 2.0 Capabilities

Mode A: Inbound SAML Federation (/connections)

External Enterprise IdP → SSO.ID (SP) → Your App

Your customer uses Okta, Azure AD, PingFederate, or ADFS. You create a SAML 2.0 Connection in /connections. SSO.ID acts as the SAML Service Provider (ACS: https://{your-tenant}.sso.id/auth/saml/acs).

Mode B: Outbound SAML IdP (/applications)

SSO.ID (IdP) → External or Legacy SAML SP App

Your application (or a third-party tool like Salesforce/Zendesk) requires a SAML 2.0 Identity Provider. You set the Application protocol to SAML 2.0 in /applications and point the SP to https://{your-tenant}.sso.id/auth/saml/metadata?appId={id}.

2. Step-by-Step: Creating a SAML 2.0 Connection in `/connections`

Download SSO.ID SP Metadata for Your Customer's IT Admin

Share SSO.ID's Service Provider metadata with your enterprise customer using GET https://{your-tenant}.sso.id/auth/Saml/SPMetadata or GET https://{your-tenant}.sso.id/api/connections/sp-metadata (and SP X.509 certificate via GET https://{your-tenant}.sso.id/api/connections/sp-certificate). The ACS URL is https://{your-tenant}.sso.id/auth/saml/acs.

Enter the Customer's IdP Entity ID, SSO URL & X.509 Certificate

In /connections → Add Connection → SAML 2.0, provide the external IdP's Entity ID (Issuer), Single Sign-On Service URL, Single Logout (SLO) URL, and PEM/Base64 X.509 Signing Certificate (or import their IdP Metadata XML).

Choose Binding (`HTTP-POST` vs. `HTTP-Redirect`) & Test Live

Select whether AuthnRequest messages use HTTP-POST or HTTP-Redirect (Deflate + Base64), map SAML Attribute Statements (emailaddress, givenname, surname, groups), and click Test Connection (POST /api/connections/test) to verify the end-to-end XML assertion signature before saving.

3. SAML 2.0 Security Controls & Single Logout (SLO)

XML Signature & Digest Verification: Enforces rsa-sha256 signature validation against the configured X.509 certificate, preventing XML Signature Wrapping (XSW) attacks.
Replay & Time-Window Protection: Validates assertion ID uniqueness, InResponseTo correlation, NotBefore, NotOnOrAfter, and AudienceRestriction.
Single Logout (SLO): Coordinated session termination across both SP and IdP via https://{your-tenant}.sso.id/auth/saml/logout (aliased at /saml/slo and /auth/saml/slo).

4. SAML 2.0 Endpoints & AI Agent Integration Prompt

Method	Endpoint	Description
GET	`https://{your-tenant}.sso.id/auth/saml/metadata?appId={appId}`	IdP Metadata XML for an Application configured with SAML 2.0 protocol.
GET	`https://{your-tenant}.sso.id/auth/saml/GetIDPMetadataBase64?appId={appId}`	Base64-encoded IdP Metadata XML for automated SDK/CLI configuration.
GET / POST	`https://{your-tenant}.sso.id/auth/Saml/Login`	IdP Single Sign-On endpoint accepting `SAMLRequest` and `RelayState`.
POST / GET	`https://{your-tenant}.sso.id/auth/saml/acs`	SP Assertion Consumer Service (ACS) receiving signed `SAMLResponse` assertions from external IdPs.
GET	`https://{your-tenant}.sso.id/auth/Saml/SPMetadata`	SP Metadata XML (`GET https://{your-tenant}.sso.id/api/connections/sp-metadata`).
GET / POST	`https://{your-tenant}.sso.id/auth/saml/logout`	SAML 2.0 Single Logout (SLO) endpoint.

AI Agent Prompt Implement a SAML 2.0 Service Provider (SP) Connected to SSO.ID v2

You are an enterprise authentication engineer. Implement a **SAML 2.0 Service Provider (SP)** in my application that authenticates against **SSO.ID v2** (`https://{your-tenant}.sso.id/auth`).

### SSO.ID v2 SAML 2.0 Identity Provider Endpoints
- **IdP Metadata XML URL**: `https://{your-tenant}.sso.id/auth/saml/metadata?appId=`
- **IdP SSO Login URL**: `https://{your-tenant}.sso.id/auth/Saml/Login` (Supports HTTP-Redirect and HTTP-POST)
- **IdP Single Logout (SLO) URL**: `https://{your-tenant}.sso.id/auth/saml/logout`
- **IdP X.509 Certificate**: `https://{your-tenant}.sso.id/api/applications/certificate?id=`

### Implementation Requirements
1. Configure our SAML SP with Entity ID (`spEntityId`), ACS Callback URL (`POST /saml/acs`), and dynamic metadata loading from `https://{your-tenant}.sso.id/auth/saml/metadata?appId=`.
2. Expose `GET /login/saml` to generate a signed `AuthnRequest` and redirect to `https://{your-tenant}.sso.id/auth/Saml/Login`.
3. Expose `POST /saml/acs` to verify the XML signature (`rsa-sha256`), validate `Audience` and timestamps, extract `NameID`, `emailaddress`, `givenname`, `surname`, and `role` claims, and issue an authenticated session.
4. Expose `GET /saml/metadata` so we can register our SP metadata in the SSO.ID Admin Console (`/applications`).