captured admin.plugin-enable

Enable and disable an AuthMethod plugin in a realm

An admin of the realm asks the admin API to enable an installed plugin. The pipeline checks the permission plugins.security, which only a token with qauth:admin:security uses, then the approval the request names; the handler checks that the plugin is installed, that the state is the one the request was written against, and that the realm's config of the plugin passes the plugin's own schema, then turns it on. While it is on, the plugin's routes under /upstream/<type> answer on the realm host; off, they answer the not_found document of a path no route serves. Disabling takes the same checks but the config one, and keeps the config.

What this view shows

one admin enabling, then disabling, one installed plugin in one realm, and the plugin's routes in between.

Open world: what is not drawn here is not ruled out. Only the guarantees below are binding.

Left out of this view:

loading the plugin at boot (AUTH_METHOD_PLUGINS, the PLUGIN_API_ENABLED switch, the first-party list): a plugin the boot did not load is not installed, and the admin API answers 404 for it
configuring the plugin (plugins.update, naming the version it replaces): its secret members, sealed first by plugins.secrets.seal with the realm data_at_rest key and named apart from the plain ones, so no approval holds a value in the clear, and the schema check of the whole config
filing and giving the approval (approvals.create, the approval page, the factor), and the token guard and realm lookup of the admin pipeline, which run before every state drawn here
what a plugin's callback does once its route answers: the upstream step (#599) and the sign-in flow (#639)

The main story

When: Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema.

The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable
Check the permission and the approval of the enable: the caller holds the permission and the approval, which the handler transaction consumes
Check the plugin, its state and its config, and turn it on: the row is written enabled, conditional on its version, and the audit row records the change
The plugin is on in the realm: a browser requests one of the plugin's routes on the realm host

Result: Hand the request to the plugin's route.

The flow

Show failure paths and “the user closes the page”

blue line: the main storydotted line: decided by a rule, nobody actsdashed grey box: the server decides, nothing is shown

What each step answers

Step	The outside world sees
Answer the plugin's route as a path no route serves not_found.plugin_off	404 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#not-found","status":404,"code":"not_found"}
Hand the request to the plugin's route bad_request.no_pending_sign_in	400 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#bad-request","status":400,"code":"bad_request"}
Refuse a caller whose role lacks the permission forbidden.no_permission	403 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#forbidden","status":403,"code":"forbidden"}
Refuse a token without qauth:admin:security, naming the scope insufficient_scope.no_security_scope	403 · headers: {"WWW-Authenticate":"Bearer realm=\"OAuth\", error=\"insufficient_scope\", scope=\"qauth:admin:security\""} · body: {"type":"https://docs.qauth.dev/reference/problem-types/#forbidden","status":403,"code":"forbidden"}
Refuse a security operation without its approval approval_required.no_approval	403 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#approval-required","status":403,"code":"approval_required"}
Refuse a plugin the deployment did not load not_found.plugin_unknown	404 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#not-found","status":404,"code":"not_found"}
Refuse a request written against another state precondition_failed.state_moved	412 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#precondition-failed","status":412,"code":"precondition_failed"}
Refuse to enable a plugin whose config its schema refuses bad_request.config_invalid	400 · body: {"type":"https://docs.qauth.dev/reference/problem-types/#bad-request","status":400,"code":"bad_request"}

How it decides what happens next

Check the permission and the approval of the enable

#	If	Then
1	the role lacks the permission: no token would pass, and the challenge names no scope	Refuse a caller whose role lacks the permission
2	only the token withholds the permission: qauth:admin:write is refused	Refuse a token without qauth:admin:security, naming the scope
3	no approval for exactly this request: the operation never runs	Refuse a security operation without its approval
4	the caller holds the permission and the approval, which the handler transaction consumes	Check the plugin, its state and its config, and turn it on

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`roleLacksPermission`	`forbidden.no_permission`	16 of 48
2	`scopeLacksSecurity`	`insufficient_scope.no_security_scope`	16 of 48
3	`noApproval`	`approval_required.no_approval`	8 of 48
4	otherwise	`enabling`	8 of 48

