Secret Management and Scoped Identities

Bounded lesson outcome

A secret is not merely a sensitive string. It is a security object with an owner, consumers, authorization scope, retrieval path, lifecycle, and audit evidence. The bounded outcome of this lesson is to design a local, inspectable model in which each synthetic service can access only the secret object and capability required for its task, secret material never enters evidence, and rotation/revocation is recorded as an observable state transition. The evidence destination is Secret Scope and Lifecycle Record v1, and the executable fixture is SEC010-LAB1.

This lesson does not claim that an environment variable automatically makes secret handling safe, that every organization should use one specific secret manager, that dynamic secrets exist in every environment, or that one universal rotation cadence is correct. A green local run is not production-security proof. Every identifier in the lab is opaque and synthetic; no real credential, token, password, key material, cloud account, or external secret-management target is used.

1. Secret value is not access authority

A common design error is to collapse possession of a secret value and authority to retrieve or use a secret into one concept. In a bounded design, a secret object has an identifier and a workload identity must satisfy an explicit policy before it receives the capability needed for its owned task. If wid-orders-api needs secret://orders-read-v1 to read order data, that need creates no authority over secret://batch-export-v1.

SEC010-LAB1 encodes that distinction with an entirely local policy fixture. It stores opaque object identifiers but no secret values. Positive Evidence is produced when the correct workload identity requests its own object with an allowed capability. Negative Evidence is produced when the same identity requests an unrelated object, a wildcard scope, or a capability outside its task and the decision is denied.

2. Inventory comes before rotation

Rotation cannot be defended if consumers and dependencies are unknown. Before saying that a secret was rotated, the owner needs to know the secret object, owning service, consuming workload identities, retrieval path, human-access expectation, lifecycle state, and evidence that the old reference became unusable. Without that inventory, rotation can create an outage or leave the old credential silently valid.

Secret Scope and Lifecycle Record v1 therefore carries Secret Object, Owning Service, Workload Identity, Required Capability, Allowed Access, Human Access?, Retrieval Path, Rotation-Revocation Evidence, Audit Fields, and Residual Risk. It deliberately has no secret-value field. Its purpose is to make the decision reviewable: which identity can touch which object, for what capability, by what path, and with what lifecycle evidence.

3. Prefer scoped workload identity over broad secret copying where supported

Copying credentials into source files, shared configuration, messages, or broadly readable artifacts expands blast radius and obscures ownership. Where the platform supports it, a scoped workload identity with automated retrieval can reduce unnecessary human handling and long-lived copied credentials. This is not a claim that all static secrets are forbidden; it means copying a credential is a risk decision rather than a convenient default.

The synthetic fixture gives an interactive API and a batch worker separate identities. The API can retrieve only the orders object. The batch worker can retrieve only the export-job object. A cross-service request must be denied. Wildcard secret access is also denied. Operational convenience is not sufficient justification for allowing every engineer or service to read all application secrets.

4. Human access is a distinct decision

An operator may need to start a job or trigger rotation without needing to read the secret itself. NO_DIRECT_READ and CAN_TRIGGER_ROTATION are different capabilities. A stronger boundary can expose the operational action while withholding secret material. The lesson models that boundary only with synthetic policy metadata; it never creates or handles a real human credential.

If direct human reading is actually required, the evidence should record why, how narrowly it is scoped, and what residual risk remains. Missing justification should not be silently converted into broad default access. Audit evidence should preserve identity and event metadata while excluding the secret value.

5. Rotation and revocation are two parts of one transition

Creating a new secret identifier is not sufficient rotation evidence. In this lab, a valid rotation transition requires the new identifier to become active, declared consumers to move to the new reference, the old identifier to be revoked, and an audit event to exist. If the old reference is still usable, lifecycle evidence is incomplete. If consumers were not updated, the system may fail or fall back to an unsafe path.

Positive rotation evidence therefore includes new_active=true, old_revoked=true, consumers_updated=true, and audit_event_present=true. Removing any invariant creates Negative Evidence and the transition must return DENY_ROTATION_INCOMPLETE. The model does not prescribe a global cadence; it tests the completeness of one bounded transition.

6. Revocation must be observable

Revocation should not be a decorative label. If an old secret identifier is revoked, a later use attempt for that identifier should be denied and the attempt should remain auditable. Evidence of attempted use of a revoked reference can support incident response, while the secret material itself must not appear in the log.

The local audit event records only identity_id, secret_id, decision, lifecycle_event, and a synthetic timestamp. Inputs named secret_value, plaintext, token, password, or similar are never copied into the evidence record. Redaction does not mean erasing the security decision; the decision metadata remains inspectable.

