What Is .well-known/openid-configuration? A Developer's Guide

• Google: https://accounts.google.com/.well-known/openid-configuration
• Microsoft: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
• Authgear: https://your-project.authgear.cloud/.well-known/openid-configuration

💡 Try it now: Use the Authgear OIDC Discovery Endpoint Explorer to fetch and inspect any provider's .well-known/openid-configuration — no curl, no command line. Enter an issuer URL and see the full document with a structured field summary.

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "scopes_supported": ["openid", "email", "profile"],
  "response_types_supported": ["code", "token", "id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "claims_supported": ["sub", "iss", "aud", "iat", "exp", "email", "name"]
}

# Fetch and pretty-print the discovery document
curl -s https://accounts.google.com/.well-known/openid-configuration | python3 -m json.tool

# Extract just the authorization endpoint
curl -s https://accounts.google.com/.well-known/openid-configuration | jq '.authorization_endpoint'

# Extract the JWKS URI
curl -s https://accounts.google.com/.well-known/openid-configuration | jq '.jwks_uri'

// Fetch the discovery document and extract endpoints
async function getOIDCConfig(issuerUrl) {
  const discoveryUrl = `${issuerUrl}/.well-known/openid-configuration`;
  const response = await fetch(discoveryUrl);

  if (!response.ok) {
    throw new Error(`Failed to fetch discovery document: ${response.status}`);
  }

  const config = await response.json();

  return {
    authorizationEndpoint: config.authorization_endpoint,
    tokenEndpoint: config.token_endpoint,
    jwksUri: config.jwks_uri,
    userinfoEndpoint: config.userinfo_endpoint,
    endSessionEndpoint: config.end_session_endpoint,
  };
}

// Usage
const config = await getOIDCConfig('https://your-project.authgear.cloud');
console.log(config.authorizationEndpoint);

import requests

def get_oidc_config(issuer_url):
    discovery_url = f"{issuer_url.rstrip('/')}/.well-known/openid-configuration"
    response = requests.get(discovery_url)
    response.raise_for_status()
    return response.json()

config = get_oidc_config('https://your-project.authgear.cloud')
print(config['authorization_endpoint'])
print(config['jwks_uri'])

• Provider changes break your app. If the provider changes an endpoint URL, your app breaks silently until someone notices.
• Multi-tenant apps need different config per tenant. Azure AD has a different URL per tenant. Without discovery, managing this is a hardcoded map. With discovery, you construct the URL dynamically from the tenant ID.
• JWKS rotation breaks token verification. Providers rotate signing keys. If you've hardcoded the public key, your token verification breaks after rotation. Fetching from jwks_uri — found in the discovery document — handles this automatically.

• The provider doesn't support OIDC Discovery — some older or custom identity systems don't publish a discovery document. You'll need to configure endpoints manually.
• Wrong issuer URL — the discovery URL is constructed from the issuer, so a wrong base URL means a 404. Check the provider's documentation for the exact issuer format (especially for Azure AD and Keycloak, which include tenant/realm segments).
• CORS restrictions — some providers restrict cross-origin access to the discovery endpoint. Browser-based fetches may fail even if curl works.
• Private or internal provider — the provider is not reachable from the public internet. This is expected for internal deployments.

• Inspect any provider's discovery document with the free OIDC Discovery Endpoint Explorer
• Learn about JWKS in What Is a JWKS URI? JWT Key Sets Explained for Developers