API-Fassade und Sicherheit

  • Tutorial

Dieses Dokument stellt die RestFrontage-Einstiegspunkte für die Authentifizierung eines Clients, das Anzeigen oder Ändern von Sicherheitsmaßnahmen, das Filtern von OData-Objekten und die Nutzung von Razor-Tools vor.

Für das konzeptuelle Modell und Entscheidungsregeln siehe siehe Überblick über immersive Sicherheit.

Authentifizierung eines API-Clients

Hol dir einen Token

POST {{baseUrl}}/api/Security/User/Authenticate
Content-Type: application/json

{
  "AccountName": "utilisateur",
  "Password": "mot-de-passe"
}

Alias akzeptiert: POST /api/Security/Users/Authenticate.

Vereinfachte Antwort:

{
  "Domain": "DC=Immersive, DC=GraphicStream, DC=fr",
  "Token": "eyJ...",
  "AuthenticatedUser": {
    "Identifier": 123,
    "DistinguishedNameValue": "AN=utilisateur, OU=Users, ..."
  }
}

Der Kunde übermittelt dann:

Authorization: Bearer {{token}}

Logins und Passwörter dürfen nur über HTTPS gesendet werden.

Tokenzyklus

Wort und Straße Funktion
POST /api/Security/Token/Renew Erneuere einen gültigen Token
GET oder POST /api/Security/Token/Validate Überprüfen Sie, dass die Pipeline das Token akzeptiert
GET oder POST /api/Security/Whoami Erfahren Sie den Namen der aktuellen Identität

Primäre Sicherheitsendpunkte

Alle untenstehenden Straßen haben das Präfix /api/Security.

Rechtekontrolle und Verwaltung

Wort und Straße Verwendung Empfohlener Status
GET /Users/{askerId}/Rights/{flags}/SecurizedObjects/{type}/{objectId} Test einer Maske an einem Objekt Geschichte; enthält keine Aktien
GET /Rights?securedObjectIdentifier=...&securedObjectTypeIdentifier=... Lesen Sie die expliziten Rechte eines Objekts Kann für die Verwaltung verwendet werden
POST /Rights Wenden Sie eine Sammlung von Rechten an: ISecurityAdministrationService Empfohlener Schreibpunkt
DELETE /Rights?rightIdentifiers=... Rechte durch ID entfernen Geschichte; um zur zentralen Fassade zu wandern.
GET /Permissions Konfigurierende Leseberechtigungen Empfohlen für den Aufbau einer Benutzeroberfläche ohne fest codierte Flags

Beispiel für die Anwendung eines Rechts:

POST {{baseUrl}}/api/Security/Rights
Authorization: Bearer {{token}}
Content-Type: application/json

[
  {
    "Identifier": 0,
    "DomainSecurityObjectIdentifier": 145,
    "SecurizedObjectIdentifier": 902,
    "SecurizedObjectType": 15,
    "AuthorizedFlags": 3,
    "DeniedFlags": 0
  }
]

Regeln von POST /Rights :

  • Der Akteur wird immer aus dem authentifizierten Kontext gelesen;
  • Cerebrate- und Root-Administratoren können alle Rechte verwalten;
  • ansonsten müssen der Akteur und die Begünstigten der aktuellen Organisation angehören;
  • Ein Begünstigter BuiltIn geschützt ist;
  • Der Akteur muss in der Lage sein, jedes Zielobjekt zu verwalten;
  • Flags müssen mit den konfigurierten Berechtigungen übereinstimmen;
  • AuthorizedFlags = 0 und DeniedFlags = 0 schafft die entsprechende Abgabe ab;
  • Mehrere Abfragen für dasselbe Triplet werden vor dem Schreiben normalisiert.

Fehlerantworten:

  • 400 - Ungültige Daten oder Flags
  • 401 : Fehlen einer authentifizierten Identität;
  • 403 : unbefugter Akteur oder schlechte Organisation;
  • 409 : Dateninkonsistenz oder -konflikt, wie alte doppelte Rechte.

Aktien

