Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Common Issues

Server Connection Issues

“Connection refused” or timeouts

  1. Check server health: curl -k https://auth.example.com/health
  2. Check DNS resolution: dig auth.example.com
  3. Check TLS: openssl s_client -connect auth.example.com:443
  4. Check firewall rules (port 443 must be accessible)

SCIM Provisioning Issues

User not de-provisioned

  • Verify the SCIM bearer token is valid and not expired
  • Check the SCIM audit log for errors
  • Confirm the IdP is sending DELETE requests to the correct endpoint

SCIM token rejected

  • Tokens are shown once at creation and cannot be retrieved after
  • Generate a new token via the admin API (POST /api/v1/org/scim-tokens) and update the IdP configuration

Identity Provider Issues

“Failed to fetch upstream OIDC discovery document”

  1. Verify the configured VOUCH_IDP_<SLUG>_ISSUER is correct and reachable: curl -s $VOUCH_IDP_<SLUG>_ISSUER/.well-known/openid-configuration | jq .issuer
  2. Check that the issuer URL uses HTTPS (HTTP is only allowed for localhost)
  3. Ensure the server can make outbound HTTPS requests (check firewall/proxy)

“Issuer mismatch” during OIDC discovery

  • The issuer field in the discovery document must exactly match VOUCH_IDP_<SLUG>_ISSUER (trailing slashes matter)
  • Some providers require a trailing slash (e.g., Auth0: https://tenant.auth0.com/)
  • Entra /organizations/v2.0 is special-cased — its {tenantid} template issuer is accepted
  • Entra /common/v2.0 is rejected at startup; use /organizations/v2.0 or a single-tenant URL (see Microsoft Entra ID)

“Failed to fetch SAML IdP metadata”

  • Verify the configured VOUCH_IDP_<SLUG>_METADATA_URL is correct and reachable
  • Check that the URL returns XML, not an HTML login page
  • Ensure the server can make outbound HTTPS requests

SAML signature verification errors

  • Confirm the IdP’s signing certificate in the metadata is current and not expired
  • Ensure the server clock is synchronized via NTP — SAML assertions have time-based validity windows (typically 5 minutes of skew tolerance)
  • Check the IdP assertion signing algorithm matches what the server expects

Enrollment broken after upgrade, and only the old VOUCH_OIDC_* / VOUCH_SAML_* env vars or S3 oidc / saml blocks are set

  • The flat legacy variables and S3 blocks are no longer read by the server — they are silently ignored. Migrate to the unified VOUCH_IDPS + VOUCH_IDP_<SLUG>_* env vars (or the S3 idps array). See IdP Overview for the full mapping.

“Duplicate IdP slug”

  • Every entry in VOUCH_IDPS / idps[].id must be unique. Rename one of them.

Debug Logging

Enable verbose logging for troubleshooting:

# Server
RUST_LOG=debug vouch-server

For component-specific logging:

RUST_LOG=vouch_server=debug

Getting Help