Condividi tramite

Autorizzazione e ruoli in Generatore API dati

  • Articolo

Il generatore di API dati usa un flusso di lavoro di autorizzazione basato sui 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 nel file di configurazione per comprendere quali azioni, campi e criteri sono disponibili per tale ruolo nell'entità richiesta.

Ruoli

I ruoli impostano il contesto delle autorizzazioni in cui deve essere eseguita una richiesta. Per ogni entità definita nella configurazione di runtime, è possibile definire un set di ruoli e autorizzazioni associate che determinano come è possibile accedere all'entità negli endpoint REST e GraphQL.

Il generatore di API dati valuta le richieste nel contesto di un singolo ruolo:

  • anonymous quando non viene presentato alcun token di accesso.
  • authenticated quando viene presentato un token di accesso valido.
  • <CUSTOM_USER_ROLE> quando viene presentato un token di accesso valido e l'intestazione X-MS-API-ROLE HTTP è inclusa specificando un ruolo utente incluso anche nell'attestazione del token di roles accesso.

I ruoli non sono additivi, il che significa che un utente membro di entrambi Role1 e Role2 non eredita le autorizzazioni associate a entrambi i ruoli.

Ruoli del 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 autorizzazioni per il anonymous ruolo se si desidera l'accesso non autenticato.

Esempio

La configurazione di runtime del generatore di API dati seguente illustra in modo esplicito la configurazione del ruolo anonymous di sistema per includere l'accesso in lettura all'entità Book:

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

Quando un'applicazione client invia una richiesta di accesso 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 configurazione di runtime del generatore di API dati seguente illustra in modo esplicito la configurazione del ruolo authenticated di sistema per includere l'accesso in 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. Il token di accesso fornito dall'app client deve includere attestazioni del ruolo che elencano l'appartenenza al ruolo 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 è un membro del ruolo anonimo per impostazione predefinita. Se l'utente è autenticato, l'utente è membro di entrambi i anonymous ruoli e authenticated .

Quando un'app client invia una richiesta autenticata a Generatore API dati distribuita usando App Web statiche connessioni alle banche dati (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é Il generatore di 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 roles accesso 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 sui risultati restituiti da una richiesta?

La sintassi per la definizione delle autorizzazioni è descritta nell'articolo sulla configurazione del 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, il ruolo anonymous del sistema o authenticated
  • Se incluso, il ruolo impostato nell'intestazione X-MS-API-ROLE HTTP.

Protezione per impostazione predefinita

Per impostazione predefinita, un'entità non ha 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 anonymous ruoli e authenticated . Uno o più ruoli utente possono essere definiti all'interno della configurazione delle autorizzazioni di un'entità e tutti gli altri ruoli, sistema o definiti dall'utente non definiti 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 administrator ruolo e includere tale ruolo nell'intestazione HTTP per operare sull'entità X-MS-API-ROLEbook :

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

Nota

Per applicare il controllo di accesso per le query GraphQL quando si usa generatore di 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 procedure: execute

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

Accesso ai campi

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

L'esempio seguente impedisce agli utenti del 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" ]
              }
            }
          ]
        }
      ]
    }

Nota

Per applicare il controllo di accesso per le query GraphQL quando si usa generatore di API dati con Azure Cosmos DB, è necessario usare la @authorize direttiva nel file di schema GraphQL fornito. Per le mutazioni e i filtri di GraphQL nelle query GraphQL, tuttavia, 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:

  • create
  • lettura
  • update
  • eliminazione

Avviso

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

Nota

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