Bagikan melalui

Otorisasi dan peran dalam penyusun API Data

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

Menentukan peran pengguna

Tidak ada role yang memiliki izin bawaan. Setelah aturan ditentukan oleh penyusun API Data, entitas permissions harus menentukan actions peran tersebut agar permintaan berhasil.

Token Disediakan x-ms-api-role Disediakan x-ms-api-role dalam Token Peran yang Dihasilkan
Tidak. Tidak. Tidak. anonymous
Ya Tidak. Tidak. authenticated
Ya Ya Tidak. Pengecualian
Ya Ya Ya x-ms-api-role nilai

Untuk memiliki peran selain anonymous atau authenticated, x-ms-api-role header diperlukan.

Nota

Permintaan hanya dapat memiliki satu peran. Bahkan jika token mengindikasikan beberapa peran, nilai x-ms-api-role memilih peran mana yang ditetapkan untuk permintaan.

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 ditunjukkan dalam token akses mereka. Ada dua peran sistem: anonymous dan authenticated.

Peran sistem anonim

Peran anonymous sistem dialamatkan ke permintaan yang dilakukan oleh pengguna tidak terotentikasi. Entitas yang ditentukan dalam konfigurasi runtime harus menyertakan izin bagi peran anonymous jika diinginkan akses yang tidak diautentikasi.

Contoh

Konfigurasi runtime pembangun API Data berikut secara eksplisit menunjukkan cara mengonfigurasi peran sistem anonymous 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 yang diautentikasi

Fungsi authenticated sistem ditetapkan untuk permintaan yang dilakukan oleh pengguna terautentikasi.

Contoh

Konfigurasi runtime pembangun API Data berikut secara eksplisit menunjukkan cara mengonfigurasi peran sistem authenticated 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 penyedia identitas 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" ]
        }
    ]
}

Di 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 koneksi database Static Web Apps (Pratinjau), aplikasi klien menyediakan token akses yang ditransformasi Static Web Apps menjadi JSON:

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

Karena penyusun API Data mengevaluasi permintaan dalam konteks satu peran, pembangun 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

Penting

Permintaan aplikasi klien ditolak ketika klaim token roles akses yang disediakan tidak berisi peran yang tercantum di X-MS-API-ROLE header.

Hak akses

Deskripsi izin:

  • 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.

Penting

Mungkin ada beberapa peran yang ditentukan dalam konfigurasi izin entitas tunggal. Namun, permintaan hanya dievaluasi dalam konteks satu peran:

  • Secara bawaan, peran sistem anonymous atau authenticated
  • Ketika disertakan, peran ditetapkan di X-MS-API-ROLE header HTTP.

Aman secara default

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

Izin harus dikonfigurasi secara eksplisit

Untuk mengizinkan akses yang tidak diautentikasi ke entitas, peran anonymous harus ditentukan secara eksplisit pada izin entitas. Misalnya, izin untuk entitas book telah secara eksplisit diatur untuk memungkinkan akses baca tanpa otentikasi.

"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 tersebut digunakan. Konfigurasi yang ditampilkan sebelumnya book memungkinkan pengguna anonim atau yang terautentikasi untuk melakukan operasi baca pada suatu book entitas.

Ketika 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 peran anonymous dan authenticated. Satu atau beberapa peran pengguna dapat ditentukan dalam konfigurasi izin entitas, sedangkan semua peran lain yang tidak terdefinisi, baik itu sistem atau yang ditentukan pengguna, secara otomatis ditolak aksesnya.

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

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

Nota

Untuk menerapkan kontrol akses untuk kueri GraphQL saat menggunakan penyusun Api Data dengan Azure Cosmos DB, Anda diharuskan menggunakan @authorize arahan dalam file skema GraphQL yang disediakan. Namun, untuk mutasi dan filter GraphQL dalam kueri GraphQL, kontrol akses masih diberlakukan oleh konfigurasi izin seperti yang dijelaskan sebelumnya.

Tindakan

Tindakan menjelaskan aksesibilitas entitas dalam cakupan peran. Tindakan dapat ditentukan satu per satu atau dengan pintasan wildcard: * (asterisk). 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" ]
              }
            }
          ]
        }
      ]
    }

Nota

Untuk menerapkan kontrol akses untuk kueri GraphQL saat menggunakan penyusun Api Data dengan Azure Cosmos DB, Anda diharuskan menggunakan @authorize arahan dalam file skema GraphQL yang disediakan. Namun, untuk mutasi dan filter GraphQL dalam kueri GraphQL, kontrol akses masih diberlakukan oleh konfigurasi izin seperti yang dijelaskan di sini.

Keamanan tingkat item

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

  • buat
  • baca
  • perbarui
  • hapus

Peringatan

Aksi eksekusi , yang digunakan dengan prosedur tersimpan, tidak mendukung kebijakan basis data.

Nota

Kebijakan database saat ini tidak didukung oleh CosmosDB untuk NoSQL.

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

Contoh

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

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

Konten terkait

  • Last updated on