Condividi tramite

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

Non esistono role autorizzazioni predefinite. Dopo che una regola è determinata dal generatore di permissions API dati, l'entità deve definire actions per tale ruolo affinché la richiesta venga completata correttamente.

Token fornito x-ms-api-role Fornito x-ms-api-role in Token Ruolo risultante
NO NO NO anonymous
Sì NO NO authenticated
Sì Sì NO Eccezione
Sì Sì Sì valore x-ms-api-role

Per avere un ruolo diverso da anonymous o authenticated, l'intestazione x-ms-api-role è obbligatoria.

Annotazioni

Una richiesta può avere un solo ruolo. Anche se il token indica più ruoli, il valore seleziona il x-ms-api-role ruolo assegnato alla richiesta.

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'app client deve fornire un token di accesso che includa attestazioni di ruolo che indicano l'appartenenza ai ruoli di un utente.
  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" ]
        }
    ]
}

In App Web statiche un utente è membro del ruolo anonimo per impostazione predefinita. Se l'utente è autenticato, è membro di entrambi i ruoli anonymous e authenticated.

Quando un'app client invia una richiesta autenticata a Generatore API dati distribuita usando connessioni di database di App Web statiche (anteprima), l'app client fornisce un token di accesso che App Web statiche trasforma in JSON:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Poiché Generatore API dati valuta le richieste nel contesto di un singolo ruolo, valuta la richiesta nel contesto del ruolo authenticated di 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 -r 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" ]
  }]
}

Per semplificare la definizione delle autorizzazioni in un'entità, si supponga che se non sono presenti autorizzazioni specifiche per il authenticated ruolo, vengono usate le autorizzazioni definite per il anonymous ruolo. La book configurazione illustrata in precedenza consente a qualsiasi utente anonimo o autenticato di eseguire operazioni di lettura sull'entità book .

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, il controllo di accesso viene ancora applicato dalla configurazione delle autorizzazioni 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, il controllo di accesso viene ancora applicato dalla configurazione delle autorizzazioni, come descritto qui.

Sicurezza a livello di elemento

Le espressioni dei criteri di database consentono di limitare ulteriormente i risultati. I criteri di database convertono le espressioni in predicati di query eseguiti sul database. Le espressioni dei criteri di database sono supportate per le azioni seguenti:

  • creare
  • leggere
  • aggiornare
  • eliminare

Avvertimento

L'azione esegui, utilizzata con le stored procedure, non supporta i criteri di database.

Annotazioni

I criteri di database non sono attualmente supportati da CosmosDB per NoSQL.

Per altre informazioni sui criteri di database, vedere la documentazione del file di configurazione .

Esempio

Criteri di database che limitano l'azione read sul consumer ruolo per restituire solo i record in cui il titolo è "Titolo di esempio".

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

Contenuti correlati

  • Last updated on