Microsoft Entra Id kimlik doğrulamayı yapılandırma

Bu kılavuz, Veri API'si oluşturucusu için Microsoft Entra Id (eski adıYla Azure Active Directory) kimlik doğrulamasını yapılandırma konusunda size yol gösterir. Sonunda, istemci uygulamanız Entra aracılığıyla kullanıcıların kimliğini doğrular, Veri API'si oluşturucusu için belirteçler alır ve DAB, Azure SQL'e bağlanmak için yönetilen kimliği kullanabilir.

Veri API'si oluşturucusu, JWT taşıyıcı doğrulamasını () veya platform tarafından sağlanan kimlik üst bilgilerini (EntraID/AzureAD/CustomAppService ) kullanarak gelen isteklerin kimliğini doğrular. Yerel geliştirme ve izin testi için sağlayıcıyı Simulator kullanın.

İstemcilerin JWT belirteçleri kullanarak Veri API oluşturucusuna nasıl kimlik doğrulaması yaptığını gösteren çizim.

Kimlik doğrulama sağlayıcısı kılavuzları

Kimlik sağlayıcınıza göre bir kılavuz seçin:

Provider	Guide
Microsoft Entra Kimliği	Bu makale
Okta, Auth0 veya diğer	Özel JWT kimlik doğrulamayı yapılandırma
Azure App Service	App Service kimlik doğrulamayı yapılandırma
Yerel test	Simülatör kimlik doğrulamayı yapılandırma

Kimlik doğrulama akışı

Aşağıdaki diyagramda, Veri API'si oluşturucusu ile Microsoft Entra Id kullanılırken kimlik doğrulama akışının tamamı gösterilmektedir:

Kullanıcı oturum açma, belirteç alma ve veritabanı erişimini gösteren Microsoft Entra Id kimlik doğrulama dizisinin çizimi.

Akışın üç ayrı aşaması vardır:

Phase	Description
Kullanıcı kimlik doğrulaması	Kullanıcı, Microsoft Entra Id aracılığıyla istemci uygulamanız aracılığıyla oturum açar
İstemci kimlik doğrulaması	İstemci uygulaması DAB kapsamlı bir belirteç alır ve Veri API oluşturucusunu çağırır
Veritabanı erişimi	Veri API oluşturucusu belirteci doğrular, ardından kendi kimliğini (yönetilen kimlik veya bağlantı dizesi kimlik bilgileri) kullanarak veritabanına bağlanır

Önemli

Veri API oluşturucusu, API kimlik doğrulaması için gelen kullanıcı belirtecini doğrular, ancak veritabanına kendi kimlik bilgilerini (yönetilen kimlik veya SQL kimlik doğrulaması) kullanarak bağlanır. DAB, çağıran kullanıcı olarak veritabanına erişmek için On-Behalf-Of (OBO) token değişimi gerçekleştirmez.

Önkoşullar

Microsoft Entra ID kiracısı ile Azure aboneliği
Data API builder CLI yüklü (yükleme kılavuzu)
En az bir varlığa sahip mevcut dab-config.json
(İsteğe bağlı) Yönetilen kimlik senaryoları için Azure SQL Veritabanı

Hızlı referans

Setting	Değer
Provider	`EntraID` (veya `AzureAD` uyumluluk için)
Doğrulama için gerekli	`aud`, `iss`, `exp`, geçerli imza
Yetkilendirme için gerekli	`roles` talep bildirimi (yalnızca özel roller kullanılıyorsa)
Veren biçimi	`https://login.microsoftonline.com/<tenant-id>/v2.0`
İzleyici biçimi	`api://<app-id>` veya özel Uygulama Kimliği URI'si
Varsayılan rol	`Authenticated`
Özel rol başlığı	`X-MS-API-ROLE`
Rol talep türü	`roles` (düzeltildi, yapılandırılamaz)

Uyarı

EntraID veya AzureAD sağlayıcı olarak kullanıldığında, DAB, Microsoft Entra jetonlarına özgü ek imzalama anahtarı sağlayıcı doğrulamasını etkinleştirir. Bu, genel Custom sağlayıcıya kıyasla daha güçlü güvenlik sağlar.

1. Adım: Bir uygulamayı Microsoft Entra Id'ye kaydetme

Veri API'sini oluşturucu API'nizi temsil eden bir uygulama kaydı oluşturun. İstemci uygulamaları, bu kayıtla eşleşen bir hedef kitleye sahip belirteçler istemektedir.

Microsoft Entra yönetim merkezinde oturum açın.
Kimlik>Uygulamaları>Uygulama kayıtları'na gidin.
Yeni kayıtseçin.
Bir Ad girin (örneğin, Data API Builder API).
Senaryonuz için uygun Desteklenen hesap türlerini seçin:
- Tek kiracı: Yalnızca kuruluşunuzdaki kullanıcılar
- Multitenant: Herhangi bir Microsoft Entra dizinindeki kullanıcılar
Yeniden Yönlendirme URI'sini boş bırakın (bu kayıt istemciye değil API'ye yöneliktir).
Kaydıseçin.

Uygulamanın Genel Bakış sayfasında şu değerleri kaydedin:

Değer	Nerede bulunur?	Kullanım amacı
Uygulama (istemci) kimliği	Genel bakış sayfası	İzleyici URI'sini oluşturma
Dizin (kiracı) ID'si	Genel bakış sayfası	Veren URL'sini oluşturma

Uygulama Kimliği URI'sini yapılandırma

Uygulama kaydında API'yi kullanıma sunma bölümüne gidin.
Uygulama Kimliği URI'si'nin yanındaki Ekle'yi seçin.
Varsayılanıapi://<app-id> () kabul edin veya özel bir URI girin.
Kaydetseçeneğini seçin.

