stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-03 00:47:24 +02:00
parent 3f197814c5
commit ca578801fd
319 changed files with 32478 additions and 2202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md
View File

@@ -50,7 +50,7 @@ Capability flags let the host reason about what your plug-in supports:
**Operational reminder:** the Authority host surfaces capability summaries during startup (see `AuthorityIdentityProviderRegistry` log lines). Use those logs during smoke tests to ensure manifests align with expectations.
**Configuration path normalisation:** Manifest-relative paths (e.g., `tokenSigning.keyDirectory: "../keys"`) are resolved against the YAML file location and environment variables are expanded before validation. Plug-ins should expect to receive an absolute, canonical path when options are injected.
**Configuration path normalisation:** Manifest-relative paths (for example, `tokenSigning.keyDirectory` in plug-ins that actually use signing material) are resolved against the YAML file location and environment variables are expanded before validation. Plug-ins should expect to receive an absolute, canonical path when options are injected. The Standard plug-in rejects `tokenSigning` configuration because token signing is handled by the host.
**Password policy guardrails:** The Standard registrar logs a warning when a plug-in weakens the default password policy (minimum length or required character classes). Keep overrides at least as strong as the compiled defaults—operators treat the warning as an actionable security deviation.
@@ -175,9 +175,16 @@ _Source:_ `docs/assets/authority/authority-plugin-bootstrap-sequence.mmd`
- **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.
- **Capability proofing.** The plug-in performs short-lived LDAP write probes (add->delete) inside each configured container and caches the result for `capabilityProbe.cacheTtlSeconds`. Probe timeouts are controlled by `capabilityProbe.timeoutSeconds`. If a 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.
- **Connection timeout.** `connection.timeoutSeconds` controls the LDAP connection timeout so deployments can tune for slow directories or stricter fail-fast posture.
- **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.
### 6.5 SAML plug-in quick reference (PLG7.IMPL-006)
- **Metadata fetching.** `idpMetadataUrl` is used to load signing certificates when explicit IdP certs are not configured. Metadata fetches require HTTPS by default (`requireHttpsMetadata=true`) and respect `metadataTimeoutSeconds` and `metadataRefreshInterval`.
- **Unsupported flags.** `requireEncryptedAssertions`, `signAuthenticationRequests`, and `signLogoutRequests` are not supported yet; keep them disabled until signing/encryption flows are implemented.
- **Session cache isolation.** Session cache keys include the plugin name to avoid collisions when multiple SAML providers are configured.
## 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>__...`.