Microsoft Entra hitelesítés mssql-python-nal

Microsoft Entra ID identitásalapú hitelesítést biztosít Azure SQL Database, Azure SQL Managed Instance és SQL database számára a Microsoft Fabric-ben az mssql-python driveren keresztül. A Microsoft Entra hitelesítés az alábbi lehetőségeket kínálja SQL hitelesítésen keresztül:

Centralizált identitásmenedzsment a Microsoft Entra ID-n keresztül.
Token-alapú hitelesítés, amely megszünteti a jelszó szükségességét.
Feltételes hozzáférési szabályzatok támogatása.
Kezelt identitások Azure-ban hosztolt alkalmazásokhoz.

Az mssql-python illezőgép hét Microsoft Entra hitelesítési módot támogat, mindezt a Authentication kapcsolati karakterlánc kulcsszó konfigurálja.

Hitelesítési módok

Állítsd be a Authentication kapcsolati karakterlánc kulcsszavaját az alábbi értékek egyikére:

Hitelesítési érték	Leírás
`ActiveDirectoryDefault`	Használ `DefaultAzureCredential`, amely automatikusan több metódust is próbál.
`ActiveDirectoryInteractive`	Böngészőalapú interaktív bejelentkezés.
`ActiveDirectoryDeviceCode`	Kód megadása itt: https://microsoft.com/devicelogin.
`ActiveDirectoryPassword`	Felhasználónév és jelszó Microsoft Entra ID-vel. Elavult.
`ActiveDirectoryMSI`	Menedzselt identitás (rendszerhez vagy felhasználó által hozzárendelt).
`ActiveDirectoryServicePrincipal`	Szolgáltatásnév ügyfél-azonosítóval és titkos kulccsal.
`ActiveDirectoryIntegrated`	Microsoft Entra ID-val integrált Windows (Kerberos).

Megjegyzés:

A ActiveDirectoryDefault, ActiveDirectoryInteractive, és ActiveDirectoryDeviceCode módusokhoz szükség van a azure-identity csomagra. Telepítse a(z) pip install azure-identity használatával.

DefaultAzureCredential

A ActiveDirectoryDefault üzemmód az Azure Identity SDK DefaultAzureCredential elemét használja, amely a következő hitelesítési módszereket próbálja meg ebben a sorrendben:

Környezeti változók.
Munkaterhelés-identitás a Kuberneteshez.
Felügyelt identitás.
Azure CLI hitelesítő adatai.
Azure PowerShell hitelesítő adatok.
Az Azure Developer CLI hitelesítő adatai.
Interaktív böngésző, ha engedélyezve.

Példa: Alapértelmezett hitelesítés

A következő példa a(z) ActiveDirectoryDefault-hoz csatlakozik, amely a DefaultAzureCredential láncot használja egy érvényes hitelesítő adat automatikus megkeresésére:

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()}")

Ezt a módot használd helyi fejlesztéshez, mert automatikusan felveszi az Azure CLI hitelesítő adatokat. Gyártáshoz használj egy speciális hitelesítési módot (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal), helyette. DefaultAzureCredential minden első kapcsolaton több hitelesítésszolgáltatón keresztül vezet végig, ami olyan késleltetést ad, amire a termelési terhelésekhez nincs szükség.

Interaktív hitelesítés

Interaktív alkalmazásokhoz böngészőalapú hitelesítést használjunk. A felhasználónak rendelkeznie kell egy, a(z) CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER használatával létrehozott adatbázis-fiókkal. A teljes előfeltételekért lásd: Konfigurálja a Microsoft Entra hitelesítést.

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

Windows rendszeren ez a mód az ODBC-illesztőprogram natív interaktív folyamatát használja. Más platformokon az Azure Identity SDK böngészőalapú hitelesítését használja.

Eszközkód-hitelesítés

