--- id: CAP-PFM-SEC-018 title: Suspend and resume service principals feature: FEAT-PFM-SEC-05 product_area: platform module: security revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 intent_sources: - >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch 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. outcomes: - Operators can change registry status without redeploying a caller. - Historical service activity retains a readable principal name. concepts: - CON-PFM-SEC-003 actors: - ACT-PFM-004 - ACT-PFM-005 - ACT-PFM-006 surfaces: - api - job preconditions: [] postconditions: [] permissions: - key: hq.service-principals.read where_checked: api scope: global - key: hq.service-principals.manage where_checked: api scope: global rules: - id: BR-CAP-PFM-SEC-018-01 proved_by: [ATS-PFM-SEC-018-01, ATS-PFM-SEC-018-09, TST-PFM-SEC-184] statement: >- The HQ principal list returns registered principals with their kind and status to authorized staff readers. Customer Administrator authority cannot read it. kind: permission enforced_at: - api must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-02 proved_by: [ATS-PFM-SEC-018-02, ATS-PFM-SEC-018-06, ATS-PFM-SEC-018-07, TST-PFM-SEC-184] statement: >- 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. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-03 proved_by: [ATS-PFM-SEC-018-03, TST-PFM-SEC-184] statement: >- 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. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-04 proved_by: [ATS-PFM-SEC-015-15, ATS-PFM-SEC-018-04, ATS-PFM-SEC-018-08, TST-PFM-SEC-185] statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/service-principals/registered-principals.integration.spec.js#is refused 403 origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-05 proved_by: [ATS-PFM-SEC-018-05, TST-PFM-SEC-177] statement: >- 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. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/provisioning/ensure-service-principals.integration.spec.js#leaves it suspended, under its stored name, at its version origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-06 proved_by: [] statement: >- Principal records cannot be deleted. Display-name readers identify their historical writes using the principal’s display name followed by “(service)”. kind: invariant enforced_at: - database must_prove: false provenance: documented source: >- services-platform:docs/security/service-calls.md#2.1 Names: the third branch of platform.current_and_former_users origin: >- services-platform:docs/security/service-calls.md#Service calls: the service-principal registry and the kill switch - id: BR-CAP-PFM-SEC-018-07 proved_by: [] statement: >- A principal-management screen remains a product proposal; the console currently has no page that invokes these HQ operations. kind: policy enforced_at: - console must_prove: false provenance: unknown source: FND-PFM-SEC-014 origin: none scenarios: - id: SC-CAP-PFM-SEC-018-01 given: A registered integration principal is producing unwanted calls. when: An authorized HQ administrator suspends it and later resumes it. then: >- Receiving services that consult the registry reject it after cache refresh and permit eligible calls after resumption. provenance: test source: >- services-platform:modules/security/tests/integration/services/service-principals/registered-principals.integration.spec.js#is refused 403 edge_cases: [] constraints: [] depends_on: [] related: - CAP-PFM-SEC-015 - CAP-PFM-SEC-016 journeys: [] open_questions: [] evidence: - >- Pinned services-platform references for the structured rows: docs/security/service-calls.md; modules/security/tests/integration/services/provisioning/ensure-service-principals.integration.spec.js; modules/security/tests/integration/services/service-principals/hq-service-principals-routes.integration.spec.js; modules/security/tests/integration/services/service-principals/registered-principals.integration.spec.js. controls: [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] exercised_by: [FAS-PFM-SEC-05-01, FAS-PFM-SEC-05-04, FAS-PFM-SEC-05-05] suites: [TST-PFM-SEC-177, TST-PFM-SEC-184, TST-PFM-SEC-185] --- # 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.