Verwenden von Microsoft Entra ID mit dem ODBC-Treiber

ODBC-Treiber herunterladen

Hinweis

Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.

Zweck

Der Microsoft ODBC Driver for SQL Server, Version 13.1 oder höher, ermöglicht ODBC-Anwendungen das Herstellen einer Verbindung mit einer Azure SQL-Datenbank oder Azure SQL Managed Instance anhand von Identitäten in Microsoft Entra ID. Die Authentifizierung kann mit einem Benutzernamen und Kennwort, einem Microsoft Entra-Zugriffstoken, einer von Microsoft Entra verwalteten Identität (17.3+) oder einer integrierten Windows-Authentifizierung in einer in eine Domäne eingebundenen Verbundumgebung (17.6+ unter Linux/macOS) erfolgen. Bei der ODBC-Treiberversion 13.1 erfolgt die Microsoft Entra-Authentifizierung mit Zugriffstoken nur über Windows. Die ODBC Driver-Version 17 und höhere Versionen unterstützen diese Authentifizierung auf allen Plattformen (Windows, Linux und macOS). Eine neue interaktive Microsoft Entra-Authentifizierungsmethode, die die Multi-Faktor-Authentifizierung unterstützt, wird in der ODBC-Treiberversion 17.1 für Windows eingeführt. In der ODBC-Treiberversion 17.3.1.1 kam eine neue Authentifizierungsmethode mit verwalteten Microsoft Entra-Identitäten sowohl für systemseitig als auch für benutzerseitig zugewiesene verwaltete Identitäten hinzu. Alle Möglichkeiten werden über neue Schlüsselwörter für DSN und Verbindungszeichenfolgen sowie von Verbindungsattribute erreicht.

Um die Microsoft Entra-Authentifizierung verwenden zu können, müssen Sie Ihre Azure SQL-Datenquelle konfigurieren. Weitere Informationen finden Sie unter Konfigurieren und Verwalten der Microsoft Entra-Authentifizierung mit Azure SQL.

Hinweis

Der ODBC-Treiber unter Linux und macOS vor Version 17.6 unterstützt nur die Microsoft Entra-Authentifizierung direkt gegen Microsoft Entra ID. Wenn Sie die Benutzernamen-/Kennwortauthentifizierung von Microsoft Entra über einen Linux- oder macOS-Client verwenden und die Microsoft Entra-Konfiguration die Authentifizierung des Client bei einem Microsoft Entra-Verbunddienstendpunkt erfordert, kann bei der Authentifizierung ein Fehler auftreten. Diese Einschränkung wurde von Version 17.6 an entfernt.

Neue und/oder geänderte Schlüsselwörter für DSN und Verbindungszeichenfolgen

Das Schlüsselwort Authentication kann beim Herstellen einer Verbindung mit einem DSN oder einer Verbindungszeichenfolge verwendet werden, um den Authentifizierungsmodus zu steuern. Der in der Verbindungszeichenfolge festgelegte Wert überschreibt den Wert im DSN, sofern angegeben. Der pre-attribute-Wert der Einstellung Authentication ist der Wert, der aus den Werten für Verbindungszeichenfolge und DSN berechnet wird.

