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 ActiveDirectoryDefault zincirini kullanan DefaultAzureCredential 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 WITH OBJECT_ID sayfasından (Uygulama kayıtları sayfası değil) hizmet sorumlusunun Nesne Kimliğini belirtmek için 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ı Kerberos kurulumu için Linux üzerinde SQL Server için Active Directory doğrulamasına bakınız.

token_provider içeren kimlik bilgisi nesneleri

token_provider parametresiyle bir kimlik bilgisi nesnesini doğrudan geçirin. Sürücü, nesnenin get_token() belirtona ihtiyacı olduğunda metodunu çağırır, böylece tokenı kendiniz bir bağlantı özniteliğine paketlemiyorsunuz.

.token yöntemi, get_token(scope) özniteliğine sahip bir nesne döndüren herhangi bir nesne sözleşmeyi karşılar. Azure-identity paketindeki tüm kimlik bilgileri uygundur, bunlar arasında DefaultAzureCredential, AzureCliCredential, ManagedIdentityCredential, ve ClientSecretCredential.

import mssql_python
from azure.identity import DefaultAzureCredential

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Encrypt=yes",
    token_provider=DefaultAzureCredential(),
)

Sürücü https://database.windows.net/.default kapsamını talep ediyor. Bu parametre yalnızca Azure ticari bulut kapsamını destekler. Egemen bulutlar için, Access token doğrulama kullan ve bulutunuzun gerektirdiği kapsamı talep et.

Toplu kopyalama işlemleri, her işlem için sağlayıcıdan yeni bir token alır, çünkü kendi bağlantılarını açarlar.

Ayrıca kendi nesnenizi de sağlayabilirsiniz; bu, belirteç azure-identity dışında bir yerden geldiğinde faydalıdır; örneğin, kendi belirteç yardımcısını sunan bir notebook ortamında:

from types import SimpleNamespace

class NotebookTokenProvider:
    def get_token(self, scope):
        # Return any object with a .token attribute holding the raw JWT string.
        return SimpleNamespace(token=get_platform_token(scope))

conn = mssql_python.connect(connection_string, token_provider=NotebookTokenProvider())

Sürücü, statik tip kontrolü için bir TokenProvider protokol tipini dışa aktarır:

from mssql_python import TokenProvider

def open_connection(credential: TokenProvider):
    return mssql_python.connect(connection_string, token_provider=credential)

token_provider parametresi, bu parametreyi kullanan bir bağlantı için tek belirteç kaynağıdır. Sürücü, aşağıdakilerden biriyle birleştirirseniz InterfaceError oluşturur:

• Bağlantı dizesindeki Authentication anahtar kelime.

• Bir belirteç, SQL_COPT_SS_ACCESS_TOKEN ile attrs_before içinden geçirildi.

get_token() yöntemi olmayan bir nesneyi geçirmek de ayrıca InterfaceError hatasına neden olur.

Bağlantı dizesi PWD veya UID içeriyorsa, sürücü bunları yok sayar ve göz ardı edilen anahtar sözcükleri belirten bir UserWarning yayımlar. Uyarıyı susturmak için onları bağlantı dizesi'den çıkarın.

Note

Bir kimlik bilgisi nesnesi kullanılarak kimliği doğrulanan bağlantılar, kimlik başına havuzda toplanır. Daha fazla bilgi için Bağlantı havuzlaması bölümünü inceleyin.

Erişim belirteci kimlik doğrulaması

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

Kimlik bilgileriniz token_provider kaynağından geliyorsa, önceki bölümde açıklanan azure-identity parametresini tercih edin. Token kodlamasını sizin için yönetir ve havuzlu bağlantılar için tokenları yeniler.

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

• mssql-python için bağlantı dizileri
• Troubleshoot mssql-python
• Python uygulamasını Azure SQL Veritabanı ile parolasız bağlantılar kullanacak şekilde geçirme
• Azure SQL için Microsoft Entra kimlik doğrulaması