Konfigurasikan autentikasi Microsoft Entra ID

Panduan ini memandu Anda mengonfigurasi autentikasi Microsoft Entra ID (sebelumnya Azure Active Directory) untuk penyusun API Data. Pada akhirnya, aplikasi klien Anda mengautentikasi pengguna melalui Entra, memperoleh token untuk pembuat API Data, dan DAB dapat menggunakan identitas terkelola untuk terhubung ke Azure SQL.

Penyusun API Data mengautentikasi permintaan masuk menggunakan validasi pembawa JSON Web Token (JWT) (EntraID/AzureAD/Custom) atau header identitas yang disediakan platform ().AppService Untuk pengembangan lokal dan pengujian izin, gunakan Simulator penyedia.

Ilustrasi tentang bagaimana klien mengautentikasi ke pembuat API Data menggunakan token JWT.

Panduan penyedia otentikasi

Pilih panduan berdasarkan penyedia identitas Anda:

Provider Panduan
Microsoft Entra ID Artikel ini
Okta, Auth0, atau lainnya Mengonfigurasi autentikasi JWT kustom
Azure App Service Mengonfigurasi autentikasi pada App Service
Pengujian lokal Konfigurasikan autentikasi Simulator

Proses autentikasi

Alur memiliki tiga fase yang berbeda:

Fase Deskripsi
Autentikasi pengguna Pengguna masuk melalui aplikasi klien Anda melalui Microsoft Entra ID
Autentikasi klien Aplikasi klien memperoleh token cakupan DAB dan memanggil penyusun API Data
Akses database Penyusun API Data memvalidasi token, lalu menyambungkan ke database menggunakan identitasnya sendiri (identitas terkelola atau kredensial string koneksi)

Penting

Pembuat API Data memvalidasi token pengguna masuk untuk autentikasi API, tetapi terhubung ke database menggunakan kredensialnya sendiri (identitas terkelola atau autentikasi SQL). DAB tidak melakukan pertukaran token On-Behalf-Of (OBO) untuk mengakses database sebagai pengguna panggilan secara default. Untuk mengaktifkan OBO sehingga database mengautentikasi sebagai pemanggil aktual, lihat Mengonfigurasi autentikasi OBO.

Prasyarat

  • Langganan Azure dengan instansi Microsoft Entra ID
  • CLI penyusun API Data terinstal (panduan penginstalan)
  • Yang ada dab-config.json dengan setidaknya satu entitas
  • (Opsional) Azure SQL Database untuk skenario identitas terkelola

Referensi cepat

Setting Nilai
Provider EntraID (atau AzureAD untuk kompatibilitas)
Diperlukan untuk validasi aud, iss, exp, tanda tangan valid
Diperlukan untuk otorisasi roles klaim (hanya jika menggunakan peran kustom)
Format pengeluar sertifikat https://login.microsoftonline.com/<tenant-id>/v2.0
Format penonton api://<app-id> atau URI ID Aplikasi kustom
Peran bawaan Authenticated
Header peran khusus X-MS-API-ROLE
Jenis klaim peran roles (diperbaiki, tidak dapat dikonfigurasi)

Nota

Jika Anda menggunakan EntraID atau AzureAD sebagai penyedia, DAB memungkinkan validasi penerbit kunci penandatanganan tambahan khusus untuk token Microsoft Entra. Validasi ini memberikan keamanan yang lebih kuat dibandingkan dengan penyedia generik Custom .

Langkah 1: Mendaftarkan aplikasi di Microsoft Entra ID

Buat pendaftaran aplikasi yang mewakili API penyusun API Data Anda. Aplikasi klien meminta token dengan audiens yang sesuai dengan registrasi ini.

  1. Masuk ke pusat admin Microsoft Entra.

  2. Navigasi ke Identity>Aplikasi>Pendaftaran Aplikasi.

  3. Pilih Pendaftaran baru.

  4. Masukkan Nama (misalnya, Data API Builder API).

  5. Pilih jenis akun yang didukung yang sesuai untuk skenario Anda:

    • Single tenant: Hanya pengguna di organisasi Anda
    • Multitenant: Pengguna di direktori Microsoft Entra mana pun

  6. Biarkan URI Pengalihan kosong (pendaftaran ini untuk API, bukan klien).

  7. Pilih Daftarkan.

  8. Pada halaman Gambaran Umum aplikasi, rekam nilai-nilai ini:

    Nilai Di mana menemukannya Digunakan untuk
    ID aplikasi (klien) Halaman gambaran umum Membangun audiens URI
    ID direktori (penyewa) Halaman gambaran umum Membangun URL penerbit

