Facciata API e Sicurezza

  • Tutorial

Questo documento introduce i punti di ingresso RestFrontage per l'autenticazione di un client, la visualizzazione o modifica della sicurezza, il filtraggio degli oggetti OData e l'utilizzo degli strumenti Razor.

Per il modello concettuale e le regole decisionali, vedi Panoramica di Immersive Security.

Autenticazione di un client API

Prendi un gettone

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

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

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

Risposta semplificata:

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

Il cliente trasmette poi:

Authorization: Bearer {{token}}

Gli accessi e la password devono essere inviati solo tramite HTTPS.

Ciclo dei token

Parola e strada Funzione
POST /api/Security/Token/Renew Rinnova un token valido
GET oppure POST /api/Security/Token/Validate Verifica che la pipeline accetti il token
GET oppure POST /api/Security/Whoami Ottieni il nome dell'identità attuale

Endpoint di sicurezza primari

Tutte le strade sottostanti hanno il prefisso /api/Security.

Controllo dei diritti e amministrazione

Parola e strada Utilizzo Stato raccomandato
GET /Users/{askerId}/Rights/{flags}/SecurizedObjects/{type}/{objectId} Testare una maschera su un oggetto Storia; non include azioni
GET /Rights?securedObjectIdentifier=...&securedObjectTypeIdentifier=... Leggi i diritti espliciti di un oggetto Può essere usato per l'amministrazione
POST /Rights Applica una serie di diritti tramite ISecurityAdministrationService Consiglio per la scrittura
DELETE /Rights?rightIdentifiers=... Rimuovere i diritti tramite ID Storia; per migrare sulla facciata centrale
GET /Permissions Permessi di lettura configurati Consigliato per costruire un'interfaccia senza flag codificati

Esempio dell'applicazione di un diritto:

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

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

Regole di POST /Rights :

  • l'attore viene sempre letto dal contesto autenticato;
  • Gli amministratori cerebrali e di radice possono amministrare tutti i diritti;
  • altrimenti l'attore e i beneficiari devono appartenere all'organizzazione corrente;
  • Un beneficiario BuiltIn è protetto;
  • l'attore deve essere in grado di somministrare ogni oggetto target;
  • i flag devono corrispondere ai permessi configurati;
  • AuthorizedFlags = 0 e DeniedFlags = 0 abolisce il corrispondente dovere;
  • Più query per lo stesso triplio vengono normalizzate prima di scrivere.

Risposte agli errori:

  • 400 - Dati o flag non validi
  • 401 : assenza di identità autenticata;
  • 403 : attore non autorizzato o organizzazione scadente;
  • 409 : Incoerenza o conflitto di dati, come i vecchi diritti duplicati.

Azioni

Parola e strada Utilizzo
POST /SharedAccess Crea una condivisione che AccessLinkIdentifier Nota a piè di pagina uno TinyUrl Esistente
POST /SharedAccess/Aggregate Creare esplicitamente un aggregato e specificare il TinyUrl a livello radice
POST /SharedAccess/{grantIdentifier}/Revoke Revoca la condivisione senza eliminare il TinyUrl

Esempio di condivisione interna per una settimana:

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
      }
    ]
  }
}

Per un destinatario esterno, sostituire ExternalRecipientEmail e se ne andiamo BeneficiaryDomainSecurityObjectIdentifier à null. Deve essere definito esattamente uno dei due campi.

Risposta semplificata:

{
  "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"
}

Il server non deduisce alcuna dipendenze. Beholder, Forge o il Giocatore devono inviare la lista completa degli oggetti necessari per aprire il bersaglio.

Non esiste ancora una via REST dedicata per la lista di condivisioni. Questa lista è attualmente consumata dal parziale Razor tramite GetSharedAccessGrantsAsync.

Chiamata minima del modale di condivisione:

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

Elenco

La facciata mostra anche le seguenti famiglie:

