Microsoft Entra-authenticatie met mssql-python

Microsoft Entra ID biedt identiteitsgebaseerde authenticatie voor Azure SQL Database, Azure SQL Managed Instance en SQL-database in Microsoft Fabric via de mssql-python-driver. Microsoft Entra-authenticatie biedt deze mogelijkheden boven SQL-authenticatie:

• Gecentraliseerd identiteitsbeheer via Microsoft Entra ID.
• Tokengebaseerde authenticatie die de noodzaak van wachtwoorden overbodigt.
• Ondersteuning voor beleid voor voorwaardelijke toegang.
• Beheerde identiteiten voor Azure-gehoste applicaties.

De mssql-python-driver ondersteunt zeven Microsoft Entra-authenticatiemodi, allemaal geconfigureerd via het Authentication verbindingsreeks-sleutelwoord.

Verificatiemodi

Stel het Authentication trefwoord in je verbindingsreeks in op een van de volgende waarden:

DefaultAzureCredential

De ActiveDirectoryDefault modus gebruikt DefaultAzureCredential de Azure Identity SDK, die deze authenticatiemethoden in volgorde probeert:

1. Omgevingsvariabelen.
2. Workload-identiteit voor Kubernetes.
3. Beheerde identiteit.
4. Azure CLI-referenties.
5. Azure PowerShell-referenties.
6. Referenties voor Azure Developer CLI.
7. Interactieve browser, indien ingeschakeld.

Voorbeeld: Standaardauthenticatie

Het volgende voorbeeld verbindt met ActiveDirectoryDefault, dat de DefaultAzureCredential keten gebruikt om automatisch een geldig credential te vinden:

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

Gebruik deze modus voor lokale ontwikkeling omdat deze automatisch Azure CLI-inloggegevens oppikt. Voor productie gebruik je in plaats daarvan een specifieke authenticatiemodus (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal), in plaats daarvan. DefaultAzureCredential doorloopt bij elke eerste verbinding meerdere referentieproviders, wat extra latentie veroorzaakt die voor productie-workloads onnodig is.

Interactieve verificatie

Voor interactieve toepassingen gebruik browsergebaseerde authenticatie. De gebruiker moet een databaseaccount hebben aangemaakt met CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Voor volledige vereisten, zie Configureer Microsoft Entra-authenticatie.

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

In Windows maakt deze modus gebruik van het eigen interactieve proces van het ODBC-stuurprogramma. Op andere platforms gebruikt het de browsergebaseerde authenticatie van de Azure Identity SDK.

Verificatie van apparaatcode

Gebruik apparaatcode-authenticatie voor omgevingen zonder browser, zoals SSH-sessies of containers. De gebruiker moet een databaseaccount hebben aangemaakt met CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Voor de vereisten, zie Microsoft Entra-authenticatie configureren.

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.

Volg de prompt om te authenticeren in een browser op een ander apparaat.

Authenticatie van service principal

Gebruik service principal authenticatie voor geautomatiseerde applicaties die geen gebruikersinteractie vereisen:

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

Een service-principal maken

1. Registreer een applicatie in Microsoft Entra ID.
2. Een clientgeheim maken.
3. Verleen de dienstleider toegang tot uw database:

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

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

Beheerde identiteit

Gebruik beheerde identiteitsauthenticatie voor Azure-gehoste applicaties, zoals App Service, Azure Functions en VM's:

Door het systeem toegewezen beheerde identiteit

Verbind met de identiteit die direct aan de Azure-resource is toegewezen:

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

Door de gebruiker toegewezen beheerde identiteit

Specificeer de client-ID van een door de gebruiker toegewezen beheerde identiteit in het UID veld:

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

Database-toegang configureren

Verleen de beheerde identiteitstoegang in je database. Een Microsoft Entra-beheerder moet op de server zijn geconfigureerd voordat je externe gebruikers kunt aanmaken. Om beheerde identiteit op je Azure-resource in te schakelen, zie Managed Identities for Azure resources.

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

Wachtwoordauthenticatie (verouderd)

Microsoft Entra ID wachtwoordverificatie is gebaseerd op de OAuth 2.0 ROPC-toekenning (Resource Owner Password Credentials), waarmee een toepassing zich kan aanmelden bij de gebruiker door het wachtwoord rechtstreeks te verwerken.

