Gambaran umum otorisasi

Otorisasi menentukan pengguna terautentikasi apa yang diizinkan untuk dilakukan di aplikasi penyusun API Data Anda. Meskipun autentikasi memverifikasi siapa penggunanya, otorisasi mengontrol apa yang dapat mereka akses dan ubah.

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.

Konsep otorisasi utama

Izin untuk entitas

Kontrol operasi CRUD (Buat, Baca, Perbarui, Hapus) di tingkat entitas. Setiap peran dapat diberikan atau ditolak tindakan tertentu pada entitas tertentu.

Kontrol akses berbasis peran

Tetapkan pengguna ke peran dan berikan izin berdasarkan keanggotaan peran. Peran menyederhanakan manajemen grup pengguna besar dengan pola akses serupa.

Keamanan tingkat baris (RLS)

Memfilter data berdasarkan identitas pengguna atau konteks sesi. Pengguna hanya dapat melihat baris yang mereka diizinkan untuk akses, yang diterapkan di tingkat basis data.

Kebijakan API

Terapkan predikat dan filter OData ke respons API. Kebijakan secara otomatis membatasi hasil kueri berdasarkan klaim dan identitas pengguna.

Otorisasi berbasis klaim

Untuk menentukan akses, gunakan klaim dari token autentikasi (misalnya, grup, peran, atribut kustom). Klaim memberikan keputusan izin yang fleksibel dengan tingkat detail tinggi.

Cara kerjanya

  1. Pengguna mengautentikasi menggunakan salah satu metode autentikasi yang didukung
  2. Sistem mengekstrak klaim dari token autentikasi (peran, grup, organisasi, dll.)
  3. Aturan otorisasi dievaluasi terhadap klaim pengguna dan sumber daya yang diminta
  4. Akses diberikan atau ditolak berdasarkan izin entitas, kebijakan, dan aturan keamanan tingkat baris

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 JSON Web Token (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
No No N/A Anonymous
Ya (valid) No N/A Authenticated
Ya (valid) Yes No Ditolak (403 Terlarang)
Ya (valid) Yes Yes 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): header yang disuntikkan oleh platform (seperti X-MS-CLIENT-PRINCIPAL) digunakan untuk mengatur autentikasi daripada menggunakan token jenis bearer.
  • Simulator: permintaan diperlakukan sebagai authenticated 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.

Example

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.

Example

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.

Permissions

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 satu entitas. 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.

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.

Kebijakan database (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"
      }
    }
  ]
}

Pewarisan peran

DAB 2.0 memperkenalkan warisan peran sehingga Anda tidak perlu mengulangi blok izin yang sama di setiap peran. Rantai warisan adalah:

named-role → authenticated → anonymous
  • Jika authenticated tidak dikonfigurasi secara eksplisit untuk entitas, entitas tersebut mewarisi dari anonymous.
  • Jika peran bernama tidak dikonfigurasi, peran tersebut mewarisi dari authenticated, atau dari anonymous jika authenticated juga tidak ada.

Anda dapat menentukan izin sekali pada anonymous dan setiap peran yang lebih luas mendapatkan akses yang sama secara otomatis, tanpa memerlukan duplikasi.

Nota

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

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

Dengan konfigurasi ini, anonymous, authenticated, dan peran bernama yang belum dikonfigurasi semuanya dapat membaca Book.

Gunakan dab configure --show-effective-permissions untuk menampilkan izin yang telah ditentukan untuk setiap entitas setelah pewarisan diterapkan.

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" ]
  }]
}

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.

Model keamanan berlapis

Pembuat API Data menggunakan beberapa lapisan otorisasi:

  • Tingkat entitas: Entitas dan operasi mana yang dapat diakses
  • Tingkat kebijakan: Data apa yang dikembalikan (pemfilteran berdasarkan klaim)
  • Tingkat baris: Database menerapkan pemfilteran baris melalui RLS
  • Tingkat API: Header HTTP dan validasi permintaan

Langkah berikutnya

  • Last updated on