Prometheus Exporter to monitor SAML2.0 metadata and Signing Certificate expiry
426
Tag: spgreen/saml_multi_target_exporter:20251021
A multi-target Prometheus exporter for monitoring the validity and expiry of SAML 2.0 metadata files.
The SAML Multi-Target Exporter is a Python-based tool designed to monitor the validity of SAML 2.0 metadata files from multiple URLs. It follows the "multi-target exporter" pattern, similar to the official Blackbox exporter. This means you run a single instance of the exporter as a Docker container, and Prometheus instructs which SAML URL to probe during each scrape.
This image is ideal for SREs, DevOps engineers, and administrators who need to proactively monitor SAML federation metadata to prevent outages caused by expired certificates or metadata.
The exporter runs as a web server on port 8000 within the container. To run it, map this port to a port on your Docker host.
docker run -d \
--name saml-exporter \
-p 8000:8000 \
spgreen/saml_multi_target_exporter:20251021
The container is now running and ready to accept probe requests from Prometheus.
You must configure a Prometheus job to use the exporter. This involves listing your SAML endpoints as targets and using relabel_configs to direct the scrapes to the exporter container.
Add the following job to your prometheus.yml file:
scrape_configs:
- job_name: 'saml_metadata'
# Scrape the exporter on its /probe endpoint
metrics_path: /probe
# A list of all the SAML metadata URLs you want to monitor
static_configs:
- targets:
- https://idp.example.com/FederationMetadata/2007-06/FederationMetadata.xml
- https://sp.another-service.net/saml/metadata
# This section transforms the targets above into valid scrape requests for our exporter
relabel_configs:
# Step 1: Take the target address (the SAML URL) and use it as the 'target' URL parameter for the probe
- source_labels: [__address__]
target_label: __param_target
# Step 2: Set the 'instance' label in Prometheus to the SAML URL for readability
- source_labels: [__param_target]
target_label: instance
# Step 3: Rewrite the scrape address (__address__) to point to the exporter container
- target_label: __address__
# IMPORTANT: Replace this with the IP/hostname of your Docker host and the mapped port
replacement: 'docker-host-ip:8000'
After adding the configuration, reload your Prometheus instance.
The exporter provides the following three metrics for each target URL:
| Metric Name | Labels | Description |
|---|---|---|
| saml_metadata_probe_success | url | Returns 1 if the probe was successful, 0 if it failed (e.g., network error, parsing error). |
| saml_metadata_expiry_seconds | url | The number of seconds until the validUntil attribute in the metadata expires. A negative value means it has already expired. |
| saml_signing_cert_expiry_seconds | url | The number of seconds until the embedded X.509 signing certificate expires. A negative value means it has already expired. |
You can use the exposed metrics to create alerting rules in Prometheus.
groups:
- name: saml_metadata_alerts
rules:
- alert: SamlMetadataProbeFailed
expr: saml_metadata_probe_success == 0
for: 5m
labels:
severity: critical
annotations:
summary: "SAML metadata probe failed for {{ $labels.instance }}"
- alert: SamlMetadataExpiringSoon
expr: saml_metadata_expiry_seconds < (14 * 86400) # 14 days
for: 1h
labels:
severity: warning
annotations:
summary: "SAML metadata for {{ $labels.instance }} will expire in less than 14 days."
- alert: SamlSigningCertificateExpiringSoon
expr: saml_signing_cert_expiry_seconds < (30 * 86400) # 30 days
for: 1h
labels:
severity: critical
annotations:
summary: "SAML signing certificate for {{ $labels.instance }} will expire in less than 30 days."
Content type
Image
Digest
sha256:e9ccbff0e…
Size
26.8 MB
Last updated
11 months ago
docker pull spgreen/saml_multi_target_exporter