Wort und Straße Verwendung
POST /SharedAccess Erstellen Sie eine Teilung, die AccessLinkIdentifier Fußnote eins TinyUrl existierend
POST /SharedAccess/Aggregate Erstellen Sie explizit ein Aggregat und geben Sie das TinyUrl auf Wurzelebene
POST /SharedAccess/{grantIdentifier}/Revoke Widerrufe das Teilen ohne Löschen der TinyUrl

Beispiel für eine Woche internes Teilen:

POST {{baseUrl}}/api/Security/SharedAccess/Aggregate
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "TinyUrlIdentifier": "equipment-902-share",
  "Grant": {
    "BeneficiaryDomainSecurityObjectIdentifier": 245,
    "ExternalRecipientEmail": null,
    "ValidFromUtc": "2026-08-18T10:00:00Z",
    "ExpiresAtUtc": "2026-08-25T10:00:00Z",
    "Rights": [
      {
        "SecurizedObjectIdentifier": 902,
        "SecurizedObjectType": 18,
        "AuthorizedFlags": 1
      },
      {
        "SecurizedObjectIdentifier": 84,
        "SecurizedObjectType": 15,
        "AuthorizedFlags": 1
      },
      {
        "SecurizedObjectIdentifier": 31,
        "SecurizedObjectType": 48,
        "AuthorizedFlags": 1
      }
    ]
  }
}

Für einen externen Empfänger füllen Sie das aus ExternalRecipientEmail und gehen BeneficiaryDomainSecurityObjectIdentifier à null. Genau eines der beiden Felder muss definiert werden.

Vereinfachte Antwort:

{
  "grantIdentifier": 12,
  "publicIdentifier": "...",
  "externalAccessToken": "retourné uniquement pour un partage externe",
  "tinyUrlIdentifier": "equipment-902-share",
  "tinyUrlPath": "/?TU=equipment-902-share",
  "externalAccessPath": "/Shared?token=...&tinyUrl=equipment-902-share"
}

Der Server schließt keine Abhängigkeiten ab. Beholder, Forge oder der Spieler müssen die vollständige Liste der Objekte senden, die zum Öffnen des Ziels benötigt werden.

Es gibt noch keine dedizierte REST-Route für die Share-Liste. Diese Liste wird derzeit vom teilweisen Razor über Razor genutzt GetSharedAccessGrantsAsync.

Mindestaufruf des Sharing-Modals:

/Security/Modals/SharedAccess
    ?SecurizedObjectIdentifier={identifier}
    &SecurizedObjectType={type}
    &TinyUrlIdentifier={tinyUrlExistante}

Verzeichnis

Die Fassade zeigt außerdem folgende Familien:

Familie Hauptstraßen
Auflösung GET /DomainObjects/{dnOuId}, POST /Discover
Navigation GET /DomainObjects/{dn}/Members, GET /Explorer/{dn}/Search/{criteria}
Zugehörigkeiten GET, POST, PUT, DELETE /DomainObjects/{dn}/Membership
Gruppenmitglieder PUT, POST, DELETE /Groups/{dn}/Members
Hierarchie GET /DomainObjects/{dn}/GroupMembershipHierarchy
Erweiterbare Felder GET, PUT, POST /DomainObjects/{dn}/Fields
Nutzer POST /Users, PUT /Users, PATCH /Users({id}), DELETE /Users/{id}
Gruppen POST /Groups, PUT /Groups, PATCH /Groups({id}), DELETE /Groups/{id}
ODER POST /OrganizationalUnits, PUT /OrganizationalUnits, PATCH /OrganizationalUnits({id}), DELETE /OrganizationalUnits/{id}
Organisatorischer Umbau POST /OrganizationalUnits/{id}/SubDomain/Rebuild

Diese Verzeichnisrouten sind teilweise historisch und führen nicht alle durch. ISecurityAdministrationService. Jede neue Mutation muss die transversale Fassade nutzen oder sie erweitern.

Sichere OData

ODataCrudController<TEntity> Erzwingt Sicherheit nur, wenn der Typ Immersive Berechtigungen konfiguriert hat.

