Özel JWT kimlik doğrulamasını yapılandırma (Okta, Auth0)

Veri API oluşturucusu, JSON Web Belirteci (JWT) doğrulamasını kullanarak Özel kimlik doğrulama sağlayıcısı aracılığıyla üçüncü taraf kimlik sağlayıcılarını destekler. Kuruluşunuz Okta, Auth0 veya başka bir OAuth 2.0/OpenID Connect uyumlu kimlik sağlayıcısı kullanıyorsa bu yaklaşımı kullanın.

Kimlik doğrulama akışı

Özel bir kimlik sağlayıcısıyla istemci uygulamanız kullanıcı kimlik doğrulamasını işler ve ardından erişim belirtecini Veri API'sinin oluşturucusna gönderir:

Üçüncü taraf kimlik sağlayıcısıyla özel JWT kimlik doğrulama akışını gösteren diyagram.

Phase	Ne olur?
Kullanıcı kimlik doğrulaması	Kullanıcı kimlik sağlayıcısı aracılığıyla oturum açar (Okta, Auth0 vb.)
Jeton edinimi	İstemci uygulaması IdP'den erişim belirteci alır
API çağrısı	İstemci, belirteci üst bilgi başlığındaki `Authorization` DAB'ye gönderir.
Doğrulama	DAB, JWT'yi (veren, hedef kitle, imza) doğrular
Authorization	DAB rolleri ayıklar ve izinleri değerlendirir

Önkoşullar

Kimlik sağlayıcınızla bir hesap (Okta, Auth0 vb.)
Kimlik sağlayıcınıza kayıtlı bir uygulama
Data API builder CLI yüklü (yükleme kılavuzu)
En az bir varlığa sahip mevcut dab-config.json

Hızlı referans

Setting	Değer
Provider	`Custom`
Doğrulama için gerekli	`iss`, `aud`, `exp`, geçerli imza
Yetkilendirme için gerekli	`roles` seçilen rolü içeren talep
Token üst bilgisi	`Authorization: Bearer <token>`
Rol talep türü	`roles` (düzeltildi, yapılandırılamaz)
Rol seçimi başlığı	`X-MS-API-ROLE`

1. Adım: Kimlik sağlayıcınızı yapılandırma

Tam adımlar sağlayıcınıza bağlıdır. İhtiyacınız olan temel değerler şunlardır:

Toplayacak değerler

Değer	Nerede bulunur?	Kullanım amacı
İssuer URL'si	Sağlayıcının belgeleri veya OAuth meta veri uç noktası	DAB `jwt.issuer` (JWT Yetkilisi olarak kullanılır)
Seyirci	Uygulamanızın istemci kimliği veya özel API tanımlayıcısı	DAB `jwt.audience`

Uyarı

DAB, JWT jwt.issuer olarak yapılandırılan öğesini kullanır. İmzalama anahtarları standart OpenID Connect meta verileri (genellikle <issuer>/.well-known/openid-configuration) aracılığıyla otomatik olarak bulunur.

Okta örneği

Okta Yönetim Konsolu'nda oturum açın.
Uygulamalar>Uygulamaları'na gidin.
Bir uygulama oluşturun veya seçin.
İstemci Kimliğini not edin (hedef kitle olarak kullanın).
Vereniniz genellikle https://<your-domain>.okta.com olur.

Auth0 örneği

Auth0 Panosu'nda oturum açın.
Uygulamalar>API'lerine gidin.
API oluşturun veya seçin.
Tanımlayıcıyı not edin (hedef kitle olarak kullanın).
Vereniniz şeklindedir https://<your-tenant>.auth0.com/.

Önemli

Veri API oluşturucusu, rol tabanlı yetkilendirme için sabit talep türü roles kullanır. Bu değer yapılandırılamaz. Kimlik sağlayıcınız rolleri farklı bir claim’de (groups veya permissions gibi) yayımlıyorsa, ayrıca bir roles claim’i de yayımlayacak şekilde yapılandırın. Auth0 kullanıcılarının devam etmeden önce bilinen ad alanı çakışmasını incelemesi gerekir.

