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:

  1. Környezeti változók.
  2. Munkaterhelés-identitás a Kuberneteshez.
  3. Felügyelt identitás.
  4. Azure CLI hitelesítő adatai.
  5. Azure PowerShell hitelesítő adatok.
  6. Az Azure Developer CLI hitelesítő adatai.
  7. 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 adatbázisfiókkal, amelyet a(z) CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER használatával hoztak létre. 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

  1. Regisztrálj egy alkalmazást a Microsoft Entra ID-ben.
  2. Titkos ügyfélkódok létrehozása.
  3. 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: Az Active Directory-hitelesítés használata SQL Serverrel Linux rendszeren az ügyféloldali Kerberos beállításához.

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

Például külső tokeneket szerezhetsz meg, egyedi token szolgáltatón vagy megosztott token cache-en 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.

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

"Bejelentkezés sikertelen az 'NT AUTHORITY\ANONYMOUS LOGON' felhasználó számára"

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

Kapcsolódó tartalom

  • Last updated on