Mengonfigurasi URI ID Aplikasi

  1. Dalam pendaftaran aplikasi, buka Mengekspos API.

  2. Pilih Tambahkan di samping URI ID Aplikasi.

  3. Terima default (api://<app-id>) atau masukkan URI kustom.

  4. Pilih Simpan.

Petunjuk / Saran

URI ID Aplikasi menjadi audience nilai dalam konfigurasi DAB Anda. Gunakan format yang konsisten di seluruh lingkungan.

Tambah cakupan

Cakupan diperlukan sehingga aplikasi klien (termasuk Azure CLI) dapat meminta token akses yang didelegasikan untuk API Anda.

  1. Dalam pendaftaran aplikasi, buka Mengekspos API.

  2. Di bawah Cakupan yang ditentukan oleh API ini, pilih Tambahkan cakupan.

  3. Masuk:

    • Nama cakupan: Endpoint.Access
    • Siapa yang dapat menyetujui?: Admin dan pengguna
    • Nama tampilan persetujuan admin: Execute requests against Data API builder
    • Deskripsi persetujuan admin: Allows client app to send requests to Data API builder endpoint.
    • Nama tampilan persetujuan pengguna: Execute requests against Data API builder
    • Deskripsi persetujuan pengguna: Allows client app to send requests to Data API builder endpoint.
    • Status: Diaktifkan

  4. Pilih Tambahkan cakupan.

Nota

Nilai cakupan lengkap adalah api://<app-id>/Endpoint.Access. Aplikasi klien menggunakan nilai ini saat meminta token.

Menambahkan peran aplikasi (opsional)

Jika Anda ingin menggunakan peran kustom di luar Anonymous dan Authenticated:

  1. Masuk ke Peran Aplikasi.

  2. Pilih Buat peran aplikasi.

  3. Masuk:

    • Nama tampilan: Reader
    • Jenis anggota yang diizinkan: Pengguna/Grup atau Keduanya
    • Nilai: reader (nilai ini muncul dalam klaim token roles )
    • Deskripsi: Read-only access to data

  4. Pilih Terapkan.

  5. Ulangi untuk peran lainnya (misalnya, writer, admin).

Setel versi token manifes

Secara default, manifes pendaftaran aplikasi diatur accessTokenAcceptedVersion ke null, yang menghasilkan token v1.0. Token V1 menggunakan format pengeluar sertifikat yang berbeda (https://sts.windows.net/<tenant-id>/) daripada pengeluar sertifikat v2.0 yang dikonfigurasi di DAB, yang menyebabkan validasi token gagal.

  1. Di pendaftaran aplikasi, buka Manifes.

  2. Temukan accessTokenAcceptedVersion dan ubah nilainya menjadi 2.

  3. Pilih Simpan.

Penting

Jika accessTokenAcceptedVersion adalah null atau 1, klaim iss dalam token tidak cocok dengan URL pengeluar v2.0 yang dikonfigurasi di DAB, dan semua permintaan gagal dengan 401 Unauthorized.

Menetapkan pengguna ke peran aplikasi

Membuat peran aplikasi tidak secara otomatis memberikan peran tersebut kepada pengguna. Anda harus menetapkan pengguna atau grup melalui Aplikasi Perusahaan.

  1. Di pusat admin Microsoft Entra, navigasikan ke Identity>Aplikasi>Aplikasi perusahaan.

  2. Cari dan pilih aplikasi Anda (misalnya, Data API Builder API). Aplikasi perusahaan dibuat secara otomatis saat Anda mendaftarkan aplikasi.

  3. Masuk ke Pengguna dan grup.

  4. Pilih Tambahkan pengguna/grup.

  5. Di bawah Pengguna, pilih akun pengguna untuk ditetapkan dan pilih Pilih.

  6. Di bawah Pilih peran, pilih peran yang akan ditetapkan (misalnya, Reader). Jika peran Anda tidak muncul, tunggu beberapa menit hingga replikasi Microsoft Entra selesai.

  7. Pilih Tetapkan.

  8. Ulangi untuk setiap peran yang ingin Anda tetapkan.

Nota

Tanpa penetapan peran, roles klaim dalam token pengguna kosong, dan permintaan yang menggunakan X-MS-API-ROLE dengan peran kustom ditolak dengan 403 Forbidden.

Langkah 2: Mengonfigurasi penyusun API Data

Konfigurasikan DAB untuk memvalidasi token yang dikeluarkan oleh penyewa Entra Anda untuk audiens API Anda.

CLI

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

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Konfigurasi yang dihasilkan

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

Langkah 3: Mengonfigurasi izin entitas

Tentukan peran mana yang dapat mengakses setiap entitas. Permintaan dievaluasi berdasarkan peran yang ditetapkan oleh token.

Memberikan akses ke pengguna terautentikasi

dab update Book \
  --permissions "Authenticated:read"

Memberikan akses ke peran kustom

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

Konfigurasi yang dihasilkan

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Langkah 4: Mengonfigurasi koneksi database

Penyusun API Data terhubung ke database menggunakan identitasnya sendiri, terpisah dari pengguna yang diautentikasi. Untuk skenario produksi dengan Azure SQL, gunakan identitas terkelola.

Nota

Koneksi database menggunakan identitas layanan DAB (identitas terkelola atau info masuk SQL), bukan identitas pengguna panggilan. DAB tidak meneruskan token pengguna ke database.

Identitas terkelola yang diberikan oleh sistem

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

Identitas terkelola yang ditetapkan pengguna

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Opsi B: Autentikasi SQL (pengembangan)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Penting

Jangan pernah menerapkan string koneksi dengan kata sandi ke kontrol sumber. Gunakan variabel lingkungan atau Azure Key Vault.

Opsi C: Pengembangan lokal dengan az login

Untuk pengembangan lokal terhadap Azure SQL, gunakan kredensial Azure CLI Anda:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Sebelum memulai DAB, login terlebih dahulu.

az login

Langkah 5: Uji konfigurasi

Mengotorisasi Azure CLI sebagai aplikasi klien

Sebelum Azure CLI dapat memperoleh token untuk API Anda, Anda harus menambahkannya sebagai aplikasi klien resmi.

  1. Dalam pendaftaran aplikasi, buka Mengekspos API.

  2. Di bagian Aplikasi klien yang diotorisasi, pilih Tambahkan aplikasi klien.

  3. Masukkan ID klien Azure CLI: 00001111-aaaa-2222-bbbb-3333cccc4444.

  4. Pilih cakupan api://<app-id>/Endpoint.Access.

  5. Pilih Tambahkan aplikasi.

Memperoleh token dengan Azure CLI

Masuk ke Azure CLI dan atur penyewa tempat pendaftaran aplikasi Anda ada:

az login
az account set --tenant <your-tenant-id>

Minta token untuk API Anda

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

Nota

Jika Anda menerima kesalahan persetujuan AADSTS65001, verifikasi bahwa Anda menambahkan ID klien Azure CLI (00001111-aaaa-2222-bbbb-3333cccc4444) sebagai aplikasi klien resmi pada langkah sebelumnya.

Anda dapat memeriksa token di jwt.ms untuk memverifikasi audklaim , iss, dan roles .

Mulai DAB dan kirim permintaan

  1. Mulai penyusun API Data:

    dab start

  2. Panggil API dengan token:

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

  3. Untuk menggunakan peran kustom, sertakan X-MS-API-ROLE header:

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: reader"

Nota

Peran yang ditentukan dalam X-MS-API-ROLE harus ada di klaim token roles. Jika peran tidak ada dalam token, permintaan akan ditolak.

Perilaku pemilihan peran

Penyusun API Data menentukan peran permintaan menggunakan logika ini:

Ada token? Header X-MS-API-ROLE? Peran dalam token? Result
No No — Anonymous
Ya (valid) No — Authenticated
Ya (valid) Yes No Ditolak (403 Terlarang)
Ya (valid) Yes Yes Nilai Header
Ya (tidak valid) — — Ditolak (401 Tidak Sah)

Troubleshooting

Gejala Kemungkinan penyebab Solusi
401 Unauthorized Token kedaluwarsa atau salah bentuk Memperoleh token baru; periksa token di jwt.ms
401 Unauthorized Ketidakcocokan audiens Verifikasi jwt.audience cocok dengan klaim token aud
401 Unauthorized Ketidakcocokan pengeluar sertifikat Verifikasi jwt.issuer cocok dengan klaim token iss dengan tepat
403 Forbidden Peran tidak ada dalam token Pastikan pengguna ditetapkan ke peran di aplikasi Entra
403 Forbidden Tidak ada izin untuk peran Tambahkan peran ke array entitas permissions

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=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Konten terkait

  • Last updated on