SAML Federation

QNSP supports SAML 2.0 for enterprise SSO and authenticated identity linking.

Configuration

Register a SAML federation provider:

{
  "id": "saml-main",
  "provider": "saml",
  "name": "Example SAML IdP",
  "enabled": true,
  "metadata": {
    "entityId": "https://idp.example.com",
    "ssoUrl": "https://idp.example.com/sso",
    "certificate": "<certificate_pem_or_base64>"
  }
}

Flow

1. QNSP initiates a SAML flow against the configured provider and receives a signed assertion at its ACS endpoint.
2. QNSP validates:
   • XML signature
   • issuer
   • audience
   • recipient / destination
   • InResponseTo
   • replay protection
   • assertion time bounds with clock-skew tolerance
3. The validated assertion is processed by QNSP:

   POST /auth/federation/saml/acs
   {
     "providerId": "saml-main",
     "samlResponse": "<base64_assertion>",
     "relayState": "<optional_relay_state>",
     "linkMode": false
   }
   

4. QNSP either issues access + refresh tokens for sign-in or binds the SAML identity to the current authenticated QNSP user when linkMode=true.

Attribute mapping

Map SAML attributes to QNSP:

SAML Attribute	QNSP Attribute
NameID	External ID
email	Email
displayName	Display name
memberOf	Roles

SP metadata

QNSP exposes SP metadata at:

GET /auth/federation/:providerId/metadata?type=saml

Security

• Assertions must be signed
• Replay detection is enforced
• Audience, recipient, destination, and InResponseTo are validated
• Metadata refresh and certificate rollover are supported
• Encryption supported but optional