7. Audit without secret material

Audit should answer who or what accessed which secret object, what decision occurred, and which lifecycle event was involved. It should not duplicate the secret into another sensitive system. Secret scanning can help find exposed credentials, but scanning alone is not a complete secret-management program and does not replace inventory, access control, scoped retrieval, rotation, or revocation.

A deliberate negative probe passes an input containing a secret_value key to the audit builder. The output must omit that key and retain only allowed metadata. This demonstrates why “log everything for debugging” is not an acceptable shortcut around the secret boundary.

8. Retrieval path is part of the trust boundary

A secret may have a narrow IAM policy and still be exposed by a poor retrieval path. Placing a secret in a source repository, shared configuration file, or downloadable artifact can bypass the intended workload-identity boundary. In this lesson the retrieval path is represented only by a local synthetic reference; no external secret manager is contacted. The goal is to observe the decision rule, not to teach vendor configuration.

The policy fixture defines the exact object/capability pairs allowed for each identity. retrieve and use are separate capabilities. If a workload may retrieve an object but is not authorized for a requested capability, the request is denied. This avoids the assumption that visibility automatically implies unrestricted use.

9. Lifecycle from provisioning to retirement

The bounded lifecycle covers create/provision, scoped retrieval/use, rotate, revoke, and retire. Each stage needs an owner and observable evidence. There is no universal cadence in the lesson because different secrets protect different assets, have different consumers, and carry different recovery risks.

A strong lifecycle row does more than say “rotate monthly.” It identifies the object, consumers, trigger, evidence that the new reference became active, evidence that the old reference was revoked, and the residual risk. This moves the design from checklist language to an inspectable control model.

10. Positive Evidence

The baseline includes several positive observations. wid-orders-api can request its assigned orders secret object with an allowed capability. wid-batch-worker can request its export secret object. A complete synthetic rotation activates the new reference and revokes the old reference. Every observation is traceable to the local policy and fixture.

A useful record does not contain only ALLOW; it also records why access was allowed and which object/capability pair was evaluated. Evidence that cannot explain the decision is weak owner-review material.

11. Negative Evidence

Required negative evidence includes wildcard scope, unrelated-object access, a missing revocation step, a missing consumer-update step, and an attempt to insert secret material into audit output. These are harmless local probes; they do not attack a real secret system.

Negative evidence prevents the reasoning error “the happy path worked, therefore the policy is secure.” A bounded security claim must demonstrate at least one boundary rejection and preserve that denied path rather than deleting it after repair.

12. Changed-context transfer

The transfer task changes the consumer model. A synthetic batch worker and an interactive API have different capabilities and lifetimes. The learner must rebuild the scope instead of copying the baseline matrix. For each workload, the learner identifies required objects, human-access expectations, retrieval path, and rotation/revocation dependencies. The transfer template is intentionally blank so the decisive conclusion is not prefilled.

A short-lived batch worker may justify a temporary identity and narrow object scope. A long-running interactive API may have different rollout and rotation dependencies. These differences show why one global access matrix or rotation cadence is insufficient.

13. Assessment and blocking boundaries

The assessment includes retrieval, application, diagnosis, decision, and transfer. Application, diagnosis, and transfer are blocking. Answers must point to observed local evidence. Completion is not valid if the learner enters real secret material, permits wildcard access without justification, or treats a newly created reference as rotated while the old reference remains active.

AI support may suggest defensive probes after the learner states the objective and may organize observed synthetic outputs. It may not create real secrets, fabricate evidence, or make the final residual-risk and owner-acceptance decision.

14. Freshness and source boundary

Current claims are bound only to OWASP-SECRETS. That source is used for secret lifecycle, fine-grained least privilege, reducing unnecessary human handling through automation where suitable, rotation/revocation, and IAM scoping. Vendor-specific configuration remains out of scope. The frozen review due date is 2026-10-02; authoring occurs on 2026-09-16, and a voluntary current-source recheck remained within the same authority boundary.

15. Residual Risk

Even when every synthetic gate passes, production security has not been proven. Product-specific IAM behavior, deployment compromise, supply-chain risk, incident response, key-material protection, availability, and organizational operating procedures are outside this lab. Residual Risk must keep those limitations explicit.

16. Summary

The compact rule is: separate secret value from access authority; keep workload scope minimal; close rotation with revocation and consumer evidence; audit lifecycle metadata without secret material. Secret Scope and Lifecycle Record v1 must preserve both allowed and denied evidence, and the changed-context transfer must remain an independent learner decision.