Autorisatie en rollen in Data API Builder

Data API Builder maakt gebruik van een op rollen gebaseerde autorisatiewerkstroom. Een binnenkomende aanvraag, geverifieerd of niet, 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 de configuratie om te begrijpen welke acties, velden en beleidsregels beschikbaar zijn voor die rol op de aangevraagde entiteit.

De rol van de gebruiker bepalen

Nee role heeft standaardmachtigingen. Zodra data-API builder een regel bepaalt, moet de entiteit permissions deze rol definiëren actions om de aanvraag te laten slagen.

Opgegeven token	x-ms-api-role Geleverd	x-ms-api-role in Token	Resulterende rol
Nee.	Nee.	Nee.	anonymous
Ja	Nee.	Nee.	authenticated
Ja	Ja	Nee.	Uitzondering
Ja	Ja	Ja	x-ms-api-role waarde

Als u een andere rol dan anonymous of authenticatedwilt hebben, is de x-ms-api-role header vereist.

Opmerking

Een aanvraag kan slechts één rol hebben. Zelfs als het token meerdere rollen aangeeft, selecteert de x-ms-api-role waarde welke rol aan de aanvraag is toegewezen.

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 dat is 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. Gedefinieerde runtimeconfiguratie-entiteiten moeten machtigingen voor de anonymous rol bevatten als niet-geverifieerde toegang is vereist.

Voorbeeld

De volgende runtimeconfiguratie van Data API Builder laat zien hoe u de systeemrol anonymous expliciet configureert 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 verzendt die toegang heeft tot de entiteit Book, mag de app de HTTP-header niet bevatten Authorization .

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 hoe u de systeemrol authenticated expliciet configureert om leestoegang tot de entiteit Book op te nemen:

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

Gebruikersrollen

Gebruikersrollen zijn niet systeemrollen die aan gebruikers zijn toegewezen binnen de identiteitsprovider die u in de runtimeconfiguratie instelt. Voor Data API builder om een aanvraag te evalueren in de context van een gebruikersrol, moet aan twee vereisten worden voldaan:

1. Het toegangstoken dat door de client-app wordt geleverd, moet rolclaims bevatten die het rollidmaatschap van een gebruiker opsommen.
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 worden aanvragen voor de Book entiteit gedemonstreerd, zoals geconfigureerd in de runtime-configuratie van de Data API Builder:

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

In App Service is een gebruiker standaard lid van de anonieme rol. Als de gebruiker is geverifieerd, is de gebruiker lid van zowel de anonymous-rol als de authenticated-rol.

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 voorbeeld van een aanvraag 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 roltoewijzing?
• Welke acties (maken, lezen, bijwerken, verwijderen, uitvoeren) die een gebruiker kan uitvoeren?
• Welke velden zijn toegankelijk voor een bepaalde actie?
• Welke extra beperkingen gelden voor de resultaten die door een aanvraag worden geretourneerd?

De syntaxis voor het definiëren van machtigingen wordt beschreven in het artikel over 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 wordt de systeemrol anonymous of authenticated
• Wanneer deze is opgenomen, wordt de rol die is ingesteld in de X-MS-API-ROLE HTTP-header.

Standaard beveiligd

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, gaat u ervan uit dat als er geen specifieke machtigingen voor de authenticated rol zijn, de machtigingen die voor de anonymous rol zijn gedefinieerd, worden gebruikt. Met de book configuratie die eerder wordt weergegeven, kunnen anonieme of geverifieerde gebruikers leesbewerkingen uitvoeren op de book entiteit.

Wanneer leesbewerkingen alleen moeten worden beperkt tot geverifieerde gebruikers, moet de volgende machtigingsconfiguratie worden ingesteld, wat resulteert in het afwijzen van niet-geverifieerde aanvragen:

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

Een entiteit vereist niet en is niet vooraf geconfigureerd met machtigingen voor de anonymous en authenticated rollen. Een of meer gebruikersrollen kunnen worden gedefinieerd in de machtigingsconfiguratie van een entiteit en alle andere niet-gedefinieerde rollen, het systeem of de gebruiker die zijn gedefinieerd, 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": [ "*" ]
  }]
}

Opmerking

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

Acties

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

• Tabellen en weergaven: create, read, updatedelete
• Opgeslagen procedures: execute

Zie de documentatie van 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 voorkomt u dat gebruikers in 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" ]
              }
            }
          ]
        }
      ]
    }

Opmerking

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

Beveiliging op itemniveau

Met databasebeleidsexpressies kunnen resultaten nog verder worden beperkt. Databasebeleid vertaalt expressies naar querypredicaten die op de database worden uitgevoerd. Databasebeleidexpressies worden ondersteund voor de volgende acties:

• creëren
• lezen
• bijwerken
• verwijderen

Waarschuwing

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

Opmerking

Azure Cosmos DB for NoSQL biedt momenteel geen ondersteuning voor databasebeleid.

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

Voorbeeld

Een databasebeleid dat de read actie voor de consumer rol beperkt tot alleen records retourneren waarin de titel 'Voorbeeldtitel' is.

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

Verwante inhoud

• Azure-verificatie
• lokale authenticatie