mssql-python ile Microsoft Entra kimlik doğrulaması

Microsoft Entra ID, Microsoft Fabric'te Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve SQL database için mssql-python sürücüsü aracılığıyla kimlik tabanlı kimlik doğrulama sağlar. Microsoft Entra doğrulaması, SQL kimlik doğrulaması üzerinden şu özellikleri sunar:

  • Microsoft Entra ID üzerinden merkezi kimlik yönetimi.
  • Şifre ihtiyacını ortadan kaldıran token tabanlı kimlik doğrulama.
  • Koşullu erişim politikaları için destek.
  • Azure’da barındırılan uygulamalar için yönetilen kimlikler.

mssql-python sürücüsü, yedi Microsoft Entra kimlik doğrulama modunu destekler; bunların tümü Authentication bağlantı dizesi anahtar sözcüğüyle yapılandırılır.

Kimlik doğrulama modları

bağlantı dizesi'inizdeki anahtar kelimeyi Authentication aşağıdaki değerlerden birine ayarlayın:

Kimlik doğrulama değeri Açıklama
ActiveDirectoryDefault Kullanır DefaultAzureCredential, bu da otomatik olarak birden fazla yöntem dener.
ActiveDirectoryInteractive Tarayıcı tabanlı etkileşimli giriş.
ActiveDirectoryDeviceCode Kod girişi: https://microsoft.com/devicelogin.
ActiveDirectoryPassword Microsoft Entra ID ile kullanıcı adı ve şifre. Kaldırıl -mış.
ActiveDirectoryMSI Yönetilen kimlik (sistem tarafından atanmış veya kullanıcı tarafından atanan).
ActiveDirectoryServicePrincipal İstemci kimliği ve gizli anahtarı olan hizmet sorumlusu.
ActiveDirectoryIntegrated Windows, Microsoft Entra ID (Kerberos) ile entegre edilmiştir.

Note

ActiveDirectoryDefault, ActiveDirectoryInteractive, ve ActiveDirectoryDeviceCode modları paketi azure-identity gerektirir. pip install azure-identity ile yükleyin.

DefaultAzureCredential

ActiveDirectoryDefault modu, Azure Identity SDK'sındaki DefaultAzureCredential öğesini kullanır; bu öğe aşağıdaki kimlik doğrulama yöntemlerini sırayla dener:

  1. Ortam değişkenleri.
  2. Kubernetes için iş yükü kimliği.
  3. Yönetilen kimlik.
  4. Azure CLI kimlik bilgileri.
  5. Azure PowerShell kimlik bilgileri.
  6. Azure Developer CLI kimlik bilgileri.
  7. Eğer açıksa, etkileşimli tarayıcı.

Örnek: Varsayılan kimlik doğrulama

Aşağıdaki örnek, geçerli kimlik bilgilerini otomatik olarak bulmak için DefaultAzureCredential zincirini kullanan ActiveDirectoryDefault ile bağlantı kurar:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

cursor = conn.cursor()
cursor.execute("SELECT USER_NAME()")
print(f"Connected as: {cursor.fetchval()}")

Bu modu yerel geliştirme için kullanın çünkü Azure CLI kimlik bilgilerini otomatik olarak alır. Üretim için, bunun yerine belirli bir kimlik doğrulama modu (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) kullanın. DefaultAzureCredential Her ilk bağlantıda birden fazla kimlik doğrulama sağlayıcısından geçer, bu da üretim iş yüklerinin ihtiyaç duymadığı gecikmeyi artırır.

Etkileşimli kimlik doğrulaması

Etkileşimli uygulamalar için tarayıcı tabanlı kimlik doğrulama kullanın. Kullanıcının CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER ile oluşturulmuş bir veritabanı hesabına sahip olması gerekir. Tam ön koşullar için bkz. Microsoft Entra doğrulamasını Yapılandırma.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryInteractive;"
    "Encrypt=yes;"
)

Windows'ta bu mod, ODBC sürücüsünün yerel etkileşimli akışına devretmektedir. Diğer platformlarda ise Azure Identity SDK'nın tarayıcı tabanlı kimlik doğrulamasını kullanır.

Cihaz kodu kimlik doğrulaması

Tarayıcı olmayan ortamlar için, örneğin SSH oturumları veya konteynerler için cihaz kodu kimlik doğrulaması kullanın. Kullanıcının, CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER ile oluşturulmuş bir veritabanı hesabına sahip olması gerekir. Ön koşullar için bkz. Microsoft Entra doğrulamasını Yapılandırma.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Output: To sign in, use a web browser to open https://microsoft.com/devicelogin
# and enter the code XXXXXXX to authenticate.

Başka bir cihazda tarayıcıda kimlik doğrulama için bu komutu takip edin.

Hizmet sorumlusu kimlik doğrulaması

Kullanıcı etkileşimi gerektirmeyen otomatik uygulamalar için hizmet ana doğrulaması kullanın:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"       # Application (client) ID
    "PWD=<client-secret>;"   # Client secret
    "Encrypt=yes;"
)

