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

Bu kılavuz, Veri API 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, JSON Web Belirteci (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ı rehberleri

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ışı

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

Phase Açıklama
Kullanıcı kimlik doğrulaması Kullanıcı, Microsoft Entra ID aracılığıyla istemci uygulamanız üzerinden 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, veritabanına varsayılan olarak çağıran kullanıcı olarak erişmek için On-Behalf-Of (OBO) belirteç değişimi gerçekleştirmez. Veritabanının gerçek arayan olarak kimlik doğrulaması yapmasını sağlamak için bkz. OBO kimlik doğrulamasını yapılandırma.

Ö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ı

Sağlayıcı olarak EntraID veya AzureAD kullanıyorsanız, DAB, Microsoft Entra tokenlarına özgü imzalama anahtarı verenin doğrulanmasını etkinleştirir. Bu doğrulama, 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.

  1. Microsoft Entra yönetim merkezinde oturum açın.

  2. Identity>Applications>App registrations adresine gidin.

  3. Yeni kayıtseçin.

  4. Bir Ad girin (örneğin, Data API Builder API).

  5. 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

  6. Yeniden Yönlendirme URI'sini boş bırakın (bu kayıt istemciye değil API'ye yöneliktir).

  7. Kaydıseçin.

  8. 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

  1. Uygulama kaydında API'yi kullanıma sunma bölümüne gidin.

  2. Uygulama Kimliği URI'si'nin yanındaki Ekle'yi seçin.

  3. Varsayılanıapi://<app-id> () kabul edin veya özel bir URI girin.

  4. Kaydetseçeneğini seçin.

Tavsiye

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.

Kapsam ekle

İstemci uygulamalarının (Azure CLI dahil) API'niz için temsilci erişim belirteçleri istemesi için bir kapsam gereklidir.

  1. Uygulama kaydında API'yi kullanıma sunma bölümüne gidin.

  2. Bu API tarafından tanımlananKapsamlar altında Kapsam ekleöğesini seçin.

  3. Giriş:

    • Kapsam adı: Endpoint.Access
    • Kimler onay verebilir?: Yöneticiler ve kullanıcılar
    • Yönetici onayı görünen adı: Execute requests against Data API builder
    • Yönetici onayı açıklaması: Allows client app to send requests to Data API builder endpoint.
    • Kullanıcı onayı görünen adı: Execute requests against Data API builder
    • Kullanıcı onayı açıklaması: Allows client app to send requests to Data API builder endpoint.
    • Durum: Etkin

  4. Kapsam ekle'yi seçin.

Uyarı

Tam kapsam değeri api://<app-id>/Endpoint.Access. İstemci uygulamaları belirteç isteğinde bulunurken bu değeri kullanır.

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

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

  1. Uygulama Rolleri'ne gidin.

  2. Uygulama rolü oluştur'u seçin.

  3. 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

  4. seçin, sonra daUygula'yı seçin.

  5. Daha fazla rol (örneğin, , writeradmin) için yineleyin.

Bildirim belirteci sürümünü ayarlama

Varsayılan olarak, uygulama kayıt bildirimi, accessTokenAcceptedVersion'ü null olarak ayarlayarak v1.0 belirteçleri üretir. V1 belirteçleri, DAB'de yapılandırılan v2.0 verenden farklı bir veren biçimi (https://sts.windows.net/<tenant-id>/) kullanır ve bu da belirteç doğrulamasının başarısız olmasına neden olur.

  1. Uygulama kaydında Bildirim'e gidin.

  2. accessTokenAcceptedVersion değerini bulun ve 2 olarak değiştirin.

  3. Kaydetseçeneğini seçin.

Önemli

Eğer accessTokenAcceptedVersion veya null veya 1 ise, belirteçteki iss talep, DAB'de tanımlanan v2.0 sağlayıcı URL'si ile eşleşmez ve tüm istekler 401 Unauthorized ile başarısız olur.

Uygulama rollerine kullanıcı atama

Uygulama rolleri oluşturmak, bu rolleri kullanıcılara otomatik olarak tanımlamaz. Kurumsal Uygulama aracılığıyla kullanıcı veya grup atamanız gerekir.

  1. Microsoft Entra yönetim merkezindeIdentity>Applications>Enterprise applications adresine gidin.

  2. Uygulamanızı arayın ve seçin (örneğin, Data API Builder API). Uygulamayı kaydettiğinizde otomatik olarak bir kurumsal uygulama oluşturuldu.

  3. Kullanıcılar ve gruplar'a gidin.

  4. Kullanıcı/grup ekle'yi seçin.

  5. Kullanıcılar'ın altında, atanacak kullanıcı hesabını seçin ve seç'i seçin.

  6. Rol seçin altında, atanacak rolü seçin (örneğin, Reader). Rolünüz görünmüyorsa, Microsoft Entra çoğaltma işleminin tamamlanmasını beklemek için birkaç dakika süre tanıyın.

  7. Atama'yı seçin.

  8. Atamak istediğiniz her rol için yineleyin.

Uyarı

Rol ataması olmadan, roles kullanıcının belirtecindeki talep boş olur ve X-MS-API-ROLE özel bir rolle kullanan istekler 403 Forbidden ile reddedilir.

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.

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"

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

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

Özel bir role erişim izni verme

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.

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ı 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;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

Azure CLI istemci uygulaması olarak yetkilendirme

Azure CLI, API için belirteçleri almadan önce onu yetkili istemci uygulaması olarak eklemeniz gerekir.

  1. Uygulama kaydında API'yi kullanıma sunma bölümüne gidin.

  2. Yetkili istemci uygulamaları'nın altında İstemci uygulaması ekle'yi seçin.

  3. Azure CLI istemci kimliğini girin: 00001111-aaaa-2222-bbbb-3333cccc4444.

  4. api://<app-id>/Endpoint.Access kapsamını seçin.

  5. Uygulama ekle'yi seçin.

Azure CLI ile token alma

Azure CLI oturum açın ve uygulama kaydınızın bulunduğu kiracıyı ayarlayın:

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

API'niz için kapsamlı bir belirteç isteyin.

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

Uyarı

AADSTS65001 onay hatası aldıysanız, önceki adımda Azure CLI istemci kimliğini (00001111-aaaa-2222-bbbb-3333cccc4444) yetkili bir istemci uygulaması olarak eklediğinizi doğrulayın.

Belirteci jwt.ms inceleyerek aud, iss, ve roles iddialarını doğrulayabilirsiniz.

DAB'ı başlatma ve istek gönderme

  1. Veri API'si oluşturucusunu başlatma:

    dab start

  2. API'yi belirteçle çağırın:

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

  3. Ö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: 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ır Hayır — Anonymous
Evet (geçerli) Hayır — Authenticated
Evet (geçerli) Evet Hayır Reddedildi (403 Yasak)
Evet (geçerli) Evet Evet Başlık değeri
Evet (geçersiz) — — Reddedildi (401 Yetkisiz)

Sorun giderme

Belirti Olası nedeni Çözüm
401 Unauthorized Jeton süresi dolmuş veya yanlış 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ının Entra'daki uygulama rolüne 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"]
        }
      ]
    }
  }
}

İlgili içerik

  • Last updated on