App Service kimlik doğrulamasını yapılandırma (EasyAuth)

Azure App Service, istekler uygulamanıza ulaşmadan önce kullanıcı oturum açma işlemlerini işleyen yerleşik kimlik doğrulaması ("EasyAuth" olarak adlandırılır) sağlar. Veri API'sinin oluşturucusu, App Service'in ekleyen kimlik bilgilerini okuyarak belirteçleri doğrudan yönetmeden kimlik doğrulamasını etkinleştirebilir.

Önemli

Sağlayıcı, AppService EasyAuth tarafından iletilen kimlik üst bilgilerine güvenir. İstemcilerin EasyAuth'ı atlayıp Veri API'sini oluşturucuya doğrudan ulaşamadığından emin olun.

Kimlik doğrulama akışı

Azure App Service'in arkasında kimlik doğrulaması etkinken Veri API oluşturucu çalıştığında, App Service OAuth akışını işler ve kimlik bilgilerini HTTP üst bilgileri aracılığıyla aktarır.

EasyAuth'un kimlik üst bilgilerini nasıl ekleyişini gösteren App Service kimlik doğrulama akışının çizimi.

Phase	Ne olur?
Kullanıcı kimlik doğrulaması	App Service kimliği doğrulanmamış istekleri durdurur ve kimlik sağlayıcısına yönlendirir
Kimlik ekleme	Kimlik doğrulamasından sonra App Service `X-MS-CLIENT-PRINCIPAL` başlığını ekler
DAB işleme	Veri API oluşturucusu Base64,JSON üst bilgisinin kodunu çözer ve diziden `ClaimsPrincipal` bir `claims` oluşturur
Authorization	DAB, `ClaimsPrincipal.IsInRole()` kullanarak `X-MS-API-ROLE` üst bilgisini doğrular ve ardından izinleri ve ilkeleri değerlendirir.

Önkoşullar

Azure aboneliği
Azure App Service veya Azure İşlevleri (App Service altyapısında)
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	`AppService`
Kimlik üst bilgisi	`X-MS-CLIENT-PRINCIPAL` (Base64 ile kodlanmış JSON)
Rol seçimi başlığı	`X-MS-API-ROLE`
Özel talepleri destekler	Yes
Yerel test	Evet (manüel olarak ayarlanan başlıklar)

1. Adım: App Service kimlik doğrulamasını etkinleştirme

Azure App Service'te kimlik doğrulamayı yapılandırma:

Azure portalında App Service'inize gidin.
Ayarlar>Kimlik Doğrulama'yı seçin.
Kimlik sağlayıcısı ekle'yi seçin.
Microsoft'u (veya desteklenen başka bir sağlayıcıyı) seçin.
Ayarları yapılandırın:
- Uygulama kayıt türü: Yeni oluşturma veya mevcut olanı seçme
- Desteklenen hesap türleri: Senaryonuza göre seçin
- Erişimi kısıtla: Kimlik doğrulaması gerektir
Add (Ekle) seçeneğini belirleyin.

Tip

App Service kimlik doğrulaması Microsoft, Google, Facebook, Twitter ve OpenID Connect gibi birden çok kimlik sağlayıcısıyla çalışır.

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

Kimlik doğrulama sağlayıcısını olarak AppServiceayarlayın:

dab configure \
  --runtime.host.authentication.provider AppService

dab configure ^
  --runtime.host.authentication.provider AppService

Sonuçta elde edilen yapılandırma

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

Uyarı

EntraID / AzureAD veya Custom sağlayıcılarından farklı olarak, AppService veya jwt.audience ayarlarını gerektirmezjwt.issuer. App Service, kimlik bilgilerini DAB'ye geçirmeden önce belirteci doğrular.

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

Roller için izinleri tanımlayın. Data API Builder, ClaimsPrincipal.IsInRole() üst bilgiden ayrıştırılan talepleri denetleyen X-MS-CLIENT-PRINCIPAL aracılığıyla rolleri değerlendirir. claims dizisine uygun rol talep türüyle rol beyanlarını dahil edin.

Örnek yapılandırma

Bash
Komut İstemi

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

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

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

REM Allow editors to create and update
dab update Book ^
  --permissions "editor:create,read,update"

Sonuçta elde edilen yapılandırma

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

4. Adım: X-MS-CLIENT-PRINCIPAL ile yerel olarak test edin

App Service kimlik doğrulamasını yerel olarak, "header"X-MS-CLIENT-PRINCIPAL'ı elle sağlayarak test edebilirsiniz. Bu yaklaşım, EasyAuth'un uygulamanıza ilettiğinin simülasyonunu oluşturur ve Azure'a dağıtmadan rol ve talep temelli davranışı test etmenizi sağlar.

İstemci sorumlusu oluşturma

Başlık X-MS-CLIENT-PRINCIPAL Base64 ile kodlanmış bir JSON nesnesi içerir. Veri API'sinin oluşturucusu aşağıdaki özellikleri ayrıştırıyor:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Ana öğeyi kodla

JSON'yi Base64 olarak kodlayın. Herhangi bir aracı kullanabilirsiniz:

