Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 1 addition & 44 deletions contracts/api/v2/breaking-approvals.json
Original file line number Diff line number Diff line change
@@ -1,46 +1,3 @@
{
"approvals": [
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "758bc212b081efa8d4532211cf311e027e493fb36971a7b6c9dcf912f025a11e",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
},
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "a3a523da084f36d085bff481d94cebadd34aef3beb97b83d36fd24f79e813acc",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
},
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "d2fbcd692e1d26043b7f191350163753c9df6e86b9007a46204dbad0dd024922",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
},
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "6ab3919a77cf889c326d06ea05fbc49ce68490490a6cd850466928e6cb136c0e",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
},
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "db3bc0b9bc885edf79e8d775113459c401e27e0999625f46c949fbaf1f097240",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
},
{
"operation_id": "updateDownloadSubscription",
"change_id": "request-property-became-not-nullable",
"fingerprint": "ac753659fe85643f58ede9067603f9a00b4af6c911480a374c7471eb54b7f7a8",
"reason": "The handler already refuses null on every monitor patch field and docs/downloads-api.md says null is rejected; only the document claimed it was accepted. silo-apple omits nil fields, and silo-android and web do not call this operation.",
"approved_in": "#3535"
}
]
"approvals": []
}
6 changes: 3 additions & 3 deletions contracts/api/v2/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -16469,7 +16469,7 @@
"type": "string"
},
"config": {
"description": "Staged global configuration entries, unsaved, merged as updateAdminPluginInstallationConfig would merge them. Entries and fields not named here use the stored values; a declared non-secret field sent as null or a blank string is cleared so the plugin default applies; blank secret fields use the stored secret; clear_secrets drops it from the test",
"description": "Staged global configuration entries, unsaved, merged as updateAdminPluginInstallationConfig would merge them. Entries and fields not named here use the stored values; a declared non-secret field sent as null or a blank string is cleared so the plugin default applies; blank secret fields use the stored secret only while the rest of that entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered), otherwise only the secrets entered are used and stored top-level fields the schema does not declare are left out of that entry; clear_secrets drops it from the test",
"items": {
"$ref": "#/components/schemas/AdminPluginConfigWrite"
},
Expand Down Expand Up @@ -16823,7 +16823,7 @@
},
"value": {
"additionalProperties": true,
"description": "The entry's fields, merged over the stored entry. A declared non-secret top-level field sent as null or a blank string is removed so the plugin default applies; blank secret fields preserve the stored secret",
"description": "The entry's fields, merged over the stored entry. A declared non-secret top-level field sent as null or a blank string is removed so the plugin default applies; blank secret fields preserve the stored secret. A connection test reuses a stored secret only while the rest of the entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered); otherwise it also leaves out stored top-level fields the schema does not declare",
"type": "object",
"x-silo-extension-bag": "plugin-json-value"
}
Expand Down Expand Up @@ -109708,7 +109708,7 @@
},
"/api/v2/admin/plugins/installations/{id}/auth-binding/test": {
"post": {
"description": "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically.",
"description": "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A blank secret field reuses the stored secret only while the rest of that entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered); otherwise that entry is tested with only the secrets entered. The rule is per entry: stored entries not named here keep their secrets. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically.",
"operationId": "testAdminPluginAuthBinding",
"parameters": [
{
Expand Down
13 changes: 12 additions & 1 deletion docs/admin-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -3503,7 +3503,18 @@ so the plugin's default applies; fields the manifest does not declare (plugin-ow
are kept. Manifest-declared secret fields left blank keep their stored value, and a secret is
removed only when named in `clear_secrets`. The
connection test (`.../config/test` and the auth connection test) merges a staged entry the
same way without storing it. The server validates the merged entry against the
same way without storing it, with one difference: a blank secret reuses the stored secret
only while the entry is otherwise unchanged. Unchanged means no secret is typed and every
other field, after clears, matches the stored entry; a field the stored entry lacks
matches its declared default. A secret object or list (such as a map of servers with keys
inside) counts as typed whenever it is sent, because its contents are secret. A staged entry that changes a server URL, issuer, CA or any
other setting, or types a secret, is tested with only the secrets the administrator typed
and without undeclared stored top-level fields, so a destination changed in an entry never
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
receives the saved secrets that entry declares. An undeclared key stored inside a declared
object is kept, and an entry whose schema declares no secret is merged as a save would
merge it, undeclared stored fields included. The rule is per entry: the other stored entries go to the
plugin unchanged, so a plugin that keeps a credential in one entry and its destination in
another is not covered. The server validates the merged entry against the
plugin's schema and returns 422 with the plugin's own message on failure, then persists
under a compare-and-swap on the stored revision and stops the running plugin so it rebinds.
Success is 204. Repeating the same request converges on one stored entry, so the row is
Expand Down
2 changes: 1 addition & 1 deletion docs/auth-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -686,7 +686,7 @@ linking rule whether or not `network_sign_in` is served.
| `POST /admin/users/{id}/identities` (`createAdminUserIdentity`) | acting admin | Links by `installation_id` and the exact `external_subject`. Turns local password sign-in off unless the account is break-glass or the installation is a network identity provider. |
| `DELETE /admin/users/{id}/identities/{identity_id}` (`deleteAdminUserIdentity`) | acting admin | May leave the account without a sign-in method; setting a password with `updateAdminUser` turns its local password sign-in back on. |
| `PUT /admin/users/{id}` (`updateAdminUser`) | acting admin | `break_glass` sets or clears the flag: admin accounts only, and only the server Owner may change it (403 `permission_denied`). The Owner has it by default (set at first-run setup and on every ownership move) and may clear it on its own account. A `password` also turns the account's local password sign-in back on, so an admin other than the Owner may not set its own while its local sign-in is off (403 `permission_denied`). Demoting, disabling or clearing the last usable break-glass admin while local sign-in is off is 409 `break_glass_required`; so is deleting it (`deleteAdminUser`) or turning `auth.local_password_login` off without one (`updateAdminSettings`, `updateAdminSetting`). |
| `POST /admin/plugins/installations/{id}/auth-binding/test` (`testAdminPluginAuthBinding`) | acting admin | Sends staged `config` entries (blank secrets keep the stored value) to the plugin's `TestConnection`; answers `ok`, the plugin's `steps` and `callback_url`, the redirect URI to register at an OAuth provider (empty without a public URL). A plugin without a connection test, or a disabled installation, is 409. Not retried automatically. |
| `POST /admin/plugins/installations/{id}/auth-binding/test` (`testAdminPluginAuthBinding`) | acting admin | Sends staged `config` entries (blank secrets keep the stored value only while the rest of that entry is unchanged and no secret in it is typed) to the plugin's `TestConnection`; answers `ok`, the plugin's `steps` and `callback_url`, the redirect URI to register at an OAuth provider (empty without a public URL). A plugin without a connection test, or a disabled installation, is 409. Not retried automatically. |
| `PUT /admin/plugins/installations/{id}/auth-binding` (`updateAdminPluginAuthBinding`) | acting admin | Applies without a restart (`X-Silo-Restart-Required: false`). `auto_provision` defaults to true. Enabling a second binding of the same kind is 409 `provider_already_enabled`; one network identity binding may be enabled beside the one OIDC or LDAP binding. |
| `GET /admin/plugins/installations` (`listAdminPluginInstallations`) | acting admin | Each OAuth auth binding carries `callback_url` (the callback to register at the provider) and `post_logout_redirect_url` (`/login`, to register for provider logout), both on `server.public_url`; empty without a public URL and for a password provider. The other operations that answer an installation carry them too. |

Expand Down
6 changes: 4 additions & 2 deletions internal/apiv2/admin_plugin_configuration.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,12 @@ type AdminPluginConfigurationService interface {
// value. A declared non-secret top-level field sent as null or a blank string
// is removed, so the plugin's default applies; undeclared fields are never
// cleared that way. Manifest-declared secret fields left blank keep their
// stored value; a secret is removed only when named in clear_secrets.
// stored value; a secret is removed only when named in clear_secrets. A
// connection test keeps a stored secret only while the rest of the entry is
// unchanged and no secret in it is entered.
type AdminPluginConfigWrite struct {
Key string `json:"key" minLength:"1" maxLength:"256" doc:"The manifest global_config_schema key"`
Value PluginJSONValue `json:"value" doc:"The entry's fields, merged over the stored entry. A declared non-secret top-level field sent as null or a blank string is removed so the plugin default applies; blank secret fields preserve the stored secret"`
Value PluginJSONValue `json:"value" doc:"The entry's fields, merged over the stored entry. A declared non-secret top-level field sent as null or a blank string is removed so the plugin default applies; blank secret fields preserve the stored secret. A connection test reuses a stored secret only while the rest of the entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered); otherwise it also leaves out stored top-level fields the schema does not declare"`
ClearSecrets []string `json:"clear_secrets,omitempty" maxItems:"64" doc:"Secret fields to remove; each must be a manifest-declared secret of this key"`
}
type AdminPluginConfigInput struct {
Expand Down
4 changes: 2 additions & 2 deletions internal/apiv2/external_sign_in.go
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ type AdminPluginAuthBindingTestInput struct {
RawBody []byte
Body struct {
CapabilityID string `json:"capability_id,omitempty" maxLength:"256" doc:"auth_provider.v1 capability to test; empty tests the plugin's first one"`
Config []AdminPluginConfigWrite `json:"config,omitempty" maxItems:"64" doc:"Staged global configuration entries, unsaved, merged as updateAdminPluginInstallationConfig would merge them. Entries and fields not named here use the stored values; a declared non-secret field sent as null or a blank string is cleared so the plugin default applies; blank secret fields use the stored secret; clear_secrets drops it from the test"`
Config []AdminPluginConfigWrite `json:"config,omitempty" maxItems:"64" doc:"Staged global configuration entries, unsaved, merged as updateAdminPluginInstallationConfig would merge them. Entries and fields not named here use the stored values; a declared non-secret field sent as null or a blank string is cleared so the plugin default applies; blank secret fields use the stored secret only while the rest of that entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered), otherwise only the secrets entered are used and stored top-level fields the schema does not declare are left out of that entry; clear_secrets drops it from the test"`
}
}

Expand Down Expand Up @@ -593,7 +593,7 @@ func registerExternalSignIn(reg *Registry) {

test := Operation{Operation: humaOp(http.MethodPost, Prefix+"/admin/plugins/installations/{id}/auth-binding/test", "testAdminPluginAuthBinding", "admin-plugins",
"Test an auth plugin's connection with staged, unsaved settings."), Class: ClassActingAdmin, DemoRestricted: true, ServiceBacked: true, RetrySafety: RetrySafetyNonRetryable}
test.Description = "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically."
test.Description = "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A blank secret field reuses the stored secret only while the rest of that entry is unchanged and no secret in it is entered (a secret object or list sent in it counts as entered); otherwise that entry is tested with only the secrets entered. The rule is per entry: stored entries not named here keep their secrets. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically."
test.Errors = []int{http.StatusNotFound, http.StatusConflict}
Register(reg, test, func(ctx context.Context, in *AdminPluginAuthBindingTestInput) (*AuthConnectionTestOutput, error) {
if reg.deps.ExternalSignIn == nil || !reg.deps.ExternalSignIn.ConnectionTestAvailable() {
Expand Down
Loading
Loading