Testing SSO Configuration — SSO Providers

Built-In SSO Test Endpoint

Passport provides a test endpoint that simulates the full SSO flow for a consumer without requiring the actual SP to be available. Use this to verify your consumer registration before setting up the real SP.

POST /passport/admin/consumers/{consumerKey}/test
Authorization: Bearer {admin-token}
Content-Type: application/json

{
  "testUserId": "user-guid-to-impersonate",
  "validateSignature": true,
  "protocol": "SAML2"
}

// Response — full decoded assertion
{
  "success": true,
  "protocol": "SAML2",
  "nameId": "user@example.com",
  "sessionIndex": "_abc123",
  "attributes": {
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "roles": ["manager", "finance-user"]
  },
  "assertionXml": "<saml:Assertion ...>...",
  "signatureValid": true,
  "warnings": []
}

SAML Tracer (Browser Extension)

The SAML Tracer browser extension (available for Chrome and Firefox) intercepts and decodes SAML messages in real time. Use it to inspect assertions during live SSO flows.

Install SAML Tracer

Install from the Chrome Web Store or Firefox Add-ons. The extension adds a toolbar button that turns orange when SAML messages are detected.

Open SAML Tracer Panel

Click the SAML Tracer button to open the panel. Keep it open during the SSO flow. All HTTP requests are listed — SAML messages are highlighted in orange.

Initiate SSO

Navigate to your SP's login page and click the "Sign in with BizFirstAI" button. The SAML AuthnRequest and SAMLResponse will both appear in the tracer.

Inspect the SAMLResponse

Click the POST to the ACS URL. In the SAML tab, you will see the decoded assertion XML. Verify: NameID value, attribute names, role values, NotOnOrAfter timestamp, and signature status.

OIDC Debugger

For OIDC testing, use the OIDC Debugger (oidcdebugger.com) or Passport's own introspection endpoint to validate tokens.

// Introspect an access token
POST /passport/token/introspect
Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJSUzI1NiJ9...

// Response
{
  "active": true,
  "sub": "user-guid",
  "client_id": "myapp-prod",
  "scope": "openid profile email roles tenant",
  "exp": 1748120400,
  "iat": 1748119500,
  "iss": "https://passport.bizfirst.ai",
  "email": "user@example.com",
  "roles": ["manager"],
  "tenant_id": "tenant-abc"
}

// Check JWKS for signature verification
GET /passport/.well-known/jwks.json
// Returns public keys — use jwt.io or a local verifier to validate signature

Common Configuration Errors

Error	Likely Cause	Fix
Assertion rejected — invalid signature	SP has old signing certificate	Re-import Passport metadata or update the certificate on the SP
Assertion rejected — expired	Clock skew > 60s between Passport and SP	Sync NTP on Passport and SP servers; or increase `assertionLifetimeSeconds`
Invalid redirect URI	URI in request doesn't exactly match registered URIs	Add the exact URI to consumer registration; check trailing slashes
Unknown consumer key	`consumerKey` not found or cache not cleared	Verify the key exists; call `/purge-cache` if recently created
Attribute missing in assertion	Attribute mapping references undefined user field	Check user profile has the field; verify mapping config uses correct source path
MFA required but user has no MFA enrolled	Consumer requires MFA; user hasn't set it up	Enroll MFA in user profile, or adjust consumer policy for gradual rollout
PKCE verification failed	`code_verifier` doesn't match `code_challenge`	Ensure code_verifier is the original value, not re-hashed; use SHA-256 base64url

Diagnostic API

// Get SSO event history for a consumer
GET /passport/admin/consumers/{consumerKey}/events
  ?limit=50&from=2026-05-25T00:00:00Z
Authorization: Bearer {admin-token}

// Response
{
  "events": [
    {
      "eventId": "evt-abc",
      "timestamp": "2026-05-25T10:00:00Z",
      "type": "SSOSuccess",
      "userId": "user-guid",
      "consumerKey": "salesforce-prod",
      "protocol": "SAML2",
      "durationMs": 45
    },
    {
      "eventId": "evt-def",
      "timestamp": "2026-05-25T10:01:00Z",
      "type": "SSOFailure",
      "reason": "AssertionExpired",
      "consumerKey": "salesforce-prod",
      "protocol": "SAML2"
    }
  ]
}

Checklist Before Go-Live

Run the admin test endpoint and verify all attributes are present and correctly mapped
Use SAML Tracer / OIDC Debugger to verify the live flow in a staging environment
Confirm clock synchronization between Passport and the SP
Test Single Logout from both directions (SP-initiated and IdP-initiated)
Test MFA step-up if configured
Verify the consumer cache purge works as expected
Review the diagnostic event log for any errors after initial test logins

← MFA in SSO Flows