Használj eszközkód hitelesítést böngésző nélküli környezetekben, például SSH ülésekben vagy konténerekben. A felhasználónak rendelkeznie kell egy, a(z) CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER használatával létrehozott adatbázis-fiókkal. Az előfeltételekért lásd: Konfiguráld Microsoft Entra hitelesítést.

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.

Kövesd a promptot, hogy autentikálj egy böngészőben egy másik eszközön.

Szolgáltatási főazonosító hitelesítése

Használj szolgáltatási hitelesítést olyan automatizált alkalmazásokhoz, amelyekhez nem szükséges felhasználói interakció:

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;"
)

Szolgáltatási főszereplő létrehozása

Regisztrálj egy alkalmazást a Microsoft Entra ID-ben.
Titkos ügyfélkódok létrehozása.
Biztosíts hozzáférést a szolgáltatási főnököknek az adatbázisodhoz:

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

Jótanács

Ha CREATE USER 33131 hibával (duplikált megjelenítő név) meghibásodik, használja WITH OBJECT_ID a szolgáltatásfő objektumazonosítóját az Azure portál Enterprise alkalmazások oldalán (nem az App regisztrációs oldalon) megadni:

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

További információ: Microsoft Entra-bejelentkezések és nem egyedi megjelenített névvel rendelkező felhasználók.

Felügyelt identitás

Használj menedzselt identitáshitelesítést Azure-ban hosztolt alkalmazásokhoz, mint például az App Service, Azure Functions és VM-ek:

Rendszer által hozzárendelt felügyelt identitás

Csatlakozz közvetlenül az Azure erőforráshoz rendelt identitással:

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

Felhasználó által hozzárendelt felügyelt identitás

A mezőben megadjuk egy felhasználó által kirendelt UID menedzselt identitás kliensazonosítóját:

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

Adatbázis-hozzáférés konfigurálása

Engedélyezd a menedzselt identitáshoz hozzáférést az adatbázisodban. A szerveren konfigurálni kell egy Microsoft Entra admint, mielőtt külső felhasználókat létrehozhatnál. Az Azure erőforrás menedzselt identitásának engedélyezéséhez lásd: Menedzselt identitások az Azure erőforrásokhoz.

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

Jelszóazonosítás (elavult)

Important

Az ActiveDirectoryPassword hitelesítési lehetőség (Microsoft Entra ID jelszóhitelesítés) elavult a Microsoft SQL-illesztőprogramokban. Ez a magas kockázatú hitelesítési folyamat nem kompatibilis a kötelező Microsoft Entra többtényezős hitelesítéssel (MFA), és előfordulhat, hogy nem működik olyan bérlőkben, ahol az MFA kényszerítve van. Tervezze meg a migrálást egy másik Microsoft Entra hitelesítési módszerre.

A Microsoft Entra ID jelszóhitelesítése a OAuth 2.0 Resource Owner Password Credentials (ROPC) engedélyezési folyamaton alapul, amely lehetővé teszi, hogy egy alkalmazás a felhasználó jelszavának közvetlen kezelésével jelentkeztesse be a felhasználót.

Microsoft azt javasolja, hogy ne használja a ROPC-folyamatot, mert nem kompatibilis az MFA-val. A legtöbb forgatókönyvben biztonságosabb alternatívák érhetők el és ajánlottak. Ez a folyamat nagy fokú bizalmat igényel az alkalmazásban, és olyan kockázatokat hordoz, amelyek más folyamatokban nem jelennek meg. Ezt a folyamatot csak akkor használja, ha a biztonságosabb folyamatok nem életképesek. A Microsoft távolodik ettől a magas kockázatú hitelesítési folyamattól, hogy megvédje a felhasználókat a rosszindulatú támadásoktól. További információ: Kötelező többtényezős hitelesítés tervezése az Azure-ban.

Ha egy felhasználó jelen van a bejelentkezéskor, használja az ActiveDirectoryInteractive vagy az ActiveDirectoryIntegrated hitelesítést, hogy a bejelentkezett felhasználó és a feltételes hozzáférési szabályzat naplózási útvonal attribútumai érvényesek legyenek.

