Skip to content

Commit edc1543

Browse files
touilleManFirelightFlagboy
touilleMan
authored and
FirelightFlagboy
committed
Add RFC1022 Server configuration API
1 parent 150e8d9 commit edc1543

File tree

1 file changed

+254
-0
lines changed

1 file changed

+254
-0
lines changed

‎docs/rfcs/1022-server-config-api.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
<!-- Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS -->
2+
3+
# Server configuration API
4+
5+
## 1 - Goals
6+
7+
Currently the client is able to obtain some configuration from the server, but only on a per-organization base.
8+
9+
Per-organization configuration is convenient since it allows widely different organizations
10+
to be hosted on the same server, however:
11+
12+
- It increases server complexity: configuration has to be stored in the database,
13+
dedicated administration APIs are required to update the configuration.
14+
- It increase client complexity: configuration cannot be obtained before device login
15+
(as querying the organization config without authentication would be a form of oracle
16+
allowing an attacker to know what organization exist).
17+
- In practice widely different organizations are most likely to be hosted on different
18+
server (typically an organization with very high security requirements may consider
19+
hosting on a dedicated server as part of its security requirements).
20+
21+
For this reason, this RFC describe a new sever-wide configuration that can be queried
22+
without any authentication.
23+
24+
> Note:
25+
>
26+
> The server-wide configuration doesn't fully replace per-organization configuration
27+
> (typically the user or data limit are still pertinent to be per-organization).
28+
29+
## 2 - Protocol changes
30+
31+
### 2.1 - Replace anonymous account API commands family by anonymous server
32+
33+
Querying the server configuration is done without authentication and without the need
34+
to specify an organization ID.
35+
36+
Currently the anonymous account API family already correspond to this, so we choose to
37+
re-use this API family (and rename it so reflect the fact it is just a route that allow
38+
sending command without authentication that are global to the server).
39+
40+
Changes:
41+
42+
- Rename API commands family "anonymous account" -> "anonymous server"
43+
- Rename server API route `/anonymous_account` -> `/anonymous_server`
44+
45+
> Note:
46+
>
47+
> Since the Parsec account features are not in production yet, we consider acceptable
48+
> to break compatibility by renaming this route.
49+
50+
### 2.2 - Server configuration API
51+
52+
New anonymous server API:
53+
54+
```json5
55+
[
56+
{
57+
"major_versions": [
58+
5
59+
],
60+
"cmd": "server_config",
61+
"req": {},
62+
"reps": [
63+
{
64+
"status": "ok",
65+
"fields": [
66+
{
67+
"name": "client_agent",
68+
"type": "ClientAgentConfig"
69+
},
70+
{
71+
"name": "account",
72+
"type": "AccountConfig"
73+
},
74+
{
75+
"name": "organization_bootstrap",
76+
"type": "OrganizationBootstrapConfig"
77+
},
78+
{
79+
"name": "openbao",
80+
"type": "OpenBaoConfig"
81+
}
82+
]
83+
}
84+
],
85+
"nested_types": [
86+
{
87+
"name": "ClientAgentConfig",
88+
"variants": [
89+
{
90+
// The server will reject any connection from a web client
91+
// (i.e. only request containing a user-agent starting
92+
// with `Parsec-client/` is allowed).
93+
"name": "NativeOnly",
94+
"discriminant_value": "NATIVE_ONLY"
95+
},
96+
{
97+
// The server allows connection from a web client.
98+
"name": "NativeOrWeb",
99+
"discriminant_value": "NATIVE_OR_WEB"
100+
}
101+
]
102+
},
103+
{
104+
"name": "AccountConfig",
105+
"variants": [
106+
{
107+
// Parsec account is not available
108+
"name": "Disabled",
109+
"discriminant_value": "DISABLED"
110+
},
111+
{
112+
// Any anonymous client is allowed to create a Parsec account (as
113+
// long as the user can validate the email address he provided).
114+
// This Parsec account can then be used as a cross-organization
115+
// hub to:
116+
// - List the organization he (i.e. his email address) is part of
117+
// - List the pending invitation related to his email address
118+
// - Use the account vault to store a key itself protecting a
119+
// local device (used to protect local device on web with the
120+
// Parsec account authentication instead of a separate password).
121+
// - Use the account vault to store registration device (used, to
122+
// skip the device-to-device enrollment process when connecting
123+
// to an organization from a machine with no local device).
124+
"name": "EnabledWithVault",
125+
"discriminant_value": "ENABLED_WITH_VAULT"
126+
},
127+
{
128+
// The user should not store any sensitive data with a low entropy
129+
// key server-side using his account vault (typically storing,
130+
// encrypted with a password, a registration device or a key
131+
// itself protecting a local device).
132+
//
133+
// Note this is a purely advisory configuration since only the
134+
// client can decrypt the vault content, and hence it would be
135+
// pointless to try to enforce it on the server side.
136+
"name": "EnabledWithoutVault",
137+
"discriminant_value": "ENABLED_WITHOUT_VAULT"
138+
}
139+
]
140+
},
141+
{
142+
"name": "OrganizationBootstrapConfig",
143+
"variants": [
144+
{
145+
// The organization must have been first created by a server
146+
// administrator, leading to a bootstrap organization URL
147+
// (containing a bootstrap token) that must be used to proceed
148+
// with the bootstrap.
149+
"name": "WithBootstrapToken",
150+
"discriminant_value": "WITH_BOOTSTRAP_TOKEN"
151+
},
152+
{
153+
// If the organization doesn't already exists on the server,
154+
// it will be automatically created when a bootstrap is attempted
155+
// (hence there is no bootstrap token involved in this case and
156+
// any anonymous client is allowed to create an organization,
157+
// use this carefully!).
158+
"name": "Spontaneous",
159+
"discriminant_value": "SPONTANEOUS"
160+
}
161+
]
162+
},
163+
{
164+
// An OpenBao server can be configured to allow SSO (using Open ID
165+
// Connect) authentication for users.
166+
// This is done by storing an opaque key on the OpenBao server that is
167+
// itself typically used to encrypt the local device keys.
168+
//
169+
// Obviously the level of security is lower than traditional approaches
170+
// (e.g. storing the opaque key on the OS Keyring or derive it from a
171+
// strong password).
172+
// However this is a trade-of to increase user-friendliness, the decision
173+
// whether or not to use this is to be made by the server administrator
174+
// according to its own threat model.
175+
"name": "OpenBaoConfig",
176+
"discriminant_field": "type",
177+
"variants": [
178+
{
179+
"name": "Disabled",
180+
"discriminant_value": "DISABLED"
181+
},
182+
{
183+
"name": "Enabled",
184+
"discriminant_value": "ENABLED",
185+
"fields": [
186+
{
187+
// Base URL to the OpenBao server
188+
"name": "server_url",
189+
"type": "String"
190+
},
191+
{
192+
"name": "secret",
193+
"type": "OpenBaoSecretConfig"
194+
},
195+
{
196+
"name": "auths",
197+
"type": "List<OpenBaoAuthConfig>"
198+
}
199+
]
200+
}
201+
]
202+
},
203+
{
204+
"name": "OpenBaoSecretConfig",
205+
"discriminant_field": "type",
206+
"variants": [
207+
{
208+
"name": "KV2",
209+
"discriminant_value": "KV2",
210+
"fields": [
211+
{
212+
// Basically secret are going to be fetched from
213+
// `<openbao_server_url>/<openbao_secret_mount_path>/data/<secret_path>`
214+
// see https://openbao.org/api-docs/secret/kv/kv-v2/#read-secret-version
215+
"name": "mount_path",
216+
"type": "String"
217+
}
218+
]
219+
}
220+
]
221+
},
222+
{
223+
"name": "OpenBaoAuthConfig",
224+
"fields": [
225+
{
226+
"name": "id",
227+
"type": "String"
228+
},
229+
{
230+
// Basically OIDC authentication is going to be done with
231+
// `<openbao_server_url>/<openbao_mount_path>/oidc/auth_url`
232+
// see https://openbao.org/api-docs/auth/jwt/#oidc-authorization-url-request
233+
"name": "mount_path",
234+
"type": "String"
235+
}
236+
]
237+
}
238+
]
239+
}
240+
]
241+
```
242+
243+
### 2.3 - Move `allowed_client_agent/account_vault_strategy` from organization-level to server-level config
244+
245+
Changes:
246+
247+
- Remove `allowed_client_agent/account_vault_strategy` from `list_organizations` (administration REST API)
248+
- Remove `allowed_client_agent/account_vault_strategy` from `events_listen` (authenticated API)
249+
- Remove `allowed_client_agent/account_vault_strategy` from `organization_self_list` (authenticated account API)
250+
- Remove `--organization-initial-allowed-client-agent/--organization-initial-account-vault-strategy` from `parsec run` server CLI command and replace them by `--allowed-client-agent/--account-config`.
251+
252+
### 2.4 - Add OpenBao configuration
253+
254+
Add `--openbao-server-url/--openbao-secret-mount-path/--openbao-auth-pro-connect/--openbao-auth-hexagone` to `parsec run` server CLI command.

0 commit comments

Comments
 (0)