> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Configuring JWT Validation Timeouts in Spring Boot 4.0+

If you're using Spring Boot 4.0.0 or later and experiencing connection timeout errors when validating JWT tokens from Scalekit, you'll need to explicitly configure timeout values. This is a known issue affecting Spring Security's OAuth2 resource server configuration.

## The problem

Your Spring Boot application successfully configures the `issuer-uri` for JWT validation:

```yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.scalekit.com
```

But authentication fails with timeout errors like:

```
java.net.SocketTimeoutException: Connect timed out
  at org.springframework.security.oauth2.jwt.JwtDecoders.fromIssuerLocation
```

## Why this happens

Starting with Spring Boot 4.0.0, Spring Security changed how it handles HTTP connections during JWT validation:

- **Before 4.0.0**: Spring used default system timeouts (often much longer)
- **After 4.0.0**: Spring enforces strict, short timeout defaults that can be too aggressive for production

When your application starts or validates its first JWT token, Spring Security:

1. Fetches the OpenID Connect discovery document from `issuer-uri`
2. Retrieves the JWKS (JSON Web Key Set) to verify token signatures
3. Caches these for future validations

If these initial requests timeout, authentication fails completely.

## Who needs this fix

This issue specifically affects:

- ✅ Spring Boot applications version **4.0.0 or later**
- ✅ Using `issuer-uri` for JWT validation (not manual `jwk-set-uri`)
- ✅ Production environments with network latency or firewall rules
- ✅ Applications experiencing intermittent authentication failures

You **don't** need this if:

- ❌ Using Spring Boot 3.x or earlier
- ❌ Manually configuring `jwk-set-uri` instead of `issuer-uri`
- ❌ Already have custom `RestTemplate` or `WebClient` configurations

## The solution

For Spring Security servlet resource servers, there are no properties to configure JWT discovery/JWKS HTTP timeouts. Use a custom `JwtDecoder` bean with `RestOperations` (for example, `RestTemplate`) and explicit timeout values:

```java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.web.client.RestTemplate;

@Configuration
public class SecurityConfig {

    @Bean
    public JwtDecoder jwtDecoder() {
        // Create a RestTemplate with custom timeouts
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(10000);  // 10 seconds
        factory.setReadTimeout(10000);     // 10 seconds

        RestTemplate restTemplate = new RestTemplate(factory);

        // Use the custom RestTemplate for JWT validation
        return NimbusJwtDecoder
            .withIssuerLocation("https://auth.scalekit.com")
            .restOperations(restTemplate)
            .build();
    }
}
```

This gives you:
- Full control over HTTP client configuration
- Ability to add custom headers or interceptors
- Environment-specific timeout tuning (development: 5000ms, production: 10000–15000ms)

## Verifying the fix

After applying the configuration:

1. **Restart your application** - Spring Security initializes the JWT decoder on startup
2. **Test authentication** - Make a request with a valid Scalekit JWT token
3. **Check logs** - You should see successful JWKS retrieval:

```
DEBUG o.s.security.oauth2.jwt.JwtDecoder - Retrieved JWKS from https://auth.scalekit.com/.well-known/jwks.json
```

If you still see timeout errors:
- Verify network connectivity to `auth.scalekit.com`
- Check firewall rules allowing outbound HTTPS
- Increase timeout values if your network has high latency

## When to use standard Spring Security instead

This cookbook addresses a specific Spring Boot 4.0+ timeout issue. For general JWT validation setup:

- Follow the [Spring Security OAuth2 Resource Server documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html)
- Use Scalekit's standard Java SDK for token validation if not using Spring Security
- Consider the default `issuer-uri` configuration if you're not experiencing timeouts

## Related resources

- [Spring Security OAuth2 Resource Server - JWT Timeouts](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html#oauth2resourceserver-jwt-timeouts)
- [Scalekit API reference](/apis/#tag/authentication)
- [Spring Boot 4.0 Release Notes](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes)

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |