SAML Metadata & Certificate Rotation Monitor

Track public SAML 2.0 identity-provider federation metadata and X.509 certificate summaries between scheduled runs. Each target produces one structured dataset row with signing-certificate expiry health, persistent snapshot hashes, and review-oriented changes such as certificate additions/removals, SSO endpoint drift, entity changes, metadata-validity changes, and certificate-use changes.

This Actor is for identity/platform, SRE, MSP, and enterprise integration teams that depend on third-party SAML identity providers. It creates an independent change ledger that can feed Apify schedules, webhooks, and existing incident or vendor-management workflows.

It does not exercise a login, validate SAML assertions, rotate certificates, modify an IdP or service provider, prove trust, or guarantee uninterrupted SSO. Native provider notifications and maintained SAML libraries remain essential. The Actor parses published metadata over validated HTTPS but does not verify an XML digital signature.

Independent community Actor: This Actor is not affiliated with or endorsed by OASIS, Microsoft, Okta, Auth0, Google, Amazon Web Services, or any identity provider whose public metadata you monitor. Provider metadata remains the provider's source material; verify identity/security changes against provider documentation, your service-provider configuration, and live authentication telemetry.

Why monitor SAML metadata?

A scheduled independent record can help teams:

• see signing certificates approaching expiry before the next manual renewal window;
• notice certificate prepublication, replacement, or retirement in public metadata;
• review SSO/SLO endpoint, entity ID, protocol, NameID format, and signing-policy changes;
• track metadata validUntil alongside embedded certificate validity;
• keep a provider-independent history when a service provider's metadata cache is opaque;
• route changed, expiry-review, or error rows into existing Apify integrations.

A poll can miss transitions that happen entirely between checks. no_certificate_overlap_observed_between_checks therefore describes only the two sampled snapshots; it does not prove the provider never published an overlap.

Input

Field	Required	Description
monitorId	Yes	Stable ID for one independent watchlist. Reuse it across schedules to retain the same baselines.
targets	Yes	1–50 public HTTPS SAML metadata targets. Duplicate metadataUrl values are checked once.
targets[].metadataUrl	Yes	Public URL returning SAML 2.0 IdP federation metadata XML.
targets[].label	No	Internal environment, vendor, application, or owner label.
targets[].expectedEntityId	No	Exact IdP entityID to select and verify. It is required when a document contains multiple IdP entities.
warningDays	No	Expiry review window, 1–365 days (default 45).
timeoutSeconds	No	Per-request timeout, 5–60 seconds (default 30).
maxConcurrency	No	Targets processed concurrently, 1–5 (default 3).

The default input checks Microsoft's public Microsoft Entra common federation-metadata template without credentials, so a default run produces a non-empty dataset. It is an unofficial public QA target and contains placeholder tenant values; replace the default monitorId, URL, and entity ID with your own provider metadata before scheduling production checks.

{
  "monitorId": "production-saml-trust",
  "targets": [
    {
      "label": "Primary workforce IdP",
      "metadataUrl": "https://idp.example.com/saml/metadata",
      "expectedEntityId": "https://idp.example.com/saml/metadata"
    }
  ],
  "warningDays": 45,
  "timeoutSeconds": 30,
  "maxConcurrency": 3
}

Output

Every processed target emits one dataset row.

Successful comparison statuses

status	Meaning
initial_snapshot	The first validated IdP metadata/certificate summary was stored.
unchanged	Monitored metadata and certificate summaries match the prior successful snapshot.
changed	At least one monitored metadata or certificate field changed.

Non-billable errors

status	Meaning
metadata_fetch_error	The URL was blocked, unavailable, redirected unsafely, too large, or returned a network/HTTP error.
metadata_validation_error	XML was unsafe/malformed/oversized, lacked one selectable SAML 2.0 IdP entity or SSO endpoint, or contained invalid certificate data.

Common successful fields include:

• entity_id, metadata_url, final_metadata_url, and metadata_valid_until;
• normalized SSO/SLO endpoints, protocols, NameID formats, and want_authn_requests_signed;
• bounded certificate summaries with SHA-256 fingerprint, uses, subject/issuer, validity, key type/size, and signature OID;
• certificate_health, signing-certificate counts, nearest expiry, and days remaining;
• expired, expiring, or not-yet-valid signing-certificate fingerprint lists;
• content_hash, previous_hash, state_store_mode, and requirement status;
• added, removed, and retained certificate fingerprints;
• rotation_pattern, priority counts, change_summary, and bounded changes records.

