Mengonfigurasi autentikasi App Service (EasyAuth)

Azure App Service menyediakan autentikasi bawaan (sering disebut "EasyAuth") yang menangani masuk pengguna sebelum permintaan mencapai aplikasi Anda. Pembuat API Data dapat membaca informasi identitas yang disuntikkan App Service, mengaktifkan autentikasi tanpa mengelola token secara langsung.

Penting

Penyedia AppService mempercayai header identitas yang diteruskan oleh EasyAuth. Pastikan klien tidak dapat melewati EasyAuth dan menjangkau pembuat API Data secara langsung.

Warning

Gunakan penyedia autentikasi AppService hanya saat menghosting di Azure App Service atau Azure Functions di App Service. Mengatur penyedia ini pada host Windows mandiri atau lingkungan non-App Service menyebabkan kegagalan saat memulai karena infrastruktur EasyAuth yang diperlukan tidak tersedia. Untuk pengujian lokal, simulasikan EasyAuth dengan mengirim X-MS-CLIENT-PRINCIPAL header secara manual. Lihat Menguji secara lokal dengan X-MS-CLIENT-PRINCIPAL.

Proses autentikasi

Saat penyusun API Data berjalan di belakang Azure App Service dengan autentikasi diaktifkan, App Service menangani alur OAuth dan meneruskan informasi identitas melalui header HTTP:

Ilustrasi alur autentikasi App Service memperlihatkan bagaimana EasyAuth menyuntikkan header identitas.

Fase Apa yang terjadi
Autentikasi pengguna Layanan Aplikasi mencegat permintaan yang tidak diautentikasi dan mengarahkan ulang ke penyedia identitas.
Injeksi identitas Setelah autentikasi, App Service menambahkan X-MS-CLIENT-PRINCIPAL header
Pemrosesan DAB Penyusun API Data Base64-decode header JSON dan membangun ClaimsPrincipal dari claims array
Otorisasi DAB menggunakan ClaimsPrincipal.IsInRole() untuk memvalidasi X-MS-API-ROLE header, lalu mengevaluasi izin dan kebijakan

Prasyarat

  • Langganan Azure
  • Azure App Service atau Azure Functions (pada infrastruktur App Service)
  • CLI penyusun API Data terinstal (panduan penginstalan)
  • Yang ada dab-config.json dengan setidaknya satu entitas

Referensi cepat

Setting Nilai
Provider AppService
Header identitas X-MS-CLIENT-PRINCIPAL (JSON yang dikodekan Base64)
Tajuk pemilihan peran X-MS-API-ROLE
Mendukung klaim khusus Yes
Pengujian lokal Ya (atur header secara manual)

Langkah 1: Aktifkan autentikasi App Service

Mengonfigurasi autentikasi di Azure App Service:

  1. Di portal Microsoft Azure, navigasikan ke App Service Anda.

  2. Pilih Pengaturan>Autentikasi.

  3. Pilih Tambahkan Penyedia Identitas.

  4. Pilih Microsoft (atau penyedia lain yang didukung).

  5. Konfigurasikan pengaturan:

    • Jenis pendaftaran aplikasi: Buat baru atau pilih yang sudah ada
    • Jenis akun yang didukung: Pilih berdasarkan skenario Anda
    • Membatasi akses: Memerlukan autentikasi

  6. Pilih Tambahkan.

Petunjuk / Saran

Autentikasi App Service berfungsi dengan beberapa penyedia identitas termasuk Microsoft, Google, Facebook, Twitter, dan OpenID Connect.

Langkah 2: Mengonfigurasi penyusun API Data

Atur penyedia autentikasi ke AppService:

CLI

dab configure \
  --runtime.host.authentication.provider AppService

Konfigurasi yang dihasilkan

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

Nota

EntraID / AzureADTidak seperti penyedia Custom, AppService tidak memerlukan pengaturan jwt.audience atau jwt.issuer. App Service memvalidasi token sebelum meneruskan informasi identitas ke DAB.

Langkah 3: Mengonfigurasi izin entitas

Tentukan izin untuk peran. Pembangun API Data mengevaluasi peran melalui ClaimsPrincipal.IsInRole(), yang memeriksa klaim yang diurai dari header X-MS-CLIENT-PRINCIPAL. Sertakan klaim peran dalam claims array dengan jenis klaim peran yang sesuai.

Konfigurasi contoh

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

