> **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>`: `agent-auth`, `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

Configure explicit timeout values for the OAuth2 resource server's HTTP client. Spring Security provides configuration properties specifically for this:

```yaml
    spring:
      security:
        oauth2:
          resourceserver:
            jwt:
              issuer-uri: https://auth.scalekit.com
              # Configure timeouts for JWKS and discovery endpoints
              client:
                registration:
                  connect-timeout: 10000  # 10 seconds for connection
                  read-timeout: 10000     # 10 seconds for reading response
    ```
  ```properties
    spring.security.oauth2.resourceserver.jwt.issuer-uri=https://auth.scalekit.com
    # Configure timeouts for JWKS and discovery endpoints
    spring.security.oauth2.resourceserver.jwt.client.registration.connect-timeout=10000
    spring.security.oauth2.resourceserver.jwt.client.registration.read-timeout=10000
    ```
  ### Timeout values explained

- **connect-timeout**: Maximum time (in milliseconds) to establish a connection to Scalekit's servers
- **read-timeout**: Maximum time (in milliseconds) to wait for a response after connection is established

**Recommended values**:
- **Development**: 5000ms (5 seconds) for faster feedback
- **Production**: 10000-15000ms (10-15 seconds) to handle network variability

## Alternative: Programmatic configuration

If you need more control or want to configure this per-environment, use Java configuration:

```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 approach gives you:
- Full control over HTTP client configuration
- Ability to add custom headers or interceptors
- Environment-specific timeout tuning

## 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 Java SDK Documentation](https://docs.scalekit.com/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 |