generated from coulomb/repo-seed
118 lines
4.3 KiB
Markdown
118 lines
4.3 KiB
Markdown
# Pattern: STS Credential Vending
|
|
|
|
Status: reviewed
|
|
Readiness target: RL3 production
|
|
Primary owners: NetKingdom, flex-auth, Railiance platform
|
|
|
|
## Problem
|
|
|
|
Applications need object-storage access, but long-lived access keys in
|
|
application pods, repositories, or tenant namespaces create a durable
|
|
compromise path. Provider-specific bucket policy alone is not enough for
|
|
NetKingdom because access decisions must include identity, tenant,
|
|
resource, action, TTL, assurance, and audit context.
|
|
|
|
## Context
|
|
|
|
Use this pattern when a workload, service, agent, or human needs
|
|
temporary access to S3-compatible object storage. The first target
|
|
consumer is `artifact-store`, but the pattern is intended for any
|
|
NetKingdom-enabled platform or tenant workload.
|
|
|
|
The pattern applies across AWS S3, Ceph RGW, MinIO/AIStor, Cloudflare R2,
|
|
and OpenBao-assisted broker paths.
|
|
|
|
## Forces
|
|
|
|
- Provider-native STS gives strong backend expiration semantics, but
|
|
providers differ in API shape and OIDC support.
|
|
- Applications need a simple credential contract, but security decisions
|
|
require rich context.
|
|
- OpenBao can protect parent credentials and audit broker operations, but
|
|
must not become the authorization policy engine.
|
|
- Tenant administrators need self-service within tenant scope, but must
|
|
not receive platform-root object-store or OpenBao authority.
|
|
- Temporary credentials reduce blast radius, but consumers must refresh
|
|
safely and support session tokens.
|
|
|
|
## Solution
|
|
|
|
Introduce a credential-vending service that accepts a NetKingdom IAM
|
|
Profile token or workload identity, asks flex-auth for an authorization
|
|
decision, and exchanges approved requests for provider-native temporary
|
|
credentials or an OpenBao-assisted broker path.
|
|
|
|
The consumer receives normalized credentials:
|
|
|
|
```text
|
|
access key id
|
|
secret access key
|
|
session token
|
|
expiration
|
|
scope metadata
|
|
decision/audit correlation id
|
|
```
|
|
|
|
## Implementation Sketch
|
|
|
|
1. Caller authenticates through key-cape or Keycloak.
|
|
2. Credential-vending service validates issuer, audience, subject,
|
|
tenant, expiration, and assurance evidence.
|
|
3. Service builds a flex-auth request with protected-system id, bucket,
|
|
prefix/object, actions, TTL, actor, tenant, and context.
|
|
4. flex-auth evaluates policy, delegated to Topaz where appropriate.
|
|
5. Deny returns a stable reason code and audit id.
|
|
6. Allow invokes backend exchange:
|
|
- AWS STS `AssumeRoleWithWebIdentity`;
|
|
- Ceph RGW STS;
|
|
- MinIO/AIStor STS;
|
|
- Cloudflare R2 temporary credential API;
|
|
- OpenBao-assisted broker path for protected parent material.
|
|
7. Service records identity, policy, backend, lease, and audit metadata.
|
|
8. Consumer refreshes before expiration.
|
|
|
|
## Failure Modes
|
|
|
|
| Failure | Mitigation |
|
|
| --- | --- |
|
|
| Consumer lacks `AWS_SESSION_TOKEN` support | keep static bridge only as transitional; add session token refs |
|
|
| flex-auth unavailable | fail closed except documented emergency platform workflows |
|
|
| OpenBao unavailable | fail if parent material or broker config is required |
|
|
| Backend STS unavailable | return retryable backend error; do not fall back to root credentials |
|
|
| Tenant mismatch | deny with stable reason code |
|
|
| TTL too long | reduce to policy maximum or deny |
|
|
| Audit sink unavailable | deny privileged/platform-scoped requests; buffer only if policy permits |
|
|
|
|
## Related Capabilities
|
|
|
|
- Object storage access.
|
|
- Authorization and access control.
|
|
- Secrets, keys, and credentials.
|
|
- Tenant isolation.
|
|
- Observability, detection, and audit.
|
|
|
|
## Maturity
|
|
|
|
Reviewed. The pattern has architecture and ADR coverage in NetKingdom.
|
|
It should not be marked canonical until artifact-store temporary session
|
|
token support and at least one backend exchange path are verified.
|
|
|
|
## Verification
|
|
|
|
- IAM Profile validation rejects wrong issuer or audience.
|
|
- flex-auth decision includes tenant, protected system, bucket/prefix,
|
|
action set, TTL, obligations, and deny reason.
|
|
- Backend returns access key id, secret access key, session token, and
|
|
expiration.
|
|
- OpenBao audit record exists when parent material or broker config is
|
|
accessed.
|
|
- Consumer refreshes before expiration.
|
|
- Deny paths emit stable reason codes.
|
|
|
|
## References
|
|
|
|
- NetKingdom `docs/object-storage-sts-credential-vending.md`.
|
|
- NetKingdom `ADR-0008 - Object Storage STS Credential Vending Boundary`.
|
|
- Railiance Platform `docs/openbao.md`.
|
|
- Artifact-store `ARTIFACT-STORE-WP-0007`.
|