2. Adım: Veri API'si oluşturucusunu yapılandırma

Kimlik doğrulama sağlayıcısını Custom olarak ayarlayın ve JWT ayarlarını yapılandırın:

# 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>/"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider Custom

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

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

Sonuçta elde edilen yapılandırma

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

3. Adım: Varlık izinlerini yapılandırma

Kimlik sağlayıcınızın atadığına ilişkin roller için izinleri tanımlayın:

CLI

Bash
Komut İstemi

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

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

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

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

Sonuçta elde edilen yapılandırma

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

4. Adım: Kimlik sağlayıcınızdaki rolleri yapılandırma

DAB, bir roles talepteki rolleri önemser. Kimlik sağlayıcınızı bu talebi içerecek şekilde yapılandırın.

Okta: Grupları rol olarak ekleme

Okta Yönetim Konsolu'nda Güvenlik>API'sine gidin.
Yetkilendirme sunucunuzu seçin.
Talepler sekmesine gidin.
Talep ekleyin:
- İsim: roles
- Belirteç türüne ekle: Erişim Belirteci
- Değer türü: Gruplar
- Filtre: Eklenecek grupları seçin

Auth0: Eylem ile rol ekleme

Auth0, çakışmaya dayanıklı ad alanı adları (örneğin, https://example.com/roles) kullanmak için özel talepler gerektirir. Ayrılmış adlarla çakışan, ad alanına sahip olmayan talepler belirtece sessizce dahil edilmez. Daha fazla bilgi için Auth0 belgelerinde Özel talep oluşturma bölümüne bakın.

Veri API'sinin oluşturucusu ad alanı değişkenini değil tam talep adını rolesbekler. Auth0'un ad alanı roles olmayan bir talep kabul edip etmediği kiracı yapılandırmanıza bağlıdır.

Auth0 Pano'da Eylemler>Kitaplık bölümüne gidin.
Yeni bir Eylem oluşturun (Oturum Açma Sonrası tetikleyicisi).

Rolleri eklemek için kod ekleyin:

exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};

Eylemi dağıtın ve Oturum Açma akışınıza ekleyin.
Kodu çözülmüş erişim belirtecini doğrulayın ve jwt.io üzerinde roles claim’inin mevcut olduğunu onaylayın.

Warning

Auth0, tenant ayarlarınıza bağlı olarak ad alanı olmayan roles claim’ini sessizce yok sayabilir. Belirteçte talep eksikse, ad alanı zorlaması için Auth0 Panosu'nda Gelişmiş Ayarlar'ı> işaretleyin. Ad alanlı talepler gerektiren kiracılar, şu anda Data API builder'ın özel roller için rol tabanlı yetkilendirmesiyle uyumlu değildir. Yerleşik authenticated ve anonymous rolleri, bir roles beyanına bağlı olmadıkları için çalışmaya devam eder.

Tavsiye

Okta ile JWT taleplerini yapılandırma hakkında ayrıntılı yönergeler için bkz. Okta'dan döndürülen belirteçleri özelleştirme.

5. Adım: Yapılandırmayı test edin

Veri API'si oluşturucusunu başlatma:
```
dab start
```
Kimlik sağlayıcınızdan bir belirteç alın. Sağlayıcınızın SDK'sını veya Postman gibi bir aracı kullanın.
Doğrulamak için jwt.io belirteci inceleyin:
- İddia aud yapılandırılmış hedef kitlenizle uyuşuyor.
- Talep, iss yapılandırılan vereninizle eşleşir
- Talep roles beklenen değerleri içerir

API'yi çağırın:

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

Özel rol kullanmak için X-MS-API-ROLE üst bilgisini ekleyin.

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

JWT doğrulama ayrıntıları

Veri API'sinin oluşturucusu, JWT'nin şu yönlerini doğrular:

