Engedélyezés és szerepkörök a Data API Builderben
A Data API Builder szerepköralapú engedélyezési munkafolyamatot használ. A hitelesített vagy nem hitelesített bejövő kérések szerepkörhöz vannak rendelve. A szerepkörök lehetnek rendszerszerepkörök vagy felhasználói szerepkörök. A hozzárendelt szerepkört ezután a konfigurációs fájlban megadott engedélyek alapján ellenőrzi, hogy milyen műveletek, mezők és szabályzatok érhetők el az adott szerepkörhöz a kért entitáson.
Szerepkörök
A szerepkörök beállítják azt az engedélykörnyezetet, amelyben a kérést végre kell hajtani. A futtatókörnyezet konfigurációjában definiált minden entitáshoz meghatározhat szerepköröket és kapcsolódó engedélyeket, amelyek meghatározzák, hogy az entitás hogyan érhető el a REST- és GraphQL-végpontokon.
A Data API Builder egyetlen szerepkör kontextusában értékeli ki a kéréseket:
anonymous
ha nem jelenik meg hozzáférési jogkivonat.authenticated
ha érvényes hozzáférési jogkivonat jelenik meg.<CUSTOM_USER_ROLE>
ha egy érvényes hozzáférési jogkivonat jelenik meg , és aX-MS-API-ROLE
HTTP-fejléc tartalmazza a hozzáférési jogkivonat jogcímébenroles
is szereplő felhasználói szerepkört.
A szerepkörök nem additívak, ami azt jelenti, hogy azok a felhasználók, akik mindkettő Role1
tagja, és Role2
nem öröklik mindkét szerepkörhöz tartozó engedélyeket.
Rendszerszerepkörök
A rendszerszerepkörök a Data API Builder által felismert beépített szerepkörök. A rendszerszerepkör automatikusan hozzárendelhető a kérelmezőhöz, függetlenül attól, hogy a kérelmező szerepkör-tagsága szerepel-e a hozzáférési jogkivonataikban. Két rendszerszerepkör létezik: anonymous
és authenticated
.
Névtelen rendszerszerepkör
A anonymous
rendszerszerepkör a nem hitelesített felhasználók által végrehajtott kérésekhez van hozzárendelve. A futtatókörnyezet-konfigurációban definiált entitásoknak tartalmazniuk kell a anonymous
szerepkör engedélyeit, ha nem hitelesített hozzáférésre van szükség.
Példa
Az alábbi Data API Builder-futtatókörnyezeti konfiguráció bemutatja, hogyan konfigurálja explicit módon a rendszerszerepkört anonymous
úgy, hogy az olvasási hozzáférést is tartalmazza a Book entitáshoz:
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
}
]
}
Amikor egy ügyfélalkalmazás kérést küld a Book entitáshoz egy nem hitelesített felhasználó nevében, 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örnyezeti konfiguráció bemutatja, hogyan konfigurálja explicit módon a rendszerszerepkört authenticated
úgy, hogy az olvasási hozzáférést is tartalmazza a Book entitáshoz:
"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:
- Az ügyfélalkalmazás által megadott hozzáférési jogkivonatnak tartalmaznia kell a felhasználó szerepkör-tagságát listázó szerepkörjogcímeket.
- Az ügyfélalkalmazásnak tartalmaznia kell a KÉRÉSEKET tartalmazó HTTP-fejlécet
X-MS-API-ROLE
, és a fejléc értékét meg kell adnia 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ásra irányuló 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 Static Web Apps a felhasználó alapértelmezés szerint a névtelen szerepkör tagja. Ha a felhasználó hitelesítése megtörtént, a felhasználó a és authenticated
a anonymous
szerepkör tagja is.
Amikor egy ügyfélalkalmazás hitelesített kérést küld a Static Web Apps adatbázis kapcsolatok (előzetes verzió) használatával üzembe helyezett Data API Buildernek, az ügyfélalkalmazás egy hozzáférési jogkivonatot biztosít, amely Static Web Apps JSON-vá alakul át:
{
"identityProvider": "azuread",
"userId": "d75b260a64504067bfc5b2905e3b8182",
"userDetails": "username",
"userRoles": ["anonymous", "authenticated", "author"]
}
Mivel a Data API Builder egyetlen szerepkör kontextusában értékeli ki a kéréseket, alapértelmezés szerint a rendszerszerepkör authenticated
kontextusában értékeli ki a kérést.
Ha az ügyfélalkalmazás kérése a HTTP-fejlécet X-MS-API-ROLE
is tartalmazza a értékkel author
, a kérés kiértékelése a author
szerepkör kontextusában történik. Példakérés hozzáférési jogkivonattal és X-MS-API-ROLE
HTTP-fejléccel:
curl -k -r 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 a következőket írják le:
- Ki kezdeményezhet kéréseket egy entitáson 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 találja.
Fontos
Egy entitás engedélykonfigurációjában több szerepkör is definiálható. A kérések azonban csak egyetlen szerepkör kontextusában lesznek kiértékelve:
- Alapértelmezés szerint a rendszerszerepkör
anonymous
vagyauthenticated
- Ha belefoglalja, a szerepkör a
X-MS-API-ROLE
HTTP-fejlécben van beállítva.
Alapértelmezés szerint biztonságos
Alapértelmezés szerint egy entitáshoz nincs konfigurálva engedély, 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
Egy entitáshoz való hitelesítés nélküli hozzáférés engedélyezéséhez a anonymous
szerepkört explicit módon meg kell határozni az entitás engedélyeiben. Például az book
entitás engedélyei explicit módon úgy van beállítva, hogy engedélyezve legyen a hitelesítés nélküli olvasási hozzáférés:
"book": {
"source": "dbo.books",
"permissions": [{
"role": "anonymous",
"actions": [ "read" ]
}]
}
Az entitások engedélydefiníciójának egyszerűsítése érdekében feltételezzük, hogy ha a szerepkörhöz authenticated
nincsenek külön engedélyek, akkor a rendszer a szerepkörhöz anonymous
meghatározott engedélyeket használja. A book
korábban bemutatott konfiguráció lehetővé teszi, hogy bármely névtelen vagy hitelesített felhasználó olvasási műveleteket hajtson végre az book
entitáson.
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" ]
}]
}
Az entitások nem igényelnek és nincsenek előre konfigurálva a és authenticated
szerepkörök anonymous
engedélyeivel. Egy vagy több felhasználói szerepkör definiálható az entitás engedélykonfigurációjában, és a rendszer automatikusan megtagadja az összes többi definiálatlan szerepkört, rendszert vagy felhasználót.
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 a szerepkör tagjának kell lennie, administrator
és bele kell foglalnia ezt a szerepkört a X-MS-API-ROLE
HTTP-fejlécbe az book
entitáson való működéshez:
"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, amikor a Data API Buildert az Azure Cosmos DB-vel használja, az @authorize
irányelvet a megadott GraphQL-sémafájlban kell használnia.
A GraphQL-lekérdezések GraphQL-mutációi és -szűrői esetében azonban a hozzáférés-vezérlést továbbra is érvényesíti az engedélykonfiguráció a korábban leírtak szerint.
Műveletek
A műveletek a szerepkörök hatókörébe tartozó entitások akadálymentességét írják le. A műveletek megadhatóak egyenként vagy a helyettesítő karakteres billentyűparanccsal: *
(csillag). A helyettesítő karakteres parancsikon 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ör felhasználói olvasási műveleteket hajtsanak végre a következőn: Column3
. Column3
A GET-kérések (REST-végpont) vagy lekérdezések (GraphQL-végpont) hivatkozásai 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, amikor a Data API Buildert az Azure Cosmos DB-vel használja, az @authorize
irányelvet a megadott GraphQL-sémafájlban kell használnia. A GraphQL-lekérdezések GraphQL-mutációi és -szűrői esetében azonban a hozzáférés-vezérlést továbbra is az itt leírt engedélykonfiguráció kényszeríti ki.
Elemszintű biztonság
Az adatbázis-szabályzatkifejezések lehetővé teszik az eredmények további korlátozását. Az adatbázis-szabályzatok kifejezéseket fordítanak le az adatbázison végrehajtott lekérdezési predikátumokra. Az adatbázisházirend-kifejezések a következő műveletekhez támogatottak:
- létrehozás
- olvasás
- update
- delete
Figyelmeztetés
A tárolt eljárásokkal használt végrehajtási művelet nem támogatja az adatbázis-szabályzatokat.
Megjegyzés
A CosmosDB for NoSQL jelenleg nem támogatja az adatbázis-szabályzatokat.
Az adatbázis-szabályzatokkal kapcsolatos további információkért tekintse meg a konfigurációs fájl dokumentációját.
Példa
Egy adatbázis-szabályzat, amely korlátozza a read
consumer
szerepkör műveletét, hogy csak olyan rekordokat adjon vissza, amelyek címe "Mintacím".
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.title eq 'Sample Title'"
}
}
]
}