8000 Introduce traceId to freemarker attributes #34435 by sonOfRa · Pull Request #47338 · keycloak/keycloak · GitHub
[go: up one dir, main page]

Skip to content

Introduce traceId to freemarker attributes #34435 - #47338

Merged
ahus1 merged 1 commit into
keycloak:mainfrom
sonOfRa:freemarker-traceid
Mar 26, 2026
Merged

ahus1 merged 1 commit into
keycloak:mainfrom
sonOfRa:freemarker-traceid

Conversation

@sonOfRa
@sonOfRa sonOfRa commented Mar 20, 2026 •
Copy link
Copy Markdown
Contributor

This introduces a traceId attribute in the common freemarker attributes.

This allows any freemarker template to include the traceId. This is especially useful for error.ftl or custom error-templates, as it allows Keycloak admins to include a message like "When contacting support, please include this identifier in your message: TRACEID_HERE".

Possible additions to this PR:

  1. Also add the traceId in FreemarkerEmailTemplateProvider#processTemplate, so emails can include the trace as well
  2. Introduce a message key and introduce a default message to error.ftl in the base theme

Closes #44090
Closes #34435

@sonOfRa
sonOfRa requested a review from a team as a code owner March 20, 2026 14:22
@sonOfRa
sonOfRa force-pushed the freemarker-traceid branch 2 times, most recently from a9dc5b2 to 3c383ed Compare March 20, 2026 15:06
@ahus1
ahus1 commented Mar 21, 2026
Copy link
Copy Markdown
Member

Thank you for this PR. As usual, we need PRs to link to an issue. I found issue #44090 to link it, so consider this resolved.

If we want people to use it in their custom templates, it would need to be documented on the tracing page and the the page to customize themes, and maybe the error template should have a commented-out section that people could enable when they want to show that information.

In addition, it would be great to have a test for that - and it would be so much easier if it would be showing automatically on the error page. So I'd say I'm +1 for item (2), which is adding it by default to the error page. Once that's done, TracingDistTest might a please for a test?

Let's also hear from others what they think.

@ahus1
ahus1 commented Mar 21, 2026
Copy link
Copy Markdown
Member

One more comment: The trace ID might be considered user provided content, and we should ensure not to encode malicious content. Given that it is "32-character lowercase hexadecimal string representing a 16-byte value", I'd assume it is safe to reflect it to user. Happy to hear from other if they think differently.

@sonOfRa
sonOfRa commented Mar 22, 2026
Copy link
Copy Markdown
Contributor Author

Thanks for linking it to one of the issues, I'm used to an issue number being part of a commit message automatically linking an issue, so I forgot that that's necessary :)

In addition, it would be great to have a test for that - and it would be so much easier if it would be showing automatically on the error page. So I'd say I'm +1 for item (2), which is adding it by default to the error page. Once that's done, TracingDistTest might a please for a test?

maybe it would be a good idea to introduce a realm attribute (or a top level config flag?) along the lines of includeTraceIdInErrorTemplates so that users can opt in at the realm or keycloak level. If that flag is set, and the attribute is set in the freemarker context, we include a standard message like traceIdMessage=If contacting support, please include this identifier in your message: {0}. Either way (realm or config) would be fine with me, and both would yield themselves well for a test scenario

One more comment: The trace ID might be considered user provided content, and we should ensure not to encode malicious content. Given that it is "32-character lowercase hexadecimal string representing a 16-byte value", I'd assume it is safe to reflect it to user. Happy to hear from other if they think differently.

Personally, I've always assumed that the opentelemetry integration would reject inbound trace IDs that are not valid in some way. I've not personally verified it, but everything else just seems wrong, and I feel like I would have heard about CVEs with malicious trace IDs, if that was not the case. What remains is the potential DoS vector: If you accept trace IDs from the public internet without filtering, people can just always send 00000000000000000000000000000000 as a trace ID and confuse the tracing system. But that is, at least to me, outside the scope of this PR

Any opinion to also add the traceId to the freemarker context for emails? I don't really see a usecase for it to be included in any emails that Keycloak sends by default, but others may have use cases for their own custom email templates

@sonOfRa
sonOfRa force-pushed the freemarker-traceid branch from 3c383ed to 03b7569 Compare March 23, 2026 10:53
@sonOfRa
sonOfRa requested review from a team as code owners March 23, 2026 10:53
@sonOfRa
sonOfRa force-pushed the freemarker-traceid branch from 03b7569 to 3967c58 Compare March 23, 2026 11:03
@sonOfRa
sonOfRa commented Mar 23, 2026
Copy link
Copy Markdown
Contributor Author

I've added a small message template to error.ftl which contains the trace ID if it is present, as well as two test-cases to test for the presence (when tracing is enabled) as well as the absence (when tracing is disabled) of the message.

I did not add an additional flag to guard it, so for now, when tracing is enabled, and the theme is not changed, the message will always be displayed every time error.ftl is rendered and a valid trace context is available. I'm not sure if this is something that is wanted - if users don't want this part of the default template in their themes, they can always override it and not include the message in their theme.

I've also added a short paragraph on the tracing.adoc on how it can be used. Do you think it should be additionally also mentioned explicitly somewhere in themes.adoc?

@ahus1 ahus1 left a comment
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok to make this not configurable in the realm settings, but leaving it to be a theme configuration as IMHO it is ok for Keycloak to be reasonably opinionated.

See below for a suggested change to the docs.

Comment thread docs/guides/observability/tracing.adoc Resolved
@sonOfRa
sonOfRa force-pushed the freemarker-traceid branch from 3967c58 to 735d381 Compare March 26, 2026 11:30
Signed-off-by: Simon Levermann <github@simon.slevermann.de>
@sonOfRa
sonOfRa force-pushed the freemarker-traceid branch from 735d381 to 660f80e Compare March 26, 2026 11:30
@ahus1
ahus1 merged commit f4225b4 into keycloak:main Mar 26, 2026
84 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ErrorId for error screens and logging OTEL: Add tracing ID to user facing error message

2 participants

0