Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Keycloak token issuer does not match when the app runs in Docker

ErrorInvalid token issuer

Short 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.

  • Applies to Keycloak 26, Docker Compose 2, Spring Boot 3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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-configuration
  2. 2Match what you see, then jump to its fix

    1. 1The two discovery documents show different hostsNo explicit hostname is set, so Keycloak derives URLs from each requestFix
    2. 2Token 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. 3Settings look right but URLs still differYou need to see what Keycloak resolvesFix

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_HOSTNAME

2Fix

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:8080

3Verify

Fetch the discovery document again; the issuer should show the configured address.

curl -s http://localhost:8080/realms/myrealm/.well-known/openid-configuration

Confirmed by keycloak.org

Did this fix it?

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 50

2Fix

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-configuration

Confirmed by keycloak.org

Did this fix it?

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-debug

2Fix

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-debug

Confirmed by keycloak.org

Did this fix it?

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.