Hizmet sorumlusu oluşturma

  1. Microsoft Entra ID'de bir uygulama kaydedin.
  2. İstemci sırrını oluşturun.
  3. Hizmet yöneticisine veritabanınıza erişim izni verin:
-- In Azure SQL
CREATE USER [app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [app-name];
ALTER ROLE db_datawriter ADD MEMBER [app-name];

Tip

CREATE USER, 33131 hatasıyla (yinelenen görünen ad) başarısız olursa, Azure portalındaki Enterprise applications sayfasından (Uygulama kayıtları sayfası değil) hizmet sorumlusunun Nesne Kimliğini belirtmek için WITH OBJECT_ID kullanın:

CREATE USER [app-name] FROM EXTERNAL PROVIDER
    WITH OBJECT_ID = '<enterprise-app-object-id>';

Ayrıntılar için bkz. Microsoft Entra oturum açma işlemleri ve benzersiz olmayan görünen adlara sahip kullanıcılar.

İdare edilen kimlik

App Service, Azure İşlevleri ve VM'ler gibi Azure barındırılan uygulamalar için yönetilen kimlik doğrulaması kullanın:

Sistem tarafından atanan yönetilen kimlik

Doğrudan Azure kaynağına atanan kimlik kullanılarak bağlanın:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes;"
)

Kullanıcı tarafından atanan yönetilen kimlik

Kullanıcı tarafından atanan yönetilen kimliğin istemci kimliğini UID alanında belirtin:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "UID=<managed-identity-client-id>;"
    "Encrypt=yes;"
)

Veritabanı erişimini yapılandırma

Veritabanınızda yönetilen kimlik erişimi verin. Dış kullanıcı oluşturabilmeniz için Microsoft Entra yöneticisinin sunucuda yapılandırılması gerekir. Azure kaynağınızda yönetilen kimlik etkinleştirmek için Azure kaynakları için Yönetilen kimlikler bölümüne bakınız.

-- Replace 'my-app-service' with your Azure resource name
CREATE USER [my-app-service] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-service];
ALTER ROLE db_datawriter ADD MEMBER [my-app-service];

Şifre doğrulama (kullanımdan kaldırılmıştır)

Important

ActiveDirectoryPassword kimlik doğrulama seçeneği (parola kimlik doğrulaması Microsoft Entra ID) Microsoft SQL sürücülerinde kullanım dışıdır. Bu yüksek riskli kimlik doğrulama akışı zorunlu Microsoft Entra çok faktörlü kimlik doğrulaması (MFA) ile uyumsuzdur ve MFA'nın zorlandığı kiracılarda çalışmayabilir. Farklı bir Microsoft Entra kimlik doğrulama yöntemine geçmeyi planlayın.

Microsoft Entra ID parola kimlik doğrulaması, OAuth 2.0 Kaynak Sahibi Parola Kimlik Bilgileri (ROPC) iznini temel alır ve bu da bir uygulamanın parolasını doğrudan işleyerek kullanıcıda oturum açmasına olanak tanır.

Microsoft, MFA ile uyumsuz olduğundan ROPC akışını kullanmamanızı önerir. Çoğu senaryoda daha güvenli alternatifler kullanılabilir ve önerilir. Bu akış, uygulamaya yüksek düzeyde güven gerektirir ve diğer akışlarda mevcut olmayan riskleri taşır. Bu akışı yalnızca daha güvenli akışlar uygun olmadığında kullanın. Microsoft, kullanıcıları kötü amaçlı saldırılardan korumak için bu yüksek riskli kimlik doğrulama akışından uzaklaşıyor. Daha fazla bilgi için bkz. Azure için zorunlu çok faktörlü kimlik doğrulamasını planlama.

Oturum açma sırasında bir kullanıcı mevcutsa, denetim izinin oturum açan kullanıcıya atfedilmesi ve Koşullu Erişim ilkelerinin uygulanması için ActiveDirectoryInteractive veya ActiveDirectoryIntegrated kimlik doğrulamasını kullanın.

Katılımsız hizmetten hizmete senaryoları için Microsoft Entra hizmet hesabı kılavuzunu izleyin:

  • Uygulamanız Azure altyapıda çalışıyorsa ActiveDirectoryMSI (veya bazı sürücülerde ActiveDirectoryManagedIdentity) kullanın. Yönetilen kimlikler, gizli anahtarların ve sertifikaların yönetimi ile yenilenmesinden kaynaklanan ek yükü ortadan kaldırır.
  • Yönetilen kimlik kullanılamıyorsa (örneğin, uygulama Azure dışında çalışır), ActiveDirectoryServicePrincipal kullanın. Sürücü destekliyorsa, istemci parolası yerine istemci sertifikasını tercih edin. Sertifikayla, özel anahtar istemcide kalır ve istemcinin kimliğini doğrulamak için Microsoft Entra yalnızca imzalı bir onay gönderilir. Anahtar donanımda (TPM veya HSM gibi) depolanıyorsa ya da dışarı aktarılamaz olarak işaretlenmişse, istemci gizli anahtarında olduğu gibi dize olarak dışarı kopyalanamaz.
  • hizmet hesabı olarak Microsoft Entra kullanıcı hesabı kullanmayın.

