Rhythm 2.0 Specifications

Appearance

CAP-PFM-SEC-018Suspend and resume service principals

Markdown

CAP-PFM-SEC-018

Suspend and resume service principals

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-SEC-05
Exercised by
FAS-PFM-SEC-05-01, FAS-PFM-SEC-05-04, FAS-PFM-SEC-05-05
Key concepts
CON-PFM-SEC-003
Actors
ACT-PFM-004, ACT-PFM-005, ACT-PFM-006
Related
CAP-PFM-SEC-015, CAP-PFM-SEC-016
Proved by
ATS-PFM-SEC-018

Implementation

Executable suites
TST-PFM-SEC-177, TST-PFM-SEC-184, TST-PFM-SEC-185

KindCapabilityProduct areaPlatformModuleSecurity, Customers and WorkspacesRevision1

Read atservices-platform ad3f6a65

Suspend and resume service principals ​

Purpose ​

HQ operations can change a service principal’s status. Receiving services that consult the registry use that status to refuse suspended callers without a deployment.

How It Works ​

An authorized staff reader obtains the principal list through HQ operations. A manager suspends or resumes a registered principal and receives the resulting record. The operation preserves audit history for real changes and reports invalid or missing identifiers. Receiving handlers that consult the registry act on its status after their cache refresh. Release activation adds missing principals without undoing an operator’s suspension. The product should add a console page so staff can perform this work through an operator screen.

Relationships ​

  • Request enforcement governs service-function authorization.
  • HQ staff administration identifies the operator’s authority.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Operators can change registry status without redeploying a caller.Historical service activity retains a readable principal name.
Surfaces
apijob
Intent sources
services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch

Controls

38 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-004 TC-IAM-001 TC-IAM-003 TC-IAM-006 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
hq.service-principals.readapiglobal
hq.service-principals.manageapiglobal

Business Rules

7 rules, 5 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
The HQ principal list returns registered principals with their kind and status to authorized staff readers. Customer Administrator authority cannot read it.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
proved by ATS-PFM-SEC-018-01, ATS-PFM-SEC-018-09, TST-PFM-SEC-184
permissionapitest
services-platform:modules/security/tests/integration/services/service-principals/hq-service-principals-routes.integration.spec.js#refuses a customer's administrator 403, holding every key of their own customer
02must prove
Proposed
Suspension and resumption require the principal-management key, assigned to Rhythm Administrator. A status change records its before and after values, with resumption marked as widening. Repeating the current status changes neither the principal nor its audit history.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
proved by ATS-PFM-SEC-018-02, ATS-PFM-SEC-018-06, ATS-PFM-SEC-018-07, TST-PFM-SEC-184
permissionapi, servicetest
services-platform:modules/security/tests/integration/services/service-principals/hq-service-principals-routes.integration.spec.js#answers a second suspension 200 and records nothing more, the principal being suspended already
03must prove
Proposed
An unknown valid principal identifier returns not found and produces a refusal audit event. An identifier outside the accepted grammar returns an invalid-request response.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
proved by ATS-PFM-SEC-018-03, TST-PFM-SEC-184
validationapi, servicetest
services-platform:modules/security/tests/integration/services/service-principals/hq-service-principals-routes.integration.spec.js#records the refused suspension of that id, naming the staff member
04must prove
Proposed
A receiving service that reads the principal registry rejects suspended callers after its one-minute registry cache refresh. Resumption permits eligible calls again; neither change requires deployment.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
proved by ATS-PFM-SEC-015-15, ATS-PFM-SEC-018-04, ATS-PFM-SEC-018-08, TST-PFM-SEC-185
policyservicetest
services-platform:modules/security/tests/integration/services/service-principals/registered-principals.integration.spec.js#is refused 403
05must prove
Proposed
Activation inserts configured principals missing from the registry as active. It does not rename, remove or change existing principals, including suspended ones. Reconciliation failure is reported without stopping activation.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
proved by ATS-PFM-SEC-018-05, TST-PFM-SEC-177
lifecycleservicetest
services-platform:modules/security/tests/integration/services/provisioning/ensure-service-principals.integration.spec.js#leaves it suspended, under its stored name, at its version
06
Proposed
Principal records cannot be deleted. Display-name readers identify their historical writes using the principal’s display name followed by “(service)”.
origin: services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch
invariantdatabasedocumented
services-platform:docs/security/service-calls.md#2.1 Names: the third branch of platform.current_and_former_users
07
Proposed
A principal-management screen remains a product proposal; the console currently has no page that invokes these HQ operations.
policyconsoleunknown
FND-PFM-SEC-014

Scenarios

IdGivenWhenThenProvenance
01A registered integration principal is producing unwanted calls.An authorized HQ administrator suspends it and later resumes it.Receiving services that consult the registry reject it after cache refresh and permit eligible calls after resumption.test
services-platform:modules/security/tests/integration/services/service-principals/registered-principals.integration.spec.js#is refused 403

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software