Using Keycloak as a Reverse Proxy for 3rd Party API Authentication

Keycloak does not function as a generic reverse proxy for authenticating outbound requests to third-party APIs. Instead, it acts as an identity provider that issues tokens via OAuth 2.0 or OpenID Connect. To authenticate server-to-server calls, your application must act as an OAuth client, obtain an access token from Keycloak, and include it in the API request headers.

Understanding the Architecture

The core misunderstanding in many architectural diagrams is treating Keycloak as a network-level proxy like Nginx or HAProxy. Keycloak is a software-based Identity Provider (IdP). It manages users, realms, clients, and roles. When you need to call a third-party API, your backend service (the "client") needs proof of identity. Keycloak provides this proof by issuing JSON Web Tokens (JWTs) after validating credentials. This approach separates concerns. Your application logic handles business rules, while Keycloak handles authentication and authorization. This pattern is known as the Authorization Code Grant flow or the Client Credentials Grant flow, depending on whether there is an interactive user involved. For pure server-to-server communication, the Client Credentials Grant is the standard choice because it requires no human interaction. You can read more about managing user sessions in Trigger Automatic Logins/Logouts for Users on Multiple Websites Connected with Keycloak, which shares underlying session management concepts relevant to token lifecycle handling.

Configuring the Client in Keycloak

Before writing code, you must configure Keycloak to recognize your application as a trusted client. This involves creating a new client within the appropriate Realm. Navigate to the Clients section in the Admin Console and select Create. Enter a Client ID that identifies your application, such as my-backend-service. Set the Client Type to OpenID Connect. The most critical setting here is the Access Type. For server-to-server authentication, set the Access Type to Confidential. This ensures that the client secret is kept secure on your server and not exposed to browsers or mobile devices. Next, configure the Valid Redirect URIs. While this field is primarily used for browser-based flows, some implementations require at least one entry to pass validation. You can use https://localhost as a placeholder if no UI redirect is needed. Ensure that the Standard Flow is disabled if you are strictly using the Client Credentials grant, although leaving it enabled does not harm security in this context. Save the configuration. Note down the Client ID and generate a new Secret. These two values are required for your application to authenticate with Keycloak's token endpoint.

Implementing Token Acquisition

Your backend service must now implement the logic to request an access token. This is typically done using an HTTP POST request to the Keycloak token endpoint. The URL format is generally /realms/{realm-name}/protocol/openid-connect/token. The request body must contain several parameters:

• grant_type: Set this to client_credentials for server-to-server auth.
• client_id: The ID you created in the previous step.
• client_secret: The secret generated for that client.
• scope: Optional. Specify the resources or permissions your API needs.

If you are using a language like Java or Python, libraries exist to handle this automatically. For example, Spring Security provides auto-configuration for Keycloak. If you are using raw HTTP, ensure you handle the response correctly. A successful response returns a JSON object containing the access_token, refresh_token, and expiration time. It is crucial to cache these tokens. Requesting a new token for every single API call introduces latency and increases load on Keycloak. Implement a simple cache with a TTL slightly shorter than the token's expiration time. When the token expires, refresh it silently before making the next request. For deeper insights into connecting your application infrastructure, see Troubleshooting Java Connect Exception: Connection Refused in Docker Compose Spring Boot Keycloak, which addresses common networking issues when your app talks to Keycloak.

Using the Token with the Third-Party API

Once you have the access token, passing it to the third-party API is straightforward. Most modern APIs expect authentication via the HTTP Authorization header. Construct the header value as Bearer {access_token}. Example cURL command:

curl -X GET https://api.thirdparty.com/data \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ensure that the third-party API accepts JWTs signed by Keycloak. Some APIs require specific claims within the token, such as a custom audience claim or a specific scope. You may need to configure Mappers in Keycloak to inject these claims into the token payload. Go to the Client settings in Keycloak, select Mappers, and add a new mapper to include necessary attributes.

Security Best Practices

Never expose the client secret in frontend code or version control. Store it in environment variables or a secrets manager. Use HTTPS everywhere. Keycloak should be configured to enforce TLS, and your internal services should validate certificates if they are self-signed during development. Regularly rotate your client secrets. Keycloak allows you to regenerate secrets without downtime. Update your application configuration immediately after rotation. Monitor Keycloak logs for failed login attempts, which could indicate brute-force attacks against your client credentials.

Frequently Asked Questions

Can I use Keycloak as a direct HTTP proxy?

No, Keycloak is not designed to forward HTTP traffic like Nginx or Apache. It processes authentication protocols and returns tokens. You must use a separate reverse proxy if you need load balancing or SSL termination for your API endpoints.

What happens if the Keycloak server goes down?

Your application will fail to obtain new tokens. If you have cached valid tokens, existing requests might succeed until they expire. However, once all cached tokens expire, your service will stop functioning until Keycloak is restored.

How do I handle token expiration gracefully?

Implement a retry mechanism. When the third-party API rejects a request with a 401 Unauthorized error, invalidate the local token cache, fetch a fresh token from Keycloak, and retry the original request.

Can I restrict API access to specific users?

Yes, but this requires the Authorization Code Grant flow instead of Client Credentials. In that case, the user logs in interactively, and the resulting token contains their user identity and roles, which your API can check before granting access.

Why am I getting a 401 error from Keycloak?

This usually means the client ID or secret is incorrect, or the realm name in the token URL is wrong. Verify your credentials in the Keycloak Admin Console and ensure the URL matches the exact realm identifier.