roleLacksPermission: caller == 'noSecurityRole'
scopeLacksSecurity: caller == 'writeScopeOnly'
noApproval: approval == 'missing'

Check the plugin, its state and its config, and turn it on

#	If	Then
1	the path names no installed plugin	Refuse a plugin the deployment did not load
2	the state moved since the caller read it, or its approver saw it: the body names the version the approval binds	Refuse a request written against another state
3	the realm's config does not pass the plugin's schema: a plugin is on only with a config it accepts	Refuse to enable a plugin whose config its schema refuses
4	the row is written enabled, conditional on its version, and the audit row records the change	The plugin is on in the realm

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`pluginUnknown`	`not_found.plugin_unknown`	4 of 8
2	`stateMoved`	`precondition_failed.state_moved`	2 of 8
3	`configInvalid`	`bad_request.config_invalid`	1 of 8
4	otherwise	`pluginOn`	1 of 8

pluginUnknown: plugin == 'unknown'
stateMoved: stateMatch == 'moved'
configInvalid: config == 'invalid'

Check the permission and the approval of the disable

#	If	Then
1	the role lacks the permission	Refuse a caller whose role lacks the permission
2	only the token withholds the permission	Refuse a token without qauth:admin:security, naming the scope
3	no approval for exactly this request	Refuse a security operation without its approval
4	the caller holds the permission and the approval	Check the plugin and its state, and turn it off

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`roleLacksPermission`	`forbidden.no_permission`	0 of 1
2	`scopeLacksSecurity`	`insufficient_scope.no_security_scope`	0 of 1
3	`noApproval`	`approval_required.no_approval`	0 of 1
4	otherwise	`disabling`	1 of 1

roleLacksPermission: caller == 'noSecurityRole'
scopeLacksSecurity: caller == 'writeScopeOnly'
noApproval: approval == 'missing'

Check the plugin and its state, and turn it off

#	If	Then
1	the path names no installed plugin	Refuse a plugin the deployment did not load
2	the state moved since the caller read it	Refuse a request written against another state
3	the row is written off, its config kept, conditional on its version	The plugin is off again, its config kept

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`pluginUnknown`	`not_found.plugin_unknown`	0 of 1
2	`stateMoved`	`precondition_failed.state_moved`	0 of 1
3	otherwise	`pluginOffAgain`	1 of 1

pluginUnknown: plugin == 'unknown'
stateMoved: stateMatch == 'moved'

Every way it can end

It ends with	When	What happens
Answer the plugin's route as a path no route serves ends here	Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: a browser requests one of the plugin's routes under /upstream/<type> on the realm host
Hand the request to the plugin's route ends here	Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: the caller holds the permission and the approval, which the handler transaction consumes Check the plugin, its state and its config, and turn it on: the row is written enabled, conditional on its version, and the audit row records the change The plugin is on in the realm: a browser requests one of the plugin's routes on the realm host
Refuse a caller whose role lacks the permission ends here	Its role holds no security permission, such as an editor, whatever its token carries, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: the role lacks the permission: no token would pass, and the challenge names no scope
Refuse a token without qauth:admin:security, naming the scope ends here	Its role holds plugins.security, and its token carries qauth:admin:write but not qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: only the token withholds the permission: qauth:admin:write is refused
Refuse a security operation without its approval ends here	Its role holds plugins.security and its token carries qauth:admin:security, it names none, or one for another request, or one not approved, expired or used, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: no approval for exactly this request: the operation never runs
Refuse a plugin the deployment did not load ends here	Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, it names no loaded plugin, the body's version, and If-Match when present, name the version of the plugin state the handler reads, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: the caller holds the permission and the approval, which the handler transaction consumes Check the plugin, its state and its config, and turn it on: the path names no installed plugin
Refuse a request written against another state ends here	Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body or If-Match names another version: the state changed since the caller read it, or since its approval was filed, the realm's config of the plugin, its secrets decrypted, passes the plugin's config schema	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: the caller holds the permission and the approval, which the handler transaction consumes Check the plugin, its state and its config, and turn it on: the state moved since the caller read it, or its approver saw it: the body names the version the approval binds
Refuse to enable a plugin whose config its schema refuses ends here	Its role holds plugins.security and its token carries qauth:admin:security, QAuth-Approval names an approval filed for exactly this request by this caller, approved and unexpired, the path names a plugin this deployment loaded at boot, the body's version, and If-Match when present, name the version of the plugin state the handler reads, it does not, or the realm never configured the plugin	The plugin is off in the realm: an admin sends POST /admin/v1-rc.0/realms/{realmId}/plugins/{plugin}/enable Check the permission and the approval of the enable: the caller holds the permission and the approval, which the handler transaction consumes Check the plugin, its state and its config, and turn it on: the realm's config does not pass the plugin's schema: a plugin is on only with a config it accepts

