Megosztás a következőn keresztül:


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 a X-MS-API-ROLE HTTP-fejléc tartalmazza a hozzáférési jogkivonat jogcímében roles 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:

  1. 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.
  2. 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 vagy authenticated
  • 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, , updatedelete
  • 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 readconsumer 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'"
      }
    }
  ]
}