Fix OAuth Errors in Keycloak — Self-Hosted Setup

Updated April 2026

Keycloak errors look similar to other OAuth providers but the settings live in different places. Most issues come from wrong client type (public vs confidential), missing redirect URIs, or misconfigured realm settings.

Common Keycloak OAuth errors and fixes

Error: invalid_grant — code expired or reused

# Keycloak defaults — check in Realm Settings > Tokens
Authorization Code Lifespan: 1 minute (default)
# If your server-side exchange takes longer → increase to 5 minutes

# In admin console:
Realm Settings → Tokens → Authorization Code Lifespan → change to 5 minutes

Error: invalid_redirect_uri

# In Keycloak Admin Console:
Clients → Your Client → Settings → Valid Redirect URIs

# Must include every URL including:
https://yourapp.com/callback
https://yourapp.com/callback/  # with and without trailing slash
http://localhost:3000/callback  # for development

# Common mistake: using * wildcard
# Valid Redirect URIs: https://yourapp.com/*  ← too broad
# Correct: https://yourapp.com/callback ← exact match

Error: PKCE required / client not configured for PKCE

# For public clients (SPAs, mobile):
Clients → Your Client → Settings
→ Client authentication: OFF  (this makes it a public client)
→ Authentication Flow: Standard flow checked
→ Proof Key for Code Exchange (PKCE): S256 Method required

Error: Client secret invalid

# For confidential clients:
Clients → Your Client → Credentials → Regenerate Secret
# Copy the new secret to your application config

Correct client setup for a React SPA

# Keycloak Admin → Clients → Create client
Client ID: my-react-app
Client type: OpenID Connect
Client authentication: OFF  (public client)
Authentication flow: Standard flow ON, Direct access grants OFF
Valid redirect URIs: https://yourapp.com/callback
Valid post logout redirect URIs: https://yourapp.com
Web origins: https://yourapp.com  # required for CORS

Web Origins — Keycloak's CORS setting

Keycloak's Web Origins field controls which origins can make requests to the Keycloak token endpoint. If your SPA gets a CORS error on the token endpoint, add your frontend origin here:

Clients → Your Client → Settings → Web Origins
Add: https://yourapp.com

# Or use + to allow all Valid Redirect URI origins (development only)

Test token exchange

curl -X POST \ https://your-keycloak.com/realms/your-realm/protocol/openid-connect/token \ -d "client_id=my-react-app" \ -d "grant_type=authorization_code" \ -d "code=YOUR_CODE" \ -d "redirect_uri=https://yourapp.com/callback" \ -d "code_verifier=YOUR_VERIFIER"