Auktorisering och roller i Data API Builder

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.

Fastställa användarens roll

Nej role har standardbehörigheter. När en regel bestäms av data-API-byggare måste entitetens permissions definiera actions för den rollen för att begäran ska lyckas.

Om du vill ha en annan roll än anonymous eller authenticated krävs x-ms-api-role-headern.

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. Klientappen som har angett åtkomsttoken måste innehålla rollanspråk som visar en användares rollmedlemskap.
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" ]
        }
    ]
}

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 hjälp av Static Web Apps-databasanslutningar (förhandsversion) tillhandahåller klientappen en åtkomsttoken som Static Web Apps omvandlar 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 kontexten för author rollen. Ett exempel på en begäran, inklusive en åtkomsttoken och X-MS-API-ROLE HTTP-huvud:

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

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.

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 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 är till exempel book uttryckligen inställda för att tillåta oautentiserad läsåtkomst:

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

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

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

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

Säkerhet på objektnivå

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

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

Exempel

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

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

Relaterat innehåll

• Azure-autentisering
• Lokal autentisering