docs: neutralise vendor comparisons in comments - #737
Merged
Conversation
Named products now appear only as illustrative examples of a pattern, never as a benchmark Authorizer is measured against. Comparative framing dates badly the moment another vendor changes behaviour, and it belongs in positioning material rather than in source comments. - Audience-binding comments explain why binding a machine token to its target API matters, instead of citing which vendors mandate it. - Trusted-issuer default is justified by its cost (an API round-trip per authentication), not by matching another server's default. - FGA model described by its own role/group/permission shape. - Perf checklist argues from reproducibility rather than a footprint claim. - IdP references normalised to "e.g. ..." so they read as examples. Comment- and docs-only: every changed Go line is a comment.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Several comments named other IdP vendors as a benchmark rather than as an
illustration — "what Auth0's required
audienceparameter and Keycloak'saudience mappers provide", "same as Keycloak default", "competing on lighter
than Keycloak". That framing dates badly (it is wrong the moment another vendor
changes behaviour), and it puts positioning language into source comments where
an engineer wants the reason, not the scoreboard.
Named products are kept — they are genuinely useful for orientation — but only
in example form.
Changes
internal/token/auth_token.goaudienceparameter and Keycloak's audience mappers provide"token_grant_hardening_test.goaudiencemandatory…; this is the equivalent"resourceas the standards-track spellinginternal/storage/schemas/trusted_issuer.goMIGRATION.mdperf/README.mdAlso normalised bare slash-lists to explicit example form so they cannot be read
as claims —
(Okta/Entra/ADFS)becomes(e.g. Okta, Entra, ADFS)insaml_sp.go,oauth_sso.go,scim_endpoint.go,authorize.goandtoken.go.Left alone deliberately
Auth0 doc links in
authorize.go, and the CHANGELOG's "(Auth0 compatibility)"note on base64url padding tolerance — that is literally why the code exists.
.claude/research/machine-client-authz-landscape.md— an explicitly headedcompetitive-landscape brief, doing exactly its job.
Verification
Comment- and docs-only. Mechanically confirmed that every changed Go line is a
comment:
go build,make lint-go(0 issues), and the touched packages(
internal/token,internal/storage/schemas,internal/http_handlers) all pass.