Felügyelet nélküli szolgáltatásközi forgatókönyvek esetén kövesse a Microsoft Entra szolgáltatásfiókra vonatkozó útmutatást:

Ha az alkalmazás Azure infrastruktúrán fut, használja az ActiveDirectoryMSI -t (vagy egyes illesztőprogramokban az ActiveDirectoryManagedIdentitást). A felügyelt identitások kiküszöbölik a titkos kódok és tanúsítványok karbantartásának és elforgatásának többletterhelését.
Ha a felügyelt identitás nem érhető el (például az alkalmazás Azure kívül fut), használja az ActiveDirectoryServicePrincipal parancsot. Ahol az illesztőprogram támogatja, az ügyféltanúsítványt előnyben részesítse egy titkos ügyfélkóddal szemben. Tanúsítvány esetén a titkos kulcs az ügyfélen marad, és csak egy aláírt állítás lesz elküldve Microsoft Entra az ügyfél hitelesítéséhez. Ha a kulcs hardverben (például TPM-ben vagy HSM-ben) van tárolva, vagy nem portolhatóként van megjelölve, akkor nem másolható sztringként, ahogyan az ügyféltitkok is.
Ne használjon Microsoft Entra felhasználói fiókot szolgáltatásfiókként.

Használj jelszóazonosítást, ha felhasználónévre és jelszóra van szükséged Microsoft Entra fióknál. A felhasználónak olyan adatbázis-fiókkal kell rendelkeznie, amelyet a következőképpen CREATE USER [user@domain.com] FROM EXTERNAL PROVIDERhoztak létre:

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

Windows integrált hitelesítés

Használd a Windows integrált hitelesítést a Kerberos tartományhoz csatlakoztatott Windows környezetekhez. Ebben a módban az helyi Active Directory-t össze kell kapcsolni Microsoft Entra ID-vel és egy Microsoft Entra adminnal a szerveren:

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

Ez a mód a jelenlegi Windows felhasználó Kerberos hitelesítő adatait használja. Linuxon és macOS-en manuálisan kell konfigurálnia a Kerberost (krb5.conf, valamint egy érvényes keytab vagy jegy használatával). Lásd a Active Directory-hitelesítés SQL Serverhez Linux rendszeren című témakört a kliensoldali Kerberos beállításához.

Hitelesítőadat-objektumok token_providerrel

Továbbítsd egy hitelesítési objektumot közvetlenül a token_provider paraméterrel. A driver akkor hívja az get_token() objektum metódusát, amikor tokenre van szüksége, így nem csomagolod a tokent egy kapcsolati attribútumba.

Bármely olyan objektum, amelynek metódusa get_token(scope) egy attribútummal rendelkező objektumot .token ad vissza, kielégíti a szerződést. Az azure-identity csomag minden hitelesítő adata alkalmas, beleértve a következőket: DefaultAzureCredential, AzureCliCredential, ManagedIdentityCredential és 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(),
)

Az illesztőprogram a https://database.windows.net/.default hatókört kéri. Ez a paraméter csak az Azure kereskedelmi felhő hatótávját támogatja. Szuverén felhők esetén használd az Access token hitelesítést , és kérd a felhő által előírt hatókört.

A tömeges másolási műveletek minden művelethez új tokent szereznek a szolgáltatótól, mert saját kapcsolatot nyitnak meg.

Saját objektumot is beadhatsz, ami hasznos, ha a token máshonnan érkezik, mint azure-identity, például egy notebook környezetben, amely saját token segítőt fed fel:

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())

Az illesztőprogram egy TokenProvider protokolltípust exportál a statikus típusellenőrzéshez:

from mssql_python import TokenProvider

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

Ez a token_provider paraméter az egyetlen token forrás egy olyan kapcsolathoz, amely ezt használja. Az illesztőprogram a következők valamelyikével való együttes használat esetén a(z) InterfaceError hibát váltja ki:

A Authentication kulcsszó a kapcsolati karakterlánc-ben.
Egy token át lett adva a(z) SQL_COPT_SS_ACCESS_TOKEN elemen keresztül a(z) attrs_before használatával.

Egy objektum átadása metódus get_token() nélkül szintén felemeli InterfaceError-t .

Ha a kapcsolati sztring tartalmazza a(z) UID vagy PWD elemet, az illesztőprogram figyelmen kívül hagyja őket, és kiad egy UserWarning elemet, amely megnevezi a figyelmen kívül hagyott kulcsszavakat. Távolítsd el őket a kapcsolati karakterlánc-ből, hogy elnémítsd a figyelmeztetést.

Megjegyzés:

A hitelesítő objektummal hitelesített kapcsolatok identitásonként kapcsolatcsoportokba vannak rendezve. További információkért lásd a Kapcsolatcsoportosítás című részt.

Hozzáférési jogkivonat-hitelesítés

Például külső tokeneket szerezhetsz meg, egy megosztott token cache-en vagy egy szuverén felhővégponton keresztül. Ilyen esetekben a SQL_COPT_SS_ACCESS_TOKENattrs_before paraméterrel közvetlenül továbbítsuk a tokent. Ez a megközelítés megkerüli a meghajtó beépített token beszerzési folyamatát.

Használja inkább az előző szakaszban ismertetett token_provider paramétert, ha a hitelesítő adatai a(z) azure-identity-ből származnak. Kezeli a token kódolást helyetted, és frissíti a tokeneket a pooled kapcsolatokhoz.

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

A(z) SQL_COPT_SS_ACCESS_TOKEN használatakor a kapcsolati karakterlánc nem tartalmazhatja a következőket: UID, PWD, Authentication vagy Trusted_Connection. A token maga kezeli a hitelesítést.

Hitelesítési módszer kiválasztása

Scenario	Ajánlott mód
Fejlesztő gép	`ActiveDirectoryDefault`(Azure CLI-t használ)
Azure App Service / Functions	`ActiveDirectoryMSI` (gyorsabban, mint az alapértelmezett)
Azure Kubernetes Service	`ActiveDirectoryDefault` (munkaterhelés azonosítása)
Helyszíni automatizált szkriptek	`ActiveDirectoryServicePrincipal`
Interaktív asztali alkalmazás	`ActiveDirectoryInteractive`
SSH/konténer böngésző nélkül	`ActiveDirectoryDeviceCode`

Troubleshoot

Ellenőrizd, hogy a felhasználó vagy a kezelt személyazonosság létezik-e az adatbázisban:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

AADSTS700016: Az alkalmazás nem található

A szolgáltatási alap vagy alkalmazás azonosítója hibás. Ellenőrizd az ügyfélazonosítót, és hogy az alkalmazás regisztrálva van-e a Microsoft Entra bérlődben.

A Managed Identity-végpont nem érhető el

Ellenőrizd, hogy a menedzselt identitás engedélyezve van-e az Azure erőforráson.
A felhasználó által hozzárendelt azonosítás esetén ellenőrizzük, hogy az ügyfélazonosító helyes-e.
Ellenőrizd, hogy az erőforrásnak van hálózati hozzáférése az identitásvégponthoz.

Token beszerzési időkorlát

ActiveDirectoryDefault a(z) DefaultAzureCredential elemet használja, amely egymás után végigpróbálja a hitelesítőadat-szolgáltatók láncát, amíg az egyik sikerrel nem jár. A láncon való végighaladás másodpercekkel növeli a késleltetést az első csatlakozásnál, különösen akkor, ha a láncban korábban szereplő szolgáltatók (például a környezeti változók vagy a feladatidentitás) sikertelenek, mielőtt eljutna ahhoz, amelyik működik. Éles környezetben a lánc kihagyásához közvetlenül adja meg a hitelesítési típust:

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-09-03