Autorizzazione e ruoli nel Generatore di API Dati

Il generatore di API dati usa un flusso di lavoro di autorizzazione basato su ruoli. Qualsiasi richiesta in ingresso, autenticata o meno, viene assegnata a un ruolo. I ruoli possono essere ruoli di sistema o ruoli utente. Il ruolo assegnato viene quindi controllato in base alle autorizzazioni definite specificate nella configurazione per comprendere quali azioni, campi e criteri sono disponibili per tale ruolo nell'entità richiesta.

Determinazione del ruolo dell'utente

Nessun ruolo ha autorizzazioni predefinite. Dopo che il generatore di API dati determina un ruolo, l'entità permissions deve definire actions per tale ruolo affinché la richiesta venga completata correttamente.

La matrice di valutazione del ruolo seguente si applica ai provider JWT bearer (ad esempio, EntraID/AzureAD e Custom) in cui il client invia Authorization: Bearer <token>.

Token di connessione fornito	X-MS-API-ROLE Fornito	Ruolo richiesto presente nel claim del token roles	Ruolo/risultato effettivo
NO	NO	N/A	Anonymous
Sì (valido)	NO	N/A	Authenticated
Sì (valido)	Sì	NO	Rifiutato (403 Vietato)
Sì (valido)	Sì	Sì	valore X-MS-API-ROLE
Sì (non valido)	Qualunque	N/A	Rifiutato (401 Non autorizzato)

Per usare un ruolo diverso da Anonymous o Authenticated, l'intestazione X-MS-API-ROLE è obbligatoria.

Annotazioni

Una richiesta può essere associata a molti ruoli nell'entità autenticata. Tuttavia, il generatore di API dati valuta le autorizzazioni e i criteri nel contesto di un ruolo efficace. Se specificato, l'intestazione X-MS-API-ROLE seleziona il ruolo usato.

Note del provider:

• Provider EasyAuth (ad esempio, AppService): l'autenticazione può essere stabilita da intestazioni inserite dalla piattaforma (ad esempio X-MS-CLIENT-PRINCIPAL) anziché da un bearer token.
• Simulator: le richieste vengono considerate autenticate per lo sviluppo/test, senza convalidare un token reale.

Ruoli di sistema

I ruoli di sistema sono ruoli predefiniti riconosciuti dal generatore di API dati. Un ruolo di sistema viene assegnato automaticamente a un richiedente indipendentemente dall'appartenenza al ruolo del richiedente indicato nei token di accesso. Esistono due ruoli di sistema: Anonymous e Authenticated.

Ruolo di sistema anonimo

Il ruolo di Anonymous sistema viene assegnato alle richieste eseguite da utenti non autenticati. Le entità definite dalla configurazione di runtime devono includere le autorizzazioni per il Anonymous ruolo se si desidera l'accesso non autenticato.

Esempio

La seguente configurazione di runtime del builder dell'API dati mostra esplicitamente la configurazione del ruolo Anonymous di sistema per includere l'accesso a lettura all'entità Book.

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

Quando un'applicazione client invia una richiesta che accede all'entità Book per conto di un utente non autenticato, l'app non deve includere l'intestazione Authorization HTTP.

Ruolo del sistema autenticato

Il ruolo di Authenticated sistema viene assegnato alle richieste eseguite dagli utenti autenticati.

Esempio

La seguente configurazione di runtime del builder dell'API dati mostra esplicitamente la configurazione del ruolo Authenticated di sistema per includere l'accesso a lettura all'entità Book.

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

Ruoli utente

I ruoli utente sono ruoli non di sistema assegnati agli utenti all'interno del provider di identità impostato nella configurazione di runtime. Per consentire al generatore di API dati di valutare una richiesta nel contesto di un ruolo utente, è necessario soddisfare due requisiti:

1. L'entità autenticata deve includere rivendicazioni che elencano il ruolo di appartenenza di un utente, ad esempio la rivendicazione JWT roles.
2. L'app client deve includere l'intestazione X-MS-API-ROLE HTTP con le richieste e impostare il valore dell'intestazione come ruolo utente desiderato.

Esempio di valutazione dei ruoli

L'esempio seguente illustra le richieste effettuate all'entità Book configurata nella configurazione di runtime di Generatore API dati come indicato di seguito:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Il generatore di API dati valuta le richieste nel contesto di un singolo ruolo effettivo. Se una richiesta viene autenticata e non viene fornita alcuna X-MS-API-ROLE intestazione, il generatore di API dati valuta la richiesta nel contesto del ruolo di Authenticated sistema per impostazione predefinita.

Se la richiesta dell'applicazione client include anche l'intestazione X-MS-API-ROLE HTTP con il valore author, la richiesta viene valutata nel contesto del author ruolo. Richiesta di esempio che include un token di accesso e X-MS-API-ROLE un'intestazione HTTP:

curl -k -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

Importante

La richiesta di un'app client viene rifiutata quando l'attestazione del token di accesso roles fornito non contiene il ruolo elencato nell'intestazione X-MS-API-ROLE.