Für einen sicheren Typ:

  • GET Filtert die IQueryable bevor die OData-Optionen angewendet werden.
  • GET(key) und die Navigationen überprüfen die Sichtbarkeit des Eltern;
  • PUT und PATCH Erfordern die Erlaubnis des Controllers zum Bearbeiten;
  • DELETE erfordert die Erlaubnis des Controllers zum Löschen;
  • POST erfordert Cerebrate, einen Root-Administrator oder das Administrators Die Ziel-Subdomäne.
  • Nach der Schaffung werden die automatischen Rechte von der Verwaltungsfassade angewendet.
Entitätsmenge Typ Lektüre Modifikation Löschung
/odata/Maps 15 ReadMap ModifyMap FullControlMap
/odata/Equipments 18 ReadEquipment ModifyEquipment FullControlEquipment
/odata/Workspaces 37 ReadWorkspace ModifyWorkspace FullControlWorkspace
/odata/SupervisionScopes 48 ReadSupervisionScope ModifySupervisionScope FullControlSupervisionScope

Beispiel:

GET {{baseUrl}}/odata/SupervisionScopes?$filter=Name eq 'Yvetot'&$select=Identifier,Name
Authorization: Bearer {{token}}
Accept: application/json

Der Sicherheitsfilter und der OData-Filter werden von der Geschäftsbasis erstellt und dann ausgeführt. Der Controller muss nicht die gesamte Sammlung herunterladen, bevor er filtert.

Nützliche RestFrontage-Seiten

Haupteingänge

Verlauf Funktion Zugang
/Security Aktuelles Domain-Dashboard Authentifizierter Nutzer
/Security/Explorer Durchstöbern Sie ORs, Benutzer, Gruppen und Geräte Authentifizierter Nutzer
/Security/UsersAndGroups Nutzer und Gruppen finden und verwalten Authentifizierter Nutzer; Mutationen, die von ihren Betreuern kontrolliert werden
/Security/RightsTester Erklärung eines wirksamen Rechts Authentifizierter Nutzer und aktuelle Organisation
/Security/Tools Sicherheitsprüfungen und -reparaturen Nur Cerebrate

Rechtetester

Der Tester erlaubt es Ihnen, Folgendes auszuwählen:

  1. ein Nutzer oder eine Gruppe;
  2. Ein erkannter Objekttyp.
  3. Ein Objekt, das zur aktuellen Organisation gehört.
  4. Eine für diesen Typ konfigurierte Berechtigung.

Es erzeugt ein AuditAccess die die Mitgliedschaftspfade beschreibt, die den Zugang erlaubt oder verweigert haben. Der Katalog erkennt Typen aus dem DbSet<TEntity> dessen Entität implementiert IIdentifiedObject und hat eine ImmersiveObjectAttribute.

Aktuelle Grenzen: Auswahl begrenzt auf 5.000 Objekte pro Typ und keine internen Aktien im Bericht.

Cerebrate-Werkzeuge

Die Seite /Security/Tools ist nur erreichbar über Cerebrate. Es sollte nicht als gemeinsame Verwaltungsoberfläche verwendet werden.

Unvereinbarkeit der Rechte

Das Werkzeug zeigt an:

  • die Anzahl der Rechte;
  • doppelte Gruppen;
  • das Vorhandensein des eindeutigen SQL-Indexes.

Die aktuelle manuelle Reinigung behält die aktuellste Zeile der gewählten Gruppe. Migration 20260815_EnforceUniqueRights Folgt einer konservativeren Strategie: Zuerst werden alle erlaubten und verbotenen Flaggen zusammengeführt, bevor die alten Linien entfernt werden.

Organisationsstruktur

Die Prüfung überprüft für jede Organisation:

  • ORs Groups, Users und Devices ;
  • Gruppen Administrators, Users und Sharers ;
  • Der Nutzer {Organisation}_Admin ;
  • Standardmitgliedschaften
  • konventionelle Genehmigungsgruppen bereits anerkannt.

Reparationsforderungen EnsureSubDomainDefaultsAsync und bewahrt bestehende Daten.

