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

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

De volgende role-evaluatiematrix is van toepassing op JWT Bearer-providers (bijvoorbeeld EntraID/AzureAD en Custom) waarin de client Authorization: Bearer <token> verzendt.

Als u een andere rol dan Anonymous of Authenticatedwilt gebruiken, is de X-MS-API-ROLE header vereist.

Opmerkingen van provider:

• EasyAuth-providers (bijvoorbeeld AppService): verificatie kan worden ingesteld door door platformingevoerde headers (zoals X-MS-CLIENT-PRINCIPAL) in plaats van een bearer-token.
• Simulator: aanvragen worden behandeld als geverifieerd voor ontwikkeling/testen, zonder een echt token te valideren.

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. De geverifieerde principal moet rolclaims bevatten die het rollidmaatschap van een gebruiker vermelden (bijvoorbeeld de JWT-claim roles ).
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" ]
        }
    ]
}

Data API Builder evalueert aanvragen in de context van één effectieve rol. Als een aanvraag wordt geverifieerd en er geen X-MS-API-ROLE header wordt opgegeven, evalueert Data API Builder de aanvraag standaard in de context van de Authenticated systeemrol.

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 -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

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.

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 wilt dat zowel niet-geverifieerde als geverifieerde gebruikers toegang hebben, moet u expliciet machtigingen verlenen aan zowel systeemrollen (Anonymous als Authenticated).

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": [ "*" ]
  }]
}

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" ]
              }
            }
          ]
        }
      ]
    }

Beveiliging op itemniveau

Met databasebeleid kunt u resultaten filteren op rijniveau. Beleidsregels worden omgezet in querypredicaten die door de database worden geëvalueerd, zodat gebruikers alleen toegang hebben tot geautoriseerde records.

Zie Databasebeleid configureren voor gedetailleerde configuratiestappen, syntaxisreferenties en voorbeelden.

Snel voorbeeld

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

Verwante inhoud

• Databasebeleid configureren voor filteren op rijniveau
• Microsoft Entra ID-verificatie configureren
• Simulatorverificatie configureren voor lokaal testen