Seitenzugriff konfigurieren

Diese Referenz richtet sich an Entwickler und Partneragenturen, die Pages für eine Workspace Site erstellen. Sie beschreibt, wie eine Page öffentlich, sitzungsgebunden, mandantengebunden oder systemweit geschützt wird. Nach der Konfiguration liefert Workspace die Seite nur im passenden Kontext aus und blendet nicht erlaubte Einträge aus der Navigation aus.

Der access-Block schützt die HTML-Seite. Er ersetzt nicht die Berechtigungsprüfung der API-Endpunkte, die eine Seite aufruft. Beides muss zum gleichen fachlichen Zugriff passen.

Zugriffsart auswählen

Jede Page braucht einen expliziten access-Block. Wählen Sie die Zugriffsart nach dem benötigten Kontext, nicht nach dem Slug der Seite.

surfaceGeeignet fürVoraussetzungenScopes
publicfrei erreichbare Website-, Bestätigungs- oder Informationsseitenkeine Browser-Sitzungnicht zulässig
selfDaten, die ausschließlich zur angemeldeten Identität gehören und keinen aktiven Mandanten benötigengültige Browser-Sitzungnicht zulässig
tenantinterne Seiten eines Arbeitsbereichsgültige Browser-Sitzung, aktiver Mandant und passende Mandanten-ScopesrequiredScopes oder anyScopes erforderlich
systeminstallationsweite Administrationgültige Browser-Sitzung und passende Scopes des System-MandantenrequiredScopes oder anyScopes erforderlich

Ein Pfad wie /system/status wird nicht automatisch zu einer Systemseite. Nur access.surface: system legt diese Bedeutung fest. Verwenden Sie self nur, wenn die Seite auch ohne ausgewählten Mandanten fachlich vollständig ist.

Öffentliche Seite

yaml
type: default
access:
  surface: public
variant:
  translationKey: newsletter-confirmation
  locale: de
  slug: newsletter/bestaetigt
title: Newsletter bestätigt

public erlaubt weder requiredScopes, anyScopes noch tenantAudienceKey.

Seite für angemeldete Identitäten

yaml
type: default
access:
  surface: self
variant:
  translationKey: personal-security
  locale: de
  slug: konto/sicherheit
title: Persönliche Sicherheit

self verlangt eine Browser-Sitzung, aber keinen aktiven Mandanten. Die aufgerufenen Self-Service-APIs prüfen weiterhin selbst, ob die Identität die angeforderten eigenen Daten lesen oder ändern darf.

Scopes festlegen

Ein Scope ist ein technischer Berechtigungsname wie orders:list. Workspace ermittelt die effektiven Scopes einer Identität aus ihren Rollen im aktuellen Kontext. Verwenden Sie nur Scope-Namen, die der betreffende Workspace-Vertrag vorgibt. Eigene Scope-Namen in einer Page anzulegen erweitert den Berechtigungsvertrag nicht.

Alle Pflicht-Scopes verlangen

requiredScopes ist eine UND-Liste. Alle Einträge müssen vorhanden sein:

yaml
access:
  surface: tenant
  requiredScopes:
    - orders:list
    - orders:export

Mit nur orders:list bleibt diese Seite gesperrt. Für einen allgemeinen Einstieg in einen Arbeitsbereich genügt der abgeleitete Scope tenant:member, wenn jede reguläre Mitgliedschaft die Seite öffnen darf:

yaml
access:
  surface: tenant
  requiredScopes:
    - tenant:member

Einen von mehreren Scopes akzeptieren

anyScopes ist eine ODER-Liste. Mindestens ein Eintrag muss vorhanden sein:

yaml
access:
  surface: tenant
  anyScopes:
    - accounting_reports:read
    - accounting_bank_accounts:list
    - accounting_bank_transactions:list

Dieses Muster eignet sich für eine Übersichtsseite, die mehrere gleichwertige Einstiege bündelt. Verwenden Sie es nicht, um engere Berechtigungen der einzelnen API-Aktionen zu umgehen.

Pflicht- und Alternativ-Scopes kombinieren

Wenn beide Listen gesetzt sind, müssen alle requiredScopes und mindestens ein Eintrag aus anyScopes passen:

yaml
access:
  surface: tenant
  requiredScopes:
    - orders:list
  anyScopes:
    - orders:update
    - orders:approve

