Autorisatie en rollen in Data API Builder

Data API Builder maakt gebruik van een op rollen gebaseerde autorisatiewerkstroom. Elke binnenkomende aanvraag, al dan niet geverifieerd, wordt toegewezen aan een rol. Rollen kunnen systeemrollen of gebruikersrollen zijn. De toegewezen rol wordt vervolgens gecontroleerd op basis van de gedefinieerde machtigingen die zijn opgegeven in het configuratiebestand om te begrijpen welke acties, velden en beleidsregels beschikbaar zijn voor die rol op de aangevraagde entiteit.

Rollen

Rollen stellen de machtigingencontext in waarin een aanvraag moet worden uitgevoerd. Voor elke entiteit die is gedefinieerd in de runtimeconfiguratie, kunt u een set rollen en bijbehorende machtigingen definiëren die bepalen hoe de entiteit kan worden geopend in zowel de REST- als GraphQL-eindpunten.

Data API Builder evalueert aanvragen in de context van één rol:

• anonymous wanneer er geen toegangstoken wordt weergegeven.
• authenticated wanneer een geldig toegangstoken wordt weergegeven.
• <CUSTOM_USER_ROLE> wanneer een geldig toegangstoken wordt weergegeven en de X-MS-API-ROLE HTTP-header is opgenomen om een gebruikersrol op te geven die ook is opgenomen in de claim van roles het toegangstoken.

Rollen zijn niet additief, wat betekent dat een gebruiker die lid is van beide Role1 en Role2 de machtigingen die aan beide rollen zijn gekoppeld, niet over neemt.

Systeemrollen

Systeemrollen zijn ingebouwde rollen die worden herkend door Data API Builder. Een systeemrol wordt automatisch toegewezen aan een aanvrager, ongeacht het rollidmaatschap van de aanvrager die wordt aangegeven in hun toegangstokens. Er zijn twee systeemrollen: anonymous en authenticated.

Anonieme systeemrol

De anonymous systeemrol wordt toegewezen aan aanvragen die worden uitgevoerd door niet-geverifieerde gebruikers. Door runtimeconfiguratie gedefinieerde entiteiten moeten machtigingen voor de anonymous rol bevatten als niet-geverifieerde toegang gewenst is.

Voorbeeld

De volgende runtimeconfiguratie van Data API Builder laat zien dat de systeemrol anonymous expliciet is geconfigureerd om leestoegang tot de entiteit Book op te nemen:

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

Wanneer een clienttoepassing namens een niet-geverifieerde gebruiker een aanvraag voor toegang tot de entiteit Book verzendt, mag de app de Authorization HTTP-header niet bevatten.

Geverifieerde systeemrol

De authenticated systeemrol wordt toegewezen aan aanvragen die worden uitgevoerd door geverifieerde gebruikers.

Voorbeeld

De volgende runtimeconfiguratie van Data API Builder laat zien dat de systeemrol authenticated expliciet is geconfigureerd om leestoegang tot de entiteit Book op te nemen:

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

Gebruikersrollen

Gebruikersrollen zijn niet-systeemrollen die zijn toegewezen aan gebruikers binnen de id-provider die u hebt ingesteld in de runtime-configuratie. Data API Builder moet aan twee vereisten voldoen om een aanvraag te evalueren in de context van een gebruikersrol:

1. Het opgegeven toegangstoken van de client-app moet rolclaims bevatten die het rollidmaatschap van een gebruiker vermelden.
2. De client-app moet de HTTP-header X-MS-API-ROLE met aanvragen bevatten en de waarde van de header instellen als de gewenste gebruikersrol.

Voorbeeld van rolevaluatie

In het volgende voorbeeld ziet u als volgt aanvragen voor de Book entiteit die is geconfigureerd in de runtimeconfiguratie van Data API Builder:

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

In Static Web Apps is een gebruiker standaard lid van de anonieme rol. Als de gebruiker is geverifieerd, is de gebruiker lid van de anonymous rollen en authenticated .

Wanneer een client-app een geverifieerde aanvraag verzendt naar Data API Builder die is geïmplementeerd met Static Web Apps database verbindingen (preview), levert de client-app een toegangstoken dat Static Web Apps wordt omgezet in JSON:

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

Omdat Data API Builder aanvragen evalueert in de context van één rol, wordt de aanvraag standaard geëvalueerd in de context van de systeemrol authenticated .

Als de aanvraag van de clienttoepassing ook de HTTP-header X-MS-API-ROLE met de waarde authorbevat, wordt de aanvraag geëvalueerd in de context van de author rol. Een voorbeeldaanvraag met een toegangstoken en X-MS-API-ROLE HTTP-header:

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

Belangrijk

De aanvraag van een client-app wordt geweigerd wanneer de claim van roles het opgegeven toegangstoken niet de rol bevat die wordt vermeld in de X-MS-API-ROLE header.

Machtigingen

Machtigingen beschrijven:

• Wie kan aanvragen indienen voor een entiteit op basis van rollidmaatschap?
• Welke acties (maken, lezen, bijwerken, verwijderen, uitvoeren) kan een gebruiker uitvoeren?
• Welke velden zijn toegankelijk voor een bepaalde actie?
• Welke extra beperkingen gelden er voor de resultaten die door een aanvraag worden geretourneerd?

