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.

Ilustrasi tentang bagaimana penyusun Api Data memilih peran dan mengevaluasi izin untuk permintaan.

Menentukan peran pengguna

Tidak ada peran yang memiliki izin default. Setelah penyusun API Data menentukan peran, entitas permissions harus menentukan actions peran tersebut agar permintaan berhasil.

Matriks evaluasi peran berikut berlaku untuk penyedia pembawa JWT (misalnya, EntraID/AzureAD dan Custom) tempat klien mengirim .Authorization: Bearer <token>

Token pembawa disediakan X-MS-API-ROLE Disediakan Peran yang diminta tercantum dalam klaim token roles Peran /hasil yang efektif
Tidak. Tidak. N/A Anonymous
Ya (valid) Tidak. N/A Authenticated
Ya (valid) Ya Tidak. Ditolak (403 Terlarang)
Ya (valid) Ya Ya X-MS-API-ROLE nilai
Ya (tidak valid) Apa saja N/A Ditolak (401 Tidak Sah)

Untuk menggunakan peran selain Anonymous atau Authenticated, X-MS-API-ROLE header diperlukan.

Nota

Permintaan dapat dikaitkan dengan banyak peran dalam prinsipal yang diautentikasi. Namun, penyusun Data API mengevaluasi izin dan kebijakan dalam konteks tepat satu peran yang efektif. Saat disediakan, X-MS-API-ROLE header memilih peran mana yang digunakan.

Catatan penyedia:

  • Penyedia EasyAuth (misalnya, AppService): autentikasi dapat dilakukan oleh header yang disuntikkan platform (seperti X-MS-CLIENT-PRINCIPAL) daripada menggunakan token pengenal.
  • Simulator: permintaan diperlakukan sebagai diautentikasi untuk pengembangan/pengujian, tanpa memvalidasi token nyata.

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. Prinsipal yang diautentikasi harus menyertakan klaim peran yang mencantumkan keanggotaan peran pengguna (misalnya, klaim JWT roles ).
  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" ]
        }
    ]
}

Penyusun API Data mengevaluasi permintaan dalam konteks satu peran yang efektif. Jika permintaan diautentikasi dan tidak ada X-MS-API-ROLE header yang disediakan, pembuat API Data mengevaluasi permintaan dalam konteks Authenticated peran 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 -X 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, book izin entitas secara eksplisit diatur untuk mengizinkan akses baca yang tidak diautentikasi.

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

Jika Anda ingin pengguna yang tidak terautentikasi dan terautentikasi memiliki akses, berikan izin secara eksplisit kepada kedua peran sistem (Anonymous dan Authenticated).

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 harus menggunakan @authorize arahan dalam file skema GraphQL yang disediakan. Namun, untuk mutasi dan filter GraphQL dalam kueri GraphQL, konfigurasi izin masih memberlakukan kontrol akses 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 harus menggunakan @authorize arahan dalam file skema GraphQL yang disediakan. Namun, untuk mutasi dan filter GraphQL dalam kueri GraphQL, konfigurasi izin masih memberlakukan kontrol akses seperti yang dijelaskan di sini.

Keamanan tingkat item

Kebijakan database memungkinkan Anda memfilter hasil di tingkat baris. Kebijakan diterjemahkan menjadi predikat kueri yang dieksekusi oleh database, memastikan pengguna hanya dapat mengakses rekaman yang diotorisasi.

Tindakan yang didukung Tidak didukung
read update delete create, execute

Nota

Azure Cosmos DB for NoSQL saat ini tidak mendukung kebijakan database.

Untuk langkah-langkah konfigurasi terperinci, referensi sintaksis, dan contoh, lihat Mengonfigurasi kebijakan database.

Contoh cepat
{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Konten terkait

  • Last updated on