Otorisasi dan peran dalam penyusun API Data

Penyusun API Data menggunakan alur kerja otorisasi berbasis peran. Setiap permintaan masuk, diautentikasi atau tidak, ditetapkan ke peran. Peran dapat berupa Peran Sistem atau Peran Pengguna. Peran yang ditetapkan kemudian diperiksa terhadap izin yang ditentukan yang ditentukan dalam file konfigurasi untuk memahami tindakan, bidang, dan kebijakan apa yang tersedia untuk peran tersebut pada entitas yang diminta.

Peran

Peran mengatur konteks izin di mana permintaan harus dijalankan. Untuk setiap entitas yang ditentukan dalam konfigurasi runtime, Anda dapat menentukan serangkaian peran dan izin terkait yang menentukan bagaimana entitas dapat diakses di titik akhir REST dan GraphQL.

Penyusun API Data mengevaluasi permintaan dalam konteks satu peran:

• anonymous ketika tidak ada token akses yang disajikan.
• authenticated ketika token akses yang valid disajikan.
• <CUSTOM_USER_ROLE> ketika token akses yang valid disajikan danX-MS-API-ROLE header HTTP disertakan menentukan peran pengguna yang juga disertakan dalam klaim token roles akses.

Peran tidak aditif, yang berarti bahwa pengguna yang merupakan anggota keduanya Role1 dan Role2 tidak mewarisi izin yang terkait dengan kedua peran tersebut.

Peran sistem

Peran sistem adalah peran bawaan yang diakui oleh penyusun Api Data. Peran sistem ditetapkan secara otomatis kepada pemohon terlepas dari keanggotaan peran pemohon yang ditandai dalam token akses mereka. Ada dua peran sistem: anonymous dan authenticated.

Peran sistem anonim

Peran anonymous sistem ditetapkan ke permintaan yang dijalankan oleh pengguna yang tidak diautentikasi. Entitas yang ditentukan konfigurasi runtime harus menyertakan izin untuk peran jika anonymous akses yang tidak diautentikasi diinginkan.

Contoh

Konfigurasi runtime penyusun Api Data berikut menunjukkan secara eksplisit mengonfigurasi peran anonymous sistem untuk menyertakan akses baca ke entitas Buku:

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

Saat aplikasi klien mengirim permintaan yang mengakses entitas Buku atas nama pengguna yang tidak diautentikasi, aplikasi tidak boleh menyertakan Authorization header HTTP.

Peran sistem terautentikasi

Peran authenticated sistem ditetapkan ke permintaan yang dijalankan oleh pengguna yang diautentikasi.

Contoh

Konfigurasi runtime penyusun Api Data berikut menunjukkan secara eksplisit mengonfigurasi peran authenticated sistem untuk menyertakan akses baca ke entitas Buku:

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

Peran pengguna

Peran pengguna adalah peran nonsystem yang ditetapkan untuk pengguna dalam idP yang Anda tetapkan dalam konfigurasi runtime. Agar penyusun Api Data mengevaluasi permintaan dalam konteks peran pengguna, dua persyaratan harus dipenuhi:

1. Token akses yang disediakan aplikasi klien harus menyertakan klaim peran yang mencantumkan keanggotaan peran pengguna.
2. Aplikasi klien harus menyertakan header X-MS-API-ROLE HTTP dengan permintaan dan mengatur nilai header sebagai peran pengguna yang diinginkan.

Contoh evaluasi peran

Contoh berikut menunjukkan permintaan yang dibuat ke Book entitas yang dikonfigurasi dalam konfigurasi runtime penyusun API Data sebagai berikut:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Dalam Static Web Apps, pengguna adalah anggota peran anonim secara default. Jika pengguna diautentikasi, pengguna adalah anggota peran anonymous dan authenticated .

Saat aplikasi klien mengirim permintaan terautentikasi ke penyusun API Data yang disebarkan menggunakan Static Web Apps Penghubungan Database (Pratinjau), aplikasi klien menyediakan token akses yang Static Web Apps berubah menjadi JSON:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Karena penyusun Api Data mengevaluasi permintaan dalam konteks satu peran, penyusun api data mengevaluasi permintaan dalam konteks peran authenticated sistem secara default.