Kontrol	Açıklama
İmza	Yapılandırılmış `jwt.issuer` yetkilendirme aracılığıyla bulunan imzalama anahtarları kullanılarak doğrulama yapıldı (OpenID Connect meta verileri veya JSON Web Anahtarı Kümesi (JWKS)).
İhraç Eden	Yapılandırmayla tam olarak eşleşmelidir `jwt.issuer`
Seyirci	Yapılandırmayla tam olarak eşleşmelidir `jwt.audience`
Bitiş tarihi	Jeton süresi dolmamalıdır (`exp` talep)
Daha Önce Değil	Belirteç, eğer mevcutsa (`nbf` iddiası), geçerli olmalıdır.

Sorun giderme

Belirti	Olası nedeni	Çözüm
`401 Unauthorized`	İhraççı uyuşmazlığı	İddianın tam olarak eşleştiğini kontrol edin (sondaki eğik çizgi dahil)
`401 Unauthorized`	hedef kitle uyuşmazlığı	Talebin `aud` yapılandırılan değerinizle eşleşir olup olmadığını denetleyin
`401 Unauthorized`	Belirtecin süresi doldu	Yeni bir belirteç edinin
`401 Unauthorized`	Meta veriler kullanılamıyor	DAB'in ulaşabildiğinden emin olun `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	Rol belirteçte değil	Rolü IdP yapılandırmanıza ekleme
`403 Forbidden`	`roles` talep bulunamadı	IdP'nizi bir `roles` talebi içerecek şekilde yapılandırın
`403 Forbidden`	Yanlış talep adı	DAB talep türünü `roles` kullanır (düzeltildi, yapılandırılamaz)
`403 Forbidden`	Auth0 özel talebi sessizce bırakıldı	Auth0 ad alanı olmayan özel talepleri bırakabilir. `roles` claim’inin, jwt.io adresindeki kodu çözülmüş belirteçte bulunduğunu doğrulayın. Bkz . Auth0: Eylemle rol ekleme

Önemli

Talep türü roles tüm rol denetimleri için sabit kodlanmıştır ve değiştirilemez. Kimlik sağlayıcınızı tam olarak roles adlı bir talep gönderecek şekilde yapılandırın. Auth0 kullanıcıları ad alanı çakışmasını gözden geçirmelidir.

Yaygın veren biçimleri

Provider	Veren biçimi
Okta	`https://<domain>.okta.com` veya `https://<domain>.okta.com/oauth2/default`
Kimlik Doğrulaması0	`https://<tenant>.auth0.com/` (sondaki eğik çizgiyi not edin)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
Keycloak	`https://<host>/realms/<realm>`

Yapılandırmayı tamamlama örneği

Okta yapılandırması

{
  "$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"]
        }
      ]
    }
  }
}

Auth0 yapılandırması

{
  "$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": ["*"]
        }
      ]
    }
  }
}

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-14

Özel JWT kimlik doğrulamasını yapılandırma (Okta, Auth0)

Kimlik doğrulama akışı

Önkoşullar

Hızlı referans

1. Adım: Kimlik sağlayıcınızı yapılandırma

Toplayacak değerler

Okta örneği

Auth0 örneği

2. Adım: Veri API'si oluşturucusunu yapılandırma

CLI

Sonuçta elde edilen yapılandırma

3. Adım: Varlık izinlerini yapılandırma

CLI

Sonuçta elde edilen yapılandırma

4. Adım: Kimlik sağlayıcınızdaki rolleri yapılandırma

Okta: Grupları rol olarak ekleme

Auth0: Eylem ile rol ekleme

5. Adım: Yapılandırmayı test edin

JWT doğrulama ayrıntıları

Sorun giderme

Yaygın veren biçimleri

Yapılandırmayı tamamlama örneği

Okta yapılandırması

Auth0 yapılandırması

İlgili içerik

Geri Bildirim

Ek kaynaklar