Bagikan melalui

Mengonfigurasi autentikasi Simulator untuk pengujian lokal

Penyedia autentikasi Simulator memungkinkan Anda menguji izin berbasis peran secara lokal tanpa mengonfigurasi penyedia identitas. Gunakan selama pengembangan untuk memverifikasi bahwa aturan izin Anda berfungsi dengan benar sebelum menyebarkan ke produksi.

Pilih penyedia autentikasi lokal

Selama pengembangan, Anda dapat menguji autentikasi dan otorisasi tanpa mengonfigurasi penyedia identitas produksi.

Provider Paling cocok untuk Catatan
Simulator Pengujian izin cepat Hanya untuk pengembangan. Memperlakukan setiap permintaan sebagai terautentikasi. Beralih ke peran Authenticated; gantikan dengan X-MS-API-ROLE.
AppService Pengujian berbasis klaim Simulasikan EasyAuth secara lokal dengan mengirim X-MS-CLIENT-PRINCIPAL dengan klaim kustom. Untuk detailnya, lihat Mengonfigurasi autentikasi App Service.

Proses autentikasi

Penyedia Simulator memperlakukan semua permintaan sebagai terautentikasi, memungkinkan Anda fokus pada pengujian aturan otorisasi:

Ilustrasi alur autentikasi Simulator yang menunjukkan bagaimana permintaan secara otomatis diperlakukan sebagai diautentikasi.

Phase Apa yang terjadi
Permintaan tiba Pengembang mengirim permintaan HTTP ke DAB
Penetapan peran DAB menetapkan Authenticated (default) atau peran yang tercantum di X-MS-API-ROLE header
Pemeriksaan izin DAB mengevaluasi permintaan berdasarkan izin entitas untuk peran yang dimaksud
Pelaksanaan kueri Jika diizinkan, DAB mengkueri database dan mengembalikan hasil

Penting

Penyedia Simulator hanya untuk pengembangan. Jangan pernah menggunakannya dalam lingkungan produksi—mengabaikan semua autentikasi nyata.

Prasyarat

  • CLI penyusun API Data terinstal (panduan penginstalan)
  • Yang ada dab-config.json dengan setidaknya satu entitas

Referensi cepat

Setting Nilai
Provider Simulator
Host mode development (diperlukan)
Peran bawaan Authenticated (disuntikkan secara otomatis)
Header penggantian peran X-MS-API-ROLE
Token diperlukan Tidak.
Bantuan Pengajuan Klaim Terbatas (hanya peran Anonymous/Authenticated sistem; tidak ada klaim sewenang-wenang)

Langkah 1: Mengonfigurasi penyedia Simulator

Atur penyedia autentikasi ke Simulator dan pastikan mode pengembangan diaktifkan.

antarmuka baris perintah (CLI)

# Enable development mode
dab configure \
  --runtime.host.mode development

# Set the Simulator provider
dab configure \
  --runtime.host.authentication.provider Simulator

Konfigurasi yang dihasilkan

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Nota

Penyedia Simulator hanya berfungsi ketika mode diatur ke development. Dalam mode produksi, DAB menolak penyedia Simulator dan gagal memulai.

Langkah 2: Mengonfigurasi izin entitas

Tentukan izin untuk peran yang ingin Anda uji. Anda dapat menguji peran sistem (Anonymous, Authenticated) dan peran kustom.

Contoh: Beberapa peran

# Allow anonymous read access
dab update Book \
  --permissions "Anonymous:read"

# Allow authenticated users full read access
dab update Book \
  --permissions "Authenticated:read"

# Allow authors to create and update
dab update Book \
  --permissions "author:create,read,update"

# Allow admins full access
dab update Book \
  --permissions "admin:*"

Konfigurasi yang dihasilkan

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Langkah 3: Uji peran yang berbeda

Mulai penyusun API Data dan kirim permintaan untuk menguji setiap peran.

dab start

Uji sebagai terautentikasi (default)

Tanpa adanya header khusus, permintaan akan dievaluasi sebagai Authenticated peran:

curl -X GET "http://localhost:5000/api/Book"

Uji sebagai anonim

X-MS-API-ROLE Gunakan header untuk menguji sebagai Anonymous:

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous"

Menguji sebagai peran kustom

X-MS-API-ROLE Gunakan header untuk menguji peran kustom apa pun:

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: author"

Nota

Dengan Simulator, pengujian peran kustom berfungsi karena DAB mengevaluasi izin berdasarkan nilai dari header X-MS-API-ROLE. Peran sistem (Anonymous, Authenticated) selalu tersedia. Jika permintaan peran kustom mengembalikan 403, verifikasi nama peran yang sama persis dengan izin entitas Anda.

Menguji tindakan yang harus ditolak

Coba lakukan tindakan yang tidak diizinkan untuk peran tersebut.

# This should fail—Anonymous can only read
curl -X POST "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Book", "author": "Test"}'

Respons yang diharapkan: 403 Forbidden

Skenario pengujian

Gunakan Simulator untuk menguji skenario umum ini:

Scenario Cara menguji
Akses Anonim Atur X-MS-API-ROLE: Anonymous
Akses terautentikasi Hilangkan header (default) atau atur X-MS-API-ROLE: Authenticated
Akses peran kustom Atur X-MS-API-ROLE: <role-name>
Tindakan ditolak Meminta tindakan yang perannya tidak memiliki izin untuk lakukan
Pembatasan bidang Mengonfigurasi izin tingkat bidang dan memverifikasi bidang respons
Peran yang hilang Atur X-MS-API-ROLE: nonexistent untuk menguji penanganan kesalahan

Keterbatasan

Penyedia Simulator memiliki batasan ini:

Batasan Penanganan masalah
Tidak ada klaim kustom Menggunakan penyedia AppService dengan X-MS-CLIENT-PRINCIPAL header
Tidak ada kebijakan database dengan klaim Menguji kebijakan menggunakan penyedia AppService
Tidak ada validasi token Beralih ke Entra atau Penyedia kustom untuk produksi
Mode pengembangan saja Menggunakan penyedia nyata dalam produksi

Petunjuk / Saran

Jika Anda perlu menguji kebijakan database yang menggunakan klaim (seperti @claims.userId), gunakan penyedia AppService sebagai gantinya. Ini memungkinkan Anda memberikan klaim kustom melalui X-MS-CLIENT-PRINCIPAL header.

Transisi ke produksi

Saat Anda siap untuk menyebarkan, ganti penyedia Simulator dengan penyedia produksi:

  1. Ubah mode dari development ke production
  2. Ubah provider dari Simulator ke penyedia pilihan Anda (EntraID/AzureAD, AppService, atau Custom)
  3. Mengonfigurasi pengaturan JWT yang diperlukan (audiens, penerbit)
{
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
        }
      }
    }
  }
}

Contoh konfigurasi lengkap

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost;Database=Library;Trusted_Connection=true;TrustServerCertificate=true;"
  },
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Konten terkait

  • Last updated on