master
607e72e2a1
Some checks failed
Build Test Deploy / docs (push) Has been cancelled
Build Test Deploy / deploy (push) Has been cancelled
Build Test Deploy / build-test (push) Has been cancelled
Build Test Deploy / authority-container (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
48 lines
2.9 KiB
Markdown
48 lines
2.9 KiB
Markdown
# StellaOps Authority Audit Events
|
|
|
|
StellaOps Authority emits structured audit records for every credential flow and bootstrap operation. The goal is to provide deterministic, privacy-aware telemetry that can be persisted offline and replayed for incident response without leaking credentials.
|
|
|
|
## Contract
|
|
|
|
Audit events share the `StellaOps.Cryptography.Audit.AuthEventRecord` contract. Key fields:
|
|
|
|
- `EventType` — canonical identifier such as `authority.password.grant`, `authority.client_credentials.grant`, or `authority.bootstrap.user`.
|
|
- `OccurredAt` — UTC timestamp captured at emission time.
|
|
- `CorrelationId` — stable identifier propagated across logs and persistence.
|
|
- `Outcome` — `Success`, `Failure`, `LockedOut`, `RateLimited`, or `Error`.
|
|
- `Reason` — optional failure or policy message.
|
|
- `Subject` — `AuthEventSubject` carrying subject identifier, username, display name, and optional realm metadata. All subject fields are tagged as PII.
|
|
- `Client` — `AuthEventClient` with client identifier, display name, and originating provider/plugin.
|
|
- `Scopes` — granted or requested OAuth scopes (sorted before emission).
|
|
- `Network` — `AuthEventNetwork` with remote address, forwarded headers, and user agent string (all treated as PII).
|
|
- `Properties` — additional `AuthEventProperty` entries for context-specific details (lockout durations, policy decisions, retries, etc.).
|
|
|
|
## Data Classifications
|
|
|
|
Every string value uses `ClassifiedString` to assign a data classification:
|
|
|
|
- `None` — public or operational metadata (event type, outcome).
|
|
- `Personal` — personally identifiable information (PII) such as subject identifiers, usernames, remote IP addresses, and user agents.
|
|
- `Sensitive` — secrets or derived credentials (client secrets, retry tokens). Avoid storing raw credentials; emit only hashed or summarised data when the classification is `Sensitive`.
|
|
|
|
Downstream log sinks and persistence layers can inspect classifications to redact or separate PII before export.
|
|
|
|
## Event Naming
|
|
|
|
Event names follow dotted notation:
|
|
|
|
- `authority.password.grant` — password grant handled by OpenIddict.
|
|
- `authority.client_credentials.grant` — client credential grant handling.
|
|
- `authority.bootstrap.user` and `authority.bootstrap.client` — bootstrap API operations.
|
|
- Future additions should preserve the `authority.<surface>.<action>` pattern to keep filtering deterministic.
|
|
|
|
## Persistence
|
|
|
|
The Authority host converts audit records into `AuthorityLoginAttemptDocument` rows for MongoDB persistence. Documents must:
|
|
|
|
- Preserve `CorrelationId`, `SubjectId`, `ClientId`, `Plugin`, `Outcome`, `Reason`, and `OccurredAt`.
|
|
- Store remote address in `remoteAddress` only after classification as PII.
|
|
- Include summary booleans such as `Successful` to accelerate lockout policy checks.
|
|
|
|
When exporting to external SIEMs, honour the `ClassifiedString.Classification` tag to avoid shipping PII into restricted environments.
|