PowerShell:

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Bash:

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Başlıkla istek gönder

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

X-MS-CLIENT-PRINCIPAL yapısı

Veri API oluşturucusu, istemci sorumlusundan aşağıdaki özellikleri ayrıştırıyor:

Mülkiyet	Türü	Description
`auth_typ`	String	Kimlik doğrulama türü (örneğin, `aad`). Kimliğin doğrulanmış kabul edilmesi için gereklidir.
`name_typ`	String	(İsteğe bağlı) Kullanıcının adı için kullanılan talep türü
`role_typ`	String	(İsteğe bağlı) Roller için kullanılan talep türü (varsayılan olarak `roles`)
`claims`	object[]	`typ` ve `val` özelliklerine sahip talep dizisi. Roller buraya talep olarak eklenmelidir.

Önemli

Roller, eşlemeleri kontrol eden claims dizisini inceleyen ClaimsPrincipal.IsInRole() aracılığıyla değerlendirilir. Her rolü ayrı bir talep girdisi olarak ekleyin (örneğin, { "typ": "roles", "val": "editor" }).

Veritabanı ilkelerinde hak taleplerini kullanma

AppService sağlayıcısıyla, talepleri veritabanı ilkelerinde kullanabilirsiniz. Bu, kullanıcı kimliğine göre satır düzeyi güvenlik sağlar.

Örnek: Kullanıcı nesne kimliğine göre filtreleme

Bu örnekte, Microsoft Entra ID'nin belirteçlere dahil ettiği oid(nesne tanımlayıcısı) talebi kullanılır:

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Tip

Microsoft Entra Id'den alınan yaygın talep türleri arasında oid (nesne kimliği), email, nameve preferred_usernamebulunur. Kimlik sağlayıcınızdan tam talep türü dizesini kullanın.

Kullanılabilir talep referansları

Talep referansları, claims dizisindeki tam talep türü dizesini kullanır:

Talep referansı	Description
`@claims.<claim-type>`	Dizideki `claims` ve `typ` özelliği ile eşleşen herhangi bir talep

Örneğin, ana unsurunuz { "typ": "email", "val": "alice@contoso.com" } içeriyorsa, politikanızda @claims.email kullanın. Talep türü tam olarak eşleşmelidir.

Anonim istekler

App Service kimliği doğrulanmamış isteklere izin verdiğinde veya X-MS-CLIENT-PRINCIPAL üst bilgisi olmadan yerel olarak test edildiğinde, Veri API oluşturucusunun kimlik doğrulama ara yazılımı üst bilgiyi X-MS-API-ROLE olarak otomatik olarak ayarlaranonymous. ardından istekler şu rol kullanılarak anonymous değerlendirilir:

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Bu işlemin çalışması için, varlığınızın anonymous rolüne izinleri olmalıdır.

{
  "permissions": [
    {
      "role": "anonymous",
      "actions": ["read"]
    }
  ]
}

Sorun giderme

Semptom	Olası nedeni	Çözüm
`401 Unauthorized` (veya oturum açmaya yeniden yönlendirin)	EasyAuth isteği DAB'ye ulaşmadan önce engelledi	EasyAuth aracılığıyla oturum açın veya geçerli kimlik bilgileri gönderin; App Service Kimlik Doğrulaması ayarlarını doğrulama
`403 Forbidden`	Rol izinlerde değil	Rolü varlık izinlerine ekleyin
`403 Forbidden`	`X-MS-API-ROLE` kullanıcı rollerinde değil	Üst bilgi değerinin sorumlunun `claims` dizisindeki rol talebiyle eşleştiğinden emin olun
Talepler mevcut değil	İlk öğede eksik `claims` dizi	JSON'a `X-MS-CLIENT-PRINCIPAL` talep ekleme
Rol tanınmadı	`claims` dizisinde yer almayan roller	Doğru `role_typ` ile rol taleplerini ekleyin (örneğin, `{ "typ": "roles", "val": "editor" }`)
Yerel test başarısız oluyor	Üst bilgi Base64 ile kodlanmış değil	Göndermeden önce JSON kodunu düzgün şekilde kodlama

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": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-23

Aracılığıyla paylaş

App Service kimlik doğrulamasını yapılandırma (EasyAuth)

Kimlik doğrulama akışı

Önkoşullar

Hızlı referans

1. Adım: App Service kimlik doğrulamasını etkinleştirme

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

Örnek yapılandırma

Sonuçta elde edilen yapılandırma

4. Adım: X-MS-CLIENT-PRINCIPAL ile yerel olarak test edin

İstemci sorumlusu oluşturma

Ana öğeyi kodla

Başlıkla istek gönder

X-MS-CLIENT-PRINCIPAL yapısı

Veritabanı ilkelerinde hak taleplerini kullanma

Örnek: Kullanıcı nesne kimliğine göre filtreleme

Kullanılabilir talep referansları

Anonim istekler

Sorun giderme

Yapılandırmayı tamamlama örneği

İlgili içerik

Geri Bildirim

Ek kaynaklar