Der globale Scope * erfüllt jede Scope-Prüfung. Nutzen Sie ihn nicht als Ersatz für eine fachlich passende Rollen- und Scope-Auswahl.

Systemseite schützen

Systemseiten werden gegen den System-Mandanten geprüft. Eine Mitgliedschaft in einem normalen Arbeitsbereich reicht nicht:

yaml
access:
  surface: system
  requiredScopes:
    - system:member

Prüfen Sie vor der Fehlersuche, welchen Kontext und welche Scopes die aktuelle Sitzung besitzt:

bash
nucli --tenant <tenant> whoami --scopes
nucli --tenant system whoami --scopes

Seitenzielgruppe zusätzlich einschränken

Eine tenant-Page kann zusätzlich eine Seitenzielgruppe verlangen:

yaml
access:
  surface: tenant
  requiredScopes:
    - tenant:member
  tenantAudienceKey: SITE_AUDIENCE_VIP_CUSTOMERS

tenantAudienceKey verweist auf eine aktive Seitenzielgruppe im aktuellen Mandanten. Die Identität braucht weiterhin die geforderten Scopes und muss zusätzlich direkt zu mindestens einer hinterlegten Zugriffsgruppe gehören. Die Seitenzielgruppe kann Zugriff nur einschränken, nicht erweitern.

Fehlt die Zielgruppe, ist sie inaktiv oder besitzt sie keine gültige Gruppenzuordnung, bleibt die Seite gesperrt und verschwindet aus der Navigation. Verwalten und prüfen Sie die Zuordnung unter System > IAM > Seitenzielgruppen. Weitere Hinweise zur Rollen- und Gruppenpflege stehen in IAM und Authentifizierung.

Antworten und Weiterleitungen verstehen

Workspace prüft den Seitenzugriff, bevor es die geschützte App-Shell oder den Seiteninhalt ausliefert.

ErgebnisHTTP-VerhaltenBedeutung
Zugriff erlaubt200Kontext, Scopes und gegebenenfalls Seitenzielgruppe passen.
Nicht angemeldet401 oder konfigurierter Login-RedirectEs fehlt eine gültige Browser-Sitzung.
Angemeldet, aber nicht berechtigt403Mandant, Scopes oder Seitenzielgruppe passen nicht.
Ungültiger access-Block500Die Page ist fehlerhaft konfiguriert und wird nicht ausgeliefert.

Im eingebetteten Workspace-Backend führt eine fehlende Browser-Sitzung bei einem HTML-Hauptdokument mit 302 zu /login. Eine gültige Sitzung ohne ausreichende Berechtigung bleibt dagegen bei 403 und wird nicht zum Login umgeleitet. So bleibt erkennbar, ob eine Anmeldung fehlt oder eine Berechtigung verweigert wurde.

Eine Page kann für Ergebnisse der Zugriffsprüfung eine Weiterleitung festlegen:

yaml
redirectOnStatus:
  - status: 401
    url: /login
    code: 302

status bezeichnet das Ergebnis der Zugriffsprüfung. url ist das Ziel und code der HTTP-Redirect-Code, üblicherweise 302. Der Vertrag wertet hier 401 und 403 aus. Er ist keine allgemeine Weiterleitungstabelle für beliebige Antworten wie 404 oder 500.

Wählen Sie die Konfigurationsebene bewusst:

OrtSchlüsselWirkung
Page-YAMLredirectOnStatusGilt nur für diese Page.
pagetypes/<type>.yamlfeatures.redirectOnStatus: trueAktiviert die Übernahme des Site-Defaults für Pages dieses Typs.
config/defaults.yamlRedirectOnStatusDefiniert den Site-Default mit großem R.

Der PageType kann die Übernahme so aktivieren:

yaml
features:
  redirectOnStatus: true

Der zugehörige Site-Default steht in config/defaults.yaml:

yaml
RedirectOnStatus:
  - status: 401
    url: /login
    code: 302

Workspace übernimmt den Default nur, wenn die Funktion im PageType aktiviert ist und die konkrete Page keine eigene redirectOnStatus-Liste besitzt. Eigene Seiteneinträge ersetzen den Default vollständig; die Listen werden nicht zusammengeführt.

