feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration
- Add RateLimitConfig for configuration management with YAML binding support. - Introduce RateLimitDecision to encapsulate the result of rate limit checks. - Implement RateLimitMetrics for OpenTelemetry metrics tracking. - Create RateLimitMiddleware for enforcing rate limits on incoming requests. - Develop RateLimitService to orchestrate instance and environment rate limit checks. - Add RateLimitServiceCollectionExtensions for dependency injection registration.
This commit is contained in:
master
@@ -17,25 +17,25 @@ Authority hosts follow a deterministic plug-in lifecycle. The exported diagram (
|
||||
3. **Registrar execution** – each assembly is searched for `IAuthorityPluginRegistrar` implementations. Registrars bind options, register services, and optionally queue bootstrap tasks.
|
||||
4. **Runtime** – the host resolves `IIdentityProviderPlugin` instances, uses capability metadata to decide which OAuth grants to expose, and invokes health checks for readiness endpoints.
|
||||
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-lifecycle.mmd`
|
||||
|
||||
### 2.1 Component boundaries
|
||||
|
||||
The Standard plug-in ships with a small, opinionated surface: configuration is bound during registrar execution, capability metadata feeds the host, and credential/audit flows stay deterministic and offline-friendly. The component view below highlights those boundaries and where operators supply bundles (secrets, offline kits) for air-gapped installs.
|
||||
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-component.mmd`
|
||||
|
||||
**Data persistence primer:** the standard Mongo-backed plugin stores users in collections named `authority_users_<pluginName>` and lockout metadata in embedded documents. Additional plugins must document their storage layout and provide deterministic collection naming to honour the Offline Kit replication process.
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-lifecycle.mmd`
|
||||
|
||||
### 2.1 Component boundaries
|
||||
|
||||
The Standard plug-in ships with a small, opinionated surface: configuration is bound during registrar execution, capability metadata feeds the host, and credential/audit flows stay deterministic and offline-friendly. The component view below highlights those boundaries and where operators supply bundles (secrets, offline kits) for air-gapped installs.
|
||||
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-component.mmd`
|
||||
|
||||
**Data persistence primer:** the standard PostgreSQL-backed plugin stores users in tables named `authority_users_<pluginName>` and lockout metadata in related records. Additional plugins must document their storage layout and provide deterministic table naming to honour the Offline Kit replication process.
|
||||
|
||||
## 3. Capability Metadata
|
||||
Capability flags let the host reason about what your plug-in supports:
|
||||
|
||||
- Declare capabilities in your descriptor using the string constants from `AuthorityPluginCapabilities` (`password`, `mfa`, `clientProvisioning`, `bootstrap`). The configuration loader now validates these tokens and rejects unknown values at startup.
|
||||
- `AuthorityIdentityProviderCapabilities.FromCapabilities` projects those strings into strongly typed booleans (`SupportsPassword`, `SupportsMfa`, `SupportsClientProvisioning`, `SupportsBootstrap`). Authority Core uses these flags when wiring flows such as the password grant, bootstrap APIs, and client provisioning. Built-in plugins (e.g., Standard) will fail fast or force-enable required capabilities if the descriptor is misconfigured, so keep manifests accurate.
|
||||
- `AuthorityIdentityProviderCapabilities.FromCapabilities` projects those strings into strongly typed booleans (`SupportsPassword`, `SupportsMfa`, `SupportsClientProvisioning`, `SupportsBootstrap`). Authority Core uses these flags when wiring flows such as the password grant, bootstrap APIs, and client provisioning. Built-in plugins (e.g., Standard) will fail fast or force-enable required capabilities if the descriptor is misconfigured, so keep manifests accurate.
|
||||
- Typical configuration (`etc/authority.plugins/standard.yaml`):
|
||||
```yaml
|
||||
plugins:
|
||||
@@ -75,7 +75,7 @@ Capability flags let the host reason about what your plug-in supports:
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
(Add other references—e.g., MongoDB driver, shared auth libraries—according to your implementation.)
|
||||
(Add other references—e.g., Npgsql/EF Core, shared auth libraries—according to your implementation.)
|
||||
|
||||
## 5. Implementing `IAuthorityPluginRegistrar`
|
||||
- Create a parameterless registrar class that returns your plug-in type name via `PluginType`.
|
||||
@@ -116,76 +116,72 @@ Capability flags let the host reason about what your plug-in supports:
|
||||
- Password guidance:
|
||||
- Standard plug-in hashes via `ICryptoProvider` using Argon2id by default and emits PHC-compliant strings. Successful PBKDF2 logins trigger automatic rehashes so migrations complete gradually. See `docs/security/password-hashing.md` for tuning advice.
|
||||
- Enforce password policies before hashing to avoid storing weak credentials.
|
||||
- Health checks should probe backing stores (e.g., Mongo `ping`) and return `AuthorityPluginHealthResult` so `/ready` can surface issues.
|
||||
- When supporting additional factors (e.g., TOTP), implement `SupportsMfa` and document the enrolment flow for resource servers.
|
||||
|
||||
### 6.1 Bootstrap lifecycle
|
||||
|
||||
Standard plug-in installs begin with an operator-provided manifest and secrets bundle. The registrar validates those inputs, primes the credential store, and only then exposes the identity surface to the host. Every transition is observable (audit events + telemetry) and deterministic so air-gapped operators can replay the bootstrap evidence.
|
||||
|
||||
- Secrets bundles must already contain hashed bootstrap principals. Registrars re-hash only to upgrade algorithms (e.g., PBKDF2 to Argon2id) and log the outcome.
|
||||
- `WarmupAsync` should fail fast when Mongo indexes or required secrets are missing; readiness stays `Unhealthy` until the registrar reports success.
|
||||
- Audit and telemetry payloads (`authority.plugin.load`) are mirrored into Offline Kits so security reviewers can verify who seeded credentials and when.
|
||||
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-bootstrap-sequence.mmd`
|
||||
|
||||
### 6.2 Credential audit telemetry (SEC2/SEC3)
|
||||
|
||||
- Password verification now emits `authority.plugin.standard.password_verification` records through the shared `IAuthEventSink`. `StandardCredentialAuditLogger` converts every outcome (success, lockout, password reset, MFA requirement) into `AuthEventRecord` instances so `/token` observability can be correlated with plugin activity.
|
||||
- `IAuthorityCredentialAuditContextAccessor` captures the caller’s correlation ID, client ID, tenant, remote IP, forwarded addresses, and user agent. OpenIddict handlers push a scope right before invoking the plug-in, and the logger automatically copies those fields into the audit event:
|
||||
|
||||
```csharp
|
||||
using var scope = auditContextAccessor.BeginScope(new AuthorityCredentialAuditContext(
|
||||
correlationId,
|
||||
clientId,
|
||||
tenantId,
|
||||
rateLimiterMetadata?.RemoteIp,
|
||||
rateLimiterMetadata?.ForwardedFor,
|
||||
rateLimiterMetadata?.UserAgent));
|
||||
```
|
||||
|
||||
- Outcome mapping is deterministic: `AuthorityCredentialFailureCode.LockedOut` ⇒ `AuthEventOutcome.LockedOut`, `RequiresPasswordReset`/`PasswordExpired` ⇒ `RequiresFreshAuth`, and `RequiresMfa` ⇒ `RequiresMfa`. Anything else falls back to `Failure`.
|
||||
- Lockout/rate-limit telemetry is carried via structured properties so SOC dashboards can slice the data:
|
||||
- `plugin.failed_attempts` – running count prior to the current decision.
|
||||
- `plugin.failed_attempts_cleared` – how many failures were cleared after a successful login.
|
||||
- `plugin.lockout_until` – ISO‑8601 timestamp showing when the account unlocks (classified as `Personal`).
|
||||
- `plugin.retry_after_seconds` – ceiling of `AuthorityCredentialVerificationResult.RetryAfter.TotalSeconds`; surfaced on both the audit event and the verification result to guide HTTP 429/423 responses.
|
||||
- `plugin.rehashed` – algorithm tag (`argon2id`) when a legacy hash is upgraded.
|
||||
- `plugin.failure_code` – enum name corresponding to the failure classification.
|
||||
- Remember that everything you add to `AuthorityCredentialVerificationResult.AuditProperties` flows into both the `/token` audit event and the plug-in–scoped event above, so keep names stable and values deterministic for Offline Kit replay.
|
||||
- **Mongo2Go prerequisite:** the plugin test suite relies on Mongo2Go’s embedded `mongod`. Export the OpenSSL 1.1 shim described in `docs/19_TEST_SUITE_OVERVIEW.md` (section “Mongo2Go / OpenSSL shim”) before running `dotnet test`, e.g.:
|
||||
|
||||
```bash
|
||||
export LD_LIBRARY_PATH=\"$(pwd)/tests/native/openssl-1.1/linux-x64:${LD_LIBRARY_PATH:-}\"
|
||||
```
|
||||
|
||||
Without this step the embedded server fails to launch on OpenSSL 3 systems, causing timeouts in `StandardUserCredentialStoreTests`.
|
||||
|
||||
### 6.3 Plugin-specific mitigations (SEC5.PLG)
|
||||
|
||||
- Bootstrap seed users default to `RequirePasswordReset = true`. `StandardUserCredentialStore.EnsureBootstrapUserAsync` enforces the configured password policy, rejects partial credentials, and emits `authority.plugin.load` telemetry so operators can prove who seeded the initial principals.
|
||||
- Password policy overrides are validated against a built-in baseline (min length 12 + mixed character classes). The registrar now logs a structured warning whenever a deployment attempts to weaken those defaults, giving security reviewers an audit breadcrumb and satisfying the SEC5.PLG threat-model requirement.
|
||||
- All bootstrap and password operations use `ICryptoProvider` + Argon2id; legacy PBKDF2 hashes are upgraded inline and tagged via `plugin.rehashed`. Document any deviations so downstream plug-ins (or auditors) can reason about entropy expectations.
|
||||
- Lockout metadata is deterministic: `plugin.lockout_until` + `plugin.retry_after_seconds` form the authoritative signal for incident response, and their presence is now noted in the Authority threat model (`docs/security/authority-threat-model.md`).
|
||||
- When extending the Standard plug-in (or authoring a new one), keep these mitigations intact: enforce baseline policies, require explicit password reset flags on bootstrap flows, and emit the audit properties listed above. Third‑party plugins are expected to follow the same contract before they can advertise `SupportsPassword` or `SupportsBootstrap`.
|
||||
|
||||
### 6.4 LDAP plug-in quick reference (PLG7.IMPL-005)
|
||||
|
||||
- **Mutual TLS & trust stores.** `security.requireTls=true` enforces LDAPS/start‑TLS; set `security.requireClientCertificate=true` to demand mutual TLS. When that flag is enabled you must supply `connection.clientCertificate.pfxPath` + `passwordSecret`. Bundle CA chains under `connection.trustStore.bundlePath` and keep the files inside Offline Kit paths (`plugins/authority/ldap/**`) so air-gapped installs can import them without editing manifests.
|
||||
- **DN‑to‑role mapping.** `claims.groupToRoleMap` is ideal for static DNs (e.g. `cn=stellaops-admins,...` → `operators`). Regex mappings let you project portions of the DN into role names: define `pattern` with named captures (`(?P<role>...)`) and use `{role}` placeholders in `roleFormat`. The enricher sorts all emitted roles, dedupes, and adds them as `ClaimTypes.Role`.
|
||||
- **Attribute pass-through.** `claims.extraAttributes` pairs the outgoing claim name with the LDAP attribute to read (first value wins). Only non-empty strings are written, which keeps audit/compliance data deterministic.
|
||||
- **Mongo claims cache.** `claims.cache.enabled=true` wires the `MongoLdapClaimsCache` (default collection `ldap_claims_cache_<pluginName>`). Set `ttlSeconds` according to your directory freshness SLA and adjust `maxEntries` to cap disk usage; eviction is deterministic (oldest entries removed first). Offline Kit bundles now include the collection name requirements so replicas can pre-create capped collections.
|
||||
- **Client provisioning audit mirror.** `clientProvisioning.auditMirror.enabled=true` persists every LDAP write into Mongo (`ldap_client_provisioning_<plugin>` by default) with `{operation, dn, tenant, project, secretHash}`. That mirror is shipped in Offline Kits so regulators can diff LDAP state even without directory access. When `clientProvisioning.enabled=false`, the registrar logs a warning and downgrades the capability at runtime.
|
||||
- **Bootstrap seeding + audits.** `bootstrap.*` mirrors the provisioning contract for human operators: the plug-in writes `uid={username}` entries under `bootstrap.containerDn`, applies `staticAttributes` placeholders (`{username}`, `{displayName}`), and mirrors deterministic audit documents to Mongo (`ldap_bootstrap_<plugin>` by default) with hashed secrets (`AuthoritySecretHasher`). Bootstrap only lights up when (1) the manifest advertises the capability, (2) `bootstrap.enabled=true`, **and** (3) the plug-in proves the bind account can add/delete under the configured container. Otherwise the capability is silently downgraded and health checks surface `capabilities=bootstrapDisabled`.
|
||||
- **Capability proofing.** On startup the plug-in performs a short-lived LDAP write probe (add→delete) inside each configured container. If either probe fails, the respective capability (`clientProvisioning`, `bootstrap`) is removed, `ClientProvisioning` stays `null`, and `CheckHealthAsync` reports `Degraded` until permissions are restored. This keeps read-only deployments safe while making it obvious when operators still need to grant write scope.
|
||||
- **Sample manifest + binaries.** The curated manifest lives at `etc/authority.plugins/ldap.yaml` and demonstrates TLS, regex mappings, caching, and audit mirror options. Offline Kits copy both the manifest and the compiled plug-in into `plugins/authority/StellaOps.Authority.Plugin.Ldap/` so operators can drop them straight into air-gapped composer deployments.
|
||||
|
||||
## 7. Configuration & Secrets
|
||||
- Authority looks for manifests under `etc/authority.plugins/`. Each YAML file maps directly to a plug-in name.
|
||||
- Support environment overrides using `STELLAOPS_AUTHORITY_PLUGINS__DESCRIPTORS__<NAME>__...`.
|
||||
- Never store raw secrets in git: allow operators to supply them via `.local.yaml`, environment variables, or injected secret files. Document which keys are mandatory.
|
||||
- Health checks should probe backing stores (e.g., PostgreSQL connection check) and return `AuthorityPluginHealthResult` so `/ready` can surface issues.
|
||||
- When supporting additional factors (e.g., TOTP), implement `SupportsMfa` and document the enrolment flow for resource servers.
|
||||
|
||||
### 6.1 Bootstrap lifecycle
|
||||
|
||||
Standard plug-in installs begin with an operator-provided manifest and secrets bundle. The registrar validates those inputs, primes the credential store, and only then exposes the identity surface to the host. Every transition is observable (audit events + telemetry) and deterministic so air-gapped operators can replay the bootstrap evidence.
|
||||
|
||||
- Secrets bundles must already contain hashed bootstrap principals. Registrars re-hash only to upgrade algorithms (e.g., PBKDF2 to Argon2id) and log the outcome.
|
||||
- `WarmupAsync` should fail fast when PostgreSQL indexes or required secrets are missing; readiness stays `Unhealthy` until the registrar reports success.
|
||||
- Audit and telemetry payloads (`authority.plugin.load`) are mirrored into Offline Kits so security reviewers can verify who seeded credentials and when.
|
||||
|
||||
|
||||
|
||||
_Source:_ `docs/assets/authority/authority-plugin-bootstrap-sequence.mmd`
|
||||
|
||||
### 6.2 Credential audit telemetry (SEC2/SEC3)
|
||||
|
||||
- Password verification now emits `authority.plugin.standard.password_verification` records through the shared `IAuthEventSink`. `StandardCredentialAuditLogger` converts every outcome (success, lockout, password reset, MFA requirement) into `AuthEventRecord` instances so `/token` observability can be correlated with plugin activity.
|
||||
- `IAuthorityCredentialAuditContextAccessor` captures the caller’s correlation ID, client ID, tenant, remote IP, forwarded addresses, and user agent. OpenIddict handlers push a scope right before invoking the plug-in, and the logger automatically copies those fields into the audit event:
|
||||
|
||||
```csharp
|
||||
using var scope = auditContextAccessor.BeginScope(new AuthorityCredentialAuditContext(
|
||||
correlationId,
|
||||
clientId,
|
||||
tenantId,
|
||||
rateLimiterMetadata?.RemoteIp,
|
||||
rateLimiterMetadata?.ForwardedFor,
|
||||
rateLimiterMetadata?.UserAgent));
|
||||
```
|
||||
|
||||
- Outcome mapping is deterministic: `AuthorityCredentialFailureCode.LockedOut` ⇒ `AuthEventOutcome.LockedOut`, `RequiresPasswordReset`/`PasswordExpired` ⇒ `RequiresFreshAuth`, and `RequiresMfa` ⇒ `RequiresMfa`. Anything else falls back to `Failure`.
|
||||
- Lockout/rate-limit telemetry is carried via structured properties so SOC dashboards can slice the data:
|
||||
- `plugin.failed_attempts` – running count prior to the current decision.
|
||||
- `plugin.failed_attempts_cleared` – how many failures were cleared after a successful login.
|
||||
- `plugin.lockout_until` – ISO‑8601 timestamp showing when the account unlocks (classified as `Personal`).
|
||||
- `plugin.retry_after_seconds` – ceiling of `AuthorityCredentialVerificationResult.RetryAfter.TotalSeconds`; surfaced on both the audit event and the verification result to guide HTTP 429/423 responses.
|
||||
- `plugin.rehashed` – algorithm tag (`argon2id`) when a legacy hash is upgraded.
|
||||
- `plugin.failure_code` – enum name corresponding to the failure classification.
|
||||
- Remember that everything you add to `AuthorityCredentialVerificationResult.AuditProperties` flows into both the `/token` audit event and the plug-in–scoped event above, so keep names stable and values deterministic for Offline Kit replay.
|
||||
- **TestContainers PostgreSQL prerequisite:** the plugin test suite relies on TestContainers for an ephemeral PostgreSQL instance. Ensure Docker is available and the `Testcontainers.PostgreSql` package is referenced before running `dotnet test`.
|
||||
|
||||
Without a running Docker daemon the PostgreSQL container cannot start, causing timeouts in `StandardUserCredentialStoreTests`.
|
||||
|
||||
### 6.3 Plugin-specific mitigations (SEC5.PLG)
|
||||
|
||||
- Bootstrap seed users default to `RequirePasswordReset = true`. `StandardUserCredentialStore.EnsureBootstrapUserAsync` enforces the configured password policy, rejects partial credentials, and emits `authority.plugin.load` telemetry so operators can prove who seeded the initial principals.
|
||||
- Password policy overrides are validated against a built-in baseline (min length 12 + mixed character classes). The registrar now logs a structured warning whenever a deployment attempts to weaken those defaults, giving security reviewers an audit breadcrumb and satisfying the SEC5.PLG threat-model requirement.
|
||||
- All bootstrap and password operations use `ICryptoProvider` + Argon2id; legacy PBKDF2 hashes are upgraded inline and tagged via `plugin.rehashed`. Document any deviations so downstream plug-ins (or auditors) can reason about entropy expectations.
|
||||
- Lockout metadata is deterministic: `plugin.lockout_until` + `plugin.retry_after_seconds` form the authoritative signal for incident response, and their presence is now noted in the Authority threat model (`docs/security/authority-threat-model.md`).
|
||||
- When extending the Standard plug-in (or authoring a new one), keep these mitigations intact: enforce baseline policies, require explicit password reset flags on bootstrap flows, and emit the audit properties listed above. Third‑party plugins are expected to follow the same contract before they can advertise `SupportsPassword` or `SupportsBootstrap`.
|
||||
|
||||
### 6.4 LDAP plug-in quick reference (PLG7.IMPL-005)
|
||||
|
||||
- **Mutual TLS & trust stores.** `security.requireTls=true` enforces LDAPS/start‑TLS; set `security.requireClientCertificate=true` to demand mutual TLS. When that flag is enabled you must supply `connection.clientCertificate.pfxPath` + `passwordSecret`. Bundle CA chains under `connection.trustStore.bundlePath` and keep the files inside Offline Kit paths (`plugins/authority/ldap/**`) so air-gapped installs can import them without editing manifests.
|
||||
- **DN‑to‑role mapping.** `claims.groupToRoleMap` is ideal for static DNs (e.g. `cn=stellaops-admins,...` → `operators`). Regex mappings let you project portions of the DN into role names: define `pattern` with named captures (`(?P<role>...)`) and use `{role}` placeholders in `roleFormat`. The enricher sorts all emitted roles, dedupes, and adds them as `ClaimTypes.Role`.
|
||||
- **Attribute pass-through.** `claims.extraAttributes` pairs the outgoing claim name with the LDAP attribute to read (first value wins). Only non-empty strings are written, which keeps audit/compliance data deterministic.
|
||||
- **PostgreSQL claims cache.** `claims.cache.enabled=true` wires the `PostgresLdapClaimsCache` (default table `ldap_claims_cache_<pluginName>`). Set `ttlSeconds` according to your directory freshness SLA and adjust `maxEntries` to cap disk usage; eviction is deterministic (oldest entries removed first). Offline Kit bundles now include the table name requirements so replicas can pre-create tables.
|
||||
- **Client provisioning audit mirror.** `clientProvisioning.auditMirror.enabled=true` persists every LDAP write into PostgreSQL (`ldap_client_provisioning_<plugin>` table by default) with `{operation, dn, tenant, project, secretHash}`. That mirror is shipped in Offline Kits so regulators can diff LDAP state even without directory access. When `clientProvisioning.enabled=false`, the registrar logs a warning and downgrades the capability at runtime.
|
||||
- **Bootstrap seeding + audits.** `bootstrap.*` mirrors the provisioning contract for human operators: the plug-in writes `uid={username}` entries under `bootstrap.containerDn`, applies `staticAttributes` placeholders (`{username}`, `{displayName}`), and mirrors deterministic audit records to PostgreSQL (`ldap_bootstrap_<plugin>` table by default) with hashed secrets (`AuthoritySecretHasher`). Bootstrap only lights up when (1) the manifest advertises the capability, (2) `bootstrap.enabled=true`, **and** (3) the plug-in proves the bind account can add/delete under the configured container. Otherwise the capability is silently downgraded and health checks surface `capabilities=bootstrapDisabled`.
|
||||
- **Capability proofing.** On startup the plug-in performs a short-lived LDAP write probe (add→delete) inside each configured container. If either probe fails, the respective capability (`clientProvisioning`, `bootstrap`) is removed, `ClientProvisioning` stays `null`, and `CheckHealthAsync` reports `Degraded` until permissions are restored. This keeps read-only deployments safe while making it obvious when operators still need to grant write scope.
|
||||
- **Sample manifest + binaries.** The curated manifest lives at `etc/authority.plugins/ldap.yaml` and demonstrates TLS, regex mappings, caching, and audit mirror options. Offline Kits copy both the manifest and the compiled plug-in into `plugins/authority/StellaOps.Authority.Plugin.Ldap/` so operators can drop them straight into air-gapped composer deployments.
|
||||
|
||||
## 7. Configuration & Secrets
|
||||
- Authority looks for manifests under `etc/authority.plugins/`. Each YAML file maps directly to a plug-in name.
|
||||
- Support environment overrides using `STELLAOPS_AUTHORITY_PLUGINS__DESCRIPTORS__<NAME>__...`.
|
||||
- Never store raw secrets in git: allow operators to supply them via `.local.yaml`, environment variables, or injected secret files. Document which keys are mandatory.
|
||||
- Validate configuration as soon as the registrar runs; use explicit error messages to guide operators. The Standard plug-in now enforces complete bootstrap credentials (username + password) and positive lockout windows via `StandardPluginOptions.Validate`.
|
||||
- Cross-reference bootstrap workflows with `docs/modules/authority/operations/bootstrap.md` (to be published alongside CORE6) so operators can reuse the same payload formats for manual provisioning.
|
||||
- `passwordHashing` inherits defaults from `authority.security.passwordHashing`. Override only when hardware constraints differ per plug-in:
|
||||
@@ -205,33 +201,33 @@ _Source:_ `docs/assets/authority/authority-plugin-bootstrap-sequence.mmd`
|
||||
- Token scopes should be normalised (trimmed, unique, ordinal sort) before returning from plug-in verification paths. `TokenPersistenceHandlers` will keep that ordering for downstream consumers.
|
||||
|
||||
### 7.2 Claims & Enrichment Checklist
|
||||
- Authority always sets the OpenID Connect basics: `sub`, `client_id`, `preferred_username`, optional `name`, and `role` (for password flows). Plug-ins must use `IClaimsEnricher` to append additional claims in a **deterministic** order (sort arrays, normalise casing) so resource servers can rely on stable shapes.
|
||||
|
||||
### Claims enrichment & caching contracts
|
||||
|
||||
LDAP/AD plug-ins now expose first-class `claims.*` configuration to keep enrichment consistent:
|
||||
|
||||
- `claims.groupAttribute`, `claims.groupToRoleMap`, and `claims.regexMappings` translate directory DNs into Authority roles. Regex mappings honour both .NET-style `(?<role>)` and Python-style `(?P<role>)` capture syntax; names become `{role}` placeholders inside `roleFormat`.
|
||||
- `claims.extraAttributes` is a deterministic map of `{ claimName: ldapAttribute }`. Only the first attribute value is propagated and plug-ins must skip null/empty payloads.
|
||||
- `claims.cache.*` enables a Mongo-backed cache (`ldap_claims_cache_<pluginName>` by default) with TTL + capacity trims so repeated password grants avoid hammering the directory. TTL must be > 0 seconds and max entries ≥ 0. Collection names are normalised to lowercase ASCII and strip `/`, `\`, and `:` to remain Offline-Kit friendly.
|
||||
|
||||
When the cache is disabled, plug-ins inject `DisabledLdapClaimsCache` so the enricher path stays free of null checks. Cache documents must stay tenant-scoped and include `cachedAt`/`expiresAt` so operators can audit freshness. See `StellaOps.Authority.Plugin.Ldap.Claims` for the reference implementation.
|
||||
- Recommended enrichment keys:
|
||||
- `stellaops.realm` – plug-in/tenant identifier so services can scope policies.
|
||||
- `stellaops.subject.type` – values such as `human`, `service`, `bootstrap`.
|
||||
- `groups` / `projects` – sorted arrays describing operator entitlements.
|
||||
- Claims visible in tokens should mirror what `/token` and `/userinfo` emit. Avoid injecting sensitive PII directly; mark values with `ClassifiedString.Personal` inside the plug-in so audit sinks can tag them appropriately.
|
||||
- For client-credential flows, remember to enrich both the client principal and the validation path (`TokenValidationHandlers`) so refresh flows keep the same metadata.
|
||||
|
||||
### Client provisioning & audit mirror
|
||||
|
||||
- `clientProvisioning.enabled` must be true for the LDAP plug-in to expose `IClientProvisioningStore` and advertise the `clientProvisioning` capability. If the manifest lists the capability but the config disables it, startup logs a warning and the capability stays off.
|
||||
- `clientProvisioning.containerDn` is the base DN for machine/service accounts; the plug-in automatically builds RDNs as `<rdnAttribute>=<clientId>` (default `cn`) and escapes special characters to remain RFC 4514 compliant.
|
||||
- `clientProvisioning.secretAttribute` controls which LDAP attribute stores the client secret; the run-time writes the cleartext secret you pass during provisioning, while Mongo keeps only the hashed reference for audit (`AuthoritySecretHasher`).
|
||||
- `clientProvisioning.auditMirror.*` persists deterministic Mongo documents (default collection `ldap_client_provisioning_<plugin>`) capturing `{operation, dn, tenant, project, secretHash}` so operators can diff LDAP state even in air-gaps.
|
||||
- LDAP writes bind with the configured service account (`connection.bindDn` + secret). If the account loses modify permissions the store returns `ldap_error` and no Mongo state is changed, giving operators a single place to investigate.
|
||||
|
||||
### 7.3 Revocation Bundles & Reasons
|
||||
- Authority always sets the OpenID Connect basics: `sub`, `client_id`, `preferred_username`, optional `name`, and `role` (for password flows). Plug-ins must use `IClaimsEnricher` to append additional claims in a **deterministic** order (sort arrays, normalise casing) so resource servers can rely on stable shapes.
|
||||
|
||||
### Claims enrichment & caching contracts
|
||||
|
||||
LDAP/AD plug-ins now expose first-class `claims.*` configuration to keep enrichment consistent:
|
||||
|
||||
- `claims.groupAttribute`, `claims.groupToRoleMap`, and `claims.regexMappings` translate directory DNs into Authority roles. Regex mappings honour both .NET-style `(?<role>)` and Python-style `(?P<role>)` capture syntax; names become `{role}` placeholders inside `roleFormat`.
|
||||
- `claims.extraAttributes` is a deterministic map of `{ claimName: ldapAttribute }`. Only the first attribute value is propagated and plug-ins must skip null/empty payloads.
|
||||
- `claims.cache.*` enables a PostgreSQL-backed cache (`ldap_claims_cache_<pluginName>` table by default) with TTL + capacity trims so repeated password grants avoid hammering the directory. TTL must be > 0 seconds and max entries ≥ 0. Table names are normalised to lowercase ASCII and strip `/`, `\`, and `:` to remain Offline-Kit friendly.
|
||||
|
||||
When the cache is disabled, plug-ins inject `DisabledLdapClaimsCache` so the enricher path stays free of null checks. Cache documents must stay tenant-scoped and include `cachedAt`/`expiresAt` so operators can audit freshness. See `StellaOps.Authority.Plugin.Ldap.Claims` for the reference implementation.
|
||||
- Recommended enrichment keys:
|
||||
- `stellaops.realm` – plug-in/tenant identifier so services can scope policies.
|
||||
- `stellaops.subject.type` – values such as `human`, `service`, `bootstrap`.
|
||||
- `groups` / `projects` – sorted arrays describing operator entitlements.
|
||||
- Claims visible in tokens should mirror what `/token` and `/userinfo` emit. Avoid injecting sensitive PII directly; mark values with `ClassifiedString.Personal` inside the plug-in so audit sinks can tag them appropriately.
|
||||
- For client-credential flows, remember to enrich both the client principal and the validation path (`TokenValidationHandlers`) so refresh flows keep the same metadata.
|
||||
|
||||
### Client provisioning & audit mirror
|
||||
|
||||
- `clientProvisioning.enabled` must be true for the LDAP plug-in to expose `IClientProvisioningStore` and advertise the `clientProvisioning` capability. If the manifest lists the capability but the config disables it, startup logs a warning and the capability stays off.
|
||||
- `clientProvisioning.containerDn` is the base DN for machine/service accounts; the plug-in automatically builds RDNs as `<rdnAttribute>=<clientId>` (default `cn`) and escapes special characters to remain RFC 4514 compliant.
|
||||
- `clientProvisioning.secretAttribute` controls which LDAP attribute stores the client secret; the run-time writes the cleartext secret you pass during provisioning, while PostgreSQL keeps only the hashed reference for audit (`AuthoritySecretHasher`).
|
||||
- `clientProvisioning.auditMirror.*` persists deterministic PostgreSQL records (default table `ldap_client_provisioning_<plugin>`) capturing `{operation, dn, tenant, project, secretHash}` so operators can diff LDAP state even in air-gaps.
|
||||
- LDAP writes bind with the configured service account (`connection.bindDn` + secret). If the account loses modify permissions the store returns `ldap_error` and no PostgreSQL state is changed, giving operators a single place to investigate.
|
||||
|
||||
### 7.3 Revocation Bundles & Reasons
|
||||
- Use `IAuthorityRevocationStore` to record subject/client/token revocations when credentials are deleted or rotated. Stick to the standard categories (`token`, `subject`, `client`, `key`).
|
||||
- Include a deterministic `reason` string and optional `reasonDescription` so operators understand *why* a subject was revoked when inspecting bundles offline.
|
||||
- Plug-ins should populate `metadata` with stable keys (e.g., `revokedBy`, `sourcePlugin`, `ticketId`) to simplify SOC correlation. The keys must be lowercase, ASCII, and free of secrets—bundles are mirrored to air-gapped agents.
|
||||
@@ -264,7 +260,7 @@ _Source:_ `docs/assets/authority/authority-rate-limit-flow.mmd`
|
||||
- Emit metrics with stable names (`auth.plugins.<pluginName>.*`) when introducing custom instrumentation; coordinate with the Observability guild to reserve prefixes.
|
||||
|
||||
## 10. Testing & Tooling
|
||||
- Unit tests: use Mongo2Go (or similar) to exercise credential stores without hitting production infrastructure (`StandardUserCredentialStoreTests` is a template).
|
||||
- Unit tests: use TestContainers PostgreSQL (or similar) to exercise credential stores without hitting production infrastructure (`StandardUserCredentialStoreTests` is a template).
|
||||
- Determinism: fix timestamps to UTC and sort outputs consistently; avoid random GUIDs unless stable.
|
||||
- Smoke tests: launch `dotnet run --project src/Authority/StellaOps.Authority/StellaOps.Authority` with your plug-in under `StellaOps.Authority.PluginBinaries` and verify `/ready`.
|
||||
- Example verification snippet:
|
||||
|
||||
Reference in New Issue
Block a user