docs: add credential lifecycle guidance
This commit is contained in:
@@ -432,7 +432,6 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
|
||||
"access.admin.tenant-roles",
|
||||
"access.admin.api-keys",
|
||||
"access.admin.service-accounts",
|
||||
"access.credentials",
|
||||
],
|
||||
"route": "/admin",
|
||||
"screen": "Admin",
|
||||
@@ -500,6 +499,92 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
|
||||
],
|
||||
},
|
||||
),
|
||||
DocumentationTopic(
|
||||
id="access.workflow.manage-reusable-credentials",
|
||||
title="Manage reusable credentials safely",
|
||||
summary="Reusable credential envelopes keep secrets write-only while administrators constrain which scopes, modules, and servers may use them.",
|
||||
body=(
|
||||
"A reusable credential envelope stores a secret behind the Access boundary and never returns the configured secret through the API. Choose the credential type before entering the secret; changing the type requires a replacement secret. When editing, an empty secret field retains the current value, while Remove configured secret clears it on save and leaves dependent connections unable to authenticate until a replacement is supplied. "
|
||||
"The module and server lists are restrictions: an empty list means every module or server already permitted by the selected scope. Visible to lower scopes makes the envelope selectable from child scopes but does not bypass its module, server, or authorization limits. Deactivating keeps the configuration for review but blocks authentication. Deleting is irreversible in GovOPlaN, cannot recover the secret, and causes every referencing connection to stop authenticating. Review dependent connections and record the external secret-manager owner before clearing or deleting a credential."
|
||||
),
|
||||
layer="configured",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("system_admin", "tenant_admin", "access_admin", "operator"),
|
||||
order=32,
|
||||
conditions=(
|
||||
DocumentationCondition(
|
||||
required_modules=("access",),
|
||||
any_scopes=(
|
||||
"access:system_credential:read",
|
||||
"access:system_credential:write",
|
||||
"access:credential:read",
|
||||
"access:credential:write",
|
||||
"access:credential:manage_own",
|
||||
),
|
||||
),
|
||||
),
|
||||
links=(
|
||||
DocumentationLink(label="System credentials", href="/admin?section=system-credentials", kind="runtime"),
|
||||
DocumentationLink(label="Tenant credentials", href="/admin?section=tenant-credentials", kind="runtime"),
|
||||
DocumentationLink(label="Personal credentials", href="/settings", kind="runtime"),
|
||||
),
|
||||
translations={
|
||||
"de": {
|
||||
"title": "Wiederverwendbare Zugangsdaten sicher verwalten",
|
||||
"summary": "Wiederverwendbare Zugangsdaten geben Geheimnisse nicht wieder aus und begrenzen ihre Nutzung auf freigegebene Ebenen, Module und Server.",
|
||||
"body": "Ein Eintrag für wiederverwendbare Zugangsdaten speichert ein Geheimnis hinter der Access-Sicherheitsgrenze; das konfigurierte Geheimnis wird über die API niemals zurückgegeben. Wählen Sie den Zugangstyp vor der Eingabe. Eine Typänderung erfordert ein neues Geheimnis. Beim Bearbeiten behält ein leeres Geheimnisfeld den vorhandenen Wert. Mit „Konfiguriertes Geheimnis entfernen“ wird er beim Speichern gelöscht; abhängige Verbindungen können sich erst nach Hinterlegung eines Ersatzes wieder anmelden. Die Modul- und Serverlisten sind Einschränkungen: Eine leere Liste erlaubt alle Module beziehungsweise Server, die auf der gewählten Ebene bereits zulässig sind. „Für tiefere Ebenen sichtbar“ macht den Eintrag in Kindebenen auswählbar, umgeht aber weder Modul- und Servergrenzen noch Berechtigungen. Eine Deaktivierung erhält die Konfiguration zur Prüfung, verhindert jedoch die Anmeldung. Das Löschen kann in GovOPlaN nicht rückgängig gemacht werden, stellt das Geheimnis nicht wieder her und unterbricht die Anmeldung aller referenzierenden Verbindungen. Prüfen Sie deshalb vor dem Entfernen oder Löschen die abhängigen Verbindungen und die Zuständigkeit im externen Geheimnismanager.",
|
||||
}
|
||||
},
|
||||
metadata={
|
||||
"kind": "workflow",
|
||||
"route": "/admin",
|
||||
"screen": "Reusable credentials",
|
||||
"help_contexts": [
|
||||
"access.admin.system-credentials",
|
||||
"access.admin.tenant-credentials",
|
||||
"access.admin.group-credentials",
|
||||
"access.admin.user-credentials",
|
||||
"access.settings.credentials",
|
||||
"access.credentials",
|
||||
"access.credentials.target",
|
||||
"access.credentials.editor",
|
||||
"access.credentials.action.reload",
|
||||
"access.credentials.action.create",
|
||||
"access.credentials.action.edit",
|
||||
"access.credentials.action.save",
|
||||
"access.credentials.action.delete",
|
||||
"access.credentials.field.name",
|
||||
"access.credentials.field.type",
|
||||
"access.credentials.field.description",
|
||||
"access.credentials.field.account-label",
|
||||
"access.credentials.field.secret",
|
||||
"access.credentials.field.clear-secret",
|
||||
"access.credentials.field.allowed-modules",
|
||||
"access.credentials.field.allowed-servers",
|
||||
"access.credentials.field.inherit-to-lower-scopes",
|
||||
"access.credentials.field.active",
|
||||
"access.credentials.confirm-delete",
|
||||
],
|
||||
"prerequisites": [
|
||||
"The intended credential owner is selected.",
|
||||
"The actor may read credentials and has write authority for mutations.",
|
||||
"The external secret-manager owner and dependent connections are known.",
|
||||
],
|
||||
"steps": [
|
||||
"Select the narrowest owning scope and credential type.",
|
||||
"Restrict modules and servers explicitly when broad use is not intended.",
|
||||
"Save a new or replacement secret without expecting it to be displayed again.",
|
||||
"Review dependent connections before deactivation, secret clearing, or deletion.",
|
||||
],
|
||||
"outcome": "The credential remains write-only and is usable only within its active scope, module, server, and authorization boundaries.",
|
||||
"limitations": [
|
||||
"GovOPlaN cannot display or recover a configured secret.",
|
||||
"An empty module or server restriction means every value permitted by scope.",
|
||||
"Deleting or clearing a secret does not rewrite dependent connection references.",
|
||||
],
|
||||
"verification": "Reload the credential list, confirm its scope and availability, then test each intended dependent connection without exposing the secret in evidence.",
|
||||
},
|
||||
),
|
||||
DocumentationTopic(
|
||||
id="access.workflow.manage-service-account-credentials",
|
||||
title="Manage service accounts and credentials",
|
||||
@@ -512,7 +597,7 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
|
||||
layer="configured",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("tenant_admin", "access_admin", "operator"),
|
||||
order=32,
|
||||
order=33,
|
||||
conditions=(
|
||||
DocumentationCondition(
|
||||
required_modules=("access",),
|
||||
@@ -557,7 +642,7 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
|
||||
layer="configured",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("tenant_admin", "access_admin", "operator"),
|
||||
order=33,
|
||||
order=34,
|
||||
conditions=(
|
||||
DocumentationCondition(
|
||||
required_modules=("access", "organizations"),
|
||||
@@ -605,7 +690,7 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
|
||||
layer="configured",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("privacy_officer", "tenant_owner", "operator"),
|
||||
order=34,
|
||||
order=35,
|
||||
conditions=(
|
||||
DocumentationCondition(
|
||||
required_modules=("access", "admin"),
|
||||
|
||||
@@ -24,7 +24,19 @@ class InterfaceDocumentationContractTests(unittest.TestCase):
|
||||
"access.admin.tenant-roles",
|
||||
"access.admin.api-keys",
|
||||
"access.admin.service-accounts",
|
||||
},
|
||||
"access.workflow.manage-reusable-credentials": {
|
||||
"access.admin.system-credentials",
|
||||
"access.admin.tenant-credentials",
|
||||
"access.admin.group-credentials",
|
||||
"access.admin.user-credentials",
|
||||
"access.settings.credentials",
|
||||
"access.credentials",
|
||||
"access.credentials.field.secret",
|
||||
"access.credentials.field.clear-secret",
|
||||
"access.credentials.field.inherit-to-lower-scopes",
|
||||
"access.credentials.action.delete",
|
||||
"access.credentials.confirm-delete",
|
||||
},
|
||||
"access.reference.external-function-role-mappings": {
|
||||
"access.admin.function-mappings",
|
||||
@@ -43,6 +55,16 @@ class InterfaceDocumentationContractTests(unittest.TestCase):
|
||||
topic_id,
|
||||
)
|
||||
|
||||
credential_topic = topics["access.workflow.manage-reusable-credentials"]
|
||||
self.assertEqual(
|
||||
{"title", "summary", "body"},
|
||||
set(credential_topic.translations["de"]),
|
||||
)
|
||||
self.assertIn(
|
||||
"nicht rückgängig gemacht",
|
||||
credential_topic.translations["de"]["body"],
|
||||
)
|
||||
|
||||
def test_access_admin_surfaces_remain_declared(self) -> None:
|
||||
surface_ids = {
|
||||
surface.id for surface in manifest.frontend.view_surfaces
|
||||
|
||||
Reference in New Issue
Block a user