Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit247efc0

Browse files
authored
docs: add OAuth2 provider experimental feature documentation (#19165)
# Add OAuth2 Provider DocumentationThis PR adds comprehensive documentation for the experimental OAuth2Provider feature, which allows Coder to function as an OAuth2authorization server. The documentation covers:- Feature overview and experimental status warning- Setup requirements and enabling the feature- Methods for creating OAuth2 applications (UI and API)- Integration patterns including standard OAuth2 and PKCE flows- Discovery endpoints and token management- Testing and development guidance- Troubleshooting common issues- Security considerations and current limitationsThe documentation is marked as experimental and includes appropriatewarnings about production usage.Signed-off-by: Thomas Kosiewski <tk@coder.com>
1 parentdc395c3 commit247efc0

File tree

1 file changed

+239
-0
lines changed

1 file changed

+239
-0
lines changed
Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
#OAuth2 Provider (Experimental)
2+
3+
>⚠️**Experimental Feature**
4+
>
5+
>The OAuth2 provider functionality is currently**experimental and unstable**. This feature:
6+
>
7+
>- Is subject to breaking changes without notice
8+
>- May have incomplete functionality
9+
>- Is not recommended for production use
10+
>- Requires the`oauth2` experiment flag to be enabled
11+
>
12+
>Use this feature for development and testing purposes only.
13+
14+
Coder can act as an OAuth2 authorization server, allowing third-party applications to authenticate users through Coder and access the Coder API on their behalf. This enables integrations where external applications can leverage Coder's authentication and user management.
15+
16+
##Requirements
17+
18+
- Admin privileges in Coder
19+
- OAuth2 experiment flag enabled
20+
- HTTPS recommended for production deployments
21+
22+
##Enable OAuth2 Provider
23+
24+
Add the`oauth2` experiment flag to your Coder server:
25+
26+
```bash
27+
coder server --experiments oauth2
28+
```
29+
30+
Or set the environment variable:
31+
32+
```env
33+
CODER_EXPERIMENTS=oauth2
34+
```
35+
36+
##Creating OAuth2 Applications
37+
38+
###Method 1: Web UI
39+
40+
1. Navigate to**Deployment Settings** →**OAuth2 Applications**
41+
2. Click**Create Application**
42+
3. Fill in the application details:
43+
-**Name**: Your application name
44+
-**Callback URL**:`https://yourapp.example.com/callback`
45+
-**Icon**: Optional icon URL
46+
47+
###Method 2: Management API
48+
49+
Create an application using the Coder API:
50+
51+
```bash
52+
curl -X POST \
53+
-H"Authorization: Bearer$CODER_SESSION_TOKEN" \
54+
-H"Content-Type: application/json" \
55+
-d'{
56+
"name": "My Application",
57+
"callback_url": "https://myapp.example.com/callback",
58+
"icon": "https://myapp.example.com/icon.png"
59+
}' \
60+
"$CODER_URL/api/v2/oauth2-provider/apps"
61+
```
62+
63+
Generate a client secret:
64+
65+
```bash
66+
curl -X POST \
67+
-H"Authorization: Bearer$CODER_SESSION_TOKEN" \
68+
"$CODER_URL/api/v2/oauth2-provider/apps/$APP_ID/secrets"
69+
```
70+
71+
##Integration Patterns
72+
73+
###Standard OAuth2 Flow
74+
75+
1.**Authorization Request**: Redirect users to Coder's authorization endpoint:
76+
77+
```url
78+
https://coder.example.com/oauth2/authorize?
79+
client_id=your-client-id&
80+
response_type=code&
81+
redirect_uri=https://yourapp.example.com/callback&
82+
state=random-string
83+
```
84+
85+
2.**Token Exchange**: Exchange the authorization code for an access token:
86+
87+
```bash
88+
curl -X POST \
89+
-H"Content-Type: application/x-www-form-urlencoded" \
90+
-d"grant_type=authorization_code" \
91+
-d"code=$AUTH_CODE" \
92+
-d"client_id=$CLIENT_ID" \
93+
-d"client_secret=$CLIENT_SECRET" \
94+
-d"redirect_uri=https://yourapp.example.com/callback" \
95+
"$CODER_URL/oauth2/tokens"
96+
```
97+
98+
3.**API Access**: Use the access token to call Coder's API:
99+
100+
```bash
101+
curl -H"Authorization: Bearer$ACCESS_TOKEN" \
102+
"$CODER_URL/api/v2/users/me"
103+
```
104+
105+
###PKCE Flow (Public Clients)
106+
107+
For mobile apps and single-page applications, use PKCE for enhanced security:
108+
109+
1. Generate a code verifier and challenge:
110+
111+
```bash
112+
CODE_VERIFIER=$(openssl rand -base64 96| tr -d"=+/"| cut -c1-128)
113+
CODE_CHALLENGE=$(echo -n$CODE_VERIFIER| openssl dgst -sha256 -binary| base64| tr -d"=+/"| cut -c1-43)
114+
```
115+
116+
2. Include PKCE parameters in the authorization request:
117+
118+
```url
119+
https://coder.example.com/oauth2/authorize?
120+
client_id=your-client-id&
121+
response_type=code&
122+
code_challenge=$CODE_CHALLENGE&
123+
code_challenge_method=S256&
124+
redirect_uri=https://yourapp.example.com/callback
125+
```
126+
127+
3. Include the code verifier in the token exchange:
128+
129+
```bash
130+
curl -X POST \
131+
-d"grant_type=authorization_code" \
132+
-d"code=$AUTH_CODE" \
133+
-d"client_id=$CLIENT_ID" \
134+
-d"code_verifier=$CODE_VERIFIER" \
135+
"$CODER_URL/oauth2/tokens"
136+
```
137+
138+
##Discovery Endpoints
139+
140+
Coder provides OAuth2 discovery endpoints for programmatic integration:
141+
142+
-**Authorization Server Metadata**:`GET /.well-known/oauth-authorization-server`
143+
-**Protected Resource Metadata**:`GET /.well-known/oauth-protected-resource`
144+
145+
These endpoints return server capabilities and endpoint URLs according to[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) and[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).
146+
147+
##Token Management
148+
149+
###Refresh Tokens
150+
151+
Refresh an expired access token:
152+
153+
```bash
154+
curl -X POST \
155+
-H"Content-Type: application/x-www-form-urlencoded" \
156+
-d"grant_type=refresh_token" \
157+
-d"refresh_token=$REFRESH_TOKEN" \
158+
-d"client_id=$CLIENT_ID" \
159+
-d"client_secret=$CLIENT_SECRET" \
160+
"$CODER_URL/oauth2/tokens"
161+
```
162+
163+
###Revoke Access
164+
165+
Revoke all tokens for an application:
166+
167+
```bash
168+
curl -X DELETE \
169+
-H"Authorization: Bearer$CODER_SESSION_TOKEN" \
170+
"$CODER_URL/oauth2/tokens?client_id=$CLIENT_ID"
171+
```
172+
173+
##Testing and Development
174+
175+
Coder provides comprehensive test scripts for OAuth2 development:
176+
177+
```bash
178+
# Navigate to the OAuth2 test scripts
179+
cd scripts/oauth2/
180+
181+
# Run the full automated test suite
182+
./test-mcp-oauth2.sh
183+
184+
# Create a test application for manual testing
185+
eval$(./setup-test-app.sh)
186+
187+
# Run an interactive browser-based test
188+
./test-manual-flow.sh
189+
190+
# Clean up when done
191+
./cleanup-test-app.sh
192+
```
193+
194+
For more details on testing, see the[OAuth2 test scripts README](../../../scripts/oauth2/README.md).
195+
196+
##Common Issues
197+
198+
###"OAuth2 experiment not enabled"
199+
200+
Add`oauth2` to your experiment flags:`coder server --experiments oauth2`
201+
202+
###"Invalid redirect_uri"
203+
204+
Ensure the redirect URI in your request exactly matches the one registered for your application.
205+
206+
###"PKCE verification failed"
207+
208+
Verify that the`code_verifier` used in the token request matches the one used to generate the`code_challenge`.
209+
210+
##Security Considerations
211+
212+
-**Use HTTPS**: Always use HTTPS in production to protect tokens in transit
213+
-**Implement PKCE**: Use PKCE for all public clients (mobile apps, SPAs)
214+
-**Validate redirect URLs**: Only register trusted redirect URIs for your applications
215+
-**Rotate secrets**: Periodically rotate client secrets using the management API
216+
217+
##Limitations
218+
219+
As an experimental feature, the current implementation has limitations:
220+
221+
- No scope system - all tokens have full API access
222+
- No client credentials grant support
223+
- Limited to opaque access tokens (no JWT support)
224+
225+
##Standards Compliance
226+
227+
This implementation follows established OAuth2 standards including[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) (OAuth2 core),[RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) (PKCE), and related specifications for discovery and client registration.
228+
229+
##Next Steps
230+
231+
- Review the[API Reference](../../reference/api/index.md) for complete endpoint documentation
232+
- Check[External Authentication](../external-auth/index.md) for configuring Coder as an OAuth2 client
233+
- See[Security Best Practices](../security/index.md) for deployment security guidance
234+
235+
---
236+
237+
>📝**Feedback**
238+
>
239+
>This is an experimental feature under active development. Please report issues and feedback through[GitHub Issues](https://github.com/coder/coder/issues) with the`oauth2` label.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp