Engedélyezés és szerepkörök a Data API Builderben

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 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 azokra a JWT-tulajdonos szolgáltatókra vonatkozik (például EntraID/AzureAD és Custom), 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
Nem	Nem	N/A	Anonymous
Igen (érvényes)	Nem	N/A	Authenticated
Igen (érvényes)	Igen	Nem	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:

• EasyAuth-szolgáltatók (például AppService): a hitelesítés platformba ágyazott fejlécekkel (például X-MS-CLIENT-PRINCIPAL) hozható létre, nem pedig tulajdonosi jogkivonattal.
• Simulator: a kérelmeket a rendszer a fejlesztéshez/teszteléshez hitelesítettként kezeli, 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.

példa

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.

példa

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 .

Engedélyek

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.

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 azt szeretné, hogy a hitelesítés nélküli és a hitelesített felhasználók is rendelkezzenek hozzáféréssel, explicit módon adjon engedélyeket mindkét rendszerszerepkörnek (Anonymous és Authenticated).

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.

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.

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

Kapcsolódó tartalom

• Adatbázis-szabályzatok konfigurálása sorszintű szűréshez
• A Microsoft Entra-azonosító hitelesítésének konfigurálása
• Szimulátor-hitelesítés konfigurálása helyi teszteléshez