# SAML 2.0 SSO Integration Diagram & Specifications This document provides a comprehensive technical reference for the SAML 2.0 Identity Provider (IdP) integration. It includes sequence diagrams, an endpoint directory, and data flow models detailing request/response payloads, service responsibilities, and cryptographic boundaries. --- ## End-to-End SSO Authentication Flow Below is the complete sequence diagram detailing how a user authenticates into **Microsoft Teams / Outlook** via this Laravel SSO Identity Provider. ```mermaid sequenceDiagram autonumber actor User as User Browser participant MS as Microsoft Entra ID
(Service Provider) participant IdP as Laravel SSO Portal
(Identity Provider) participant DB as Database %% Step 1-3: SP Redirection User ->> MS: 1. Access Microsoft Teams/Outlook (e.g. user@company.com) MS ->> MS: 2. Detect company.com is federated to Laravel SSO Portal MS ->> User: 3. Redirect with SAMLRequest & RelayState (HTTP-Redirect) %% Step 4: Access SSO Endpoint User ->> IdP: 4. Request /saml/sso?SAMLRequest=...&RelayState=... %% Step 5-6: Auth Check & Interception alt User is NOT Authenticated IdP ->> IdP: 5a. Save SAMLRequest & RelayState to Session IdP ->> User: 5b. Redirect to /login User ->> IdP: 5c. User inputs credentials (Fortify login) IdP ->> DB: 5d. Authenticate user IdP ->> User: 5e. Redirect to /dashboard (ResolveDashboardRouteController) Note over IdP, User: ResolveDashboardRouteController intercepts session,
detects saml_pending_request, redirects back to /saml/sso User ->> IdP: 5f. Request /saml/sso (Authenticated) else User IS Authenticated Note over User, IdP: Immediately proceed to Step 6 end %% Step 7: Parse and Retrieve IdP ->> DB: 6. Match SAML Issuer (SP Entity ID) against ConnectedApps DB -->> IdP: Return Connected App metadata & SAML configurations %% Step 8-11: Response Generation Note over IdP: App\Services\SamlIdpService
1. Build SAML Response XML
2. Retrieve User email & immutable_id
3. Cryptographically sign Assertion node using idp.key IdP ->> IdP: 7. Base64 encode signed SAML XML IdP ->> IdP: 8. Clear SAML pending request from session IdP -->> User: 9. Render post_response.blade.php with hidden auto-submitting form %% Step 12-14: Microsoft ACS Callback User ->> MS: 10. POST SAMLResponse & RelayState to Microsoft ACS URL Note over MS: 1. Validate XML Signature against IdP public certificate (idp.crt)
2. Map SAML NameID claim to user's ImmutableId MS -->> User: 11. Grant secure access to Microsoft Teams & Outlook! ``` --- ## SAML 2.0 Endpoint Directory This table maps all endpoints involved in the SAML 2.0 integration, including input values, controller and service responsibilities, and outputs. | Endpoint | HTTP Method | Request Inputs / Parameters | Internal Service Called | Core Responsibility | Response Output | |:---------------------|:---------------|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------| | **`/saml/metadata`** | `GET` | *None* | `App\Services\SamlIdpService@generateMetadata` | Generates the IdP's official SAML 2.0 XML metadata descriptor to share signing certificates and SSO endpoints with external systems. | `200 OK` (XML payload)
`Content-Type: application/xml` | | **`/saml/sso`** | `GET` / `POST` | `SAMLRequest` (base64/deflated)
`RelayState` (optional redirect URL) | `App\Services\SamlIdpService@parseRequest`
`App\Services\SamlIdpService@findConnectedApp`
`App\Services\SamlIdpService@generateResponse` | - Decodes and parses SAMLRequest.
- Matches Issuer (Entity ID) to an active SAML Connected App.
- Redirects guests to `/login` with session preservation.
- Intercepts authenticated sessions to build and sign SAML XML assertions. | `200 OK` (renders redirect view) or `302 Redirect` to `/login` | | **`/dashboard`** | `GET` | *Session Cookie* | `App\Helpers\DashboardRoute` | Intercepts successful post-login routing. If the session holds a pending SAML request, redirects the browser back to `/saml/sso`. | `302 Redirect` to `/saml/sso` (if pending) or dashboard routes | --- ## Data Mapping & Cryptographic Flow Here is the step-by-step overview of how the Laravel Identity Provider translates local user attributes into a cryptographically signed assertion accepted by Microsoft: ``` [Local Database] [Cryptographic Signing] User: Private Key: storage/app/saml/idp.key ├── email: user@company.com Public Cert: storage/app/saml/idp.crt └── immutable_id: user-123-immutable │ │ ▼ │ (Maps to) ┌───────────────────────────┐ ▼ │ XMLSecLibs RSA-SHA256 │ ┌─────────────────────────────┐ │ Signs │ │ SAML Assertion Claims │────────>│ Moves node │ │ - NameID: persistent │ │ before for │ │ - IDPEmail: user@company │ │ schema validation. │ │ - mail: user@company │ └───────────────────────────┘ │ - upn: user@company │ │ └─────────────────────────────┘ ▼ ┌───────────────────────────┐ │ Base64-encoded Payload │ │ SAMLResponse = PHNhb... │ └───────────────────────────┘ ``` ### Claim & Attribute Mapping Details Microsoft Entra ID maps the incoming assertion elements exactly to the cloud user directory: - **`saml:NameID` (persistent format)**: Directly maps to the user's **`ImmutableId`** (configured locally in the admin panel or auto-generated deterministically as the base64-encoded user ID). - **`IDPEmail` / `upn` claims**: Map to the user's **`UserPrincipalName`** (the email address used for login inside Microsoft 365, e.g. `user@company.com`).