Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Spring Security fails to resolve the issuer configuration for a JWT or Keycloak

Errorjava.lang.IllegalArgumentException: Unable to resolve the Configuration with the provided Issuer of "http://localhost:8080/realms/demo"

Short answer

Spring Security fetches the issuer's discovery document before it can validate tokens. The error means every discovery URL answered 4xx, or the server could not be reached at all. Open the three discovery URLs with curl, correct the issuer-uri, or switch to jwk-set-uri.

  • Applies to Spring Boot 3.5, Spring Security 6.5, Keycloak 26, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Call the discovery URLs the library tries, from the same host or container as the app. The one that returns JSON tells you what the issuer-uri should be.

    curl -i https://idp.example.com/realms/demo/.well-known/openid-configuration
    curl -i https://idp.example.com/.well-known/openid-configuration/realms/demo
    curl -i https://idp.example.com/.well-known/oauth-authorization-server/realms/demo
  2. 2Match what you see, then jump to its fix

    1. 1All three URLs return 404, and the error has no nested causeThe issuer-uri is wrong or points at a path with no discovery documentFix
    2. 2The error has a nested cause such as connection refused, a timeout or an unknown hostThe issuer cannot be reached from where the app runsFix
    3. 3The app fails to start if the identity server is down, even though it normally starts without itA JwtDecoder bean calls the issuer at startupFix

What does the error look like?

  • java.lang.IllegalArgumentException: Unable to resolve the Configuration with the provided Issuer of "http://localhost:8080/realms/demo"
  • The identity server is up but the Spring app fails on the first token

Cause 1 of 3

The issuer-uri is wrong or points at a path with no discovery document

1Check

The library tries the issuer plus /.well-known/openid-configuration, then the RFC 8414 form with the issuer path after the well-known part, then /.well-known/oauth-authorization-server. When every attempt gives a 4xx, it throws this message without a cause.

grep -rn "issuer-uri" src/main/resources/

2Fix

Set issuer-uri to the exact value of the iss claim the server puts in its tokens, with no trailing path that the server does not serve.

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/realms/demo

3Verify

Restart and call a protected endpoint with a token.

curl -i -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/me

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The issuer cannot be reached from where the app runs

1Check

A network failure or a non-4xx response stops the search at the first URL and is wrapped in this message. Check the host name from the same machine or container that runs the app.

curl -i http://idp:8080/realms/demo/.well-known/openid-configuration

2Fix

Use an address the app can reach. When the app cannot ask the issuer at all, give it the key location directly and keep issuer-uri only for checking the iss claim.

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/realms/demo
          jwk-set-uri: http://idp:8080/realms/demo/protocol/openid-connect/certs

3Verify

Start the app, then send a request with a valid token. The decoder is built lazily, on the first request that carries a JWT.

curl -i -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/me

Confirmed by docs.spring.io

Did this fix it?

Cause 3 of 3

A JwtDecoder bean calls the issuer at startup

1Check

JwtDecoders.fromIssuerLocation contacts the discovery endpoint as soon as it is called, so declaring it in a @Bean method couples startup to the server. The property-based setup defers discovery to the first request with a JWT.

grep -rn "fromIssuerLocation" src/main/java

2Fix

Use the property setup, or build the decoder from a known JWK Set URI so no discovery call is made.

@Bean
JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
}

3Verify

Stop the identity server and start the app; it should start.

./mvnw -q spring-boot:run

Confirmed by docs.spring.io

Did this fix it?

How do I stop it coming back?

  • Copy the issuer from a real token's iss claim instead of typing it.
  • Test discovery URLs with curl from inside the container or pod that runs the app.
  • Prefer the property setup so the app does not depend on the identity server being up at boot.

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

Next step

Want this handled for good?

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