54 lines
3.6 KiB
Markdown
54 lines
3.6 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, `request.tampered`/`request.unexpected_parameter`, `bootstrap.invite_token`, 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.token.tamper` — suspicious `/token` request detected (unexpected parameters or manipulated payload).
|
|
- `authority.bootstrap.user` and `authority.bootstrap.client` — bootstrap API operations.
|
|
- `authority.bootstrap.invite.created` — operator created a bootstrap invite.
|
|
- `authority.bootstrap.invite.consumed` — invite consumed during user/client provisioning.
|
|
- `authority.bootstrap.invite.expired` — invite expired without being used.
|
|
- `authority.bootstrap.invite.rejected` — invite was rejected (invalid, mismatched provider/target, or already consumed).
|
|
- `authority.token.replay.suspected` — replay heuristics detected a token being used from a new device fingerprint.
|
|
- 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.
|