Famiglia Strade principali
Risoluzione GET /DomainObjects/{dnOuId}, POST /Discover
Navigazione GET /DomainObjects/{dn}/Members, GET /Explorer/{dn}/Search/{criteria}
Affiliazioni GET, POST, PUT, DELETE /DomainObjects/{dn}/Membership
Membri del gruppo PUT, POST, DELETE /Groups/{dn}/Members
Gerarchia GET /DomainObjects/{dn}/GroupMembershipHierarchy
Campi espandibili GET, PUT, POST /DomainObjects/{dn}/Fields
Utenti POST /Users, PUT /Users, PATCH /Users({id}), DELETE /Users/{id}
Gruppi POST /Groups, PUT /Groups, PATCH /Groups({id}), DELETE /Groups/{id}
OPPURE POST /OrganizationalUnits, PUT /OrganizationalUnits, PATCH /OrganizationalUnits({id}), DELETE /OrganizationalUnits/{id}
Ricostruzione organizzativa POST /OrganizationalUnits/{id}/SubDomain/Rebuild

Questi percorsi di elenco sono in parte storici e non tutti attraversano ISecurityAdministrationService. Ogni nuova mutazione deve utilizzare o estendere la facciata trasversale.

Secure OData

ODataCrudController<TEntity> Applica la sicurezza solo se il tipo Immersive ha i permessi configurati.

Per un tipo sicuro:

  • GET filtra il IQueryable prima che vengano applicate le opzioni OData.
  • GET(key) e le navigazioni verificano la visibilità del genitore;
  • PUT e PATCH richiedere il permesso del controller per modificare;
  • DELETE richiede il permesso del controller per eliminare;
  • POST richiede Cerebrate, un amministratore root, oppure il Administrators Il sottodominio target.
  • Dopo la creazione, i diritti automatici sono applicati dalla facciata amministrativa.
Insieme di entità Tipo Lettura Modifiche Cancellazione
/odata/Maps 15 ReadMap ModifyMap FullControlMap
/odata/Equipments 18 ReadEquipment ModifyEquipment FullControlEquipment
/odata/Workspaces 37 ReadWorkspace ModifyWorkspace FullControlWorkspace
/odata/SupervisionScopes 48 ReadSupervisionScope ModifySupervisionScope FullControlSupervisionScope

Esempio:

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

Il filtro di sicurezza e il filtro OData sono composti e poi eseguiti dalla business base. Il controller non deve scaricare l'intera collezione prima del filtraggio.

Pagine utili di RestFrontage

Ingressi principali

Percorso Funzione Accesso
/Security Cruscotto del Dominio Attuale Utente autenticato
/Security/Explorer Naviga in OR, utenti, gruppi e dispositivi Utente autenticato
/Security/UsersAndGroups Trova e amministra utenti e gruppi Utente autenticato; mutazioni controllate dai loro gestori
/Security/RightsTester Spiegazione di un diritto efficace Utente autenticato e organizzazione attuale
/Security/Tools Audit e riparazioni di sicurezza Solo cervello

Tester dei diritti

Il tester ti permette di scegliere:

  1. un utente o un gruppo;
  2. Un tipo di oggetto riconosciuto.
  3. Un oggetto appartenente all'organizzazione attuale.
  4. Un permesso configurato per questo tipo.

Produce un AuditAccess che dettaglia i percorsi di appartenenza che hanno permesso o negato l'accesso. Il catalogo rileva tipi dal DbSet<TEntity> la cui entità implementa IIdentifiedObject e ha un ImmersiveObjectAttribute.

Limiti attuali: selezione limitata a 5.000 oggetti per tipo e nessuna quota interna nel rapporto.

Strumenti per il cervello

La pagina /Security/Tools è accessibile solo da Cerebrate. Non dovrebbe essere usato come interfaccia amministrativa comune.

Unicità dei diritti

Lo strumento mostra:

  • il numero di diritti;
  • gruppi duplicati;
  • la presenza dell'indice SQL univoco.