Jika permintaan aplikasi klien juga menyertakan header X-MS-API-ROLE HTTP dengan nilai author, permintaan dievaluasi dalam konteks author peran. Contoh permintaan termasuk token akses dan X-MS-API-ROLE header HTTP:

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

Izin

Izin menjelaskan:

• Siapa yang dapat membuat permintaan pada entitas berdasarkan keanggotaan peran?
• Tindakan apa (membuat, membaca, memperbarui, menghapus, menjalankan) yang dapat dilakukan pengguna?
• Bidang mana yang dapat diakses untuk tindakan tertentu?
• Batasan tambahan mana yang ada pada hasil yang dikembalikan oleh permintaan?

Sintaks untuk menentukan izin dijelaskan dalam artikel konfigurasi runtime.

Aman secara default

Secara default, entitas tidak memiliki izin yang dikonfigurasi, yang berarti tidak ada yang dapat mengakses entitas. Selain itu, penyusun Api Data mengabaikan objek database saat tidak dirujuk dalam konfigurasi runtime.

Izin harus dikonfigurasi secara eksplisit

Untuk mengizinkan akses tidak terauthentikasi ke entitas, anonymous peran harus secara eksplisit didefinisikan dalam izin entitas. Misalnya, book izin entitas secara eksplisit diatur untuk memungkinkan akses baca yang tidak diatomatiskan:

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

Untuk menyederhanakan definisi izin pada entitas, asumsikan bahwa jika tidak ada izin khusus untuk peran tersebut authenticated , maka izin yang ditentukan untuk anonymous peran digunakan. Konfigurasi yang book ditampilkan sebelumnya memungkinkan pengguna anonim atau terautentikasi untuk melakukan operasi baca pada book entitas.

Saat operasi baca harus dibatasi hanya untuk pengguna yang diautentikasi, konfigurasi izin berikut harus diatur, yang mengakibatkan penolakan permintaan yang tidak diautentikasi:

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

Entitas tidak memerlukan dan tidak dikonfigurasi sebelumnya dengan izin untuk anonymous peran dan authenticated . Satu atau beberapa peran pengguna dapat ditentukan dalam konfigurasi izin entitas dan semua peran, sistem, atau pengguna lain yang ditentukan, secara otomatis ditolak aksesnya.

Dalam contoh berikut, peran administrator pengguna adalah satu-satunya peran yang ditentukan untuk book entitas. Pengguna harus menjadi anggota administrator peran dan menyertakan peran tersebut X-MS-API-ROLE di header HTTP untuk beroperasi pada book entitas:

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

Tindakan

Tindakan menjelaskan aksesibilitas entitas dalam cakupan peran. Tindakan dapat ditentukan satu per satu atau dengan pintasan kartubebas: * (tanda bintang). Pintasan kartubebas mewakili semua tindakan yang didukung untuk jenis entitas:

• Tabel dan Tampilan: create, read, update, delete
• Prosedur Tersimpan: execute

Untuk informasi selengkapnya tentang tindakan, lihat dokumentasi file konfigurasi .

Akses bidang

Anda dapat mengonfigurasi bidang mana yang harus dapat diakses untuk tindakan. Misalnya, Anda dapat mengatur bidang mana yang akan disertakan dan dikecualikanread dari tindakan.

Contoh berikut mencegah pengguna dalam free-access peran melakukan operasi baca pada Column3. Referensi ke Column3 dalam permintaan GET (titik akhir REST) atau kueri (titik akhir GraphQL) menghasilkan permintaan yang ditolak:

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

Keamanan tingkat item

Ekspresi kebijakan database memungkinkan hasil dibatasi lebih lanjut. Kebijakan database menerjemahkan ekspresi ke predikat kueri yang dijalankan terhadap database. Ekspresi kebijakan database didukung untuk tindakan berikut:

Untuk informasi selengkapnya tentang kebijakan database, lihat dokumentasi file konfigurasi .

Contoh

Kebijakan database yang read membatasi tindakan pada consumer peran untuk hanya mengembalikan rekaman di mana judulnya adalah "Judul Sampel."

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

Konten terkait

• Autentikasi Azure
• Autentikasi lokal