How to Fix Dex OIDC Discovery URL Error

In this tutorial, you'll learn about How to Fix Dex OIDC Discovery URL Error. We cover key concepts, practical examples, and best practices.

Dex OIDC discovery URL returns 404 Not Found or discovery failed: issuer did not match — the Dex issuer URL does not match the actual domain or the discovery endpoints are not configured.

The Problem

$ curl https://dex.example.com/.well-known/openid-configuration
404 Not Found

Step-by-Step Fix

Step 1: Set the correct issuer URL

# /etc/dex/config.yaml
issuer: https://dex.example.com
# Must match the actual URL where Dex is served
# No trailing slash

Step 2: Ensure web handler serves discovery

# Dex automatically serves these endpoints when issuer is set:
# /.well-known/openid-configuration
# /keys (JWKS)
# /token
# /auth
# /userinfo

Step 3: Test discovery URL

curl -v https://dex.example.com/.well-known/openid-configuration

Expected:

{
  "issuer": "https://dex.example.com",
  "authorization_endpoint": "https://dex.example.com/auth",
  "token_endpoint": "https://dex.example.com/token",
  "jwks_uri": "https://dex.example.com/keys",
  ...
}

Step 4: Check issuer mismatch

# The issuer in the discovery document MUST match the expected issuer
# If your app sends the wrong issuer, fix it in the app config

Step 5: Verify JWKS endpoint

curl https://dex.example.com/keys

Step 6: Configure proxy for Dex

# Nginx proxy must pass all Dex endpoints
location / {
    proxy_pass http://127.0.0.1:5556;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Prevention Tips

• Access Dex directly (not through a proxy) for initial testing
• Ensure issuer matches the browser URL exactly (protocol, host, port)
• Use https:// in the issuer URL when behind TLS
• Test the discovery URL before configuring clients

Common Mistakes with oidc discovery

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world DEX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