Tip

Uygulama Kimliği URI'si, DAB yapılandırmanızdaki audience değerine dönüşür. Ortamlar arasında tutarlı bir biçim kullanın.

Uygulama rolleri ekleme (isteğe bağlı)

Anonymous ve Authenticated dışında özel roller kullanmak istiyorsanız:

Uygulama Rolleri'ne gidin.
Uygulama rolü oluştur'u seçin.
Giriş:
- Görünen ad: Reader
- İzin verilen üye türleri: Kullanıcılar/Gruplar veya Her İkisi
- Değer: reader (Bu değer belirtecin roles talepinde görünür)
- Açıklama: Read-only access to data
seçin, sonra daUygula'yı seçin.
Ek roller için yineleyin (örneğin, writer, admin).

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

DAB'yi, Entra kiracınız tarafından API hedef kitleniz için verilen belirteçleri doğrulayacak şekilde yapılandırın.

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

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

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

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

Sonuçta elde edilen yapılandırma

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

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

Her varlığa hangi rollerin erişebileceğini tanımlayın. İstekler belirteçten belirlenen role göre değerlendirilir.

Kimliği doğrulanmış kullanıcılara erişim izni verme

Bash
Komut İstemi

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

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

Özel bir role erişim izni verme

Bash
Komut İstemi

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

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

Sonuçta elde edilen yapılandırma

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

4. Adım: Veritabanı bağlantısını yapılandırma

Veri API oluşturucusu, kimliği doğrulanmış kullanıcıdan ayrı olarak kendi kimliğini kullanarak veritabanına bağlanır. Azure SQL ile üretim senaryoları için yönetilen kimliği kullanın.

Uyarı

Veritabanı bağlantısı, çağıran kullanıcının kimliğini değil DAB'nin hizmet kimliğini (yönetilen kimlik veya SQL kimlik bilgileri) kullanır. DAB, kullanıcı belirteçlerini veritabanına geçirmez.

Seçenek A: Yönetilen kimlik (Azure için önerilir)

Sistem tarafından atanan yönetilen kimlik

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

Kullanıcı atamalı yönetilen kimlik

{
  "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;"
  }
}

Seçenek B: SQL kimlik doğrulaması (geliştirme)

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

Önemli

Bağlantı dizelerini hiçbir zaman parolalarla kaynak denetimine işlemeyin. Ortam değişkenlerini veya Azure Key Vault'i kullanın.

C Seçeneği: `az login` ile yerel geliştirme

Azure SQL'de yerel geliştirme için Azure CLI kimlik bilgilerinizi kullanın:

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

DAB'yi başlatmadan önce oturum açın:

az login

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

Veri API'si oluşturucusunu başlatma:
```
dab start
```
API'niz için bir belirteç alın. Test için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) veya jwt.ms gibi bir aracı kullanın.

API'yi belirteçle ç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 bağlamını ekleyin:

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

Uyarı

İçinde X-MS-API-ROLE belirtilen rolün, belirtecin roles talepinde mevcut olması gerekir. Rol belirteçte değilse istek reddedilir.

Rol seçimi davranışı

Veri API'sinin oluşturucusu şu mantığı kullanarak isteğin rolünü belirler:

Token var mı?	X-MS-API-ROLE üst bilgisi?	Belirteçteki rol?	Result
Hayı	Hayı	—	`Anonymous`
Evet (geçerli)	Hayı	—	`Authenticated`
Evet (geçerli)	Yes	Hayı	Reddedildi (403 Yasak)
Evet (geçerli)	Yes	Yes	Başlık değeri
Evet (geçersiz)	—	—	Reddedildi (401 Yetkisiz)

Sorun giderme

Semptom	Olası nedeni	Çözüm
`401 Unauthorized`	Belirtecin süresi dolmuş veya hatalı biçimlendirilmiş	Yeni bir belirteç alın; belirteci jwt.ms üzerinde kontrol edin
`401 Unauthorized`	hedef kitle uyuşmazlığı	Doğrula `jwt.audience` , belirtecin `aud` iddiasıyla eşleştiğini
`401 Unauthorized`	İhraççı uyuşmazlığı	Doğrula ki `jwt.issuer`, belirtecin `iss` iddiasıyla tam olarak eşleşiyor.
`403 Forbidden`	Rol belirteçte değil	Kullanıcıya Entra'da uygulama rolünün atandığından emin olun
`403 Forbidden`	Bu rol için herhangi bir izin yok	Rolü varlığın `permissions` dizisine ekleme

Yapılandırmayı tamamlama örneği

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-23

Aracılığıyla paylaş

Microsoft Entra Id kimlik doğrulamayı yapılandırma

Kimlik doğrulama sağlayıcısı kılavuzları

Kimlik doğrulama akışı

Önkoşullar

Hızlı referans

1. Adım: Bir uygulamayı Microsoft Entra Id'ye kaydetme

Uygulama Kimliği URI'sini yapılandırma

Uygulama rolleri ekleme (isteğe bağlı)

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

Kimliği doğrulanmış kullanıcılara erişim izni verme

Özel bir role erişim izni verme

Sonuçta elde edilen yapılandırma

4. Adım: Veritabanı bağlantısını yapılandırma

Seçenek A: Yönetilen kimlik (Azure için önerilir)

Sistem tarafından atanan yönetilen kimlik

Kullanıcı atamalı yönetilen kimlik

Seçenek B: SQL kimlik doğrulaması (geliştirme)

C Seçeneği: az login ile yerel geliştirme

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

Rol seçimi davranışı

Sorun giderme

Yapılandırmayı tamamlama örneği

İlgili içerik

Geri Bildirim

Ek kaynaklar

C Seçeneği: `az login` ile yerel geliştirme