De syntaxis voor het definiëren van machtigingen wordt beschreven in het artikel runtimeconfiguratie.

Belangrijk

Er kunnen meerdere rollen zijn gedefinieerd binnen de machtigingsconfiguratie van één entiteit. Een aanvraag wordt echter alleen geëvalueerd in de context van één rol:

• Standaard is de systeemrol anonymous of authenticated
• Indien opgenomen, de rol die is ingesteld in de X-MS-API-ROLE HTTP-header.

Standaardbeveiliging

Een entiteit heeft standaard geen machtigingen geconfigureerd, wat betekent dat niemand toegang heeft tot de entiteit. Bovendien negeert Data API Builder databaseobjecten wanneer er niet naar wordt verwezen in de runtimeconfiguratie.

Machtigingen moeten expliciet worden geconfigureerd

Als u niet-geverifieerde toegang tot een entiteit wilt toestaan, moet de anonymous rol expliciet worden gedefinieerd in de machtigingen van de entiteit. De machtigingen van de book entiteit zijn bijvoorbeeld expliciet ingesteld om niet-geverifieerde leestoegang toe te staan:

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

Als u de definitie van machtigingen voor een entiteit wilt vereenvoudigen, wordt ervan uitgegaan dat als er geen specifieke machtigingen voor de authenticated rol zijn, de machtigingen worden gebruikt die voor de anonymous rol zijn gedefinieerd. Met de book configuratie die eerder is weergegeven, kunnen anonieme of geverifieerde gebruikers leesbewerkingen uitvoeren op de book entiteit.

Wanneer leesbewerkingen alleen moeten worden beperkt tot geverifieerde gebruikers, moet de volgende configuratie van machtigingen worden ingesteld, wat resulteert in de afwijzing van niet-geverifieerde aanvragen:

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

Een entiteit is niet vereist en is niet vooraf geconfigureerd met machtigingen voor de anonymous rollen en authenticated . Een of meer gebruikersrollen kunnen worden gedefinieerd in de machtigingsconfiguratie van een entiteit en alle andere niet-gedefinieerde rollen, het systeem of de door de gebruiker gedefinieerde rollen worden automatisch de toegang geweigerd.

In het volgende voorbeeld is de gebruikersrol administrator de enige gedefinieerde rol voor de book entiteit. Een gebruiker moet lid zijn van de administrator rol en die rol opnemen in de X-MS-API-ROLE HTTP-header om op de book entiteit te kunnen werken:

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

Notitie

Als u toegangsbeheer wilt afdwingen voor GraphQL-query's wanneer u Data API Builder gebruikt met Azure Cosmos DB, moet u de instructie gebruiken in het @authorize opgegeven GraphQL-schemabestand. Voor GraphQL-mutaties en -filters in GraphQL-query's wordt toegangsbeheer echter nog steeds afgedwongen door de configuratie van machtigingen, zoals eerder beschreven.

Acties

Acties beschrijven de toegankelijkheid van een entiteit binnen het bereik van een rol. Acties kunnen afzonderlijk worden opgegeven of met de snelkoppeling met jokertekens: * (sterretje). De snelkoppeling met jokertekens vertegenwoordigt alle acties die worden ondersteund voor het entiteitstype:

• Tabellen en weergaven: create, read, update, delete
• Opgeslagen procedures: execute

Zie de documentatie voor het configuratiebestand voor meer informatie over acties.

Veldtoegang

U kunt configureren welke velden toegankelijk moeten zijn voor een actie. U kunt bijvoorbeeld instellen welke velden u wilt opnemen en uitsluiten van de read actie.

In het volgende voorbeeld wordt voorkomen dat gebruikers met de free-access rol leesbewerkingen uitvoeren op Column3. Verwijzingen naar Column3 in GET-aanvragen (REST-eindpunt) of query's (GraphQL-eindpunt) resulteren in een geweigerde aanvraag:

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

Notitie

Als u toegangsbeheer wilt afdwingen voor GraphQL-query's wanneer u Data API Builder gebruikt met Azure Cosmos DB, moet u de instructie gebruiken in het @authorize opgegeven GraphQL-schemabestand. Voor GraphQL-mutaties en -filters in GraphQL-query's wordt toegangsbeheer echter nog steeds afgedwongen door de configuratie van machtigingen, zoals hier wordt beschreven.

Beveiliging op itemniveau

Met expressies voor databasebeleid kunnen de resultaten nog verder worden beperkt. Met databasebeleid worden expressies omgezet in querypredicaten die worden uitgevoerd op de database. Expressies voor databasebeleid worden ondersteund voor de volgende acties:

• maken
• lezen
• update
• delete

Waarschuwing

De uitvoeringsactie , die wordt gebruikt met opgeslagen procedures, biedt geen ondersteuning voor databasebeleid.

Notitie

Databasebeleid wordt momenteel niet ondersteund door CosmosDB for NoSQL.

Zie de documentatie voor het configuratiebestand voor meer informatie over databasebeleid.

Voorbeeld

Een databasebeleid dat de read actie voor de consumer rol beperkt tot het retourneren van records waarvan de titel 'Voorbeeldtitel' is.

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

Gerelateerde inhoud

• Azure-verificatie
• Lokale verificatie