Dela via

Auktorisering och roller i Data API Builder

  • Artikel

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 konfigurationsfilen 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.

Roller

Roller anger behörighetskontexten där en begäran ska köras. För varje entitet som definieras i körningskonfigurationen kan du definiera en uppsättning roller och associerade behörigheter som avgör hur entiteten kan nås i både REST- och GraphQL-slutpunkterna.

Data API Builder utvärderar begäranden i kontexten för en enda roll:

  • anonymous när ingen åtkomsttoken visas.
  • authenticated när en giltig åtkomsttoken visas.
  • <CUSTOM_USER_ROLE> när en giltig åtkomsttoken visas ochX-MS-API-ROLE HTTP-huvudet ingår och anger en användarroll som också ingår i åtkomsttokens roles anspråk.

Roller är inte additiva, vilket innebär att en användare som är medlem i båda Role1 och Role2 inte ärver de behörigheter som är associerade med båda rollerna.

Systemroller

Systemroller är inbyggda roller som identifieras av Data API Builder. En systemroll tilldelas automatiskt till en beställare oavsett vilken rollmedlemskap som anges i deras åtkomsttoken. Det finns två systemroller: anonymous och authenticated.

Anonym systemroll

Systemrollen anonymous tilldelas till 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 att systemrollen anonymous uttryckligen konfigureras 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 till begäranden som körs av autentiserade användare.

Exempel

Följande körningskonfiguration för Data API Builder visar att systemrollen authenticated uttryckligen konfigureras 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 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. Klientappen som tillhandahålls åtkomsttoken måste innehålla rollanspråk som visar en användares rollmedlemskap.
  2. Klientappen måste innehålla 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 av Data API Builder-körningen på följande sätt:

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

I Static Web Apps är en användare medlem i den anonyma rollen som standard. Om användaren autentiseras är användaren medlem i både rollerna anonymous och authenticated .

När en klientapp skickar en autentiserad begäran till data-API-byggare som distribuerats med Static Web Apps Databasanslutningar (förhandsversion) tillhandahåller klientappen en åtkomsttoken som Static Web Apps omvandlas till JSON:

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

Eftersom Data API Builder utvärderar begäranden i kontexten för en enda roll utvärderas 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 rollens author kontext. Ett exempel på en begäran, inklusive en åtkomsttoken och X-MS-API-ROLE ETT HTTP-huvud:

curl -k -r 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 den ingår anges rolluppsättningen X-MS-API-ROLE i 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.

Behörigheter måste konfigureras uttryckligen

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

Om du vill förenkla behörighetsdefinitionen anonymous för en entitet förutsätter du att om det inte finns några specifika behörigheter för authenticated rollen används de behörigheter som definierats för rollen. Den book konfiguration som visades tidigare gör att alla anonyma eller autentiserade användare kan utföra läsåtgärder på book entiteten.

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 book entiteten. En användare måste vara medlem i rollen och inkludera den administrator rollen i X-MS-API-ROLE HTTP-huvudet för att fungera på book entiteten:

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

Anteckning

För att 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 framtvingas åtkomstkontrollen fortfarande av behörighetskonfigurationen enligt beskrivningen tidigare.

Å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). Genvägen med jokertecken 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 undantas från åtgärden read .

I följande exempel förhindras 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" ]
              }
            }
          ]
        }
      ]
    }

Anteckning

För att 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 framtvingas åtkomstkontrollen fortfarande av behörighetskonfigurationen enligt beskrivningen här.

Säkerhet på objektnivå

Databasprinciputtryck gör att resultaten kan begränsas ytterligare. Databasprinciper översätter uttryck till frågepredikat som körs mot databasen. Databasprinciputtryck stöds för följande åtgärder:

  • skapa
  • läsa
  • update
  • delete

Varning

Körningsåtgärden, som används med lagrade procedurer, stöder inte databasprinciper.

Anteckning

Databasprinciper stöds för närvarande inte av CosmosDB för NoSQL.

Mer information om databasprinciper finns i dokumentationen för konfigurationsfilen .

Exempel

En databasprincip som read begränsar åtgärden för consumer rollen till att endast returnera poster där rubriken är "Exempelrubrik".

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

Relaterat innehåll