Ověřování Microsoft Entra pomocí mssql-python

Microsoft Entra ID poskytuje autentizaci založenou na identitě pro Azure SQL Database, Azure SQL Managed Instance a SQL databázi v Microsoft Fabric prostřednictvím ovladače mssql-python. Autentizace Microsoft Entra nabízí tyto možnosti přes SQL autentizaci:

Centralizovaná správa identity prostřednictvím Microsoft Entra ID.
Autentizace založená na tokenech, která eliminuje potřebu hesel.
Podpora politik podmíněného přístupu.
Spravované identity pro aplikace hostované v Azure.

Ovladač mssql-python podporuje sedm autentizačních režimů Microsoft Entra, všechny konfigurované pomocí Authentication klíčového slova připojovací řetězec.

Režimy ověřování

Nastavte klíčové slovo Authentication ve svém připojovací řetězec na jednu z následujících hodnot:

Autentizační hodnota	Popis
`ActiveDirectoryDefault`	Používá `DefaultAzureCredential`, která automaticky zkouší více metod.
`ActiveDirectoryInteractive`	Interaktivní přihlášení v prohlížeči.
`ActiveDirectoryDeviceCode`	Zadejte kód na https://microsoft.com/devicelogin.
`ActiveDirectoryPassword`	Uživatelské jméno a heslo s Microsoft Entra ID. Zavrhovaný.
`ActiveDirectoryMSI`	Spravovaná identita (systémově nebo uživatelsky přiřazená).
`ActiveDirectoryServicePrincipal`	Hlavní pracovník služby s identifikací klienta a tajemstvím.
`ActiveDirectoryIntegrated`	Windows integrovaný s Microsoft Entra ID (Kerberos).

Note

Módy ActiveDirectoryDefault, ActiveDirectoryInteractive, a ActiveDirectoryDeviceCode vyžadují azure-identity balíček. Nainstalujte ho pomocí pip install azure-identity.

DefaultAzureCredential

Režim ActiveDirectoryDefault používá DefaultAzureCredential ze sady Azure Identity SDK, která se pokouší použít tyto metody ověřování v tomto pořadí:

Proměnné prostředí.
Identita úlohy pro Kubernetes.
Spravovaná identita
Azure CLI přihlašovací údaje.
Přihlašovací údaje Azure PowerShell.
Azure Developer CLI přihlašovací údaje.
Interaktivní prohlížeč, pokud je zapnutý.

Příklad: Výchozí autentizace

Následující příklad se připojí k ActiveDirectoryDefault a pomocí řetězce DefaultAzureCredential automaticky vyhledá platné přihlašovací údaje:

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

Tento režim použijte pro lokální vývoj, protože automaticky zachytí přihlašovací údaje Azure CLI. Pro produkci použijte místo toho specifický autentizační režim (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal). DefaultAzureCredential Při každém prvním připojení prochází více poskytovatelů přihlašovacích údajů, což přidává latenci, kterou produkční pracovní zátěže nepotřebují.

Interaktivní ověřování

Pro interaktivní aplikace používejte autentizaci založenou na prohlížeči. Uživatel musí mít databázový účet vytvořený s .CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER Pro úplné předpoklady viz Konfigurovat autentizaci Microsoft Entra.

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

Na Windows tento režim deleguje nativní interaktivní tok ovladače ODBC. Na jiných platformách využívá autentizaci v prohlížeči Azure Identity SDK.

Ověřování kódu zařízení

Používejte autentizaci kódem zařízení pro prostředí bez prohlížeče, například pro SSH relace nebo kontejnery. Uživatel musí mít databázový účet vytvořený s .CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER Pro předpoklady viz Konfigurovat autentizaci Microsoft Entra.

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.

Postupujte podle pokynu k ověření v prohlížeči na jiném zařízení.

Ověřování principálu služby

Používejte autentizaci principu služby pro automatizované aplikace, které nevyžadují interakci uživatele:

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

Vytvořte služebního principála

Zaregistrujte aplikaci v Microsoft Entra ID.
Vytvořte tajný kód klienta.
Udělte zástupci služby přístup do vaší databáze:

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

Pokud CREATE USER selže s chybou 33131 (duplicitní zobrazovaný název), použijte WITH OBJECT_ID k zadání ID objektu instančního objektu služby ze stránky Enterprise applications v portálu Azure (nikoli ze stránky Registrace aplikací):

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

Podrobnosti najdete v článku Přihlášení v Microsoft Entra a uživatelé s nejedinečnými zobrazovanými názvy.

Spravovaná identita

Používejte řízenou autentizaci identity pro aplikace hostované v Azure, jako jsou App Service, Azure Functions a VM:

Spravovaná identita přiřazená systémem

Připojte se pomocí identity přímo přiřazené Azure zdroji:

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

Spravovaná identita přiřazená uživatelem

Zadejte ID klienta uživatelem přiřazené spravované identity v poli:UID

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

Konfigurace přístupu k databázi

Udělte spravované identitě přístup do vaší databáze. Než můžete vytvořit externí uživatele, musí být na serveru nakonfigurován administrátor Microsoft Entra. Pro povolení spravované identity na vašem Azure zdroji viz Spravované identity pro Azure zdroje.

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

Autentizace heslem (zastaralá)

Important