Name	Werte	Standard	Beschreibung
Authentication	(nicht festgelegt), (leere Zeichenfolge), SqlPassword, ActiveDirectoryPassword, ActiveDirectoryIntegrated, ActiveDirectoryInteractive, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal	(nicht festgelegt)	Steuert den Authentifizierungsmodus. Wert BESCHREIBUNG (nicht festgelegt) Der Authentifizierungsmodus wird durch andere Schlüsselwörter bestimmt (vorhandene ältere Verbindungsoptionen). (leere Zeichenfolge) (Nur Verbindungszeichenfolge.) Überschreibt und löscht einen im DSN festgelegten Authentication-Wert. SqlPassword Direkte Authentifizierung bei SQL unter Verwendung eines Benutzernamens und eines Kennworts. ActiveDirectoryPassword Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung eines Benutzernamens und eines Kennworts. ActiveDirectoryIntegrated Nur Windows-Treiber und Linux/Mac-Treiber mit Version 17.6+ . Authentifizierung mit Windows-Anmeldedaten, die über Microsoft Entra ID mit integrierter Authentifizierung verbunden sind. ActiveDirectoryInteractive Nur Windows-Treiber. Authentifizierung mit einer Microsoft Entra-Identität unter Verwendung der interaktiven Authentifizierung. ActiveDirectoryMsi Authentifizierung mit einer verwalteten Microsoft Entra-Identität. Für die Identität, die dem Benutzer zugewiesen wurde, ist die Benutzer-ID auf die Objekt-ID der Benutzeridentität festgelegt. Für die vom System zugewiesene Identität ist keine UID erforderlich. ActiveDirectoryServicePrincipal (17.7+) Authentifizierung mit einem Microsoft Entra-Dienstprinzipal. UID wird auf die Client-ID des Dienstprinzipals festgelegt. PWD wird auf den geheimen Clientschlüssel festgelegt.
Encrypt	(nicht festgelegt), Yes/Mandatory(18.0+), No/Optional(18.0+), Strict(18.0+)	(Siehe Beschreibung)	Steuert die Verschlüsselung für eine Verbindung. Wenn der pre-attribute-Wert der Einstellung Authentication im DSN oder der Verbindungszeichenfolge nicht none lautet, ist der Standardwert Yes. Der Standardwert ist auch Yes in Version 18.0.1 und höher. Andernfalls ist der Standardwert No. Wenn das Attribut SQL_COPT_SS_AUTHENTICATION den pre-attribute-Wert Authentication überschreibt, legen Sie den Wert von „Encryption“ im DSN, in der Verbindungszeichenfolge oder im Verbindungsattribut explizit fest. Der pre-attribute-Wert von „Encryption“ ist Yes, wenn der Wert im DSN oder in der Verbindungszeichenfolge auf Yes festgelegt ist.

Neue und/oder geänderte Verbindungsattribute

Die folgenden pre-connect-Verbindungsattribute wurden eingeführt oder geändert, um die Microsoft Entra-Authentifizierung zu unterstützen. Wenn ein Verbindungsattribut über ein entsprechendes Schlüsselwort für Verbindungszeichenfolge oder DSN verfügt und festgelegt ist, hat das Verbindungsattribut Vorrang.

attribute	type	Werte	Standard	Beschreibung
SQL_COPT_SS_AUTHENTICATION	SQL_IS_INTEGER	SQL_AU_NONE, SQL_AU_PASSWORD, SQL_AU_AD_INTEGRATED, SQL_AU_AD_PASSWORD, SQL_AU_AD_INTERACTIVE, SQL_AU_AD_MSI, SQL_AU_AD_SPA, SQL_AU_RESET	(nicht festgelegt)	Siehe Beschreibung des Authentication-Schlüsselworts weiter oben. Mithilfe von SQL_AU_NONE kann ein festgelegter Authentication-Wert im DSN und/oder in der Verbindungszeichenfolge explizit überschrieben werden. SQL_AU_RESET hebt die Festlegung des Attributs auf, falls dieses festgelegt war, sodass der DSN- bzw. Verbindungszeichenfolgenwert Vorrang erhalten kann.
SQL_COPT_SS_ACCESS_TOKEN	SQL_IS_POINTER	Zeiger auf ACCESSTOKEN oder NULL	NULL	Wenn der Wert ungleich NULL ist, wird hiermit das zu verwendende Microsoft Entra-Zugriffstoken angegeben. Es ist ein Fehler, ein Zugriffstoken und auch die Schlüsselwörter UID, PWD, Trusted_Connection oder Authentication für Verbindungszeichenfolgen oder deren äquivalente Attribute anzugeben. HINWEIS: Die ODBC Driver-Version 13.1 unterstützt diese Einstellung nur unter Windows.
SQL_COPT_SS_ENCRYPT	SQL_IS_INTEGER	SQL_EN_OFF, SQL_EN_ON	(Siehe Beschreibung)	Steuert die Verschlüsselung für eine Verbindung. SQL_EN_OFF und SQL_EN_ON deaktivieren und aktivieren Sie Verschlüsselung bzw. Wenn der pre-attribute-Wert der Einstellung Authentication nicht none lautet oder SQL_COPT_SS_ACCESS_TOKEN festgelegt ist und Encrypt weder im DSN noch in der Verbindungszeichenfolge angegeben wurde, lautet der Standardwert SQL_EN_ON. Andernfalls ist der Standardwert SQL_EN_OFF. Falls das Verbindungsattribut SQL_COPT_SS_AUTHENTICATION auf einen anderen Wert als none festgelegt ist, müssen Sie SQL_COPT_SS_ENCRYPT explizit auf den gewünschten Wert festlegen, wenn Encrypt im DSN oder der Verbindungszeichenfolge nicht angegeben war. Der effektive Wert dieses Attributs steuert, ob Verschlüsselung für die Verbindung verwendet wird.
SQL_COPT_SS_OLDPWD	-	-	-	Wird mit Microsoft Entra ID nicht unterstützt, da Kennwortänderungen für Microsoft Entra-Prinzipale nicht über eine ODBC-Verbindung vorgenommen werden können. Der Ablauf von Kennwörtern bei der SQL Server-Authentifizierung wurde mit SQL Server 2005 eingeführt. Das SQL_COPT_SS_OLDPWD-Attribut wurde hinzugefügt, damit der Client sowohl das alte als auch das neue Kennwort für die Verbindung angeben kann. Wenn diese Eigenschaft festgelegt ist, verwendet der Anbieter für die erste Verbindung oder für zukünftige Verbindungen keinen Verbindungspool, da die Verbindungszeichenfolge das „alte Kennwort“ enthält, das inzwischen geändert wurde.
SQL_COPT_SS_INTEGRATED_SECURITY	SQL_IS_INTEGER	SQL_IS_OFF/SQL_IS_ON	SQL_IS_OFF	Veraltet. Verwenden Sie stattdessen SQL_COPT_SS_AUTHENTICATION, festgelegt auf SQL_AU_AD_INTEGRATED. Erzwingt die Verwendung der Windows-Authentifizierung (Kerberos unter Linux und macOS) für die Überprüfung des Zugriffs bei der Serveranmeldung. Wenn die Windows-Authentifizierung verwendet wird, ignoriert der Treiber die Werte für Benutzer-ID und Kennwort, die bei der Verarbeitung von SQLConnect, SQLDriverConnect oder SQLBrowseConnect bereitgestellt werden.

