Skip to content

Commit 870e5eb

Browse files
committed
feat(oauth2): add authorization server metadata endpoint and PKCE support
- Add /.well-known/oauth-authorization-server metadata endpoint (RFC 8414) - Implement PKCE support with S256 method for enhanced security - Add resource parameter support (RFC 8707) for token binding - Add OAuth2-compliant error responses with proper error codes - Fix authorization UI to use POST-based consent instead of GET redirects - Add comprehensive OAuth2 test scripts and interactive test server - Update CLAUDE.md with OAuth2 development guidelines Database changes: - Add migration 000341: code_challenge, resource_uri, audience fields - Update audit table for new OAuth2 fields OAuth2 provider remains development-only (requires --dev flag). Change-Id: Ifbd0d9a543d545f9f56ecaa77ff2238542ff954a Signed-off-by: Thomas Kosiewski <tk@coder.com>
1 parent 1b1d091 commit 870e5eb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+2866
-272
lines changed

.claude/settings.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"permissions": {
3+
"allow": [],
4+
"deny": [
5+
"mcp__go-language-server__edit_file"
6+
]
7+
}
8+
}

.mcp.json

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"mcpServers": {
3+
"go-language-server": {
4+
"type": "stdio",
5+
"command": "go",
6+
"args": [
7+
"run",
8+
"github.com/isaacphi/mcp-language-server@latest",
9+
"-workspace",
10+
"./",
11+
"-lsp",
12+
"go",
13+
"--",
14+
"run",
15+
"golang.org/x/tools/gopls@latest"
16+
],
17+
"env": {}
18+
}
19+
}
20+
}

CLAUDE.md

Lines changed: 165 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,22 @@
22

33
Read [cursor rules](.cursorrules).
44

