Skip to content

Document enrichment webhooks and key paths for RADIUS reply attributes - #581

Open
JoeWagstaff wants to merge 4 commits into
mainfrom
joe/webhook-keypath-docs
Open

JoeWagstaff wants to merge 4 commits into
mainfrom
joe/webhook-keypath-docs

Conversation

@JoeWagstaff

@JoeWagstaff JoeWagstaff commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Describe your changes:

The RADIUS webhook section of the wireless tutorial covered authorization webhooks only and said that Smallstep support configures them. This PR extends it to cover enrichment webhooks and the key path added to the console in smallstep/web#3177.

tutorials/protect-wireless-networks.mdx

  • Renames "RADIUS authorization webhooks" to "RADIUS webhooks" and explains the two types, authorization and enrichment.
  • Rewrites "Configuring a RADIUS webhook in Smallstep" for the self-serve console flow: type, name (no dots), URL, authentication, signing secret.
  • Adds "Reply attributes from an enrichment webhook":
    • how a key path selects a value from the data object of the webhook response, with examples for nested keys and list indexes
    • how to set a webhook value in the console and with the API (valueFromWebhook: "<webhook name>.<key path>")
    • what happens when the webhook returns no value, and how to add a static fallback rule
    • returning attributes directly in data.replyAttributes
  • Corrects the request reference: the body includes clientIP, the timestamp is RFC 3339, and the signing secret is base64 and must be decoded before computing the HMAC.

tutorials/protect-wired-networks.mdx

  • Mentions both webhook types and links the VLAN step to the new section.

Checked against the implementation

The second commit corrects the section against bouncer, gateway and the console: where the signing secret can be read, which webhooks receive clientIP, required authentication and HTTPS, what a failed enrichment webhook does to reply attributes, and that requests are not retried.

To confirm before merge

  • What the connecting device sees when an enrichment webhook fails. Bouncer returns no reply attributes at all in that case, which the docs now say. Whether FreeRADIUS then accepts the connection without attributes or rejects it has not been tested end to end. The console copy says "A 5xx response is ignored", which does not match.
  • The heading rename changes the anchor to #radius-webhooks. The console links to #radius-authorization-webhooks, so the old id is kept with a <span id> above the heading. Check on the preview that the old anchor still scrolls to the section.
  • Whether customers can add webhooks themselves in every environment yet, or whether the "contact support" fallback should stay more prominent.

Related links/other PRs/issues:

smallstep/web#3177, PRO-675, PRO-676. PRO-677 (the API reference still describes valueFromWebhook as a webhook UUID) is still open.

🤖 Generated with Claude Code

The RADIUS webhook reference covered authorization webhooks only and
said that Smallstep support configures them. It now covers both webhook
types, how to add one in the console, and how a reply attribute rule
takes its value from an enrichment webhook response with a key path.

Also corrects the request reference: the body includes clientIP, the
timestamp is RFC 3339, and the signing secret is base64 and must be
decoded before computing the signature.

Change-Type: docs
Release-Note: no
Audience: user, admin
Impact: none
Breaking: false
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

A review against bouncer, gateway and the console found statements
that did not match the code:

- The console shows signing secrets only when a RADIUS server is
  created. Document the API route for a webhook added later.
- clientIP is sent to enrichment webhooks only, and is the address of
  the network equipment.
- Webhook authentication is required and the URL must use HTTPS.
- A failed enrichment webhook drops every configured reply attribute,
  so a static fallback rule does not cover it.
- Smallstep does not retry a failed webhook request.

Also states that data must be an object, that replyAttributes is a
reserved key, which rules are ignored without an error, and keeps the
old #radius-authorization-webhooks anchor that the console links to.

Change-Type: docs
Release-Note: no
Audience: user, admin
Impact: none
Breaking: false
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
thauber
thauber previously approved these changes Nov 19, 2026

@thauber thauber left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

I had one question, but it's not blocking. Looking pretty good.


If `replyAttributes` is present, it must be an array of objects with a `name` and a `value`.
Any other shape makes the whole response invalid.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Do enriching reply attrs overwrite the radius rules reply attrs or the other way around? Or does it cause an error?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

there shouldn't be an error on our side, I guess it might be an issue depending on specific equipment might handle it. Pushed a small change to make the wording more explicit

A reviewer asked whether reply attribute rules override the
attributes an enrichment webhook returns in replyAttributes, or the
other way around. Neither does: bouncer appends the webhook's
attributes after the rule attributes without removing duplicates, so
both values reach the network equipment.

Change-Type: docs
Release-Note: no
Audience: user, admin
Impact: none
Breaking: false
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@JoeWagstaff
JoeWagstaff marked this pull request as ready for review November 19, 2026 20:34
@JoeWagstaff
JoeWagstaff requested a review from a team as a code owner November 19, 2026 20:34
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.

3 participants