Autorizzazioni

Le autorizzazioni descrivono:

• Chi può effettuare richieste su un'entità in base all'appartenenza al ruolo?
• Quali azioni (creare, leggere, aggiornare, eliminare, eseguire) che un utente può eseguire?
• Quali campi sono accessibili per una determinata azione?
• Quali restrizioni aggiuntive esistono nei risultati restituiti da una richiesta?

La sintassi per la definizione delle autorizzazioni è descritta nell'articolo sulla configurazione di runtime.

Importante

Possono essere definiti più ruoli all'interno della configurazione delle autorizzazioni di una singola entità. Tuttavia, una richiesta viene valutata solo nel contesto di un singolo ruolo:

• Per impostazione predefinita, o il ruolo di sistema Anonymous o Authenticated
• Se incluso, il ruolo è impostato nell'intestazione X-MS-API-ROLE HTTP.

Sicuro per impostazione predefinita

Per impostazione predefinita, un'entità non dispone di autorizzazioni configurate, il che significa che nessuno può accedere all'entità. Inoltre, Il generatore di API dati ignora gli oggetti di database quando non viene fatto riferimento nella configurazione di runtime.

Le autorizzazioni devono essere configurate in modo esplicito

Per consentire l'accesso non autenticato a un'entità, il Anonymous ruolo deve essere definito in modo esplicito nelle autorizzazioni dell'entità. Ad esempio, le book autorizzazioni dell'entità vengono impostate in modo esplicito per consentire l'accesso in lettura non autenticato:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

Se si vuole che gli utenti non autenticati e autenticati abbiano accesso, concedere in modo esplicito le autorizzazioni a entrambi i ruoli di sistema (Anonymous e Authenticated).

Quando le operazioni di lettura devono essere limitate solo agli utenti autenticati, è necessario impostare la configurazione delle autorizzazioni seguente, con conseguente rifiuto di richieste non autenticate:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Authenticated",
    "actions": [ "read" ]
  }]
}

Un'entità non richiede e non è preconfigurata con le autorizzazioni per i ruoli Anonymous e Authenticated. È possibile definire uno o più ruoli utente all'interno della configurazione delle autorizzazioni di un'entità e tutti gli altri ruoli non definiti, il sistema o definito dall'utente, vengono automaticamente negati l'accesso.

Nell'esempio seguente il ruolo administrator utente è l'unico ruolo definito per l'entità book . Un utente deve essere un membro del ruolo administrator e includere tale ruolo nell'intestazione X-MS-API-ROLE HTTP per operare sull'entità book.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Annotazioni

Per applicare il controllo di accesso per le query GraphQL quando si usa Generatore API dati con Azure Cosmos DB, è necessario usare la @authorize direttiva nel file di schema GraphQL fornito. Tuttavia, per le mutazioni e i filtri GraphQL nelle query GraphQL, la configurazione delle autorizzazioni applica comunque il controllo di accesso come descritto in precedenza.

Azioni

Le azioni descrivono l'accessibilità di un'entità nell'ambito di un ruolo. Le azioni possono essere specificate singolarmente o con il collegamento con caratteri jolly: * (asterisco). Il collegamento con caratteri jolly rappresenta tutte le azioni supportate per il tipo di entità:

• Tabelle e viste: create, read, update, delete
• Stored procedures: execute

Per altre informazioni sulle azioni, vedere la documentazione del file di configurazione .

Accesso al campo

È possibile configurare i campi che devono essere accessibili per un'azione. Ad esempio, è possibile impostare i campi da includere ed escludere dall'azione read .

Nell'esempio seguente viene impedito agli utenti nel free-access ruolo di eseguire operazioni di lettura su Column3. I riferimenti a Column3 nelle richieste GET (endpoint REST) o nelle query (endpoint GraphQL) generano una richiesta rifiutata:

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Annotazioni

Per applicare il controllo di accesso per le query GraphQL quando si usa Generatore API dati con Azure Cosmos DB, è necessario usare la @authorize direttiva nel file di schema GraphQL fornito. Tuttavia, per le mutazioni e i filtri graphQL nelle query GraphQL, la configurazione delle autorizzazioni applica comunque il controllo di accesso come descritto qui.

Sicurezza a livello di elemento

I criteri di database consentono di filtrare i risultati a livello di riga. I criteri si traducono in predicati di query valutati dal database, garantendo agli utenti l'accesso solo ai record autorizzati.

Azioni supportate	Non supportato
read, update, delete	create, execute

Annotazioni

Azure Cosmos DB per NoSQL attualmente non supporta i criteri di database.

Per istruzioni dettagliate sulla configurazione, informazioni di riferimento sulla sintassi ed esempi, vedere Configurare i criteri di database.

Esempio rapido

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Contenuti correlati

• Configurare i criteri di database per il filtro a livello di riga
• Configurare l'autenticazione di Microsoft Entra ID
• Configurare l'autenticazione del simulatore per i test locali