@cdmbase/wiki-browser 12.0.18-alpha.48 → 12.0.18-alpha.49
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,207 +1,445 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Form Builder Connector Documentation (OAuth and MCP)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Overview
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This guide explains how to configure connectors in Form Builder Extensions.
|
|
6
|
+
You can add two connector types:
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
- **OAuth App**: Standard OAuth 2.0 based integration (for example Google, GitHub, Slack).
|
|
9
|
+
- **MCP Connector**: Integration with an MCP server, using either OAuth or API Key authentication.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
The goal is to help you understand:
|
|
12
|
+
|
|
13
|
+
- The end-to-end setup flow in Form Builder.
|
|
14
|
+
- What each connector field means.
|
|
15
|
+
- Why PKCE is important and when to use it.
|
|
16
|
+
- When and why to enable custom OAuth endpoints.
|
|
17
|
+
- How MCP connector flow works.
|
|
10
18
|
|
|
11
19
|
---
|
|
12
20
|
|
|
13
|
-
##
|
|
21
|
+
## 1) How to reach connector configuration in Form Builder
|
|
14
22
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
│ 3. Open Google │ │ │
|
|
27
|
-
│ sign-in popup │ │ │
|
|
28
|
-
│<────────────────────│ │ │
|
|
29
|
-
│ │ │ │
|
|
30
|
-
│ 4. Sign in and │ │ │
|
|
31
|
-
│ grant access │ │ │
|
|
32
|
-
│─────────────────────────────────────────>│ │
|
|
33
|
-
│ │ │ │
|
|
34
|
-
│ │ 5. Google sends │ │
|
|
35
|
-
│ │ auth code back │ │
|
|
36
|
-
│ │<────────────────────│ │
|
|
37
|
-
│ │ │ │
|
|
38
|
-
│ │ 6. Exchange code │ │
|
|
39
|
-
│ │ for tokens │ │
|
|
40
|
-
│ │────────────────────>│ │
|
|
41
|
-
│ │ │ │
|
|
42
|
-
│ │ 7. Receive access │ │
|
|
43
|
-
│ │ & refresh token │ │
|
|
44
|
-
│ │<────────────────────│ │
|
|
45
|
-
│ │ │ │
|
|
46
|
-
│ │ 8. Store tokens │ │
|
|
47
|
-
│ │ securely │ │
|
|
48
|
-
│ │─────────────────────────────────────────>│
|
|
49
|
-
│ │ │ │
|
|
50
|
-
│ 9. Show connected │ │ │
|
|
51
|
-
│<────────────────────│ │ │
|
|
52
|
-
│ │ │ │
|
|
53
|
-
```
|
|
23
|
+
Follow this flow:
|
|
24
|
+
|
|
25
|
+
1. Open **Form Builder**.
|
|
26
|
+
2. From the left sidebar, go to **Extensions**.
|
|
27
|
+
3. Click **Create Extension**.
|
|
28
|
+
4. Fill extension details (name, description, basic metadata).
|
|
29
|
+
5. Open your extension canvas.
|
|
30
|
+
6. Drag and drop form elements into the step.
|
|
31
|
+
7. Drag and drop the **OAuth Connector** component.
|
|
32
|
+
8. Select the connector element and open its settings panel.
|
|
33
|
+
9. You will now see **OAuth Connector Settings** with all connector fields.
|
|
54
34
|
|
|
55
35
|
---
|
|
56
36
|
|
|
57
|
-
##
|
|
37
|
+
## 2) Connector Type options
|
|
58
38
|
|
|
59
|
-
|
|
39
|
+
Inside connector settings, choose one connector type:
|
|
60
40
|
|
|
61
|
-
|
|
41
|
+
- **OAuth App**
|
|
42
|
+
- Use this when connecting to OAuth providers directly.
|
|
43
|
+
- Example providers: Google, GitHub, Slack, Microsoft.
|
|
44
|
+
- **MCP Connector**
|
|
45
|
+
- Use this when connecting to an MCP server endpoint.
|
|
46
|
+
- Supports:
|
|
47
|
+
- MCP with OAuth.
|
|
48
|
+
- MCP with API Key.
|
|
62
49
|
|
|
63
|
-
|
|
50
|
+
---
|
|
64
51
|
|
|
65
|
-
|
|
52
|
+
## 3) Common fields (shown for both OAuth and MCP)
|
|
66
53
|
|
|
67
|
-
|
|
54
|
+
These fields are available for both connector types:
|
|
68
55
|
|
|
69
|
-
|
|
56
|
+
### Provider ID
|
|
70
57
|
|
|
71
|
-
|
|
58
|
+
- Unique provider selector/identifier.
|
|
59
|
+
- Can be a known provider (pre-configured) or custom.
|
|
60
|
+
- Example: `google`, `github`, `slack`, `custom`.
|
|
72
61
|
|
|
73
|
-
|
|
62
|
+
### Display Title
|
|
74
63
|
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
- Temporarily saves this information so we can match it when Google responds
|
|
78
|
-
- Builds the Google authorization URL with all required parameters
|
|
64
|
+
- User-facing connector name in the form.
|
|
65
|
+
- Example: `Connect Slack Workspace`.
|
|
79
66
|
|
|
80
|
-
###
|
|
67
|
+
### Connector Description
|
|
81
68
|
|
|
82
|
-
|
|
69
|
+
- Short text describing what this connector does.
|
|
70
|
+
- Example: `Connect Slack to send notifications from this workflow.`
|
|
83
71
|
|
|
84
|
-
###
|
|
72
|
+
### Connector Type
|
|
85
73
|
|
|
86
|
-
|
|
74
|
+
- Radio selection:
|
|
75
|
+
- `OAuth App`
|
|
76
|
+
- `MCP Connector`
|
|
87
77
|
|
|
88
|
-
###
|
|
78
|
+
### Brand Color
|
|
89
79
|
|
|
90
|
-
|
|
80
|
+
- Controls the connector card accent color in UI.
|
|
81
|
+
- Use provider brand color where possible for recognition.
|
|
91
82
|
|
|
92
|
-
###
|
|
83
|
+
### Credential Provisioning (Client ID / Client Secret)
|
|
93
84
|
|
|
94
|
-
|
|
85
|
+
- Admin-level credentials are stored securely in vault-backed configuration.
|
|
86
|
+
- They are not shown to end users at runtime.
|
|
87
|
+
- For standard OAuth app flow, these are usually required.
|
|
88
|
+
- For some MCP OAuth patterns, they may be optional or dynamically registered.
|
|
95
89
|
|
|
96
|
-
|
|
90
|
+
---
|
|
97
91
|
|
|
98
|
-
|
|
92
|
+
## 4) OAuth App fields (detailed explanation)
|
|
99
93
|
|
|
100
|
-
|
|
94
|
+
When **Connector Type = OAuth App**, configure the following:
|
|
101
95
|
|
|
102
|
-
|
|
96
|
+
### Provider URL
|
|
103
97
|
|
|
104
|
-
|
|
98
|
+
- Base URL/issuer for provider discovery.
|
|
99
|
+
- Usually the provider identity domain.
|
|
100
|
+
- Example: `https://accounts.google.com`
|
|
101
|
+
- If provider is pre-configured, this may be auto-filled and read-only.
|
|
102
|
+
|
|
103
|
+
### Token endpoint client authentication methods
|
|
104
|
+
|
|
105
|
+
Determines how `client_id` and `client_secret` are sent to token endpoint.
|
|
106
|
+
|
|
107
|
+
- `client_secret_post` (default)
|
|
108
|
+
- Sends client credentials in request body.
|
|
109
|
+
- Common and compatible with many providers.
|
|
110
|
+
- `client_secret_basic`
|
|
111
|
+
- Sends credentials in `Authorization: Basic ...` header.
|
|
112
|
+
- Needed by providers expecting HTTP Basic auth.
|
|
113
|
+
|
|
114
|
+
Use provider documentation to pick the correct method. A mismatch can cause token exchange failures.
|
|
115
|
+
|
|
116
|
+
### Use PKCE
|
|
117
|
+
|
|
118
|
+
Enable this only for providers that support the PKCE-based secure Authorization Code flow, since not all providers (such as Discord) support PKCE..
|
|
119
|
+
|
|
120
|
+
- PKCE adds:
|
|
121
|
+
- `code_challenge` during authorize request.
|
|
122
|
+
- `code_verifier` during token request.
|
|
123
|
+
- This protects against authorization code interception attacks.
|
|
124
|
+
- Recommended for browser/public-client style flows.
|
|
125
|
+
|
|
126
|
+
#### Why PKCE matters
|
|
127
|
+
|
|
128
|
+
Without PKCE, if someone intercepts the authorization code, they can exchange it for tokens.
|
|
129
|
+
With PKCE, the intercepted code is useless without the original verifier.
|
|
130
|
+
|
|
131
|
+
#### PKCE example (Slack)
|
|
132
|
+
|
|
133
|
+
For a Slack connector, enabling PKCE means:
|
|
134
|
+
|
|
135
|
+
1. System generates random `code_verifier`.
|
|
136
|
+
2. System derives `code_challenge` (S256).
|
|
137
|
+
3. User is redirected to Slack authorize URL with challenge.
|
|
138
|
+
4. Slack returns authorization code to callback.
|
|
139
|
+
5. Backend sends code + original verifier to Slack token endpoint.
|
|
140
|
+
6. Slack validates verifier and returns tokens.
|
|
141
|
+
|
|
142
|
+
Result: safer OAuth flow, especially in browser-based integrations.
|
|
143
|
+
|
|
144
|
+
### Use Custom OAuth Endpoints
|
|
145
|
+
|
|
146
|
+
Enable this when provider discovery via `Provider URL` is not sufficient.
|
|
147
|
+
|
|
148
|
+
By default, the system can discover endpoints from provider metadata.
|
|
149
|
+
When custom endpoints are enabled, you explicitly provide endpoints below.
|
|
150
|
+
|
|
151
|
+
#### OIDC discovery example (default mode)
|
|
152
|
+
|
|
153
|
+
If provider URL is `https://accounts.google.com`, the platform can use OIDC discovery metadata from:
|
|
154
|
+
|
|
155
|
+
- `https://accounts.google.com/.well-known/openid-configuration`
|
|
156
|
+
|
|
157
|
+
From this metadata, the platform automatically resolves:
|
|
158
|
+
|
|
159
|
+
- `authorization_endpoint`
|
|
160
|
+
- `token_endpoint`
|
|
161
|
+
- `revocation_endpoint` (if available)
|
|
162
|
+
|
|
163
|
+
This is important because OIDC discovery:
|
|
164
|
+
|
|
165
|
+
- reduces manual configuration errors,
|
|
166
|
+
- keeps endpoint configuration consistent with provider updates,
|
|
167
|
+
- improves reliability across environments,
|
|
168
|
+
- and simplifies onboarding for standard providers.
|
|
169
|
+
|
|
170
|
+
#### Why and when to enable custom endpoints
|
|
171
|
+
|
|
172
|
+
Enable custom endpoints when OIDC/OAuth discovery cannot provide valid endpoints for your setup, for example:
|
|
173
|
+
|
|
174
|
+
- provider has no `.well-known` metadata,
|
|
175
|
+
- enterprise/private deployment uses non-public or tenant-specific endpoints,
|
|
176
|
+
- you must override default endpoints for compatibility reasons.
|
|
177
|
+
|
|
178
|
+
In these cases, manually provide `Authorization URL`, `Token URL`, and optionally `Revocation URL`.
|
|
179
|
+
|
|
180
|
+
### Authorization URL (required when custom endpoints enabled)
|
|
181
|
+
|
|
182
|
+
- The provider authorization endpoint.
|
|
183
|
+
- Example: `https://provider.example.com/oauth/authorize`
|
|
184
|
+
|
|
185
|
+
### Token URL (required when custom endpoints enabled)
|
|
105
186
|
|
|
106
|
-
|
|
187
|
+
- The provider token endpoint for code-to-token exchange.
|
|
188
|
+
- Example: `https://provider.example.com/oauth/token`
|
|
107
189
|
|
|
190
|
+
### Revocation URL (optional)
|
|
191
|
+
|
|
192
|
+
- Endpoint used to revoke access/refresh tokens on disconnect.
|
|
193
|
+
- Example: `https://provider.example.com/oauth/revoke`
|
|
194
|
+
|
|
195
|
+
### Redirect URI
|
|
196
|
+
|
|
197
|
+
- Callback URI registered in provider app settings.
|
|
198
|
+
- Provider redirects user to this URL after consent.
|
|
199
|
+
- Typical format: `https://<your-client-domain>/connector-callback`
|
|
200
|
+
|
|
201
|
+
### OAuth Scopes
|
|
202
|
+
|
|
203
|
+
- Permissions requested from provider.
|
|
204
|
+
- Comma-separated list (if editable).
|
|
205
|
+
- Example: `openid, profile, email, channels:read`
|
|
206
|
+
- For known providers, scopes can be pre-configured and read-only.
|
|
207
|
+
|
|
208
|
+
### OAuth App connect flow diagram
|
|
209
|
+
|
|
210
|
+
```text
|
|
211
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
212
|
+
│ User │ │ Platform │ │ OAuth Provider│ │ Vault │
|
|
213
|
+
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
214
|
+
│ │ │ │
|
|
215
|
+
│ 1. Click Connect │ │ │
|
|
216
|
+
│────────────────────>│ │ │
|
|
217
|
+
│ │ 2. Generate state + │ │
|
|
218
|
+
│ │ PKCE verifier │ │
|
|
219
|
+
│ │ │ │
|
|
220
|
+
│ 3. Open authorize │ │ │
|
|
221
|
+
│ page/popup │ │ │
|
|
222
|
+
│<────────────────────│ │ │
|
|
223
|
+
│───────────────────────────────────────────>│ │
|
|
224
|
+
│ │ │ │
|
|
225
|
+
│ │ 4. Provider returns │ │
|
|
226
|
+
│ │ auth code │ │
|
|
227
|
+
│ │<─────────────────────│ │
|
|
228
|
+
│ │ 5. Exchange code for │ │
|
|
229
|
+
│ │ tokens (+verifier)│ │
|
|
230
|
+
│ │─────────────────────>│ │
|
|
231
|
+
│ │ 6. Receive tokens │ │
|
|
232
|
+
│ │<─────────────────────│ │
|
|
233
|
+
│ │ 7. Store tokens │ │
|
|
234
|
+
│ │───────────────────────────────────────────>│
|
|
235
|
+
│ 8. Show connected │ │ │
|
|
236
|
+
│<────────────────────│ │ │
|
|
108
237
|
```
|
|
238
|
+
|
|
239
|
+
### OAuth App disconnect flow diagram
|
|
240
|
+
|
|
241
|
+
```text
|
|
109
242
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
110
|
-
│ User │ │ Platform │ │
|
|
243
|
+
│ User │ │ Platform │ │ OAuth Provider│ │ Vault │
|
|
111
244
|
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
112
|
-
│ │
|
|
113
|
-
│
|
|
114
|
-
│
|
|
115
|
-
|
|
116
|
-
│
|
|
117
|
-
│ │
|
|
118
|
-
│
|
|
119
|
-
│
|
|
120
|
-
│
|
|
121
|
-
│
|
|
122
|
-
│ │
|
|
123
|
-
│ │────────────────────>│ │
|
|
124
|
-
│ │ │ │
|
|
125
|
-
│ │ 4. Delete tokens │ │
|
|
126
|
-
│ │ from vault │ │
|
|
127
|
-
│ │─────────────────────────────────────────>│
|
|
128
|
-
│ │ │ │
|
|
129
|
-
│ │ 5. Delete │ │
|
|
130
|
-
│ │ connector record│ │
|
|
131
|
-
│ │ │ │
|
|
132
|
-
│ 6. Show │ │ │
|
|
133
|
-
│ disconnected │ │
|
|
134
|
-
│<────────────────────│ │ │
|
|
135
|
-
│ │ │ │
|
|
245
|
+
│ │ │ │
|
|
246
|
+
│ 1. Click Disconnect │ │ │
|
|
247
|
+
│────────────────────>│ │ │
|
|
248
|
+
│ │ 2. Read tokens │ │
|
|
249
|
+
│ │<───────────────────────────────────────────│
|
|
250
|
+
│ │ 3. Revoke tokens │ │
|
|
251
|
+
│ │─────────────────────>│ │
|
|
252
|
+
│ │ 4. Clear secrets │ │
|
|
253
|
+
│ │───────────────────────────────────────────>│
|
|
254
|
+
│ 5. Show disconnected│ │ │
|
|
255
|
+
│<────────────────────│ │ │
|
|
136
256
|
```
|
|
137
257
|
|
|
138
258
|
---
|
|
139
259
|
|
|
140
|
-
##
|
|
260
|
+
## 5) When to use custom OAuth endpoints (with example)
|
|
261
|
+
|
|
262
|
+
Use **Custom OAuth Endpoints** when:
|
|
263
|
+
|
|
264
|
+
- Provider does not expose standard OIDC/OAuth discovery metadata.
|
|
265
|
+
- Discovery endpoint is disabled, private, or non-standard.
|
|
266
|
+
- You need to use tenant-specific auth/token URLs.
|
|
267
|
+
- You have a custom or self-hosted OAuth server.
|
|
268
|
+
|
|
269
|
+
### Example scenario
|
|
270
|
+
|
|
271
|
+
Assume an enterprise provider exposes:
|
|
272
|
+
|
|
273
|
+
- Authorization: `https://login.acme.internal/oauth2/v1/authorize`
|
|
274
|
+
- Token: `https://login.acme.internal/oauth2/v1/token`
|
|
275
|
+
- Revocation: `https://login.acme.internal/oauth2/v1/revoke`
|
|
276
|
+
|
|
277
|
+
If discovery is not available, enable custom endpoints and enter these URLs directly.
|
|
278
|
+
|
|
279
|
+
How it works:
|
|
280
|
+
|
|
281
|
+
1. Authorize URL is built using your custom authorization endpoint.
|
|
282
|
+
2. User authenticates and provider returns `code`.
|
|
283
|
+
3. Token exchange is sent to your custom token endpoint.
|
|
284
|
+
4. On disconnect, system uses custom revocation endpoint (if provided).
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## 6) MCP Connector flow
|
|
289
|
+
|
|
290
|
+
When **Connector Type = MCP Connector**, use these fields:
|
|
291
|
+
|
|
292
|
+
### MCP URL
|
|
141
293
|
|
|
142
|
-
|
|
294
|
+
- Base URL of MCP server.
|
|
295
|
+
- Example: `https://mcp.example.com/api`
|
|
296
|
+
- For known MCP providers, may be auto-filled.
|
|
143
297
|
|
|
144
|
-
|
|
298
|
+
### Auth Method
|
|
145
299
|
|
|
146
|
-
|
|
300
|
+
Choose one:
|
|
147
301
|
|
|
148
|
-
|
|
302
|
+
- **OAuth**
|
|
303
|
+
- MCP server uses OAuth flow.
|
|
304
|
+
- Scopes are required.
|
|
305
|
+
- PKCE is applied in MCP OAuth flow.
|
|
306
|
+
- **API Key**
|
|
307
|
+
- MCP server authenticates using an API key/token.
|
|
308
|
+
- Simpler setup where OAuth is not needed.
|
|
149
309
|
|
|
150
|
-
###
|
|
310
|
+
### MCP OAuth Scopes
|
|
151
311
|
|
|
152
|
-
|
|
312
|
+
- Required when Auth Method is OAuth.
|
|
313
|
+
- Comma-separated permissions.
|
|
314
|
+
- Example: `read, write, tools:execute`
|
|
315
|
+
- May be read-only for pre-configured providers.
|
|
153
316
|
|
|
154
|
-
|
|
317
|
+
---
|
|
155
318
|
|
|
156
|
-
|
|
319
|
+
## 7) MCP OAuth flow (what happens internally)
|
|
157
320
|
|
|
158
|
-
|
|
321
|
+
For MCP + OAuth, typical flow is:
|
|
159
322
|
|
|
160
|
-
|
|
323
|
+
1. System reads MCP discovery metadata from provider (`.well-known` endpoint).
|
|
324
|
+
2. If required, system performs dynamic OAuth client registration.
|
|
325
|
+
3. System generates state and PKCE challenge.
|
|
326
|
+
4. User is redirected to MCP authorization endpoint.
|
|
327
|
+
5. Provider returns `code` to callback.
|
|
328
|
+
6. Backend exchanges `code` using `code_verifier`.
|
|
329
|
+
7. Access/refresh tokens are stored securely.
|
|
161
330
|
|
|
162
|
-
|
|
331
|
+
This allows secure token-based access to MCP tools/services from the connector.
|
|
163
332
|
|
|
164
|
-
|
|
333
|
+
### MCP OAuth connect flow diagram
|
|
165
334
|
|
|
166
|
-
|
|
335
|
+
```text
|
|
336
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
337
|
+
│ User │ │ Platform │ │ MCP Server │ │ Vault │
|
|
338
|
+
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
339
|
+
│ │ │ │
|
|
340
|
+
│ 1. Click Connect │ │ │
|
|
341
|
+
│────────────────────>│ │ │
|
|
342
|
+
│ │ 2. Fetch .well-known │ │
|
|
343
|
+
│ │─────────────────────>│ │
|
|
344
|
+
│ │ 3. (Optional) client │ │
|
|
345
|
+
│ │ registration │ │
|
|
346
|
+
│ │─────────────────────>│ │
|
|
347
|
+
│ │ 4. Save client creds │ │
|
|
348
|
+
│ │───────────────────────────────────────────>│
|
|
349
|
+
│ │ 5. Generate state + │ │
|
|
350
|
+
│ │ PKCE challenge │ │
|
|
351
|
+
│───────────────────────────────────────────>│ │
|
|
352
|
+
│ │ │ │
|
|
353
|
+
│ │ 6. Code callback │ │
|
|
354
|
+
│ │<─────────────────────│ │
|
|
355
|
+
│ │ 7. Token exchange │ │
|
|
356
|
+
│ │─────────────────────>│ │
|
|
357
|
+
│ │ 8. Store tokens │ │
|
|
358
|
+
│ │───────────────────────────────────────────>│
|
|
359
|
+
│ 9. Show connected │ │ │
|
|
360
|
+
│<────────────────────│ │ │
|
|
361
|
+
```
|
|
167
362
|
|
|
168
|
-
|
|
363
|
+
### MCP API Key flow diagram
|
|
364
|
+
|
|
365
|
+
```text
|
|
366
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
367
|
+
│ User │ │ Platform │ │ MCP Server │
|
|
368
|
+
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
369
|
+
│ │ │
|
|
370
|
+
│ 1. Provide API key │ │
|
|
371
|
+
│────────────────────>│ │
|
|
372
|
+
│ │ 2. Test connection │
|
|
373
|
+
│ │─────────────────────>│
|
|
374
|
+
│ │ 3. Return status │
|
|
375
|
+
│ │<─────────────────────│
|
|
376
|
+
│ 4. Show connected │ │
|
|
377
|
+
│<────────────────────│ │
|
|
378
|
+
```
|
|
169
379
|
|
|
170
380
|
---
|
|
171
381
|
|
|
172
|
-
##
|
|
382
|
+
## 8) Best practices
|
|
173
383
|
|
|
174
|
-
**PKCE
|
|
175
|
-
|
|
384
|
+
- Always keep **PKCE enabled** unless provider explicitly does not support it.
|
|
385
|
+
- Use least-privilege scopes (request only what is needed).
|
|
386
|
+
- Verify redirect URI exactly matches provider app configuration.
|
|
387
|
+
- Choose token auth method based on provider docs (`client_secret_post` vs Basic).
|
|
388
|
+
- Enable custom endpoints only when discovery does not work.
|
|
176
389
|
|
|
177
|
-
|
|
178
|
-
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## 9) How secrets are stored (same model as previous flow)
|
|
393
|
+
|
|
394
|
+
Secret handling remains the same as your previous connector flow.
|
|
395
|
+
|
|
396
|
+
### Stored in Vault (encrypted)
|
|
397
|
+
|
|
398
|
+
- `clientId` and `clientSecret` (connector app credentials).
|
|
399
|
+
- `accessToken` and `refreshToken` (runtime user tokens).
|
|
400
|
+
- Token metadata where applicable (expiry/scope context).
|
|
179
401
|
|
|
180
|
-
|
|
181
|
-
The security information needed during authorization is stored temporarily and automatically deleted after 10 minutes. This ensures no sensitive data lingers if a connection attempt is abandoned.
|
|
402
|
+
### Stored in Database
|
|
182
403
|
|
|
183
|
-
|
|
184
|
-
|
|
404
|
+
- Connector metadata (provider, type, status, timestamps).
|
|
405
|
+
- References/pointers to vault-backed secrets.
|
|
406
|
+
- Project and environment association.
|
|
185
407
|
|
|
186
|
-
|
|
187
|
-
|
|
408
|
+
### Temporary during auth
|
|
409
|
+
|
|
410
|
+
- OAuth `state` and PKCE values used for request validation.
|
|
411
|
+
- Temporary auth request context for callback validation.
|
|
412
|
+
|
|
413
|
+
No provider passwords are stored in the platform database.
|
|
188
414
|
|
|
189
415
|
---
|
|
190
416
|
|
|
191
|
-
##
|
|
417
|
+
## 10) Quick configuration checklist
|
|
192
418
|
|
|
193
|
-
|
|
419
|
+
### OAuth App checklist
|
|
194
420
|
|
|
195
|
-
-
|
|
196
|
-
-
|
|
421
|
+
- Set provider ID and display metadata.
|
|
422
|
+
- Set provider URL.
|
|
423
|
+
- Select token endpoint client authentication method.
|
|
424
|
+
- Keep PKCE enabled.
|
|
425
|
+
- Configure redirect URI.
|
|
426
|
+
- Set scopes.
|
|
427
|
+
- If required, enable custom endpoints and provide authorization/token/revocation URLs.
|
|
197
428
|
|
|
198
|
-
|
|
429
|
+
### MCP Connector checklist
|
|
199
430
|
|
|
200
|
-
-
|
|
201
|
-
-
|
|
202
|
-
-
|
|
203
|
-
-
|
|
431
|
+
- Set provider ID and display metadata.
|
|
432
|
+
- Set MCP URL.
|
|
433
|
+
- Choose auth method (OAuth or API Key).
|
|
434
|
+
- If OAuth, configure MCP scopes.
|
|
435
|
+
- Validate connection flow in preview/runtime.
|
|
436
|
+
|
|
437
|
+
---
|
|
204
438
|
|
|
205
|
-
|
|
439
|
+
## 11) Troubleshooting tips
|
|
206
440
|
|
|
207
|
-
-
|
|
441
|
+
- **Token exchange fails**: check token auth method and token URL.
|
|
442
|
+
- **Invalid redirect URI**: verify exact URI match in provider console.
|
|
443
|
+
- **Insufficient permissions**: add required scopes and reconnect.
|
|
444
|
+
- **Custom provider not working**: verify all custom endpoint URLs are correct and reachable.
|
|
445
|
+
- **MCP OAuth fails early**: check MCP discovery endpoint and OAuth metadata availability.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cdmbase/wiki-browser",
|
|
3
|
-
"version": "12.0.18-alpha.
|
|
3
|
+
"version": "12.0.18-alpha.49",
|
|
4
4
|
"description": "Sample core for higher packages to depend on",
|
|
5
5
|
"license": "ISC",
|
|
6
6
|
"author": "CDMBase LLC",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"openai": "^4.52.0"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
|
-
"common": "12.0.18-alpha.
|
|
31
|
+
"common": "12.0.18-alpha.49"
|
|
32
32
|
},
|
|
33
33
|
"peerDependencies": {
|
|
34
34
|
"@common-stack/client-react": ">0.5.16",
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
}
|
|
66
66
|
]
|
|
67
67
|
},
|
|
68
|
-
"gitHead": "
|
|
68
|
+
"gitHead": "3c1a1c817bd7a4c486259bba60746627fd9068b8",
|
|
69
69
|
"typescript": {
|
|
70
70
|
"definition": "lib/index.d.ts"
|
|
71
71
|
}
|