Engedélyezés áttekintése

Az engedélyezés határozza meg, hogy a hitelesített felhasználók mit tehetnek a Data API Builder-alkalmazásban. Bár a hitelesítés ellenőrzi, hogy ki a felhasználó, az engedélyezés szabályozza , hogy mit érhetnek el és módosíthatnak.

A Data API Builder szerepköralapú engedélyezési munkafolyamatot használ. A rendszer minden bejövő kérelmet, akár hitelesítve van, akár nem, hozzárendel egy szerepkörhöz. A szerepkörök lehetnek rendszerszerepkörök vagy felhasználói szerepkörök. A hozzárendelt szerepkör ezután a konfigurációban megadott engedélyekkel van ellenőrizve, hogy megismerje, milyen műveletek, mezők és szabályzatok érhetők el az adott szerepkörhöz a kért entitáson.

A fő engedélyezési fogalmak

Entitásengedélyek

A CRUD-műveletek (létrehozás, olvasás, frissítés, törlés) szabályozása az entitás szintjén. Az egyes szerepkörök adott entitásokkal kapcsolatos konkrét műveleteket adhatnak meg vagy tagadhatnak meg.

Szerepköralapú hozzáférés-szabályozás

Felhasználók hozzárendelése szerepkörökhöz, és engedélyek megadása a szerepkör-tagság alapján. A szerepkörök leegyszerűsítik a hasonló hozzáférési mintákkal rendelkező nagy felhasználói csoportok kezelését.

Sorszintű biztonság (RLS)

Adatok szűrése felhasználói identitás vagy munkamenet-környezet alapján. A felhasználók csak azokat a sorokat látják, amelyekhez hozzáférésük van, a funkció az adatbázis szintjén érvényesítve.

API-szabályzatok

OData-predikátumok és szűrők alkalmazása API-válaszokra. A szabályzatok automatikusan korlátozzák a lekérdezési eredményeket a felhasználói jogcímek és identitások alapján.

Jogcímalapú engedélyezés

A hozzáférés meghatározásához használjon hitelesítési jogkivonatokból származó jogcímeket (például csoportokat, szerepköröket, egyéni attribútumokat). A jogcímek rugalmas, részletes jogosultsági döntéseket biztosítanak.

Hogyan működik?

  1. A felhasználó a támogatott hitelesítési módszerek egyikével hitelesít
  2. A rendszer jogcímeket nyer ki a hitelesítési jogkivonatból (szerepkörök, csoportok, szervezet stb.)
  3. Az engedélyezési szabályok kiértékelése a felhasználó jogcímei és a kért erőforrás alapján történik
  4. A hozzáférés entitásengedélyek , szabályzatok és sorszintű biztonsági szabályok alapján adható meg vagy tagadható meg

A felhasználó szerepkörének meghatározása

Egyetlen szerepkör sem rendelkezik alapértelmezett engedélyekkel. Miután a Data API Builder meghatároz egy szerepkört, az entitás permissions-t kell, hogy definiáljon actions a szerepkör számára, hogy a kérés sikeres legyen.

A következő szerepkör-kiértékelési mátrix a JSON Web Token (JWT) tulajdonosi szolgáltatóira (például EntraID, /, AzureAD és Custom) vonatkozik, ahol az ügyfél küldi Authorization: Bearer <token>.

Hordozó token megadva X-MS-API-ROLE megadva A jogkivonat-jogcímben roles található kért szerepkör Hatékony szerepkör / eredmény
No No N/A Anonymous
Igen (érvényes) No N/A Authenticated
Igen (érvényes) Igen No Elutasítva (403 Tiltott)
Igen (érvényes) Igen Igen X-MS-API-ROLE érték
Igen (érvénytelen) Bármely N/A Elutasítva (401 Jogosulatlan)

A Anonymous vagy Authenticated szerepkörön kívüli más szerepkör használatához szükség van a X-MS-API-ROLE fejlécre.

Megjegyzés:

Egy kérés több szerepkörhöz is társítható a hitelesített entitásban. A Data API Builder azonban pontosan egy hatékony szerepkör kontextusában értékeli ki az engedélyeket és a szabályzatokat. Ha meg van adva, a X-MS-API-ROLE fejléc kiválasztja a használt szerepkört.

Szolgáltatói megjegyzések:

  • Az EasyAuth-szolgáltatók (például AppService) esetén a platformba injektált fejlécek (például X-MS-CLIENT-PRINCIPAL) hitelesítést hoznak létre, nem pedig hozzáférési jogkivonatot.
  • Simulator: a kérelmeket a rendszer fejlesztési/tesztelési célokra kezeli authenticated , valódi jogkivonat érvényesítése nélkül.

Rendszerszerepkörök

A rendszerszerepkörök a Data API Builder által felismert beépített szerepkörök. A rendszerszerepkör automatikusan hozzárendelve van a kérelmezőhöz, függetlenül attól, hogy a kérelmező milyen szerepkör-tagságot jelöl a hozzáférési jogkivonataikban. Két rendszerszerepkör van: Anonymous és Authenticated.

