Spring Boot OAuth2 Client: Preventing Startup Failures When OAuth Host is Unreachable

Introduction

Spring Boot's spring-boot-starter-oauth2-client is widely used to implement OAuth2 authentication in microservices. However, one common issue developers face is that their application fails to start if the OAuth host (identity provider) is unreachable. This can be frustrating, especially in environments where external services might be temporarily unavailable.

In this blog, we'll explore why this happens, how it affects your application, and most importantly, how to prevent it while maintaining secure authentication.

---

The Problem

When using spring-boot-starter-oauth2-client, Spring Boot attempts to fetch the OAuth2 provider’s metadata (discovery document) at startup. If the OAuth server is down or unreachable, the application throws an exception and fails to start.

Example Error

java.net.UnknownHostException: authorization-server.com
    at java.base/java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:220)
    ...
Caused by: org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://authorization-server.com/.well-known/openid-configuration"

This issue is particularly problematic in CI/CD pipelines, local development, or when deploying to cloud environments where network instability is common.

---

Why Does This Happen?

Spring Boot’s spring-security-oauth2-client automatically tries to fetch the issuer’s metadata during startup by default. The metadata endpoint (e.g., https://authorization-server.com/.well-known/openid-configuration) provides details like authorization and token endpoints, scopes, and supported authentication methods.

If the server is unreachable, the application does not have enough information to proceed, leading to a startup failure.

---

Solution: Lazy Initialization of OAuth2 Client

To prevent startup failures, we can configure Spring Boot to lazily initialize the OAuth2 client. This ensures that the application starts even if the OAuth server is down, and it only attempts metadata retrieval when authentication is actually needed.

1. Disable Auto-Configuration for OAuth2 Client

One way to defer metadata retrieval is to disable the default spring-security-oauth2-client auto-configuration.

spring.security.oauth2.client.provider.myprovider.issuer-uri=optional://authorization-server.com

Setting an invalid or optional URI prevents Spring from making an HTTP request at startup.

2. Use Static Configuration Instead of Discovery

Instead of relying on Spring Boot to fetch OAuth2 metadata dynamically, manually configure the OAuth2 endpoints in application.yml:

spring:
  security:
    oauth2:
      client:
        registration:
          myclient:
            client-id: my-client-id
            client-secret: my-secret
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          myprovider:
            authorization-uri: https://authorization-server.com/oauth/authorize
            token-uri: https://authorization-server.com/oauth/token
            user-info-uri: https://authorization-server.com/userinfo
            jwk-set-uri: https://authorization-server.com/oauth/jwks

This approach ensures that Spring Boot doesn’t need to call the OAuth server at startup.

3. Enable Lazy Initialization

Another approach is to configure lazy initialization for Spring Security beans. This allows the application to start without immediately initializing OAuth2 clients.

Add this in application.properties:

spring.main.lazy-initialization=true

Or configure it in SpringBootApplication:

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(MyApplication.class);
        app.setLazyInitialization(true);
        app.run(args);
    }
}

4. Custom Exception Handling for OAuth Failures

You can wrap your OAuth client calls in a try-catch block to handle failures gracefully at runtime:

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientService authorizedClientService) {

    DefaultOAuth2AuthorizedClientManager manager =
            new DefaultOAuth2AuthorizedClientManager(
                    clientRegistrationRepository, authorizedClientService);

    manager.setAuthorizedClientProvider(clientProvider -> {
        try {
            // Custom logic to handle failures
            return clientProvider.authorize(null);
        } catch (Exception e) {
            System.out.println("OAuth2 Client Initialization Failed: " + e.getMessage());
            return null; // Handle failure gracefully
        }
    });
    return manager;
}

---

Conclusion

Spring Boot’s default behavior of fetching OAuth2 metadata at startup can cause failures if the OAuth host is unreachable. However, by implementing lazy initialization, using static configurations, and handling errors properly, you can ensure that your application starts reliably in all environments.

Would you like more insights on Spring Security and OAuth2? Drop a comment below!