[Bug]: Logout failing witch "Missing parameters: id_token_hint" when using Keycloak

[ahlund]

Installation Method

Local Installation

The Problem

Using Keycloak, when trying to log out I get an error message from Keycloak: "Missing parameters: id_token_hint".

Version of Stirling-PDF

0.46.2

Last Working Version of Stirling-PDF

No response

Page Where the Problem Occurred

No response

Docker Configuration

Relevant Log Output

From Keycloak:

2025-05-28 14:01:19,818 WARN  [org.keycloak.events] (executor-thread-8) type="LOGOUT_ERROR", realmId="xxxxxx-xxxx-xxxx-xxxx-xxxxxxx", realmName="MyRealm", clientId="null", userId="null", ipAddress="123.123.123.123", error="invalid_request", reason="Either the parameter 'client_id' or the parameter 'id_token_hint' is required when 'post_logout_redirect_uri' is used."
2025-05-28 14:01:19,819 WARN  [org.keycloak.protocol.oidc.endpoints.LogoutEndpoint] (executor-thread-8) Either the parameter 'client_id' or the parameter 'id_token_hint' is required when 'post_logout_redirect_uri' is used.

From Stirling-PDF:

2025-05-28 14:01:19,755 INFO s.s.S.c.s.CustomLogoutSuccessHandler [qtp125246542-22] Redirecting to Keycloak logout URL: https://hello.example.com/realms/MyRealm/protocol/openid-connect/logout?client_id=&post_logout_redirect_uri=https://hello.example.com:443/login?logout=true

Additional Information

Notice that the client_id is empty. This might be the problem.

The server is running:

• Debian 13
• Java v21
• Apache as proxy
• Keycloak 26.2.5 (different server)

Browsers Affected

No response

No Duplicate of the Issue

• I have verified that there are no existing issues raised related to my problem.

[dosubot]

Hi @ahlund! I'm Dosu and I’m helping the Stirling-PDF team.

The error from Keycloak—"Missing parameters: id_token_hint"—happens because the logout URL generated by Stirling-PDF is missing both the client_id and the id_token_hint parameters. According to the OpenID Connect standard and Keycloak's requirements, at least one of these must be present when using post_logout_redirect_uri.

Your Stirling-PDF logs show that client_id is empty in the logout URL. This strongly suggests that the Keycloak OAuth2 configuration in Stirling-PDF is missing the clientId value or it is not being picked up correctly.

To resolve this, check your Stirling-PDF configuration file (typically /configs/settings.yml or similar) and ensure the following section is present and correctly filled out:

security:
  enableLogin: true
  loginMethod: oauth2
  oauth2:
    client:
      keycloak:
        issuer: "https://hello.example.com/realms/MyRealm"
        clientId: "<YOUR_CLIENT_ID>"
        clientSecret: "<YOUR_CLIENT_SECRET>"
        scopes: "openid, profile, email"

Make sure to replace <YOUR_CLIENT_ID> and <YOUR_CLIENT_SECRET> with the actual values from your Keycloak client configuration. The issuer should point to your Keycloak realm's OpenID Connect Discovery endpoint. The scopes should include at least openid, profile, email as recommended in the documentation (source).

After updating and saving the configuration, restart Stirling-PDF. This should ensure that the client_id is included in the logout URL, which will satisfy Keycloak's requirements and resolve the logout error.

If you continue to see issues, double-check that the configuration file is being loaded correctly and that there are no typos or indentation errors.

There are currently no known bugs or open issues in the Stirling-PDF repository related to this specific logout problem or the id_token_hint parameter. If the problem persists after verifying your configuration, it may be worth reviewing the Keycloak client settings to ensure the client is properly configured for OIDC and logout flows.

To reply, just mention my name @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[ahlund]

If there is a problem with the security settings then it would not be possible to login, right?

I have no problem logging in, only logging out.

[dosubot]

You're correct that if there were a general problem with your security or OAuth2 settings, you would likely not be able to log in at all. The fact that login works means your basic OAuth2 configuration (client ID, secret, issuer, etc.) is valid for authentication.

However, the logout process in OpenID Connect (and with Keycloak) has additional requirements that are not needed for login. Specifically, when using post_logout_redirect_uri, Keycloak expects either a valid client_id or an id_token_hint parameter in the logout URL. If these are missing or empty, Keycloak will reject the logout request—even if login works fine.

In your logs, the logout URL generated by Stirling-PDF is missing both parameters (the client_id is empty and there is no id_token_hint). This is a separate flow from login, and it is possible for login to work while logout fails if the application does not correctly pass these parameters during logout.

Based on available documentation, there are no Stirling-PDF settings that specifically control only the logout process or these parameters—logout handling appears to rely on the same OAuth2 configuration as login, but the implementation may not be passing all required values for logout in your version. This is why you see the error only during logout, not login.

If your configuration already has the correct clientId set and login works, this may be a limitation or bug in how Stirling-PDF constructs the logout URL for Keycloak. There is no documentation or open issue addressing this specific logout parameter handling in Stirling-PDF at this time (source).

In summary: login and logout use related but distinct flows, and it's possible for one to work while the other fails if the application does not handle the logout parameters required by Keycloak.

To reply, just mention my name @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[ahlund]

Here is the problem. I set the clientId in:

security:
  oauth2:
    client:
      keycloak:
        clientId: myclientid # client ID for Keycloak OAuth2

However, there is another setting for clientId in:

security:
  oauth2:
    clientId: '' # client ID for Keycloak OAuth2

It seems that the first setting is used for logins but the second one is used for logout. Setting the correct clientId in both places fixes the problem which, in my opinion, is a settings file parsing bug.

[Ludy87]

@DarioGii could that be the problem?

Stirling-PDF/src/main/java/stirling/software/SPDF/config/security/CustomLogoutSuccessHandler.java

Line 149 in 2217cfb

+ oauth.getClientId()