Microsoft raadt u aan de ROPC-stroom niet te gebruiken omdat deze niet compatibel is met MFA. In de meeste scenario's zijn veiligere alternatieven beschikbaar en aanbevolen. Deze stroom vereist een hoge mate van vertrouwen in de toepassing en brengt risico's met zich mee die niet aanwezig zijn in andere stromen. Gebruik deze stroom alleen als veiligere stromen niet haalbaar zijn. Microsoft gaat weg van deze verificatiestroom met een hoog risico om gebruikers te beschermen tegen schadelijke aanvallen. Zie Planning voor verplichte meervoudige verificatie voor Azure voor meer informatie.

Wanneer een gebruiker aanwezig is bij het aanmelden, gebruikt u ActiveDirectoryInteractive- of ActiveDirectoryIntegrated-verificatie, zodat de kenmerken van het audittrailbeleid voor de aangemelde gebruiker en het beleid voor voorwaardelijke toegang van toepassing zijn.

Voor service-naar-servicescenario's zonder toezicht volgt u de richtlijnen voor het Microsoft Entra serviceaccount:

• Als uw toepassing wordt uitgevoerd op Azure infrastructuur, gebruikt u ActiveDirectoryMSI (of ActiveDirectoryManagedIdentity in sommige stuurprogramma's). Beheerde identiteiten elimineren de overhead van het onderhouden en roteren van geheimen en certificaten.
• Als beheerde identiteit niet beschikbaar is (de toepassing wordt bijvoorbeeld buiten Azure uitgevoerd), gebruikt u ActiveDirectoryServicePrincipal. Als het stuurprogramma dit ondersteunt, geef dan de voorkeur aan een clientcertificaat boven een clientgeheim. Met een certificaat blijft de persoonlijke sleutel op de client staan en wordt alleen een ondertekende assertie verzonden naar Microsoft Entra om de client te verifiëren. Als de sleutel is opgeslagen in hardware (zoals een TPM of HSM) of als niet-exporteerbaar is gemarkeerd, kan deze niet worden gekopieerd als een tekenreeks zoals een clientgeheim dat kan.
• Gebruik geen Microsoft Entra gebruikersaccount als een serviceaccount.

Gebruik wachtwoordauthenticatie wanneer je een gebruikersnaam en wachtwoord nodig hebt met een Microsoft Entra-account. De gebruiker moet een databaseaccount hebben aangemaakt met 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 geïntegreerde authenticatie

Gebruik Windows Integrated authenticatie voor domein-gekoppelde Windows-omgevingen met Kerberos. Deze modus vereist dat je on-premises Active Directory wordt gefedereerd met Microsoft Entra ID en een Microsoft Entra-beheerder die op de server is geconfigureerd:

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

Deze modus gebruikt de Kerberos-gegevens van de huidige Windows-gebruiker. Op Linux en macOS moet je Kerberos handmatig configureren (krb5.conf en een geldige keytab of ticket). Zie Gebruik Active Directory-authenticatie met SQL Server on Linux voor client-side Kerberos-configuratie.

Verificatie van toegangstokens

Je kunt tokens extern verkrijgen, bijvoorbeeld via een aangepaste tokenprovider of gedeelde tokencache. Gebruik in deze gevallen SQL_COPT_SS_ACCESS_TOKEN met de parameter attrs_before om de token rechtstreeks door te geven. Deze aanpak omzeilt de ingebouwde tokenacquisitiestroom van de bestuurder.

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

Een verificatiemodus kiezen

Troubleshoot

Aanmelden mislukt voor gebruiker 'NT AUTHORITY\ANONYMOUS LOGON'

Controleer of de gebruiker of beheerde identiteit in de database staat:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Applicatie niet gevonden"

De dienstprincipal of applicatie-ID is onjuist. Controleer de client-ID en dat de app geregistreerd is in je Microsoft Entra-tenant.

Eindpunt van Managed Identity niet bereikbaar

• Controleer of beheerde identiteit is ingeschakeld op de Azure-resource.
• Voor door de gebruiker toegewezen identiteit controleer je of de client-ID correct is.
• Controleer of de bron netwerktoegang heeft tot het identiteitseindpunt.

Time-out bij het verkrijgen van token

ActiveDirectoryDefault gebruikt DefaultAzureCredential, waarbij een keten van credentialproviders in volgorde wordt doorlopen totdat één slaagt. Het doorlopen van deze keten zorgt bij het maken van de eerste verbinding voor een vertraging van enkele seconden, vooral wanneer eerdere providers in de keten (omgevingsvariabelen, workloadidentiteit) mislukken voordat de provider wordt bereikt die wel werkt. In productie specificeer je direct het type credential om de keten over te slaan:

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

Verwante onderwerpen

• Verbindingsreeksen
• Troubleshooting
• Azure SQL-wachtwoordloze migratie
• Microsoft Entra-verificatie met Azure SQL