Canonical-Redirects werden erst nach erfolgreicher Zugriffsprüfung betrachtet. Sie normalisieren keine geschützten tenant-, self- oder system-Pages.

Workspace verwendet dieselbe Zugriffsentscheidung für Seitenauslieferung, Navigation und weitere serverseitige Seitensammlungen. Eine gesperrte Seite wird daher nicht nur beim direkten Aufruf abgewiesen, sondern auch aus der Navigation entfernt. Ein Navigationsordner kann ohne eigenen Link bestehen bleiben, wenn er noch erlaubte Unterseiten enthält.

Clientseitiges Ausblenden ist nur Darstellung und kein Zugriffsschutz. Schützen Sie die Page über access und jeden verwendeten API-Endpunkt über dessen eigenen Berechtigungsvertrag. Bearer-API-Keys und Basic-Credentials öffnen keine geschützten HTML-Seiten; diese verwenden Browser-Sitzungen.

Konfiguration prüfen

  1. Validieren Sie das Site-Projekt:
bash
   nucli --tenant <tenant> sites validate <site-id>
  1. Prüfen Sie Route und Access-Daten im aktuellen Quellstand oder Release:
bash
   nucli --tenant <tenant> sites route inspect <site-id> /pfad --locale de-DE --jurisdiction global --json
   nucli --tenant <tenant> sites route inspect <site-id> /pfad --locale de-DE --jurisdiction global --release live --json
  1. Öffnen Sie die Page ohne Browser-Sitzung. Für eine geschützte Page muss die konfigurierte 401-Behandlung greifen.
  2. Öffnen Sie die Page mit einem berechtigten Testkonto. Sie muss erreichbar und in der Navigation sichtbar sein.
  3. Wiederholen Sie den Test mit einem angemeldeten Testkonto, dem der notwendige Scope oder die Seitenzielgruppe fehlt. Dieser Fall muss als 403 erkennbar bleiben.
  4. Prüfen Sie die APIs der Seite getrennt. Eine sichtbare Page darf keine Aktion freigeben, die der API-Vertrag verweigert.

Die Konfiguration ist abgeschlossen, wenn validate keine Blocker meldet, die Route im vorgesehenen Kontext erreichbar ist und nicht berechtigte Konten weder die Seite noch ihren Navigationseintrag erhalten.

Automatisierte Agenten können den vollständigen Site-Ablauf mit folgendem Befehl laden:

bash
nucli --tenant <tenant> skills show sites

Häufige Fehler

SymptomWahrscheinliche UrsachePrüfung
Die Page liefert 500.access fehlt, die surface ist unbekannt oder ein geschützter Surface besitzt keine Scope-Liste.access vollständig angeben und sites validate ausführen.
Die Page liefert trotz Anmeldung 403.Der aktive Mandant, ein Scope oder die Seitenzielgruppe passt nicht.whoami --scopes, Mandant und Seitenzielgruppe prüfen.
Eine eigene Weiterleitung greift nicht.Der Status passt nicht zum Zugriffsergebnis oder der Eintrag steht auf der falschen Konfigurationsebene.401 und 403, die Schreibweise von redirectOnStatus beziehungsweise RedirectOnStatus und die PageType-Funktion prüfen.
Änderungen am Site-Default erscheinen nicht auf einer Page.Der PageType aktiviert die Übernahme nicht oder die Page besitzt eine eigene Liste.features.redirectOnStatus prüfen und entscheiden, ob die Page den Default erben oder bewusst ersetzen soll.
Die Page fehlt in der Navigation.Die serverseitige Zugriffsentscheidung verweigert dieselbe Page.Direkten Aufruf und dieselben Kontextbedingungen prüfen.
Eine public- oder self-Page ist ungültig.Sie enthält requiredScopes, anyScopes oder eine unzulässige Seitenzielgruppe.Scope-Felder entfernen oder die fachlich richtige surface wählen.
Ein API-Key funktioniert für die API, aber nicht für die Page.HTML-Seiten verlangen eine Browser-Sitzung.Im Browser anmelden; API-Key nur für den API-Vertrag verwenden.
Die Page ist sichtbar, eine Aktion liefert aber 403.Page Access und API-Autorisierung sind getrennte Prüfungen.Den Scope der konkreten API-Aktion und die zugehörige Rolle prüfen.

Verwandte Themen