Repository navigation
docs: describe the OAuth2 provider API operations and parameters - #31516
Closed
nickvigilante wants to merge 2 commits into
Closed
nickvigilante wants to merge 2 commits into
nickvigilante wants to merge 2 commits into
Conversation
The REST API reference renders these routes from swagger.json, and they had no description. Part of DOCS-1439. Assisted-by: AI
Part of DOCS-1439. Assisted-by: AI
This was referenced Oct 29, 2026
Collaborator
Author
|
Combined into #31562, where this PR's changes are the commit Generated by Coder Agents on behalf of @nickvigilante. |
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
This PR adds a
@Descriptionto the 21 OAuth2 provider routes taggedEnterprise, and improves the thin parameter text on them.The REST API reference renders these routes from
swagger.json, and they had no description.doc-check
Fact Checker, Continuity Editor, Copy Editor, and Skeptic ran on the branch diff (author self-check).
Findings fixed in the follow-up commit:
PUT /api/v2/oauth2-provider/apps/{app}body text said omittingredirect_uriskeeps the stored URIs, but sendingcallback_urlalone replaces the first one (coderd/oauth2provider/apps.go:50).secretIDtext, and gave the pronouns in the token, revoke, register, authorize and delete-tokens text one clear referent.The Skeptic rejected 2 findings: "session" against "session token" (no rule separates them, and the route uses the session credential), and sentence length over 25 words (the style guide calls the budget a target, not a ceiling).
Left as non-blocking suggestions: the
404gate names only--oauth2-provider-enable, and the deployment option also takesCODER_OAUTH2_PROVIDER_ENABLE.Deterministic checks after the follow-up commit:
check_routes.py, both swagger tests, andmake lint/emdashpass.Merge notes
This PR doesn't touch #31473's exemption lists.
If #31473 merges first,
TestEndpointsDocumentednames each route on this PR to remove from those lists.Verification
A JSON diff of
swagger.jsonagainstorigin/mainchanges onlydescriptionvalues (42 leaves, all underpaths, all on the 21 routes).The six remaining thin parameters are the
apppath ID, which accepts only a UUID (ParseUUIDParamincoderd/httpmw/oauth2.go:461).Claims checked against the code
/api/v2/oauth2-provider/apps*,/oauth2/*,/.well-known/*404unless the OAuth2 provider is enabled with--oauth2-provider-enable(a deployment flag, not an experiment or license)coderd/coderd.go:1104,:1268,:1278,:1289,:2084;coderd/httpmw/oauth2provider.go:15;codersdk/deployment.go:2810enterprise/coderd/coderd.gohas noRequireFeatureMWor entitlement check for OAuth2GET /api/v2/oauth2-provider/settings,PUTcoderd/coderd.go:2105GET /api/v2/oauth2-provider/apps,GET .../apps/{app}coderd/rbac/roles.go:453;coderd/database/dbauthz/dbauthz.go:4601,:4667GET /api/v2/oauth2-provider/appsuser_idfilters to apps the user authorized, must be a UUID, and reading another user's needs the Owner rolecoderd/oauth2provider/apps.go:127,:138;dbauthz.go:4674POST,PUT,DELETEon appsdbauthz.go:6716,:8401,:2522;coderd/rbac/roles.go:414PUT /api/v2/oauth2-provider/apps/{app}iconclears itapps.go:290,:323,:331;codersdk/oauth2.go:122DELETE /api/v2/oauth2-provider/apps/{app}coderd/database/dump.sql:5794,:5800dbauthz.go:4634,:6731,:2541POST .../secrets400for a public clientcoderd/oauth2provider/app_secrets.go:60,:97DELETE .../secrets/{secretID}app_secrets.go:117GET .../settingsdbauthz.go:4580;coderd/rbac/roles.go:495PUT .../settingsPOST /oauth2/registeraccepts new clientsdbauthz.go:9744;coderd/oauth2provider/registration.go:69GET /oauth2/authorizecoderd/coderd.go:1122,:1300POST /oauth2/authorizecoderd/oauth2provider/authorize.go:826;coderd/coderd.go:1300POST /oauth2/tokenscoderd/coderd.go:1317;coderd/oauth2provider/tokens.go:197,:266POST /oauth2/tokensgrant_typeother thanauthorization_codeorrefresh_tokengivesunsupported_grant_typetokens.go:405,:446DELETE /oauth2/tokenscoderd/coderd.go:1314;coderd/oauth2provider/revoke.go:289,:297POST /oauth2/revoke200for an unknown token or one that belongs to another clientcoderd/coderd.go:1324;revoke.go:50,:149,:154GET /.well-known/oauth-authorization-serverregistration_endpointonly when dynamic client registration is oncoderd/coderd.go:1266;coderd/oauth2provider/metadata.go:44GET /.well-known/oauth-protected-resourcecoderd/coderd.go:1276;metadata.go:61POST /oauth2/register403unless dynamic client registration is enabled, and returns a registration access tokencoderd/coderd.go:1328;registration.go:69,:124/oauth2/clients/{client_id}coderd/coderd.go:1331;registration.go:539,:561PUT /api/v2/oauth2-provider/apps/{app}redirect_urisandcallback_urlkeeps the stored redirect URIscoderd/oauth2provider/apps.go:50,:290,codersdk/oauth2.go:122PUT /oauth2/clients/{client_id}redirect_urisregistration.go:335;codersdk/oauth2_validation.go:43Writing rules applied
@Descriptionline.dbauthzandcoderd/rbac/roles.go.enterprise/coderd/coderd.gogates these routes.@Securitysay they don't require a session token and name the credential they use.<,>,{, or}outside them.Annotation bugs noticed and left alone are in the report to the author, not this PR.
CI flakes unrelated to this change
test-go-pg (windows-2022)failedTestAPISessionRecoveryWriteDeadline/messageinagent/x/agentacp, a package this PR doesn't touch: https://github.com/coder/coder/actions/runs/40937618676/job/123672476795Part of DOCS-1439.
Generated by Coder Agents on behalf of @nickvigilante.