Resolving Connection Refused in Spring Security 5 OAuth2 with Keycloak in Docker

Learn how to fix "Connection Refused" issues when running a Spring Security 5 app with Keycloak in a Docker container by using reverse proxy settings and updating your configurations.
---
This video is based on the question https://stackoverflow.com/q/71158469/ asked by the user 'Sublett' ( https://stackoverflow.com/u/13164703/ ) and on the answer https://stackoverflow.com/a/71223524/ provided by the user 'Sublett' ( https://stackoverflow.com/u/13164703/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: Spring Security 5 OAuth2 App with Keycloack 17 gets "Connection Refused" when run in Docker container with docker-compose

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
Understanding the Connection Issue in Dockerized Spring Security App

If you're developing a Spring Boot application that uses Spring Security 5 for OAuth2 authentication with Keycloak and you face a Connection Refused error while running in Docker, you're not alone. This issue can arise from several misconfigurations, particularly when using docker-compose for container orchestration.

In this guide, we will walk through the cause of this problem and how to resolve it effectively.

The Problem

When your application works well locally but fails in Docker with the following error:

[[See Video to Reveal this Text or Code Snippet]]

This indicates that the application is trying to reach the Keycloak service using http://localhost, which is incorrect when running in a Docker container. Containers have their own network, and localhost refers to the container itself, not the host machine.

Cause of the Error

The primary issue is that within the Docker network, the services do not communicate with the host through localhost. Instead, they should refer to each other by the service name defined in the docker-compose.yml file or use the Docker Gateway IP.

Additional Factors

Service Isolation: Each Docker container has its own isolated network.

Incorrect Port Binding: Ports specified (like 80:8080) must match how the application accesses them.

Hardcoded URLs: Using localhost in your configuration can lead to confusion as it is not recognized in the Docker context.

Solution Steps

To mitigate the Connection Refused error, follow these steps:

Step 1: Update Application Configuration

Change the URLs in your application.yml from http://localhost to use the service name defined in your docker-compose.yml. For example:

[[See Video to Reveal this Text or Code Snippet]]

Step 2: Reverse Proxy Configuration

Adding a reverse proxy can help in directing traffic correctly between your application and Keycloak.

Step 3: Verify Docker Compose Setup

Make sure that your docker-compose.yml reflects the correct configuration:

[[See Video to Reveal this Text or Code Snippet]]

This way, when the application requests the Keycloak service, it should route through the defined internal port, avoiding the connection issues.

Step 4: Testing

After making these configuration changes, run your Docker containers again:

[[See Video to Reveal this Text or Code Snippet]]

Ensure that all services are healthy and the application logs don't show connection errors anymore.

Conclusion

By addressing the misconfigurations related to the localhost references and implementing a reverse proxy, you can successfully run your Spring Security 5 app with Keycloak in Docker without encountering a Connection Refused error. Should you run into further problems, always check your ports and network configurations as they remain common pitfalls in a containerized setup.

Happy coding!