Microsoft Entra hesabında kullanıcı adı ve şifreye ihtiyacınız olduğunda şifre doğrulama kullanın. Kullanıcının aşağıdaki veritabanı hesabına sahip olması gerekir CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryPassword;"
    "UID=<login@domain.com>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Windows Entegre kimlik doğrulama

Kerberos ile alan bağına bağlı Windows ortamları için Windows Entegre kimlik doğrulaması kullanın. Bu mod, şirket içi Active Directory'nizin Microsoft Entra ID ve sunucuda yapılandırılmış bir Microsoft Entra yöneticisiyle birleştirilmesini gerektirir:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryIntegrated;"
    "Encrypt=yes;"
)

Bu mod, mevcut Windows kullanıcısının Kerberos kimlik bilgilerini kullanır. Linux ve macOS'ta Kerberos'u manuel olarak yapılandırmanız gerekir (krb5.conf ve geçerli bir keytab veya ticket). İstemci tarafında Kerberos kurulumu için Linux üzerinde SQL Server ile Active Directory kimlik doğrulamasını kullanma konusuna bakın.

Erişim belirteci kimlik doğrulaması

Örneğin, özel token sağlayıcısı veya paylaşılan token önbelleği aracılığıyla tokenları dışarıdan edinebilirsiniz. Bu durumlarda, belirteci doğrudan iletmek için attrs_before parametresiyle birlikte SQL_COPT_SS_ACCESS_TOKEN kullanın. Bu yaklaşım, sürücünün yerleşik token edinme akışını atlar.

import mssql_python
from azure.identity import DefaultAzureCredential
import struct

def get_token():
    credential = DefaultAzureCredential(
        exclude_interactive_browser_credential=False
    )
    token_bytes = credential.get_token(
        "https://database.windows.net/.default"
    ).token.encode("utf-16le")
    token_struct = struct.pack(
        f'<I{len(token_bytes)}s', len(token_bytes), token_bytes
    )
    return token_struct

SQL_COPT_SS_ACCESS_TOKEN = 1256

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;",
    attrs_before={SQL_COPT_SS_ACCESS_TOKEN: get_token()}
)

Important

SQL_COPT_SS_ACCESS_TOKEN kullanılırken, bağlantı dizesi UID, PWD, Authentication veya Trusted_Connection içermemelidir. Token'ın kendisi kimlik doğrulamayı gerçekleştirir.

Kimlik doğrulaması modu seçme

Scenario Önerilen mod
Geliştirme bilgisayarı ActiveDirectoryDefault(Azure CLI kullanır)
Azure App Service / Functions ActiveDirectoryMSI (Default'tan daha hızlı)
Azure Kubernetes Service ActiveDirectoryDefault (iş yükü kimliği)
Şirket içi otomatik betikler ActiveDirectoryServicePrincipal
Etkileşimli masaüstü uygulaması ActiveDirectoryInteractive
Tarayıcısız SSH/konteyner ActiveDirectoryDeviceCode

Troubleshoot

"'NT AUTHORITY\ANONYMOUS LOGON' kullanıcısı için oturum başarısız"

Kullanıcı veya yönetilen kimliğin veritabanında var olup olmadığını doğrulayın:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Başvuru bulunamadı"

Hizmet prensibi veya uygulama kimliği yanlıştır. İstemci kimliğini ve uygulamanın Microsoft Entra kiracınızda kayıtlı olduğunu doğrulayın.

"Yönetilen Kimlik uç noktasına ulaşılamıyor"

  • Azure kaynağında yönetilen kimliğin etkin olduğunu doğrulayın.
  • Kullanıcı tarafından atanan kimlik için, istemci kimliğinin doğru olduğunu doğrulayın.
  • Kaynağın kimlik uç noktasına ağ erişimi olup olmadığını kontrol edin.

Token edinme zaman aşımı

ActiveDirectoryDefault, DefaultAzureCredential kullanır; bu da kimlik bilgisi sağlayıcıları zincirini, bunlardan biri başarılı olana kadar sırayla dener. Bu zincir boyunca ilerleme süreci, özellikle zincirdeki önceki sağlayıcılar (ortam değişkenleri, iş yükü kimliği) işe yarayan sağlayıcıya ulaşmadan önce başarısız olduğunda, ilk bağlantıda birkaç saniyelik gecikmeye neden olur. Üretimde, kimlik bilgisi zincirini atlamak için kimlik bilgisi türünü doğrudan belirtin:

# Slow: DefaultAzureCredential tries multiple providers
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryDefault")

# Fast: Skip directly to managed identity
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryMSI")

İlgili içerik

  • Last updated on