Ergänzungen der Benutzeroberfläche für Microsoft Entra ID (nur Windows-Treiber)

Die Benutzeroberflächen für DSN-Setup und Verbindungen des Treibers wurden um zusätzliche Optionen erweitert, die zur Authentifizierung mit Microsoft Entra ID erforderlich sind.

Erstellen und Bearbeiten von DSNs auf der Benutzeroberfläche

Sie können die Microsoft Entra-Authentifizierungsoptionen verwenden, wenn Sie einen neuen DSN über die Setup-Benutzeroberfläche des Treibers erstellen oder bearbeiten:

Authentication=ActiveDirectoryIntegrated für die integrierte Microsoft Entra-Authentifizierung bei Azure SQL

Authentication=ActiveDirectoryPassword für die Microsoft Entra-Authentifizierung bei Azure SQL mit Benutzername/Kennwort

Authentication=ActiveDirectoryInteractive für die interaktive Microsoft Entra-Authentifizierung bei Azure SQL

Hinweis

Ab Treiberversion 17.9 hat sich das interaktive Authentifizierungsverhalten geändert. Benutzer werden immer zur Eingabe von Anmeldeinformationen aufgefordert, es sei denn, der Treiber hat ein gültiges Zugriffstoken zwischengespeichert. Diese Änderung verhindert, dass Benutzer auf in Microsoft Entra eingebundenen Geräten die Eingabeaufforderung überspringen und sich bei Verwendung der ActiveDirectoryInteractive-Authentifizierung automatisch mit zwischengespeicherten Anmeldeinformationen anmelden.

Authentication=SqlPassword für die Authentifizierung bei SQL Server und Azure SQL mit Benutzername/Kennwort

Trusted_Connection=Yes für die ältere integrierte Windows-Authentifizierung über SSPI

Authentication=ActiveDirectoryMsi für die Microsoft Entra-Authentifizierung mit verwalteter Identität

Authentication=ActiveDirectoryServicePrincipal für die Microsoft Entra-Authentifizierung mit Dienstprinzipal

Die sieben Optionen entsprechen jeweils Trusted_Connection=Yes (vorhandene integrierte Windows-Legacyauthentifizierung nur über SSPI), Authentication=ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi und ActiveDirectoryServicePrincipal.

SQLDriverConnect-Eingabeaufforderung (nur Windows-Treiber)

Die von SQLDriverConnect angezeigte Eingabeaufforderung, die Informationen zum Abschließen der Verbindung anfordert, enthält vier neue Optionen für die Microsoft Entra-Authentifizierung:

Diese Optionen entsprechen den sechs in der Benutzeroberfläche des DSN-Setups enthaltenen Optionen, wie oben beschrieben.

Exemplarische Verbindungszeichenfolgen

1. SQL Server-Authentifizierung: Legacysyntax. Das Serverzertifikat wird nicht überprüft, und eine Verschlüsselung wird nur verwendet, wenn der Server sie erzwingt. Benutzername und Kennwort werden in der Verbindungszeichenfolge übergeben.

   server=Server;database=Database;UID=UserName;PWD=Password;Encrypt=no;TrustServerCertificate=yes;

2. SQL-Authentifizierung: neue Syntax. Der Client fordert eine Verschlüsselung an (der Standardwert für Encrypt lautet true), und das Serverzertifikat wird unabhängig von der Verschlüsselungseinstellung überprüft (sofern TrustServerCertificate nicht auf true festgelegt ist). Benutzername und Kennwort werden in der Verbindungszeichenfolge übergeben.

   server=Server;database=Database;UID=UserName;PWD=Password;Authentication=SqlPassword;

3. Integrierte Windows-Authentifizierung (Kerberos unter Linux und macOS) unter Verwendung von SSPI (bei SQL Server oder SQL IaaS): aktuelle Syntax. Das Serverzertifikat wird nur dann überprüft, wenn der Server eine Verschlüsselung erfordert.

   server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;

4. (Nur Windows-Treiber.) Integrierte Windows-Authentifizierung mit SSPI (wenn es sich um eine Zieldatenbank in SQL Server oder SQL Server auf Azure VMs handelt): neue Syntax. Der Client fordert eine Verschlüsselung an (der Standardwert für Encrypt lautet true), und das Serverzertifikat wird unabhängig von der Verschlüsselungseinstellung überprüft (sofern TrustServerCertificate nicht auf true festgelegt ist).

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;

5. Microsoft Entra-Authentifizierung mit Benutzername/Kennwort (wenn es sich um eine Zieldatenbank in Azure SQL-Datenbank oder Azure SQL Managed Instance handelt). Das Serverzertifikat wird unabhängig von der Verschlüsselungseinstellung überprüft (sofern TrustServerCertificate nicht auf true festgelegt ist). Benutzername und Kennwort werden in der Verbindungszeichenfolge übergeben.

   server=Server;database=Database;UID=UserName;PWD=Password;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Nur Windows-Treiber und Linux/Mac-Treiber mit Version 17.6+.) Integrierte Windows-Authentifizierung mit ADAL oder Kerberos – dies umfasst das Abrufen von Windows-Kontoanmeldedaten für ein Microsoft Entra-Zugriffstoken. Vorausgesetzt wird eine Zieldatenbank in Azure SQL. Das Serverzertifikat wird unabhängig von der Verschlüsselungseinstellung überprüft (sofern TrustServerCertificate nicht auf true festgelegt ist). Unter Linux/macOS muss ein geeignetes Kerberos-Ticket verfügbar sein. Weitere Informationen finden Sie im Abschnitt weiter unten zu Verbundkonten und zur Verwendung der integrierten Authentifizierung.

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;

7. (Nur Windows-Treiber.) Die interaktive Microsoft Entra-Authentifizierung verwendet die Multi-Faktor-Authentifizierung von Microsoft Entra, um die Verbindung einzurichten. In diesem Modus wird durch Eingabe der Anmelde-ID ein Dialogfeld für die Azure-Authentifizierung ausgelöst, das dem Benutzer die Eingabe der zusätzlichen Überprüfung ermöglicht, um die Verbindung einzurichten. Der Benutzername wird in der Verbindungszeichenfolge übergeben.

   server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;

   

8. Die Microsoft Entra-Authentifizierung mit verwalteter Identität verwendet eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität zur Authentifizierung, um die Verbindung einzurichten. Für eine vom System zugewiesene Identität ist die UID nicht erforderlich. Für eine benutzerseitig zugewiesene Identität ist die Benutzer-ID auf die Objekt-ID der Benutzeridentität festgelegt.
   

   Für systemseitig zugewiesene Identität:

   server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;

   Für eine benutzerseitig zugewiesene Identität mit der Objekt-ID myObjectId:

   server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;

9. Microsoft Entra-Authentifizierung mit Dienstprinzipal

   server=Server;database=Database;UID=clientId;PWD=clientSecret;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Hinweise

