Bagikan melalui

Mengonfigurasi autentikasi JWT kustom (Okta, Auth0)

Pembuat API Data mendukung penyedia identitas pihak ketiga melalui Penyedia autentikasi kustom. Gunakan pendekatan ini saat organisasi Anda menggunakan Okta, Auth0, atau penyedia identitas lain yang mematuhi OAuth 2.0/OpenID Connect.

Proses autentikasi

Dengan penyedia identitas kustom, aplikasi klien Anda menangani autentikasi pengguna lalu mengirim token akses ke pembuat API Data:

Ilustrasi alur autentikasi JWT kustom dengan IdP pihak ketiga.

Phase Apa yang terjadi
Autentikasi pengguna Pengguna masuk melalui IdP (Okta, Auth0, dll.)
Akuisisi Token Aplikasi klien menerima token akses dari IdP
Panggilan API Klien mengirim token ke DAB di Authorization header
Validasi DAB memvalidasi JWT (penerbit, audiens, tanda tangan)
Otorisasi DAB mengekstrak peran dan mengevaluasi hak akses

Prasyarat

  • Akun melalui penyedia identitas Anda (Okta, Auth0, dll.)
  • Aplikasi yang terdaftar di penyedia identitas Anda
  • CLI penyusun API Data terinstal (panduan penginstalan)
  • Yang ada dab-config.json dengan setidaknya satu entitas

Referensi cepat

Setting Nilai
Provider Custom
Diperlukan untuk validasi iss, aud, exp, tanda tangan valid
Diperlukan untuk otorisasi roles klaim yang berisi peran yang dipilih
Header token Authorization: Bearer <token>
Jenis klaim peran roles (diperbaiki, tidak dapat dikonfigurasi)
Tajuk pemilihan peran X-MS-API-ROLE

Langkah 1: Mengonfigurasi penyedia identitas Anda

Langkah-langkah yang tepat bergantung pada penyedia Anda. Berikut adalah nilai kunci yang Anda butuhkan:

Nilai yang akan dikumpulkan

Nilai Di mana menemukannya Digunakan untuk
URL Pengeluar Sertifikat Dokumentasi penyedia atau titik akhir metadata OAuth DAB jwt.issuer (digunakan sebagai Otoritas JWT)
Audiens ID klien aplikasi Anda atau pengidentifikasi API kustom OLESKAN jwt.audience

Nota

DAB menggunakan yang sudah dikonfigurasi jwt.issuer sebagai Otoritas JWT. Kunci penandatanganan ditemukan secara otomatis melalui metadata OpenID Connect standar (biasanya <issuer>/.well-known/openid-configuration).

Contoh Okta

  1. Masuk ke Konsol Admin Okta.
  2. Navigasi ke Aplikasi>Aplikasi.
  3. Buat atau pilih aplikasi.
  4. Perhatikan ID Klien (gunakan sebagai audiens).
  5. Pengeluar sertifikat Anda biasanya https://<your-domain>.okta.com.

Contoh Auth0

  1. Masuk ke Dasbor Auth0.
  2. Navigasikan keAPI>.
  3. Buat atau pilih API.
  4. Perhatikan Pengidentifikasi (guna sebagai audiens).
  5. Penerbit Anda adalah https://<your-tenant>.auth0.com/.

Penting

Penyusun API Data menggunakan jenis roles klaim tetap untuk otorisasi berbasis peran. Nilai ini tidak dapat dikonfigurasi. Jika Penyedia Identitas Anda mengeluarkan peran dalam klaim yang berbeda (seperti groups atau permissions), Anda harus mengonfigurasi penyedia Anda untuk juga mengeluarkan klaim roles, atau menggunakan tindakan setelah masuk untuk menyalin nilai ke dalam klaim roles.

Langkah 2: Mengonfigurasi penyusun API Data

Atur penyedia autentikasi ke Custom dan konfigurasikan pengaturan JWT:

antarmuka baris perintah (CLI)

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

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

Konfigurasi yang dihasilkan

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Langkah 3: Mengonfigurasi izin entitas