Automatische Gebühren

Die Prüfung vergleicht die erwarteten und registrierten Ansprüche für:

  • Karten;
  • Ausrüstung;
  • Arbeitsbereiche;
  • Der Umfang der Aufsicht.

Es kann ein Objekt oder eine Auswahl reparieren. Die Reparatur fügt nur die fehlenden Auto-Flags hinzu.

Wachsamkeits- und Schärfungspunkte sind zu erwarten

Hohe Priorität

  1. GET /api/Security/ResetDomain Derzeit trägt er [AllowAnonymous]. Selbst wenn die Rechte nicht geändert werden, führt es zu einem globalen Neuladen und einer Ungültigkeit; es muss geschützt oder auf die Wiederherstellungskonsole verschoben werden.
  2. DELETE /api/Security/Rights löscht direkt in SecurityModel ohne die Genehmigung von ISecurityAdministrationService. Es muss ersetzt werden durch POST /Rights mit null Flaggen oder durch eine dedizierte zentrale Methode.
  3. Interne Aktien werden noch nicht von ObjectSecurityService. Sie bestehen fort, bieten aber noch keinen Zugang in OData.
  4. Der historische Test HaveRight und Rasiermesser-Tester SecurityUtils Direkt und sehen Sie die Aktien nicht.

Konsistenzpriorität

  1. Zentralisieren Sie schrittweise den Transfer von Nutzern, Gruppen, OR und Mitgliedschaften.
  2. Fügen Sie eine authentifizierte Organisationsauswahlroute hinzu, die für stateless Bearer-Kunden geeignet ist, oder fügen Sie einen kontrollierten Organisationskontext in den API-Vertrag ein.
  3. Stellen Sie eine Share List Route frei, falls WebGL-Kunden Share ohne Razor-Parteilichkeit verwalten müssen.
  4. Erweitern Sie das automatische Entitlement Auditing, wenn neue Typen in die Pipeline eingesteckt werden.
  5. Nach der Kundenmigration werde ich historische Aliase schließlich zurückziehen.

Fügen Sie einen neuen sicheren Typ hinzu

Um die Fassade zu verlängern, ohne einen Service nach Typ zu schaffen:

  1. Deklarieren Sie den Typ in ImmersiveObjectType ;
  2. Bewerben Sie sich ImmersiveObjectAttribute auf der Entität;
  3. Registrieren Sie seine Permission Im Feld und im Moment ObjectsToPermissions ;
  4. Leite den Controller abODataCrudController<TEntity> ;
  5. Stellen Sie bereit ReadPermission, UpdatePermission und DeletePermission ;
  6. bestehende, querschnittsübergreifende Dienstleistungen einzubauen;
  7. Stellen Sie sicher, dass ISubDomainService kann die Organisation der Entität bestimmen;
  8. Fügen Sie seine hinzu RightsDefaultPattern falls nötig;
  9. Fügen Sie den Typ zur automatischen Anspruchsprüfung hinzu.
  10. Test, lesen, erstellen, bearbeiten, löschen, sperren, Cerebrate und Multi-Instance.

Referenzdateien

| Betreff | Akte | |---|---| | REST-Controller | Controllers/SecurityController.cs | | Sitzungsleiter/Organisation | Controllers/SessionController.cs | | JWT-Pipeline | Commons/Immersive.RestFrontage.Components/Security/TokenParserMiddleware.cs, TokenCheckMiddleware.cs | | Generischer OData-Controller | corporate/Commons/GraphicStream.Server.Components/Controllers/ODataCrudController.cs | | Testerkatalog | Security/SecurizedObjectCatalog.cs | | Tester | Pages/Security/RightsTester.cshtml.cs | | Werkzeuge | Pages/Security/Tools | | Modale Teilung | Pages/Security/Modals/SharedAccess.cshtml und .cshtml.cs | | Externe Seite | Pages/Shared/Index.cshtml und .cshtml.cs |

Entwickler

  • Lernzentrum
  • Launcher
  • Immersive Script
  • Immersive Forge
  • SDK Immersive