• Wenn Sie die Microsoft Entra-Optionen mit dem Windows-ODBC-Treiber vor Version 17.4.2 verwenden, stellen Sie sicher, dass die Active Directory-Authentifizierungsbibliothek für SQL Server installiert wurde. Wenn Sie Linux- und macOS-Treiber verwenden, stellen Sie sicher, dass libcurl installiert wurde. Für die Treiberversion 17.2 und höher ist dies keine explizite Abhängigkeit, da diese Bibliothek für die anderen Authentifizierungsmethoden oder ODBC-Vorgänge nicht erforderlich ist.

• Wenn die Microsoft Entra-Konfiguration Richtlinien für bedingten Zugriff beinhaltet und es sich bei dem Client um Windows 10 oder Server 2016 oder höher handelt, kann bei Verwendung der integrierten Authentifizierung oder der Authentifizierung mit Benutzername/Kennwort ein Fehler auftreten. Für Richtlinien für bedingten Zugriff ist die Verwendung von Web Account Manager (WAM) erforderlich, der in Treiberversion 17.6 oder höher für Windows unterstützt wird. Erstellen Sie zum Verwenden von WAM einen neuen Zeichenfolgen-Wert mit dem Namen ADALuseWAM in HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, bzw. HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> oder HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> für die Konfiguration mit globalem, Benutzer-DSN- oder System-DSN-Umfang, und legen Sie ihn auf den Wert „1“ fest. Beachten Sie, dass bei der Authentifizierung mit WAM die Ausführung der Anwendung als anderer Benutzer mit runas nicht unterstützt wird. Szenarien, die Richtlinien für bedingten Zugriff erfordern, werden für Linux oder macOS nicht unterstützt.

• Zum Herstellen einer Verbindung mit einem SQL Server-Benutzernamen und dem zugehörigen Kennwort können Sie jetzt die neue SqlPassword-Option verwenden, die insbesondere für Azure SQL empfohlen wird, weil sie Verbindungsstandardwerte mit höherer Sicherheit ermöglicht.

• Um eine Verbindung über den Benutzernamen und das Kennwort eines Microsoft Entra-Kontos herzustellen, geben Sie Authentication=ActiveDirectoryPassword in der Verbindungszeichenfolge und die Schlüsselwörter UID und PWD mit dem Benutzernamen und dem Kennwort an.

• Zum Herstellen einer Verbindung mit der integrierten Windows- oder der integrierten Microsoft Entra-Authentifizierung (nur Windows-Treiber und Linux/macOS-Treiber ab Version 17.6) geben Sie Authentication=ActiveDirectoryIntegrated in der Verbindungszeichenfolge an. Der Treiber wählt automatisch den richtigen Authentifizierungsmodus aus. Für Version 17.7 des Treibers und frühere Versionen dürfen UID und PWD nicht angegeben werden. Ab Version 17.8 des Treibers werden UID und PWD ignoriert.

• Zum Herstellen einer Verbindung mit der interaktiven Microsoft Entra-Authentifizierung (nur Windows) muss UID angegeben werden. Für Version 17.7 des Treibers und frühere Versionen darf PWD nicht angegeben werden. Ab Version 17.8 des Treibers wird PWD ignoriert.

• Ab Version 18.1 verwendet Trusted_Connection=Yes nicht mehr standardmäßig die Microsoft Entra-Verbundauthentifizierung, sondern stattdessen SSPI-integriert. Zur Verwendung von Microsoft Entra ID für diese Option sollte TrustedConnection_UseAAD=Yes konfiguriert werden.