Each row is also a generated test: set the starting situation, send the events, expect the ending.

What is guaranteed

These hold in all 204 situations the model can reach, from 48 different starting situations.

A token that carries qauth:admin:write but not qauth:admin:security never turns a plugin on
A plugin is turned on only by a request an approval was given for
A plugin is on only with a config its own schema accepts
A plugin's route reaches the plugin only while the realm has it on
Only an authorized, approved request turns a plugin off

Exact rules

Id	Never
`write-scope-never-enables`	`enabled and scopeLacksSecurity`
`no-enable-without-approval`	`enabled and noApproval`
`no-enable-with-a-refused-config`	`enabled and configInvalid`
`an-off-plugin-runs-nothing`	`state == 'bad_request.no_pending_sign_in' and not enabled`
`a-refused-disable-leaves-it-on`	`state == 'pluginOffAgain' and (roleLacksPermission or scopeLacksSecurity or noApproval)`

Reference

All transitions (20)

From	Event	Guard	To	Effects	Taken
`pluginOff`	`ENABLE`		`authorizingEnable`		yes
`pluginOff`	`ROUTE_REQUEST`		`not_found.plugin_off`		yes
`authorizingEnable`	`rule 1`	`roleLacksPermission`	`forbidden.no_permission`		yes
`authorizingEnable`	`rule 2`	`scopeLacksSecurity`	`insufficient_scope.no_security_scope`		yes
`authorizingEnable`	`rule 3`	`noApproval`	`approval_required.no_approval`		yes
`authorizingEnable`	`rule 4`		`enabling`		yes
`enabling`	`rule 1`	`pluginUnknown`	`not_found.plugin_unknown`		yes
`enabling`	`rule 2`	`stateMoved`	`precondition_failed.state_moved`		yes
`enabling`	`rule 3`	`configInvalid`	`bad_request.config_invalid`		yes
`enabling`	`rule 4`		`pluginOn`	`turnOn`	yes
`pluginOn`	`ROUTE_REQUEST`		`bad_request.no_pending_sign_in`		yes
`pluginOn`	`DISABLE`		`authorizingDisable`		yes
`authorizingDisable`	`rule 1`	`roleLacksPermission`	`forbidden.no_permission`		never
`authorizingDisable`	`rule 2`	`scopeLacksSecurity`	`insufficient_scope.no_security_scope`		never
`authorizingDisable`	`rule 3`	`noApproval`	`approval_required.no_approval`		never
`authorizingDisable`	`rule 4`		`disabling`		yes
`disabling`	`rule 1`	`pluginUnknown`	`not_found.plugin_unknown`		never
`disabling`	`rule 2`	`stateMoved`	`precondition_failed.state_moved`		never
`disabling`	`rule 3`		`pluginOffAgain`	`turnOff`	yes
`pluginOffAgain`	`ROUTE_REQUEST`		`not_found.plugin_off`		yes