Dex IdP SAML Connector Authentication Error Sentinel

Automates continuous health and security surveillance of Dex identity provider (IdP) authentication connectors. Audits Prometheus login telemetry to detect SAML 2.0 assertion signature mismatches, expired identity provider signing certificates, and elevated user login failure spikes across enterprise single sign-on (SSO) infrastructure.

How it works

1. Automated Scheduled Sweep: The schedule trigger initiates a surveillance cycle every 15 minutes to inspect Dex identity provider telemetry endpoints.
2. Metric Extraction: An isolated Python task scrapes Prometheus metrics from the Dex service interface, extracting successful and failed login counters.
3. Failure Ratio Calculation: Calculates the exact percentage of user authentication attempts that resulted in errors over the lookback window.
4. Security Boundary Gate: Compares observed failure percentages against configured enterprise tolerance margins (default 5%).
5. Incident Notification: Emits formatted Slack alerts to IAM security channels with exact connector identifiers, failure rates, and error totals.
6. Manifest Publication: Outputs a structured machine-readable JSON object recording authentication telemetry for security compliance logs.

Architecture diagram

flowchart TD
    A[periodic_dex_audit Schedule Trigger] --> B[scan_dex_auth_metrics Python Script]
    B --> C[evaluate_auth_error_threshold Flowable If]
    C -- Failure Rate Breached --> D[notify_slack_iam_ops Slack Webhook]
    C -- Authentication Nominal --> E[log_nominal_dex_state Core Log]
    D --> F[emit_audit_manifest Debug Return]
    E --> F

Architecture components

• Trigger (periodic_dex_audit): Automated cron trigger executing regular surveillance sweeps across identity provider instances.
• Inspection Task (scan_dex_auth_metrics): Dockerized Python runtime interrogating Dex Prometheus metrics with connection timeout protections.
• Evaluation Gate (evaluate_auth_error_threshold): Conditional branching logic separating transient single-user password errors from systematic IdP failures.
• Notification Action (notify_slack_iam_ops): Formatted Slack webhook message delivering actionable telemetry and remediation runbooks.
• Manifest Return (emit_audit_manifest): Standardized JSON output recording exact run parameters for compliance and audit reporting.

Key capabilities

• SAML Certificate Expiration Early Warning: Detects systemic authentication breakdowns immediately when upstream Okta, Azure AD, or PingFederate SAML signing certificates rotate or expire.
• Brute-Force & Credential Stuffing Detection: Flags abnormal surges in failed authentication attempts across specific enterprise connectors.
• Zero-Touch Execution: Operates agentlessly by polling standard Dex Prometheus metrics endpoints over internal Kubernetes service networks.
• Deterministic Statistical Thresholds: Normalizes error counts against total authentication volume to prevent false alarms during off-peak hours.

What you get

• Pre-built sentinel protecting workforce and customer single sign-on portals from unmonitored authentication blackouts
• Isolated Docker execution environment with explicit network timeout safeguards preventing stalled workflow runs
• Real-time Slack notifications detailing exact connector names, failure percentages, and counts
• Standardized audit trail supporting SOC2 access management and identity governance compliance

Who it's for

• Identity and Access Management (IAM) Engineers managing enterprise Dex, Keycloak, or Okta SSO integrations
• Security Operations Engineers investigating authentication anomalies and credential stuffing incidents
• Kubernetes Platform Engineers managing Dex as an OIDC authentication gateway for cluster API servers

Why orchestrate this with Kestra

• Centralizes identity health monitoring without maintaining custom alerting scripts or cron daemon containers
• Encrypts sensitive notification webhooks and cluster access tokens using enterprise namespace secrets
• Provides historical execution archives to satisfy compliance auditors requiring proof of continuous authentication monitoring
• Enables automated multi-system remediation such as opening Jira incident tickets or failing over to secondary IdP connectors

Use cases