Možnost ověřování ActiveDirectoryPassword (ověřování hesla Microsoft Entra ID) je v ovladačích MICROSOFT SQL zastaralá. Tento tok ověřování s vysokým rizikem není kompatibilní s povinným Microsoft Entra vícefaktorovým ověřováním (MFA) a nemusí fungovat v tenantech, ve kterých se vynucuje vícefaktorové ověřování. Naplánujte migraci na jinou metodu ověřování Microsoft Entra.

Ověřování heslem v Microsoft Entra ID je založeno na grantu OAuth 2.0 Resource Owner Password Credentials (ROPC), který umožňuje aplikaci přihlásit uživatele tím, že přímo pracuje s jeho heslem.

Microsoft doporučuje nepoužívat tok ROPC, protože není kompatibilní s vícefaktorovým ověřováním. Ve většině scénářů jsou k dispozici a doporučeny bezpečnější alternativy. Tento tok vyžaduje vysokou míru důvěryhodnosti v aplikaci a nese rizika, která nejsou přítomna v jiných tocích. Tento tok používejte pouze tehdy, pokud bezpečnější toky nejsou proveditelné. Microsoft odchází od tohoto vysoce rizikového toku ověřování, aby chránil uživatele před škodlivými útoky. Další informace najdete v tématu Plánování povinného vícefaktorového ověřování pro Azure.

Pokud je při přihlašování přítomen uživatel, použijte ověřování ActiveDirectoryInteractive nebo ActiveDirectoryIntegrated, aby byla auditní stopa přiřazena přihlášenému uživateli a aby se uplatnily zásady podmíněného přístupu.

V případě bezobslužných scénářů mezi službami postupujte podle pokynů k účtu služby Microsoft Entra:

Pokud vaše aplikace běží na Azure infrastruktuře, použijte ActiveDirectoryMSI (nebo ActiveDirectoryManagedIdentity v některých ovladačích). Spravované identity eliminují režii při údržbě a obměně tajných kódů a certifikátů.
Pokud spravovaná identita není dostupná (například aplikace běží mimo Azure), použijte ActiveDirectoryServicePrincipal. Pokud ho ovladač podporuje, upřednostňujte klientský certifikát před tajným klíčem klienta. S certifikátem zůstane privátní klíč v klientovi a do Microsoft Entra k ověření klienta se odešle jenom podepsaný kontrolní výraz. Pokud je klíč uložen v hardwaru (například v modulu TPM nebo HSM) nebo je označen jako neexportovatelný, nelze jej zkopírovat jako textový řetězec tak, jako to lze u tajného klíče klienta.
Nepoužívejte Microsoft Entra uživatelský účet jako účet služby.

Používejte ověření heslem, když potřebujete uživatelské jméno a heslo s účtem Microsoft Entra. Uživatel musí mít založený databázový účet s :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;"
)

Integrovaná autentizace Windows

Používejte Windows Integrated authentication pro doménově připojená prostředí Windows s Kerberosem. Tento režim vyžaduje, aby byla vaše místní služba Active Directory federovaná s Microsoft Entra ID a aby byl na serveru nakonfigurován správce Microsoft Entra:

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

Tento režim využívá Kerberos přihlašovací údaje aktuálního uživatele Windows. Na Linuxu a macOS musíte Kerberos konfigurovat ručně (krb5.conf a platný keytab nebo ticket). Viz Použití autentizace služba Active Directory s SQL Server on Linux pro nastavení Kerberosu na straně klienta.

Ověřování přístupového tokenu

Tokeny můžete získat externě, například prostřednictvím vlastního poskytovatele tokenů nebo sdílené tokenové cache. V těchto případech použijte SQL_COPT_SS_ACCESS_TOKEN s parametrem attrs_before k přímému předání tokenu. Tento přístup obchází vestavěný tok získávání tokenů ovladačem.

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

Při použití SQL_COPT_SS_ACCESS_TOKEN, připojovací řetězec nesmí obsahovat UID, PWD, Authentication, nebo Trusted_Connection. Token sám zajišťuje autentizaci.

Výběr režimu ověřování

Scenario	Doporučený režim
Vývojový stroj	`ActiveDirectoryDefault`(uses Azure CLI)
Azure App Service / Functions	`ActiveDirectoryMSI` (rychlejší než Default)
Azure Kubernetes Service	`ActiveDirectoryDefault` (identita pracovní zátěže)
Automatizované skripty na místě	`ActiveDirectoryServicePrincipal`
Interaktivní desktopová aplikace	`ActiveDirectoryInteractive`
SSH/kontejner bez prohlížeče	`ActiveDirectoryDeviceCode`

Troubleshoot

Ověřte, že uživatel nebo spravovaná identita existuje v databázi:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Žádost nenalezena"

Instanční objekt služby nebo ID aplikace je nesprávné. Ověřte ID klienta a ověřte, že je aplikace registrovaná ve vašem Microsoft Entra tenantu.

Koncový bod spravované identity není dostupný

Ověřte, že spravovaná identita je povolena na Azure zdroji.
U uživatelem přiřazené identity ověřte, že je ID klienta správné.
Zkontrolujte, že zdroj má síťový přístup k endpointu identity.

Časový limit získávání tokenů

ActiveDirectoryDefault používá DefaultAzureCredential, která prochází řetězcem poskytovatelů přihlašovacích údajů v pořadí, dokud jeden neuspěje. Toto procházení řetězce přidává při prvním připojení několik sekund zpoždění, zejména když dřívější poskytovatelé v řetězci (proměnné prostředí, identita zátěže) selžou předtím, než se dojde k tomu, který funguje. V produkci zadejte typ přihlašovacích údajů přímo, abyste přeskočili řetězec:

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-22