Névtelen rendszerszerepkör

A Anonymous rendszerszerepkör a nem hitelesített felhasználók által végrehajtott kérelmekhez van hozzárendelve. A futtatókörnyezet konfigurációja által definiált entitásoknak engedélyekkel kell rendelkezniük a Anonymous szerepkörhöz, ha nem hitelesített hozzáférésre van szükség.

Example

Az alábbi Data API Builder-futtatókörnyezet-konfiguráció azt mutatja be, hogy a rendszerszerepkör Anonymous explicit módon konfigurálva van a Book entitás olvasási hozzáférésével:

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

Amikor egy ügyfélalkalmazás egy nem hitelesített felhasználó nevében küld egy, a Book entitáshoz hozzáférő kérést, az alkalmazásnak nem szabad tartalmaznia a Authorization HTTP-fejlécet.

Hitelesített rendszerszerepkör

A Authenticated rendszerszerepkör a hitelesített felhasználók által végrehajtott kérelmekhez van hozzárendelve.

Example

Az alábbi Data API Builder-futtatókörnyezet-konfiguráció azt mutatja be, hogy a rendszerszerepkör Authenticated explicit módon konfigurálva van a Book entitás olvasási hozzáférésével:

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

Felhasználói szerepkörök

A felhasználói szerepkörök nem rendszerszintű szerepkörök, amelyek a futtatókörnyezet konfigurációjában beállított identitásszolgáltató felhasználóihoz vannak rendelve. Ahhoz, hogy a Data API Builder kiértékeljen egy kérést egy felhasználói szerepkör kontextusában, két követelménynek kell teljesülnie:

  1. A hitelesített tagnak olyan szerepkörjogcímeket kell tartalmaznia, amelyek felsorolják a felhasználó szerepkör-tagságát (például a JWT-jogcímet roles ).
  2. Az ügyfélalkalmazásnak tartalmaznia kell a HTTP-fejlécet X-MS-API-ROLE a kérésekkel, és meg kell adnia a fejléc értékét a kívánt felhasználói szerepkörként.

Példa a szerepkör-értékelésre

Az alábbi példa a Book Data API Builder futtatókörnyezet konfigurációjában konfigurált entitáshoz érkező kéréseket mutatja be az alábbiak szerint:

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

A Data API Builder egyetlen hatékony szerepkör kontextusában értékeli ki a kéréseket. Ha egy kérés hitelesítve van, és nincs X-MS-API-ROLE fejléc megadva, a Data API Builder alapértelmezés szerint a kérést a Authenticated rendszerszerepkör kontextusában értékeli ki.

Ha az ügyfélalkalmazás kérése a HTTP-fejlécet X-MS-API-ROLE is tartalmazza az értékkel author, a rendszer kiértékeli a kérést a author szerepkör kontextusában. Példakérés hozzáférési jogkivonattal és X-MS-API-ROLE HTTP-fejléccel:

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

Fontos

Az ügyfélalkalmazás kérését a rendszer elutasítja, ha a megadott hozzáférési jogkivonat jogcíme roles nem tartalmazza a fejlécben felsorolt szerepkört X-MS-API-ROLE .

Jogosultságok

Az engedélyek leírása:

  • Ki kérhet kéréseket egy entitásnál szerepkör-tagság alapján?
  • Milyen műveleteket (létrehozás, olvasás, frissítés, törlés, végrehajtás) hajthat végre egy felhasználó?
  • Mely mezők érhetők el egy adott művelethez?
  • Milyen további korlátozások vonatkoznak a kérés által visszaadott eredményekre?

Az engedélyek meghatározásának szintaxisát a futtatókörnyezet konfigurációs cikkében ismertetjük.

Fontos

Egy entitás engedélykonfigurációjában több szerepkör is definiálható. A kérések kiértékelése azonban csak egyetlen szerepkör kontextusában történik:

  • Alapértelmezés szerint a rendszerszerepkör Anonymous vagy Authenticated
  • Amikor belefoglalásra kerül, a szerepkör a X-MS-API-ROLE HTTP-fejlécben állítható be.

Alapértelmezés szerint biztonságos

Az entitások alapértelmezés szerint nincsenek konfigurálva engedélyekkel, ami azt jelenti, hogy senki sem férhet hozzá az entitáshoz. A Data API Builder emellett figyelmen kívül hagyja az adatbázis-objektumokat, ha nem hivatkoznak rájuk a futtatókörnyezet konfigurációjában.

Műveletek

A műveletek egy szerepkör hatókörén belüli entitás akadálymentességét írják le. A műveletek egyedileg vagy a helyettesítő karakterrel is megadhatóak: * (csillag). A helyettesítő karakter parancsikonja az entitástípushoz támogatott összes műveletet jelöli:

  • Táblák és nézetek: create, read, update, delete
  • Tárolt eljárások: execute

A műveletekkel kapcsolatos további információkért tekintse meg a konfigurációs fájl dokumentációját.

Mezőhozzáférés