certificate_health is healthy, review, expired, or no_signing_certificate. review includes certificates or metadata inside the configured warning window and signing certificates that are not yet valid. These are routing hints, not proof that a login is broken or a certificate is trusted by every service provider.

Rotation-pattern labels

• initial_snapshot / no_change — baseline or no monitored change.
• certificate_addition_or_prepublication — a certificate appeared and none disappeared.
• certificate_retirement — a certificate disappeared and none appeared.
• certificate_rotation_with_retained_certificate — certificates appeared and disappeared while at least one prior certificate remained.
• no_certificate_overlap_observed_between_checks — certificates appeared and disappeared with no shared fingerprint in the two sampled snapshots.
• certificate_usage_changed — a retained certificate's advertised signing/encryption use changed.
• metadata_only_change — monitored metadata changed without a certificate-set change.

review_priority values (high, review, informational) are conservative routing hints, not security findings or outage predictions.

Persistence and scheduling

Successful normalized snapshots are stored in the named key-value store saml-metadata-certificate-monitor-state-v1. The Actor does not rely on the default run-scoped store. Snapshot keys are SHA-256 derivatives of monitorId + metadataUrl, so stable IDs retain history and separate watchlists do not collide.

Schedule the Actor at a provider-appropriate interval and route changed, non-healthy, or error rows through Apify integrations. The Actor itself sends no email, DM, chat message, or webhook. Failed fetches and invalid documents do not overwrite a prior successful baseline.

Charging behavior

The implementation emits one saml_metadata_check charge event only after a public metadata document is fetched, safely parsed, normalized, compared, and stored. Invalid URLs, fetch failures, and validation failures are not charged. Refer to the live Store listing for the current event price. The Actor honors Apify run charge limits before emitting the next billed dataset item.

Security and data handling

• Production input accepts only public HTTPS endpoints on port 443.
• URL credentials, fragments, control characters, non-ASCII raw URLs, and non-standard ports are rejected.
• Redirects are bounded and every destination is revalidated.
• DNS is resolved before connecting; every answer must be globally routable. The socket connects to a validated address while TLS certificate validation and SNI still use the original host, reducing DNS-rebinding exposure.
• Private, loopback, link-local, multicast, and reserved destinations are blocked.
• Metadata is capped at 2 MB; compressed responses are rejected.
• XML is capped at 64 levels, 50,000 nodes, 100 entities, and 100 unique certificates. DTD/entity declarations and external entity expansion are rejected through defusedxml plus an explicit declaration check.
• Each decoded certificate is capped at 100 KB and parsed as DER X.509 with cryptography.
• Stored state contains normalized metadata and public-certificate summaries/fingerprints, not complete source XML or base64/DER certificate bodies.
• Published SSO/SLO URLs are recorded but never followed.
• No authentication header, cookie, secret, assertion, user record, private-network endpoint, or uploaded private key is supported.

Local development

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python smoke_test.py
npx --yes apify-cli validate-schema
npx --yes apify-cli run --purge

The deterministic smoke test uses a process-only local fixture mode and verifies:

1. initial_snapshot;
2. unchanged with named-store reuse;
3. changed after one certificate is replaced and the SSO endpoint changes;
4. added/removed/retained fingerprints and overlap classification;
5. production private-URL blocking, entity/DTD and deep-XML rejection, no-observed-overlap classification, and a one-event PPE charge limit.

Limitations

• Public metadata only; authenticated or private enterprise IdP endpoints are intentionally unsupported.
• Exactly one IdP entity must be selected. Set expectedEntityId for aggregate federation documents; documents above the entity/size bounds remain unsupported.
• The Actor validates transport TLS and safely parses XML but does not verify an XML digital signature or certificate chain trust.
• It does not fetch keys or URLs referenced from metadata beyond the metadata document itself.
• Certificate expiry is checked from embedded X.509 dates; a service provider may apply different trust or rollover rules.
• A scheduled snapshot cannot observe transitions that occur entirely between runs.
• Native IdP/service-provider expiry notifications and metadata refresh may already cover part of this workflow. This Actor adds an independent scheduled record; it does not replace or modify native behavior.