Mengonfigurasi autentikasi JWT kustom (Okta, Auth0)

Pembuat API Data mendukung penyedia identitas pihak ketiga melalui Penyedia autentikasi kustom menggunakan validasi JSON Web Token (JWT). 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:

Diagram memperlihatkan alur autentikasi JWT kustom dengan idP pihak ketiga.

Fase 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 Penerbit 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 menghasilkan peran dalam klaim yang berbeda (seperti groups atau permissions), konfigurasikan penyedia tersebut agar juga menghasilkan klaim roles. Pengguna Auth0 harus meninjau konflik namespace yang diketahui sebelum melanjutkan.

Langkah 2: Mengonfigurasi penyusun API Data

Atur penyedia autentikasi ke Custom dan konfigurasikan pengaturan JWT:

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.

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

Auth0 mengharuskan klaim kustom menggunakan nama dengan namespace yang tahan terhadap tabrakan (misalnya, https://example.com/roles). Klaim tanpa namespace yang berkonflik dengan nama yang dicadangkan dikecualikan dari token tanpa pemberitahuan. Untuk informasi selengkapnya, lihat Membuat klaim kustom dalam dokumentasi Auth0.

Data API builder mengharapkan nama klaim yang tepat roles, bukan varian bernamespace. Apakah Auth0 menerima klaim tanpa namespace roles bergantung pada konfigurasi tenant Anda.

  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);
  }
};

  4. Terapkan Tindakan dan tambahkan ke proses login Anda.

  5. Verifikasi token akses yang didekodekan pada jwt.io dan konfirmasikan roles klaim ada.

Warning

Auth0 dapat menghapus klaim tanpa namespace roles tanpa pemberitahuan, tergantung pada pengaturan tenant Anda. Jika klaim tidak ada dalam token, periksa Pengaturan>Tingkat Lanjut di Dashboard Auth0 untuk penerapan namespace. Penyewa yang memerlukan klaim namespace saat ini tidak kompatibel dengan otorisasi berbasis peran pembuat API Data untuk peran kustom. Peran bawaan authenticated dan anonymous masih berfungsi karena tidak bergantung pada klaim roles.

Petunjuk / Saran

Untuk panduan terperinci tentang mengonfigurasi klaim JWT dengan Okta, lihat Menyesuaikan token yang dikembalikan dari 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 Deskripsi
Tanda tangan Divalidasi menggunakan kunci penandatangan yang diperoleh dari otoritas yang dikonfigurasi jwt.issuer (metadata OpenID Connect atau JSON Web Key Set (JWKS))
Penerbit Konfigurasi harus sama persis dengan jwt.issuer.
Audiens Konfigurasi harus sama persis dengan 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 Tidak ada roles klaim yang ditemukan Mengonfigurasi IdP Anda untuk menyertakan roles klaim
403 Forbidden Nama klaim salah DAB menggunakan roles jenis klaim (tetap, tidak dapat dikonfigurasi)
403 Forbidden Klaim kustom Auth0 dihilangkan secara diam-diam Auth0 dapat menghapus klaim kustom yang tidak menggunakan namespace. Verifikasi bahwa klaim roles ada dalam token yang telah didekodekan di jwt.io. Lihat Auth0: Menambahkan peran menggunakan Action

Penting

Jenis roles klaim dikodekan secara permanen untuk semua pemeriksaan peran dan tidak dapat diubah. Konfigurasikan penyedia identitas Anda untuk mengirimkan klaim dengan nama yang persis roles. Pengguna Auth0 harus meninjau konflik namespacing.

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