• Die ODBC-Treiberversionen 17.7 und niedriger weisen ein bekanntes Problem mit einem Verbindungstimeout auf, wenn Microsoft Entra-Authentifizierung und Verschlüsselungserzwingung für eine SQL Server-Instanz aktiviert sind. Das SQL Server-Fehlerprotokoll kann Fehlermeldungen enthalten, beispielsweise: Fehler: 33155, Schweregrad: 20, Status: 1. Ein Trennungsereignis wurde ausgelöst, als der Server auf das Verbundauthentifizierungstoken gewartet hat. Dies kann darauf zurückzuführen sein, dass der Client geschlossen wurde oder das Servertimeout abgelaufen ist. Wenn Sie Hochverfügbarkeitslösungen wie Always On-Verfügbarkeitsgruppen oder Failoverclusterinstanzen verwenden, kann sich dieses Verhalten auf die interne Clusterkommunikation für SQL Server auswirken, was sich wiederum auf die Ressourcenverfügbarkeit auswirken kann. Im Clusterprotokoll werden möglicherweise Fehlermeldungen angezeigt, beispielsweise: [hadrag] Connect to SQL Server ...ODBC Error: [HY000] [Microsoft][ODBC Driver 17 for SQL Server]An unknown error has occurred. Detailed error information is not available. (0). Die ODBC-Treiberversionen 17.10 und höher beheben dieses Problem, und mit SQL Server 2022 GDR KB5021522/CU1 KB5022375 wird der neueste Treiber, der diesen Fix enthält, mit der SQL Server-Installation installiert. Sie können überprüfen, welche Version des ODBC-Treibers installiert ist, indem Sie sich an den ODBC-Datenquellenadministrator wenden.

• Ab ODBC-Treiber Version 18.3 wird die Managed Identity (ActiveDirectoryMSI)-Authentifizierung in Azure Arc und Azure Cloud Shell unterstützt.

Authentifizieren mit einem Zugriffstoken

Das pre-connection-Attribut SQL_COPT_SS_ACCESS_TOKEN ermöglicht die Verwendung eines aus Microsoft Entra ID für die Authentifizierung abgerufenen Zugriffstokens anstelle von Benutzername und Kennwort und umgeht auch die Aushandlung und den Abruf eines Zugriffstokens durch den Treiber. Um ein Zugriffstoken zu verwenden, legen Sie das Verbindungsattribut SQL_COPT_SS_ACCESS_TOKEN auf einen Zeiger zu einer ACCESSTOKEN-Struktur fest:

typedef struct AccessToken
{
    DWORD dataSize;
    BYTE data[];
} ACCESSTOKEN;

ACCESSTOKEN ist eine Struktur mit variabler Länge, die aus einem 4 Bytes langen length-Wert gefolgt von length Bytes an nicht transparenten Daten besteht, die das Zugriffstoken bilden. Aufgrund der Art und Weise, in der SQL Server Zugriffstoken verarbeitet, muss ein über eine OAuth 2.0-JSON-Antwort abgerufenes Token erweitert werden, sodass jedem Byte ein NULL-Füllbyte folgt, ähnlich wie bei einer UCS-2-Zeichenfolge, die nur aus ASCII-Zeichen besteht. Das Token ist jedoch ein nicht transparenter Wert und die angegebene Länge in Bytes darf KEIN NULL-Abschlusszeichen enthalten. Aufgrund der erheblichen Einschränkungen in Bezug auf Länge und Format ist diese Authentifizierungsmethode nur programmgesteuert über das Verbindungsattribut SQL_COPT_SS_ACCESS_TOKEN verfügbar. Es gibt kein entsprechendes Schlüsselwort für DSN oder Verbindungszeichenfolgen. Die Verbindungszeichenfolge darf die Schlüsselwörter UID, PWD, Authentication und Trusted_Connection nicht enthalten.

Hinweis

Die ODBC Driver-Version 13.1 unterstützt diese Authentifizierung nur unter Windows. Nachfolgende Versionen unterstützen diese Authentifizierung auf allen Plattformen.

Beispielcode für die Microsoft Entra-Authentifizierung

Das folgende Beispiel zeigt den erforderlichen Code, um mithilfe von Microsoft Entra ID und Verbindungsschlüsselwörtern eine Verbindung mit SQL Server herzustellen. Es ist nicht notwendig, den Anwendungscode selbst zu ändern. Die Verbindungszeichenfolge bzw. der DSN, sofern verwendet, ist die einzige Änderung, die für die Verwendung von Microsoft Entra ID zur Authentifizierung erforderlich ist:

    ...
    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=myPass;Authentication=ActiveDirectoryPassword;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

