Keycloak + oauth2-proxy; how to get "id_token_hint"

Question

I use keycloak with oauth2-proxy behind a nginx server. The complete authenication flow is handled by this free tools. So my Angular frondend and NestJS backend got the access-request-token in the request header, but the authentication is completly handled by oauth2-proxy and keycloak.

Now I need the id_token/id_token_hint. The only way to get this is to use the url: http://localhost:8080/realms/myrealm/protocol/openid-connect/token with the scope: openid. (For your information: I don't use grant_type authorization_code, because the complete authentication flow goes over keycloak + oauth2-proxy. My backend/frontend never send a login/auth request directly)

This works very well and I get a id_token. The problem: If I use this id_token for the keycloak (18+) logout process the logout confirm dialog will be shown. Problem: the request create a new keycloak client session.

Is it possible to get the id_token for a clients current session, without creating a new session?

Answer 1

As you mention in the comments, oauth2-proxy v7.6.0 now includes --backend-logout-url

It comes from PR #1876

Session aware logout, backend logout url approach

--backend-logout-url: URL to call to perform backend logout, {id_token} would be replaced by the actual id_token if available in the session

Your issue was the inability to access the id_token due to the authentication and session management being entirely handled by oauth2-proxy, which stands in front of the application and Keycloak. That arrangement made it difficult to perform actions that require the id_token, such as a session-aware logout from Keycloak, without initiating a new session or directly exposing the token to the client application.

The --backend-logout-url option allows specifying a URL that oauth2-proxy will call to initiate a backend logout process.
Key point: this URL can include a placeholder {id_token} which oauth2-proxy will automatically replace with the actual id_token from the current session. That dynamic substitution makes sure the correct token is used without exposing it more broadly or requiring it to be stored client-side.

Since oauth2-proxy manages session tokens (including refreshing and expiration), integrating the logout process through this tool makes sure logout requests are inherently aware of the session context. This matches oauth2-proxy's capabilities to manage and invalidate sessions as needed.

By handling token insertion and logout URL calls within oauth2-proxy, there is no need for the application to directly manage tokens or implement custom logic for session-aware logouts. That reduces the complexity within the application codebase and enhances security by minimizing the exposure of sensitive tokens.

The ability to specify a backend logout URL that includes the id_token allows for direct integration with various authentication providers (like Keycloak) and supports different logout mechanisms, including those requiring tokens for validation. That flexibility ensures broader compatibility and simplifies integration with existing authentication infrastructure.

---

Can you post an example of how to use --backend-logout-url with Keycloak?

Assuming a logout URL for your Keycloak realm, like "https://keycloak.example.com/auth/realms/{realm-name}/protocol/openid-connect/logout", when starting oauth2-proxy, you will include the --backend-logout-url option, formatted to include your Keycloak logout URL and the {id_token} placeholder. The {id_token} will be replaced by oauth2-proxy with the user's actual id_token at runtime.

Your oauth2-proxy startup command or configuration file would include:

--backend-logout-url="https://keycloak.example.com/auth/realms/{realm-name}/protocol/openid-connect/logout?id_token_hint={id_token}&post_logout_redirect_uri={post-logout-redirect-uri}"

With {post-logout-redirect-uri}: the URL to which you want users to be redirected after logout. That URI must be one of the allowed redirect URIs configured in your Keycloak client settings.

Make sure your Keycloak client is configured to accept the post-logout redirect URI you specified. That is done in the Keycloak admin console, under your client's settings, in the "Valid Redirect URIs" section.

And oauth2-proxy must be configured to store session information, including the id_token. That typically involves configuring session storage options like --cookie-secret and --session-store-type.

A more concrete example command for starting oauth2-proxy, including the hypothetical Keycloak logout URL and redirect:

oauth2-proxy \
  --cookie-secret=<your-secret> \
  --session-store-type=cookie \
  --provider=keycloak \
  --backend-logout-url="https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/logout?id_token_hint={id_token}&post_logout_redirect_uri=https://myapp.example.com/post-logout"

That would instruct oauth2-proxy to call Keycloak's logout endpoint, automatically including the id_token for the current session and specifying where the user should be redirected after logout.