Konfigurasi yang dihasilkan

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Langkah 4: Uji secara lokal dengan X-MS-CLIENT-PRINCIPAL

Anda dapat menguji autentikasi App Service secara lokal dengan menyediakan X-MS-CLIENT-PRINCIPAL header secara manual. Pendekatan ini mensimulasikan apa yang diteruskan EasyAuth ke aplikasi Anda dan memungkinkan Anda menguji peran dan perilaku berbasis klaim tanpa menyebarkan ke Azure.

Membuat prinsipal klien

Header X-MS-CLIENT-PRINCIPAL berisi objek JSON yang dikodekan Base64. Penyusun API Data mengurai properti berikut:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Mengodekan komponen utama

Kodekan JSON sebagai Base64. Anda dapat menggunakan alat apa pun:

PowerShell:

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Bash:

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Mengirim permintaan dengan header

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

Struktur X-MS-CLIENT-PRINCIPAL

Penyusun API Data mengurai properti berikut dari prinsipal klien:

Harta benda Tipe Deskripsi
auth_typ string Jenis autentikasi (misalnya, aad). Diperlukan agar identitas dianggap diautentikasi.
name_typ string (Opsional) Jenis klaim yang digunakan untuk nama pengguna
role_typ string (Optional) Jenis klaim yang digunakan untuk peran (secara default adalah roles)
claims objek[] Array klaim dengan properti typ dan val. Peran harus disertakan di sini sebagai klaim.

Penting

Peran dievaluasi melalui ClaimsPrincipal.IsInRole(), yang memeriksa array claims untuk klaim yang sesuai dengan role_typ. Sertakan setiap peran sebagai entri klaim terpisah (misalnya, { "typ": "roles", "val": "editor" }).

Menggunakan klaim dalam kebijakan database

Dengan penyedia AppService, Anda dapat menggunakan klaim dalam kebijakan database. Kemampuan ini memungkinkan keamanan tingkat baris berdasarkan identitas pengguna.

Contoh: Filter menurut ID objek pengguna

Contoh ini menggunakan klaim oid (pengidentifikasi objek), yang disertakan dalam token oleh ID Microsoft Entra.

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Petunjuk / Saran

Jenis klaim umum dari ID Microsoft Entra termasuk oid (ID objek), email, name, dan preferred_username. Gunakan string jenis klaim yang tepat dari penyedia identitas Anda.

Referensi klaim yang tersedia

Referensi klaim menggunakan string jenis klaim tepat dari claims array:

Referensi klaim Deskripsi
@claims.<claim-type> Setiap klaim dari claims array, yang dicocokkan oleh properti typ

Misalnya, jika prinsipal Anda menyertakan { "typ": "email", "val": "alice@contoso.com" }, gunakan @claims.email dalam kebijakan Anda. Jenis klaim harus sama persis.

Permintaan anonim

Saat App Service mengizinkan permintaan yang tidak diautentikasi, atau saat menguji secara lokal tanpa X-MS-CLIENT-PRINCIPAL header, middleware autentikasi pembuat API Data mengatur X-MS-API-ROLE header ke anonymous secara otomatis. Permintaan kemudian dievaluasi menggunakan anonymous peran:

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Agar akses anonim berfungsi, entitas Anda harus memiliki izin untuk peran anonymous tersebut:

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

Troubleshooting

Gejala Kemungkinan penyebab Solusi
401 Unauthorized (atau alihkan ke masuk) EasyAuth memblokir permintaan sebelum mencapai DAB Masuk melalui EasyAuth atau kirim kredensial yang valid; verifikasi pengaturan Autentikasi App Service
403 Forbidden Peran tidak termasuk dalam izin Menambahkan peran ke izin entitas
403 Forbidden X-MS-API-ROLE bukan bagian dari peran pengguna Pastikan nilai header cocok dengan klaim peran dalam array utama claims
Klaim tidak tersedia Array claims yang hilang di prinsipal klien Menambahkan klaim pada X-MS-CLIENT-PRINCIPAL JSON
Peran tidak dikenali Peran tidak dalam claims array Tambahkan klaim peran dengan role_typ yang benar (contohnya, { "typ": "roles", "val": "editor" })
Pengujian lokal gagal Header tidak dikodekan Base64 Mengodekan JSON dengan benar sebelum mengirim

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": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Konten terkait

  • Last updated on