La pulizia manuale attuale conserva la riga più recente del gruppo scelto. Migrazione 20260815_EnforceUniqueRights segue una strategia più conservatrice: prima unisce tutte le bandiere permesse e proibite prima di rimuovere le vecchie linee.

Struttura delle organizzazioni

L'audit verifica per ciascuna organizzazione:

  • Ore Groups, Users e Devices ;
  • Gruppi Administrators, Users e Sharers ;
  • L'utente {Organisation}_Admin ;
  • Iscrizioni standard
  • gruppi di permessi convenzionali già riconosciuti.

La riparazione richiede EnsureSubDomainDefaultsAsync e preserva i dati esistenti.

Tariffe automatiche

L'audit confronta i diritti previsti e registrati per:

  • mappe;
  • equipaggiamento;
  • spazi di lavoro;
  • L'ambito della supervisione.

Può riparare un oggetto o una selezione. La riparazione aggiunge solo le bandiere automatiche mancanti.

Punti di vigilanza e rafforzamento da aspettarsi

Alta priorità

  1. GET /api/Security/ResetDomain Attualmente trasmette [AllowAnonymous]. Anche se non cambiano i diritti, provoca un ricaricamento globale e l'invalidazione; deve essere protetto o spostato nella console di recupero.
  2. DELETE /api/Security/Rights elimina direttamente in SecurityModel senza passare attraverso l'autorizzazione di ISecurityAdministrationService. Deve essere sostituito da POST /Rights senza flag o tramite un metodo centrale dedicato.
  3. Le azioni interne non sono ancora visualizzate da ObjectSecurityService. Sono mantenuti ma non forniscono ancora accesso in OData.
  4. La prova storica HaveRight e uso del tester di rasoio SecurityUtils direttamente e non vedere le azioni.

Priorità di coerenza

  1. Centralizza gradualmente il trasferimento di utenti, gruppi, sala operatoria e iscrizioni.
  2. Aggiungere una via di selezione dell'organizzazione autenticata adatta ai clienti Bearer senza stato, oppure includere un contesto organizzativo controllato nel contratto API.
  3. Esponi una via di share list se i client WebGL devono amministrare le quote senza partigianeria Razor.
  4. Estendere l'audit automatico dei diritti quando nuovi tipi vengono inseriti nella pipeline.
  5. Alla fine ritiro gli alias storici dopo la migrazione dei clienti.

Aggiungi un nuovo tipo sicuro

Per estendere la facciata senza creare un servizio per tipo:

  1. dichiarare il tipo in ImmersiveObjectType ;
  2. Candidati ImmersiveObjectAttribute sull'entità;
  3. registra il suo Permission nel campo e nell'istante ObjectsToPermissions ;
  4. derivare il controllore daODataCrudController<TEntity> ;
  5. fornire ReadPermission, UpdatePermission e DeletePermission ;
  6. iniettare i servizi di taglio trasversali esistenti;
  7. assicurati che ISubDomainService può trovare l'organizzazione dell'entità;
  8. aggiungi il suo RightsDefaultPattern se necessario;
  9. Aggiungi il tipo all'audit automatico dei diritti di sicurezza.
  10. Test read, crea, modifica, cancella, bann, Cerebrate e multi-istanze.

File di riferimento

| Oggetto | File | |---|---| | Controller REST | Controllers/SecurityController.cs | | Controllore Sessione/Organizzazione | Controllers/SessionController.cs | | JWT Pipeline | Commons/Immersive.RestFrontage.Components/Security/TokenParserMiddleware.cs, TokenCheckMiddleware.cs | | Controller OData generico | corporate/Commons/GraphicStream.Server.Components/Controllers/ODataCrudController.cs | | Catalogo Tester | Security/SecurizedObjectCatalog.cs | | Tester | Pages/Security/RightsTester.cshtml.cs | | Strumenti | Pages/Security/Tools | | Condivisione modale | Pages/Security/Modals/SharedAccess.cshtml e .cshtml.cs | | Pagina esterna | Pages/Shared/Index.cshtml e .cshtml.cs |

Sviluppatori