Tentukan izin untuk peran-peran yang ditetapkan oleh penyedia identitas Anda.

antarmuka baris perintah (CLI)

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

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

Konfigurasi yang dihasilkan

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Langkah 4: Mengatur peran di penyedia identitas Anda

DAB mengharapkan peran pada klaim roles. Konfigurasikan IdP Anda untuk memasukkan klaim ini.

Okta: Menambahkan grup sebagai peran

  1. Di Konsol Admin Okta, buka API Keamanan>.
  2. Pilih server otorisasi Anda.
  3. Buka tab Klaim .
  4. Tambahkan klaim:
    • Nama: roles
    • Sertakan dalam jenis token: Token Akses
    • Jenis nilai: Grup
    • Filter: Pilih grup yang akan disertakan

Auth0: Menambahkan peran dengan tindakan

  1. Di Dasbor Auth0, buka Tindakan>Pustaka.
  2. Buat Tindakan baru (Pemicu Pasca Masuk).
  3. Tambahkan kode untuk menyertakan peran:
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Terapkan Tindakan dan tambahkan ke proses login Anda.

Petunjuk / Saran

Untuk panduan terperinci tentang mengonfigurasi klaim JWT dengan Okta, lihat Menerapkan Klaim JWT Tingkat Lanjut dengan SDK Okta.

Langkah 5: Uji konfigurasi

  1. Mulai penyusun API Data:

    dab start

  2. Dapatkan token dari penyedia identitas Anda. Gunakan SDK penyedia Anda atau alat seperti Postman.

  3. Periksa token di jwt.io untuk memverifikasi:

    • Klaim aud cocok dengan audiens yang Dikonfigurasi
    • Klaim iss cocok dengan pengeluar sertifikat yang dikonfigurasi
    • Klaim roles berisi nilai yang diharapkan

  4. Panggil API:

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

  5. 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: admin"

Detail validasi JWT

Penyusun API Data memvalidasi aspek-aspek JWT ini:

Periksa Description
Tanda tangan Divalidasi menggunakan kunci tanda tangan yang ditemukan melalui otoritas yang telah dikonfigurasi jwt.issuer (metadata OpenID Connect / JWKS)
Penerbit Konfigurasi harus sama persis dengan jwt.issuer.
Audiens Harus persis sesuai dengan konfigurasi jwt.audience
Kedaluwarsa Token tidak boleh kedaluwarsa (exp klaim)
Tidak Sebelumnya Token harus valid, jika ada klaim (nbf)

Troubleshooting

Gejala Kemungkinan penyebab Solusi
401 Unauthorized Ketidakcocokan pengeluar sertifikat Periksa kecocokan iss klaim dengan tepat (termasuk garis miring di akhir)
401 Unauthorized Ketidakcocokan audiens Periksa apakah klaim aud sesuai dengan nilai yang telah anda konfigurasi.
401 Unauthorized Token kedaluwarsa Memperoleh token baru
401 Unauthorized Metadata tidak tersedia Pastikan DAB dapat menjangkau <issuer>/.well-known/openid-configuration
403 Forbidden Peran tidak ada dalam token Menambahkan peran ke konfigurasi IdP Anda
403 Forbidden Klaim atas peran yang hilang Mengonfigurasi IdP Anda untuk menyertakan roles klaim
403 Forbidden Nama klaim salah DAB menggunakan roles jenis klaim (tetap, tidak dapat dikonfigurasi)

Penting

DAB saat ini menggunakan klaim jenis roles untuk semua verifikasi peran. Nilai ini dikodekan secara permanen dan tidak dapat diubah menjadi groups, permissions, atau nama klaim lainnya. Konfigurasikan penyedia identitas Anda untuk mengeluarkan peran dalam klaim bernama roles.

Format penerbit umum

Provider Format pengeluar sertifikat
Okta https://<domain>.okta.com atau https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (perhatikan garis miring di akhir)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Contoh konfigurasi lengkap

Konfigurasi Okta

{
  "$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": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Konfigurasi Auth0

{
  "$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": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Konten terkait

  • Last updated on