Das folgende Beispiel zeigt den erforderlichen Code, um mithilfe der Microsoft Entra-Authentifizierung mit Zugriffstoken eine Verbindung mit SQL Server herzustellen. In diesem Fall muss der Anwendungscode geändert werden, um das Zugriffstoken zu verarbeiten und das zugehörige Verbindungsattribut festzulegen.

    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Encrypt=yes;"
    SQLCHAR accessToken[] = "eyJ0eXAiOi..."; // In the format extracted from an OAuth JSON response
    ...
    DWORD dataSize = 2 * strlen(accessToken);
    ACCESSTOKEN *pAccToken = malloc(sizeof(ACCESSTOKEN) + dataSize);
    pAccToken->dataSize = dataSize;
    // Expand access token with padding bytes
    for(int i = 0, j = 0; i < dataSize; i += 2, j++) {
        pAccToken->data[i] = accessToken[j];
        pAccToken->data[i+1] = 0;
    }
    ...
    SQLSetConnectAttr(hDbc, SQL_COPT_SS_ACCESS_TOKEN, (SQLPOINTER)pAccToken, SQL_IS_POINTER);
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...
    free(pAccToken);

Nachstehend finden Sie ein Beispiel für eine Verbindungszeichenfolge zur Verwendung mit der interaktiven Microsoft Entra-Authentifizierung. Dieses Beispiel enthält kein PWD-Feld, da das Kennwort im Bildschirm für die Azure-Authentifizierung eingegeben wird.

SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"

Das folgende Beispiel einer Verbindungszeichenfolge ist für die Verwendung mit der Microsoft Entra-Identitätsauthentifizierung vorgesehen. Die UID wird auf die Objekt-ID der Benutzeridentität festgelegt, wenn eine dem Benutzer zugewiesene Identität verwendet wird.

// For system-assigned identity,
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Authentication=ActiveDirectoryMsi;Encrypt=yes;"
...
// For user-assigned identity with object ID equals to myObjectId
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;"

Überlegungen zur Verwendung von ADFS-Verbundkonten unter Linux/macOS

Von Version 17.6 an unterstützen die Treiber für Linux und macOS die Authentifizierung mithilfe von Microsoft Entra-ADFS-Verbundkonten unter Verwendung von Benutzername/Kennwort (ActiveDirectoryPassword) oder Kerberos (ActiveDirectoryIntegrated). Bei der Verwendung des integrierten Modus bestehen einige Einschränkungen in Abhängigkeit von der Plattform.

Wenn Sie sich bei einem Benutzer authentifizieren, dessen UPN-Suffix nicht mit dem Kerberos-Bereich identisch ist, d. h., es wird ein alternatives UPN-Suffix verwendet, muss beim Abrufen von Kerberos-Tickets die Option für einen Unternehmens-Prinzipal verwendet werden (verwenden Sie die Option -E mit kinit, und geben Sie den Prinzipalnamen in der Form user@federated-domain an). Auf diese Weise kann der Treiber sowohl die Verbunddomäne als auch den Kerberos-Bereich korrekt bestimmen.

Sie können überprüfen, ob ein passendes Kerberos-Ticket verfügbar ist, indem Sie die Ausgabe des klist-Befehls untersuchen. Wenn die Verbunddomäne mit dem Kerberos-Bereich und dem UPN-Suffix übereinstimmt, weist der Prinzipalname die Form user@realm auf. Weichen sie ab, muss der Prinzipalname die Form user@federated-domain@realm aufweisen.

Linux

Unter SUSE 11 unterstützt die standardmäßige Kerberos-Bibliotheksversion 1.6.x nicht die Option für einen Unternehmens-Prinzipal, die für die Verwendung alternativer UPN-Suffixe erforderlich ist. Zum Verwenden alternativer UPN-Suffixe mit integrierter Microsoft Entra-Authentifizierung führen Sie ein Upgrade der Kerberos-Bibliothek auf 1.7 oder höher durch.

Unter Alpine Linux unterstützt die standardmäßige libcurl nicht die SPNEGO/Kerberos-Authentifizierung, die für die integrierte Microsoft Entra-Authentifizierung erforderlich ist.

macOS

Die Kerberos-Systembibliothek kinit unterstützt einen Unternehmens-Prinzipal mit der Option --enterprise, führt jedoch zugleich implizit eine Namenskanonisierung durch, was die Verwendung alternativer UPN-Suffixe verhindert. Um alternative UPN-Suffixe mit integrierter Microsoft Entra-Authentifizierung zu verwenden, installieren Sie über brew install krb5 eine neuere Kerberos-Bibliothek, und verwenden Sie ihre kinit mit der Option -E, wie oben beschrieben.

Zugehöriger Inhalt

• Tokenbasierte Authentifizierungsunterstützung für Azure SQL-Datenbank mithilfe der Microsoft Entra-Authentifizierung
• Nutzung der Integrierten Authentifizierung