Keycloak token issuer does not match when the app runs in Docker
Invalid token issuerShort answer
Keycloak builds token and discovery URLs from the hostname it is reached with. In Docker the browser reaches it as localhost while a backend container uses a service name, so the two sides see different addresses. Set one full public hostname, and enable dynamic backchannel URLs for internal calls.
Fix it fast
1Find out which cause you have
Open the realm's discovery document through the address the browser uses and through the address the backend uses. Compare the issuer and endpoint URLs in the two answers.
curl -s http://localhost:8080/realms/myrealm/.well-known/openid-configuration docker compose exec api curl -s http://keycloak:8080/realms/myrealm/.well-known/openid-configuration2Match what you see, then jump to its fix
- 1
The two discovery documents show different hostsNo explicit hostname is set, so Keycloak derives URLs from each requestFix - 2
Token verification from inside the network fails or hits an address that is not reachableContainers call Keycloak on an internal name, but the hostname is fixed to the public oneFix - 3
Settings look right but URLs still differYou need to see what Keycloak resolvesFix
- 1
What does the error look like?
Invalid token issuer
Cause 1 of 3
No explicit hostname is set, so Keycloak derives URLs from each request
1Check
Without a full hostname URL, scheme, port and path are resolved from the request, so tokens and endpoints follow whichever address the caller used.
docker compose exec keycloak env | grep KC_HOSTNAME2Fix
Set the hostname option to the address your users and token consumers must see, as a full URL.
services:
keycloak:
environment:
KC_HOSTNAME: http://localhost:80803Verify
Fetch the discovery document again; the issuer should show the configured address.
curl -s http://localhost:8080/realms/myrealm/.well-known/openid-configurationConfirmed by keycloak.org
Cause 2 of 3
Containers call Keycloak on an internal name, but the hostname is fixed to the public one
1Check
Backend URLs (token, userinfo, JWKS) default to the same value as the front-channel URLs. For apps that reach Keycloak over a private network, Keycloak has a dynamic backchannel option; it needs hostname as a full URL.
docker compose logs keycloak | tail -n 502Fix
Keep the public hostname for the issuer and let backchannel URLs follow the internal request.
environment:
KC_HOSTNAME: https://auth.example.com
KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"3Verify
From the app container, request the discovery document using the internal name; backend endpoints should use that name while the issuer stays the public one.
docker compose exec api curl -s http://keycloak:8080/realms/myrealm/.well-known/openid-configurationConfirmed by keycloak.org
Cause 3 of 3
You need to see what Keycloak resolves
1Check
Keycloak has a debug page for hostname settings. It is off by default.
# add KC_HOSTNAME_DEBUG=true, restart, then open /realms/myrealm/hostname-debug2Fix
Enable the debug page, read the URLs it reports, correct hostname or the proxy headers, then turn it off again.
environment:
KC_HOSTNAME_DEBUG: "true"3Verify
Open the debug page for the realm and compare it with the discovery document.
curl -s http://localhost:8080/realms/myrealm/hostname-debugConfirmed by keycloak.org
How do I stop it coming back?
- Set one full hostname URL for every environment and use it as the issuer in the resource server.
- Never switch hostname-strict off in production unless your proxy overwrites the Host header.
- Turn off the hostname debug page after use.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Security
Keycloak blocks your single-page app with a CORS error
Request requires preflight, which is disallowed to follow cross-origin redirects.
Keycloak checks the Origin header of a browser call against the Web origins configured on that client and refuses it with 403 when it does not match.
2 causes, each with a fixWeb apps
Playwright cannot open a headed browser on a Linux server or in Docker
npx playwright test --headed shows no window on a Linux server
A headed browser needs a display, and a Linux server or container has none.
3 causes, each with a fixWeb apps
React dev server in Docker does not reload when you save a file
Changes appear only after docker compose restart or a rebuild
File-change events often do not cross from your host into a container, so the dev server never notices the edit.
3 causes, each with a fixWeb apps
npm install fails with 'sh: node-gyp-build: command not found'
npm error command failed
A package's install script calls node-gyp-build by name.
2 causes, each with a fixWeb apps
T3 Env stops the build with Invalid environment variables
Error: Invalid environment variables
T3 Env validates process.env against your Zod schema when the app starts or builds, and stops on the first failure.
4 causes, each with a fixWeb apps
Vite cannot find an entry point to scan in Docker or CI
Could not auto-determine entry point from rollupOptions or html files
Vite scans your .html files, or the input you configure, to find what to pre-bundle.
3 causes, each with a fix