5+
## Quick Start Checklist for New Features
6+
7+
### Before Starting
8+
9+
- [ ] Run `git pull` to ensure you're on latest code
10+
- [ ] Check if feature touches database - you'll need migrations
11+
- [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`
12+
13+
## Development Server
14+
15+
### Starting Development Mode
16+
17+
- Use `./scripts/develop.sh` to start Coder in development mode
18+
- This automatically builds and runs with `--dev` flag and proper access URL
19+
- Do NOT manually run `make build && ./coder server --dev` - use the script instead
20+
521
## Build/Test/Lint Commands
622

723
### Main Commands
@@ -34,6 +50,7 @@ Read [cursor rules](.cursorrules).
3450
- Use `gofumpt` for formatting
3551
- Create packages when used during implementation
3652
- Validate abstractions against implementations
53+
- **Test packages**: Use `package_test` naming (e.g., `identityprovider_test`) for black-box testing
3754

3855
### Error Handling
3956

@@ -63,11 +80,50 @@ Read [cursor rules](.cursorrules).
6380
- Keep message titles concise (~70 characters)
6481
- Use imperative, present tense in commit titles
6582

66-
## Database queries
83+
## Database Work
84+
85+
### Migration Guidelines
86+
87+
1. **Create migration files**:
88+
- Location: `coderd/database/migrations/`
89+
- Format: `{number}_{description}.{up|down}.sql`
90+
- Number must be unique and sequential
91+
- Always include both up and down migrations
92+
93+
2. **Update database queries**:
94+
- MUST DO! Any changes to database - adding queries, modifying queries should be done in the `coderd/database/queries/*.sql` files
95+
- MUST DO! Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `oauth2.sql`
96+
- After making changes to any `coderd/database/queries/*.sql` files you must run `make gen` to generate respective ORM changes
97+
98+
3. **Handle nullable fields**:
99+
- Use `sql.NullString`, `sql.NullBool`, etc. for optional database fields
100+
- Set `.Valid = true` when providing values
101+
- Example:
102+
103+
```go
104+
CodeChallenge: sql.NullString{
105+
String: params.codeChallenge,
106+
Valid: params.codeChallenge != "",
107+
}
108+
```
67109

68-
- MUST DO! Any changes to database - adding queries, modifying queries should be done in the `coderd\database\queries\*.sql` files. Use `make gen` to generate necessary changes after.
69-
- MUST DO! Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `provisionerjobs.sql`.
70-
- After making changes to any `coderd\database\queries\*.sql` files you must run `make gen` to generate respective ORM changes.
110+
4. **Audit table updates**:
111+
- If adding fields to auditable types, update `enterprise/audit/table.go`
112+
- Add each new field with appropriate action (ActionTrack, ActionIgnore, ActionSecret)
113+
- Run `make gen` to verify no audit errors
114+
115+
5. **In-memory database (dbmem) updates**:
116+
- When adding new fields to database structs, ensure `dbmem` implementation copies all fields
117+
- Check `coderd/database/dbmem/dbmem.go` for Insert/Update methods
118+
- Missing fields in dbmem can cause tests to fail even if main implementation is correct
119+
120+
### Database Generation Process
121+
122+
1. Modify SQL files in `coderd/database/queries/`
123+
2. Run `make gen`
124+
3. If errors about audit table, update `enterprise/audit/table.go`
125+
4. Run `make gen` again
126+
5. Run `make lint` to catch any remaining issues
71127

72128
## Architecture
73129

@@ -78,6 +134,14 @@ Read [cursor rules](.cursorrules).
78134
- **Agents**: Services in remote workspaces providing features like SSH and port forwarding
79135
- **Workspaces**: Cloud resources defined by Terraform
80136

137+
### Adding New API Endpoints
138+
139+
1. **Define types** in `codersdk/` package
140+
2. **Add handler** in appropriate `coderd/` file
141+
3. **Register route** in `coderd/coderd.go`
142+
4. **Add tests** in `coderd/*_test.go` files
143+
5. **Update OpenAPI** by running `make gen`
144+
81145
## Sub-modules
82146

83147
### Template System
@@ -104,3 +168,100 @@ Read [cursor rules](.cursorrules).
104168
The frontend is contained in the site folder.
105169

106170
For building Frontend refer to [this document](docs/about/contributing/frontend.md)
171+
172+
## Common Patterns
173+
174+
### OAuth2/Authentication Work
175+
176+
- Types go in `codersdk/oauth2.go` or similar
177+
- Handlers go in `coderd/oauth2.go` or `coderd/identityprovider/`
178+
- Database fields need migration + audit table updates
179+
- Always support backward compatibility
180+
181+
## OAuth2 Development
182+
183+
### OAuth2 Provider Implementation
184+
185+
When working on OAuth2 provider features:
186+
187+
1. **OAuth2 Spec Compliance**:
188+
- Follow RFC 6749 for token responses
189+
- Use `expires_in` (seconds) not `expiry` (timestamp) in token responses
190+
- Return proper OAuth2 error format: `{"error": "code", "error_description": "details"}`
191+
192+
2. **Error Response Format**:
193+
- Create OAuth2-compliant error responses for token endpoint
194+
- Use standard error codes: `invalid_client`, `invalid_grant`, `invalid_request`
195+
- Avoid generic error responses for OAuth2 endpoints
196+
197+
3. **Testing OAuth2 Features**:
198+
- Use scripts in `./scripts/oauth2/` for testing
199+
- Run `./scripts/oauth2/test-mcp-oauth2.sh` for comprehensive tests
200+
- Manual testing: use `./scripts/oauth2/test-manual-flow.sh`
201+
202+
4. **PKCE Implementation**:
203+
- Support both with and without PKCE for backward compatibility
204+
- Use S256 method for code challenge
205+
- Properly validate code_verifier against stored code_challenge
206+
207+
5. **UI Authorization Flow**:
208+
- Use POST requests for consent, not GET with links
209+
- Avoid dependency on referer headers for security decisions
210+
- Support proper state parameter validation
211+
212+
### OAuth2 Error Handling Pattern
213+
214+
```go
215+
// Define specific OAuth2 errors
216+
var (
217+
errInvalidPKCE = xerrors.New("invalid code_verifier")
218+
)
219+
220+
// Use OAuth2-compliant error responses
221+
type OAuth2Error struct {
222+
Error string `json:"error"`
223+
ErrorDescription string `json:"error_description,omitempty"`
224+
}
225+
226+
// Return proper OAuth2 errors
227+
if errors.Is(err, errInvalidPKCE) {
228+
writeOAuth2Error(ctx, rw, http.StatusBadRequest, "invalid_grant", "The PKCE code verifier is invalid")
229+
return
230+
}
231+
```
232+
233+
### Testing Patterns
234+
235+
- Use table-driven tests for comprehensive coverage
236+
- Mock external dependencies
237+
- Test both positive and negative cases
238+
- Use `testutil.WaitLong` for timeouts in tests
239+
240+
## Testing Scripts
241+
242+
### OAuth2 Test Scripts
243+
244+
Located in `./scripts/oauth2/`:
245+
246+
- `test-mcp-oauth2.sh` - Full automated test suite
247+
- `setup-test-app.sh` - Create test OAuth2 app
248+
- `cleanup-test-app.sh` - Remove test app
249+
- `generate-pkce.sh` - Generate PKCE parameters
250+
- `test-manual-flow.sh` - Manual browser testing
251+
252+
Always run the full test suite after OAuth2 changes:
253+
254+
```bash
255+
./scripts/oauth2/test-mcp-oauth2.sh
256+
```
257+
258+
## Troubleshooting
259+
260+
### Common Issues
261+
262+
1. **"Audit table entry missing action"** - Update `enterprise/audit/table.go`
263+
2. **"package should be X_test"** - Use `package_test` naming for test files
264+
3. **SQL type errors** - Use `sql.Null*` types for nullable fields
265+
4. **Missing newlines** - Ensure files end with newline character
266+
5. **Tests passing locally but failing in CI** - Check if `dbmem` implementation needs updating
267+
6. **OAuth2 endpoints returning wrong error format** - Ensure OAuth2 endpoints return RFC 6749 compliant errors

coderd/apidoc/docs.go

Lines changed: 125 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy