Dela via

Översikt över auktorisering

Auktorisering avgör vad autentiserade användare tillåts göra i ditt data-API builder-program. Autentisering verifierar vem en användare är, men auktorisering styr vad de kan komma åt och ändra.

Data API Builder använder ett rollbaserat auktoriseringsarbetsflöde. Alla inkommande begäranden, autentiserade eller inte, tilldelas till en roll. Roller kan vara systemroller eller användarroller. Den tilldelade rollen kontrolleras sedan mot de definierade behörigheter som anges i konfigurationen för att förstå vilka åtgärder, fält och principer som är tillgängliga för den rollen på den begärda entiteten.

Viktiga auktoriseringsbegrepp

Entitetsbehörigheter

Kontrollera CRUD-åtgärder (Skapa, Läsa, Uppdatera, Ta bort) på entitetsnivå. Varje roll kan beviljas eller nekas specifika åtgärder för specifika entiteter.

Rollbaserad åtkomstkontroll

Tilldela användare roller och bevilja behörigheter baserat på rollmedlemskap. Roller förenklar hanteringen av stora användargrupper med liknande åtkomstmönster.

Säkerhet på radnivå (RLS)

Filtrera data baserat på användaridentitet eller sessionskontext. Användarna ser bara de rader som de har behörighet att komma åt, som tillämpas på databasnivå.

API-regler

Tillämpa OData-predikat och filter på API-svar. Principer begränsar automatiskt frågeresultat baserat på användaranspråk och identitet.

Anspråksbaserad auktorisering

För att fastställa åtkomst använder du anspråk från autentiseringstoken (till exempel grupper, roller, anpassade attribut). Anspråk ger flexibla, detaljerade behörighetsbeslut.

Så här fungerar det

  1. Användaren autentiserar med någon av de autentiseringsmetoder som stöds
  2. Systemet extraherar anspråk från autentiseringstoken (roller, grupper, organisation osv.)
  3. Auktoriseringsregler utvärderas mot användarens anspråk och den begärda resursen
  4. Åtkomst beviljas eller nekas baserat på entitetsbehörigheter, principer och säkerhetsregler på radnivå

Fastställa användarens roll

Ingen roll har standardbehörigheter. När data-API-byggare har fastställt en roll måste permissions entiteten definiera actions för den rollen för att begäran ska lyckas.

Följande rollutvärderingsmatris gäller för JSON Web Token (JWT)-ägarprovidrar (till exempel EntraID/AzureAD och Custom) där klienten skickar Authorization: Bearer <token>.

Bärartoken tillhandahålls X-MS-API-ROLE tillhandahålls Begärd roll finns i roles-kravet Effektiv roll och resultat
No No Inte tillämpligt Anonymous
Ja (giltigt) No Inte tillämpligt Authenticated
Ja (giltigt) Ja No Avvisad (403 Förbjudet)
Ja (giltigt) Ja Ja X-MS-API-ROLE värde
Ja (ogiltigt) Vilket som helst Inte tillämpligt Avvisad (401 Obehörig)

För att använda en annan roll än Anonymous eller Authenticated, är X-MS-API-ROLE-huvudet nödvändigt.

Anmärkning

En begäran kan associeras med många roller i den autentiserade huvudparten. Data API-byggare utvärderar dock behörigheter och principer i kontexten för exakt en effektiv roll. När X-MS-API-ROLE tillhandahålls väljer rubriken vilken roll som används.

Provideranteckningar:

  • EasyAuth-providers (till exempel AppService): plattformsinmatade huvuden (till exempel X-MS-CLIENT-PRINCIPAL) upprättar autentisering i stället för en ägartoken.
  • Simulator: begäranden behandlas som authenticated för utveckling/testning, utan att verifiera en verklig token.

Systemroller

Systemroller är inbyggda roller som identifieras av Data API Builder. En systemroll tilldelas automatiskt till en begärande oavsett vilket rollmedlemskap som anges i deras åtkomsttoken. Det finns två systemroller: Anonymous och Authenticated.

Anonym systemroll

Systemrollen Anonymous tilldelas begäranden som körs av oautentiserade användare. Körningskonfigurationsdefinierade entiteter måste innehålla behörigheter för Anonymous rollen om oautentiserad åtkomst önskas.

Exempel

Följande körningskonfiguration för Data API Builder visar hur du uttryckligen konfigurerar systemrollen Anonymous så att den inkluderar läsåtkomst till bokentiteten:

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

När ett klientprogram skickar en begäran till entiteten Bok för en oautentiserad användares räkning ska appen inte innehålla Authorization HTTP-huvudet.

Autentiserad systemroll

Systemrollen Authenticated tilldelas begäranden som körs av autentiserade användare.

Exempel

Följande körningskonfiguration för Data API Builder visar hur du uttryckligen konfigurerar systemrollen Authenticated så att den inkluderar läsåtkomst till bokentiteten:

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

Användarroller

Användarroller är icke-systemroller som tilldelas till användare inom den identitetsprovider som du angav i körningskonfigurationen. För att Data API-byggare ska kunna utvärdera en begäran i kontexten för en användarroll måste två krav uppfyllas:

  1. Det autentiserade huvudkontot måste innehålla rollanspråk som visar en användares rollmedlemskap (till exempel JWT-anspråket roles ).
  2. Klientappen måste inkludera HTTP-huvudet X-MS-API-ROLE med begäranden och ange huvudets värde som önskad användarroll.

Exempel på rollutvärdering

I följande exempel visas begäranden som görs till entiteten Book som har konfigurerats i konfigurationen för Data API Builder-körning på följande sätt:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Data API Builder utvärderar begäranden i kontexten för en enda effektiv roll. Om en begäran autentiseras och inget X-MS-API-ROLE huvud anges utvärderar Data API Builder begäran i kontexten för systemrollen Authenticated som standard.

Om klientprogrammets begäran även innehåller HTTP-huvudet X-MS-API-ROLE med värdet authorutvärderas begäran i kontexten för author rollen. Ett exempel på en begäran, inklusive en åtkomsttoken och X-MS-API-ROLE HTTP-huvud:

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

Viktigt!

En klientapps begäran avvisas när den angivna åtkomsttokens roles anspråk inte innehåller rollen som anges i X-MS-API-ROLE rubriken.

behörigheter

Behörigheter beskriver:

  • Vem kan göra begäranden på en entitet baserat på rollmedlemskap?
  • Vilka åtgärder (skapa, läsa, uppdatera, ta bort, köra) som en användare kan utföra?
  • Vilka fält är tillgängliga för en viss åtgärd?
  • Vilka extra begränsningar finns för de resultat som returneras av en begäran?

Syntaxen för att definiera behörigheter beskrivs i artikeln om körningskonfiguration.

Viktigt!

Det kan finnas flera roller som definierats i en enskild entitets behörighetskonfiguration. En begäran utvärderas dock endast i kontexten för en enda roll:

  • Som standard är antingen systemrollen Anonymous eller Authenticated
  • När rollen ingår anges den i X-MS-API-ROLE HTTP-huvudet.

Säker som standard

Som standard har en entitet inga konfigurerade behörigheter, vilket innebär att ingen kan komma åt entiteten. Dessutom ignorerar Data API Builder databasobjekt när de inte refereras i körningskonfigurationen.

Åtgärder

Åtgärder beskriver tillgängligheten för en entitet inom omfånget för en roll. Åtgärder kan anges individuellt eller med jokerteckengenvägen: * (asterisk). Jokertecknet representerar alla åtgärder som stöds för entitetstypen.

  • Tabeller och vyer: create, read, update, delete
  • Lagrade procedurer: execute

Mer information om åtgärder finns i dokumentationen för konfigurationsfilen .

Fältåtkomst

Du kan konfigurera vilka fält som ska vara tillgängliga för en åtgärd. Du kan till exempel ange vilka fält som ska inkluderas och exkluderas från åtgärden read .

I följande exempel hindras användare i free-access rollen från att utföra läsåtgärder på Column3. Referenser till Column3 i GET-begäranden (REST-slutpunkt) eller frågor (GraphQL-slutpunkt) resulterar i en avvisad begäran:

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

Anmärkning

Om du vill framtvinga åtkomstkontroll för GraphQL-frågor när du använder Data API Builder med Azure Cosmos DB måste du använda @authorize direktivet i den angivna GraphQL-schemafilen. Men för GraphQL-mutationer och filter i GraphQL-frågor framtvingar behörighetskonfigurationen fortfarande åtkomstkontroll enligt beskrivningen här.

Databasprinciper (säkerhet på objektnivå)

Med databasprinciper kan du filtrera resultat på radnivå. Principer översätts till frågepredikat som databasen utvärderar, vilket säkerställer att användarna endast får åtkomst till auktoriserade poster.

Åtgärder som stöds Stöds ej
read, update, delete create, execute

Anmärkning

Azure Cosmos DB för NoSQL stöder för närvarande inte databasprinciper.

Detaljerade konfigurationssteg, syntaxreferenser och exempel finns i Konfigurera databasprinciper.

Snabbexempel

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

Arv av roll

DAB 2.0 introducerar rollarv, vilket innebär att du inte behöver upprepa samma behörighetsblock för varje roll. Arvskedjan är:

named-role → authenticated → anonymous
  • Om authenticated inte uttryckligen har konfigurerats för en entitet ärver den från anonymous.
  • Om en namngiven roll inte har konfigurerats ärver den från authenticated, eller från anonymous om authenticated den också saknas.

Du kan definiera behörigheter en gång på anonymous och varje bredare roll får automatiskt samma åtkomst, utan att duplicering krävs.

Anmärkning

Funktionerna i Data API Builder 2.0 som beskrivs i det här avsnittet är för närvarande i förhandsversion och kan komma att ändras före allmän tillgänglighet. Mer information finns i Nyheter i version 2.0.

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

Med den här konfigurationen kan anonymous, authenticated och alla icke-konfigurerade namngivna roller läsa Book.

Använd dab configure --show-effective-permissions för att visa de lösta behörigheterna för varje entitet efter att arv har tillämpats.

Behörigheter måste anges explicit​

Om du vill tillåta oautentiserad åtkomst till en entitet Anonymous måste rollen uttryckligen definieras i entitetens behörigheter. Entitetens behörigheter anges till exempel book uttryckligen för att tillåta oautentiserad läsåtkomst:

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

När läsåtgärder endast ska begränsas till autentiserade användare bör följande behörighetskonfiguration anges, vilket resulterar i avvisande av oautentiserade begäranden:

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

En entitet kräver inte och är inte förkonfigurerad med behörigheter för rollerna Anonymous och Authenticated . En eller flera användarroller kan definieras i en entitets behörighetskonfiguration och alla andra odefinierade roller, system eller användardefinierade nekas automatiskt åtkomst.

I följande exempel är användarrollen administrator den enda definierade rollen för entiteten book . En användare måste vara medlem i administrator-rollen och inkludera den rollen i X-MS-API-ROLE HTTP-huvudet för att hantera book-entiteten.

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

Anmärkning

Om du vill framtvinga åtkomstkontroll för GraphQL-frågor när du använder Data API Builder med Azure Cosmos DB måste du använda @authorize direktivet i den angivna GraphQL-schemafilen. Men för GraphQL-mutationer och filter i GraphQL-frågor framtvingar behörighetskonfigurationen fortfarande åtkomstkontroll enligt beskrivningen tidigare.

Lagerbaserad säkerhetsmodell

Data API Builder använder flera auktoriseringslager:

  • Entitetsnivå: Vilka entiteter och åtgärder som är tillgängliga
  • Principnivå: Vilka data returneras (filtrering baserat på anspråk)
  • Radnivå: Databasen tillämpar radfiltrering via RLS
  • API-nivå: HTTP-huvuden och validering av begäranden

Nästa steg

  • Last updated on