ADR-0002: SAML Metadata Ingestion

• Status: Proposed
• Date: 2026-01-27
• Author: @digiwedge/engineering

Context

Enterprise tenants require SAML 2.0 single sign-on. To configure SSO, we must ingest and validate IdP metadata (entity ID, SSO endpoints, signing certificates). Metadata changes over time (certificate rotation, endpoint updates), so ingestion must be repeatable and auditable.

We need a standard ingestion approach that works across multiple IdPs and supports both self-serve and assisted onboarding.

Decision

Support two metadata ingestion modes with a shared canonical representation:

1. URL Fetch (preferred)

   • Store the metadata URL.
   • Fetch immediately on save and parse into canonical fields.
   • Re-fetch on a fixed schedule (e.g., every 6 hours) and on demand.

2. Manual Upload (fallback)

   • Accept XML uploads for IdPs without accessible metadata URLs.
   • Persist the raw XML for traceability.
   • Parse into the same canonical fields used by URL fetch.

Canonical fields include:

• idp.entityId
• idp.ssoUrl
• idp.sloUrl (optional)
• idp.signingCertificates[]
• idp.binding (HTTP-Redirect or HTTP-POST)
• idp.nameIdFormat (optional)

Validation Rules

• Metadata must include EntityDescriptor and IDPSSODescriptor.
• At least one signing certificate is required.
• Reject unsupported bindings or missing SSO URLs.

Consequences

Positive

• Consistent onboarding flow across IdPs.
• Scheduled refresh reduces drift from cert rotations.
• Canonical representation simplifies runtime validation.

Negative

• Requires a background job for periodic refresh.
• Manual uploads increase support overhead.

Alternatives Considered

Alternative	Pros	Cons	Why not chosen
Manual upload only	Simple to implement	High support load, no automatic updates	Not scalable
URL fetch only	Easy to automate	Some IdPs cannot host metadata URLs	Blocks enterprise onboarding
Store raw XML only	Minimal parsing logic	Harder to validate, brittle runtime parsing	Operational risk

Follow-ups

• Implement metadata fetch job with retry + alerting
• Add UI support for upload and validation errors
• Add audit events for metadata changes