• Upstream IdP Signing Certificate Rotation: Detect when corporate Okta or Ping Identity SAML signing certificates rotate without updating Dex connector CA bundles.
• Kubernetes OIDC Login Outage Detection: Identify when cluster developers and operators are unable to authenticate to kubectl via Dex OIDC gateways.
• Credential Stuffing Wave Identification: Flag sudden surges in failed login attempts directed at workforce authentication endpoints.

Inputs

Name	Type	Default	Description
dex_metrics_url	STRING	http://dex.auth.svc.cluster.local:5558/metrics	Base HTTP URL exposing Prometheus metrics for the Dex identity provider service.
connector_id	STRING	okta-saml-enterprise	Identifier of the configured Dex SAML 2.0 connector under surveillance.
max_auth_failure_rate	FLOAT	5.0	Maximum allowable percentage of failed SAML authentications within the audit window before alerting.
lookback_minutes	INT	15	Time duration in minutes across which Dex authentication metrics are evaluated.
alert_on_failure	BOOL	true	Toggle whether Slack alerts are dispatched upon detecting elevated SAML authentication failures.

Expected outputs

• {{ outputs.scan_dex_auth_metrics.vars.failure_rate_percent }}: Percentage of total login attempts that resulted in authentication failures.
• {{ outputs.scan_dex_auth_metrics.vars.failed_logins_count }}: Cumulative count of rejected login attempts during the polling window.
• {{ outputs.scan_dex_auth_metrics.vars.successful_logins_count }}: Total number of successful authentications recorded by the connector.
• {{ outputs.scan_dex_auth_metrics.vars.is_alerting }}: Boolean flag indicating whether observed failure rates breached tolerance ceilings.
• {{ outputs.scan_dex_auth_metrics.vars.audit_timestamp }}: ISO-8601 UTC timestamp recording exact time of sentinel verification.

Prerequisites

• Dex identity provider deployed with Prometheus telemetry enabled on port 5558 (e.g., telemetry: { http: 0.0.0.0:5558 }).
• Network connectivity allowing Kestra worker pods to reach the Dex metrics endpoint over the internal cluster network.
• Incoming Slack Webhook configured with publishing permissions into the designated IAM operations channel.

Secrets

• SLACK_WEBHOOK_URL: Enterprise secret string containing the authenticated Slack webhook endpoint.

Quick start

1. Register the SLACK_WEBHOOK_URL secret within the target Kestra namespace.
2. Import this blueprint into Kestra under the company.security namespace.
3. Update dex_metrics_url with your internal Dex service DNS name.
4. Execute a manual run to verify metric collection and webhook formatting.
5. Enable the periodic_dex_audit trigger to establish automated continuous surveillance.

Common pitfalls and troubleshooting

• Telemetry Port Configuration: Dex requires explicit configuration of the telemetry listener in config.yaml; verify telemetry.http is bound to 0.0.0.0:5558.
• SAML Assertion Encryption: If your IdP encrypts SAML assertions, verify that Dex has access to the matching private decryption key.
• Clock Skew Tolerances: SAML authentications fail if server clocks differ by more than a few seconds; verify NTP synchronization on host nodes.
• Connector Label Dimensions: Ensure Prometheus metric labels match the configured connector identifier when monitoring multi-connector deployments.

How to extend

• Automated Certificate Refresh: Trigger a sub-flow to fetch and update the upstream IdP metadata XML URL when signature errors are detected.
• PagerDuty Escalation: Escalate to PagerDuty high-urgency incident pipelines if login failure rates exceed 25% during peak business hours.
• User Account Lockout Digest: Cross-reference failed login IP addresses with threat intelligence feeds to identify targeted employee accounts.

Links

• Kestra Python Script Plugin Documentation
• Kestra Slack Plugin Documentation
• Dex Identity Provider Telemetry Reference
• Dex SAML 2.0 Connector Configuration Guide
• SAML 2.0 Security Assertions Specification