Konfigurálhatja, hogy mely mezők legyenek elérhetők egy művelethez. Beállíthatja például, hogy mely mezőket vegye fel és zárja ki a read műveletből.

Az alábbi példa megakadályozza, hogy a free-access szerepkörben lévő felhasználók olvasási műveleteket hajtsanak végre.Column3 Column3 A GET-kérelmekre (REST-végpontra) vagy lekérdezésekre (GraphQL-végpontra) mutató hivatkozások elutasított kérést eredményeznek:

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

Megjegyzés:

A GraphQL-lekérdezések hozzáférés-vezérlésének kikényszerítéséhez a Data API Builder azure Cosmos DB-vel való használatakor a megadott @authorize kell használnia az irányelvet. A GraphQL-lekérdezések GraphQL-mutációi és szűrői esetében azonban az engedélykonfiguráció továbbra is kikényszeríti a hozzáférés-vezérlést az itt leírtak szerint.

Adatbázis-szabályzatok (elemszintű biztonság)

Az adatbázis-szabályzatok lehetővé teszik az eredmények szűrését a sor szintjén. A szabályzatok az adatbázis által kiértékelt lekérdezési predikátumokra lefordítva biztosítják, hogy a felhasználók csak az engedélyezett rekordokhoz férhessenek hozzá.

Támogatott műveletek Nem támogatott
\, \, \ create, execute

Megjegyzés:

Az Azure Cosmos DB for NoSQL jelenleg nem támogatja az adatbázis-szabályzatokat.

Részletes konfigurációs lépésekről, szintaxishivatkozásokról és példákról az adatbázis-szabályzatok konfigurálása című témakörben olvashat.

Gyors példa

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

Szerepköröröklés

A DAB 2.0 szerepköröröklést vezet be, így nem kell minden szerepkörben ugyanazt az engedélyblokkot megismételnie. Az öröklési lánc a következő:

named-role → authenticated → anonymous
  • Ha authenticated nincs explicit módon konfigurálva egy entitáshoz, attól örököl anonymous.
  • Ha egy elnevezett szerepkör nincs konfigurálva, akkor authenticated-t örököl, vagy ha anonymous is hiányzik, akkor authenticated-t.

Az engedélyeket egyszer definiálhatja, anonymous és minden szélesebb szerepkör automatikusan megkapja ugyanazt a hozzáférést, nincs szükség duplikálásra.

Megjegyzés:

Az ebben a szakaszban ismertetett Data API Builder 2.0 funkció jelenleg előzetes verzióban érhető el, és az általános rendelkezésre állás előtt változhat. További információ: A 2.0-s verzió újdonságai.

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

Ezzel a konfigurációval a anonymous, authenticated és bármely nem konfigurált nevű szerepkör elolvashatja a Book.

Az dab configure --show-effective-permissions megoldott engedélyek megjelenítése minden entitás számára, miután az öröklés alkalmazásra került.

Az engedélyeket explicit módon kell konfigurálni

Az entitáshoz való hitelesítés nélküli hozzáférés engedélyezéséhez a Anonymous szerepkört explicit módon kell definiálni az entitás engedélyeiben. Az entitás engedélyei például kifejezetten úgy vannak beállítva, book hogy engedélyezhessék a hitelesítés nélküli olvasási hozzáférést:

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

Ha az olvasási műveleteket csak hitelesített felhasználókra kell korlátozni, a következő engedélykonfigurációt kell beállítani, ami a nem hitelesített kérések elutasítását eredményezi:

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

Egy entitás nem igényel és nincs előre konfigurálva a Anonymous és Authenticated szerepkörök engedélyeivel. Egy vagy több felhasználói szerepkör definiálható az entitás engedélykonfigurációjában, és minden más definiálatlan szerepkör, rendszer vagy felhasználó automatikusan megtagadja a hozzáférést.

Az alábbi példában a felhasználói szerepkör administrator az entitás egyetlen definiált szerepköre book . A felhasználónak tagja kell legyen a administrator szerepkörnek, és ezt a szerepkört bele kell foglalnia a X-MS-API-ROLE HTTP-fejlécbe, hogy az book entitáson működhessen.

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

Megjegyzés:

A GraphQL-lekérdezések hozzáférés-vezérlésének kikényszerítéséhez a Data API Builder azure Cosmos DB-vel való használatakor a megadott @authorize kell használnia az irányelvet. A GraphQL-lekérdezések GraphQL-mutációi és szűrői esetében azonban az engedélykonfiguráció továbbra is kikényszeríti a hozzáférés-vezérlést a korábban leírtak szerint.

Rétegzett biztonsági modell

A Data API Builder több engedélyezési réteget használ:

  • Entitásszintű: Mely entitások és műveletek érhetők el
  • Szabályzatszintű: Milyen adatokat ad vissza a rendszer (jogcímek szerinti szűrés)
  • Sorszintű: Az adatbázis sorszűrést alkalmaz az RLS-en keresztül
  • API-szint: HTTP-fejlécek és kérésérvényesítés

Következő lépések

  • Last updated on