Utilisation de Microsoft Entra ID avec le pilote ODBC

Télécharger le pilote ODBC

Objectif

La version 13.1 de Microsoft ODBC Driver for SQL Server et les versions ultérieures permettent aux applications ODBC de se connecter à une base de données Azure SQL ou à une Azure SQL Managed Instance à l’aide d’identités dans Microsoft Entra ID. L’authentification peut être effectuée avec un nom d’utilisateur et un mot de passe, un jeton d’accès Microsoft Entra, une identité managée Microsoft Entra (17.3+) ou une authentification Windows intégrée dans un environnement fédéré joint à un domaine (17.6+ sur Linux/macOS). Pour la version 13.1 du pilote ODBC, l’authentification par jeton d’accès Microsoft Entra est Windows uniquement. La version 17 et les versions ultérieures du pilote ODBC prennent en charge cette authentification sur toutes les plateformes (Windows, Linux et macOS). Une nouvelle méthode d’authentification interactive Microsoft Entra, qui prend en charge l’authentification multifacteur, est introduite dans la version 17.1 du pilote ODBC pour Windows. Une nouvelle méthode d'authentification des identités managées par Microsoft Entra a été ajoutée dans la version 17.3.1.1 du pilote ODBC pour les identités attribuées au système et à l'utilisateur. Toutes ces options utilisent de nouveaux mots clés de chaîne de connexion et de nom de source de données, ainsi que des attributs de connexion.

Pour utiliser l’authentification Microsoft Entra, vous devez configurer votre source de données Azure SQL. Pour plus d’informations, consultez Configurer et gérer l’authentification Microsoft Entra avec Azure SQL.

Nouveaux mots clés de chaîne de connexion et de nom de source de données et mots clés modifiés

Le mot clé Authentication peut être utilisé en cas de connexion avec un nom de source de données ou une chaîne de connexion pour contrôler le mode d’authentification. La valeur définie dans la chaîne de connexion remplace celle du nom de source de données, si elle existe. La valeur préattribut du paramètre Authentication est la valeur calculée à partir des valeurs de chaîne de connexion et de nom de source de données.

Nouveaux attributs de connexion et attributs modifiés

Les attributs de connexion préconnexion suivants ont été introduits ou modifiés de façon à prendre en charge l’authentification Microsoft Entra. Lorsqu’un attribut de connexion présente un mot clé de chaîne de connexion ou de nom de source de données correspondant et qu’il est défini, il est prioritaire.

Ajouts d’interface utilisateur pour Microsoft Entra ID (pilote Windows uniquement)

Les interfaces utilisateur de configuration du nom de source de données et de connexion du pilote ont été améliorées en intégrant les options supplémentaires nécessaires pour s’authentifier avec Microsoft Entra ID.

Créer et modifier les noms de sources de données dans l’interface utilisateur

Vous pouvez utiliser les options d’authentification Microsoft Entra quand vous créez ou modifiez un nom de source de données existant à l’aide de l’interface utilisateur de configuration du pilote :

Authentication=ActiveDirectoryIntegrated pour l’authentification intégrée avec Microsoft Entra sur Azure SQL

Authentication=ActiveDirectoryPassword pour l’authentification par nom d’utilisateur / mot de passe avec Microsoft Entra sur Azure SQL

Authentication=ActiveDirectoryInteractive pour l’authentification interactive avec Microsoft Entra sur Azure SQL

Authentication=SqlPassword pour l’authentification par nom d’utilisateur / mot de passe sur SQL Server et Azure SQL

Trusted_Connection=Yes pour l’authentification intégrée de l’interface SSPI (Security Support Provider Interface) Windows héritée

Authentication=ActiveDirectoryMsi pour l’authentification par identité managée avec Microsoft Entra

Authentication=ActiveDirectoryServicePrincipal pour l’authentification par principal de service avec Microsoft Entra

Les six options correspondent respectivement à Trusted_Connection=Yes (authentification intégrée Windows SSPI héritée uniquement) et à Authentication= ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi et ActiveDirectoryServicePrincipal.

Invite SQLDriverConnect (pilote Windows uniquement)

La boîte de dialogue d’invite affichée par SQLDriverConnect lorsqu’il demande les informations nécessaires pour établir la connexion contient quatre nouvelles options pour l’authentification avec Microsoft Entra :

Ces options correspondent aux six mêmes options disponibles dans l’interface utilisateur de configuration du nom de source de données ci-dessus.

Exemples de chaîne de connexion

1. Authentification SQL Server : ancienne syntaxe. Le certificat de serveur n’est pas validé et le chiffrement est utilisé seulement s’il est appliqué par le serveur. Le nom d’utilisateur/mot de passe est transmis dans la chaîne de connexion.

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

2. Authentification SQL : nouvelle syntaxe. Le client demande le chiffrement (la valeur par défaut de Encrypt est true) et le certificat de serveur est validé, quel que soit le paramètre de chiffrement (sauf si TrustServerCertificate est défini sur true). Le nom d’utilisateur/mot de passe est transmis dans la chaîne de connexion.

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

3. Authentification Windows intégrée (Kerberos sur Linux et macOS) avec SSPI (vers SQL Server ou SQL IaaS) : syntaxe actuelle. Le certificat de serveur n’est pas validé, sauf si le chiffrement est requis par le serveur.

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

4. (Pilote Windows uniquement.) Authentification intégrée de Windows avec SSPI (si la base de données cible se trouve dans SQL Server ou SQL Serveur sur les ordinateurs virtuels Azure) : nouvelle syntaxe. Le client demande le chiffrement (la valeur par défaut de Encrypt est true) et le certificat de serveur est validé, quel que soit le paramètre de chiffrement (sauf si TrustServerCertificate est défini sur true).

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

5. Authentification par nom d’utilisateur / mot de passe avec Microsoft Entra (si la base de données cible se trouve dans la base de données Azure SQL ou Azure SQL Managed Instance). Le certificat de serveur est validé, quel que soit le paramètre de chiffrement (sauf si TrustServerCertificate est défini sur true). Le nom d’utilisateur/mot de passe est transmis dans la chaîne de connexion.

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

6. (pilote Windows et Linux/macOS 17.6+ seulement.) Authentification intégrée de Windows avec ADAL ou Kerberos, qui implique l’acceptation d’informations d’identification de compte Windows contre un jeton d’accès Microsoft Entra, en supposant que la base de données cible se trouve dans Azure SQL. Le certificat de serveur est validé, quel que soit le paramètre de chiffrement (sauf si TrustServerCertificate est défini sur true). Sur Linux/macOS, un ticket Kerberos approprié doit être disponible. Pour plus d’informations, consultez la section ci-dessous sur les comptes fédérés et Utilisation de l’authentification intégrée.

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

7. (pilote Windows uniquement.) L’authentification interactive Microsoft Entra utilise la technologie d’authentification multifacteur Microsoft Entra pour configurer la connexion. Dans ce mode, lorsque l’ID de connexion est fourni, une boîte de dialogue d’authentification Azure est déclenchée, permettant ainsi à l’utilisateur d’entrer la vérification supplémentaire pour établir la connexion. Le nom d’utilisateur est transmis dans la chaîne de connexion.

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

   

8. L'authentification par identité gérée Microsoft Entra peut utiliser une identité gérée attribuée par le système ou par l'utilisateur. Pour une identité attribuée par l'utilisateur, définissez UID comme étant l'ID client de l'identité pour Azure App Service ou Azure Container Instance ; sinon, utilisez son ID d'objet. Pour l'identité affectée par le système, l'UID n'est pas obligatoire.
   

   Pour l'identité affectée par le système :

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

   Pour l’identité affectée par l’utilisateur avec l’ID objet, cela revient à myObjectId :

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

9. Authentification avec principal de service Microsoft Entra

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

Notes

• Si vous utilisez les options Microsoft Entra avec le pilote ODBC Windows antérieur à la version 17.4.2, vérifiez que la Bibliothèque d’authentification Active Directory pour SQL Server a été installée. Si vous utilisez les pilotes Linux et macOS, vérifiez que libcurl est installé. Pour la version 17.2 et les versions ultérieures du pilote, il ne s’agit pas d’une dépendance explicite, car elle n’est pas requise pour les autres méthodes d’authentification ni les opérations ODBC.

• Lorsque la configuration Microsoft Entra comprend des stratégies d’accès conditionnel et que le client est Windows 10 ou Server 2016 ou une version ultérieure, l’authentification via Integrated ou le nom d’utilisateur / mot de passe peut échouer. Les stratégies d’accès conditionnel exigent l’utilisation du gestionnaire de comptes Web (WAM), pris en charge dans la version 17.6 et les versions ultérieures du pilote pour Windows. Pour utiliser WAM, créez une nouvelle valeur de chaîne nommée ADALuseWAM dans HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> ou HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> pour la configuration globale, le nom de source de données de l'utilisateur ou la configuration de l'étendue du nom de source de données système et attribuez-lui la valeur 1. Notez que l’authentification avec WAM ne prend pas en charge l’exécution de l’application en tant qu’utilisateur différent avec runas. Les scénarios qui requièrent des stratégies d’accès conditionnel ne sont pas pris en charge pour Linux ou macOS.

• Pour vous connecter avec un nom d’utilisateur de compte SQL Server et un mot de passe, vous pouvez maintenant utiliser la nouvelle option SqlPassword, tout particulièrement recommandée pour Azure SQL, car elle offre des paramètres de connexion plus sécurisés.

• Pour vous connecter avec un nom d’utilisateur de compte Microsoft Entra et un mot de passe, spécifiez Authentication=ActiveDirectoryPassword dans la chaîne de connexion et les mots clés UID et PWD avec respectivement le nom d’utilisateur et le mot de passe.

• Pour vous connecter avec l’authentification intégrée Windows ou Microsoft Entra (pilote Windows et Linux/macOS 17.6+ seulement), spécifiez Authentication=ActiveDirectoryIntegrated dans la chaîne de connexion. Le pilote choisira automatiquement le mode d’authentification approprié. Avec la version 17.7 et les versions antérieures du pilote, UID et PWD ne doivent pas être spécifiés. À partir de la version 17.8 du pilote, UID et PWD sont ignorés.

• Pour vous connecter avec l’authentification interactive Microsoft Entra (pilote Windows uniquement), spécifiez UID. Avec la version 17.7 et les versions antérieures du pilote, PWD ne doit pas être spécifié. À partir de la version 17.8 du pilote, PWD est ignoré.

• À compter de la version 18.1, Trusted_Connection=Yes n’utilise plus l’authentification fédérée Microsoft Entra ID par défaut et utilise l’intégration SSPI à la place. Pour utiliser Microsoft Entra ID pour cette option, configurez TrustedConnection_UseAAD=Yes.

• Les versions 17.7 et antérieures du pilote ODBC présentent un problème connu avec le délai d’expiration de la connexion quand l’authentification Microsoft Entra et le chiffrement forcé sont activés sur une instance SQL Server. Le journal des erreurs de SQL Server peut contenir des messages d’erreur comme : « Erreur : 33155, Gravité : 20, État : 1. Un événement de déconnexion a été généré alors que le serveur attend un jeton d’authentification fédérée. Cela pourrait être dû à la fermeture du client ou à l’expiration du délai d’un serveur. ». Si vous utilisez des solutions de haute disponibilité comme des groupes de disponibilité Always On ou des instances de cluster de basculement, la communication interne du cluster pour SQL Server peut être affectée par ce comportement qui peut impacter la disponibilité des ressources. Dans le journal du cluster, vous pouvez voir des messages d’erreur comme : [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). Les versions 17.10 et ultérieures du pilote ODBC corrigent ce problème et, avec SQL Server 2022 GDR KB5021522 / CU1 KB5022375, le dernier pilote contenant ce correctif est installé lors de l’installation de SQL Server. Vous pouvez vérifier la version du pilote ODBC que vous avez installée en vous référant à l’administrateur de source de données ODBC.

• À partir de la version 18.3 du pilote ODBC, l’authentification par identité managée (ActiveDirectoryMSI) est prise en charge sur Azure Arc et Azure Cloud Shell.

S’authentifier avec un jeton d’accès

L’attribut préconnexion SQL_COPT_SS_ACCESS_TOKEN permet d’utiliser un jeton d’accès obtenu auprès de Microsoft Entra ID pour l’authentification au lieu du nom d’utilisateur et du mot de passe, et de contourner la négociation et l’obtention d’un jeton d’accès par le pilote. Pour utiliser un jeton d’accès, définissez l’attribut de connexion SQL_COPT_SS_ACCESS_TOKEN sur un pointeur désignant une structure ACCESSTOKEN :

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

ACCESSTOKEN est une structure de longueur variable composée d’une longueur de 4 octets suivie de longueur octets de données opaques qui constituent le jeton d’accès. En raison de la façon dont SQL Server gère les jetons d’accès, un jeton d’accès obtenu au moyen d’une réponse JSON OAuth 2.0 doit être développé pour que chaque octet soit suivi d’un octet de remplissage à l’aide de zéros, comme une chaîne UCS-2 contenant uniquement des caractères ASCII. Toutefois, le jeton est une valeur opaque et la longueur spécifiée, en octets, ne doit comprendre aucune marque de fin null. En raison de ses contraintes de format et de longueur considérables, cette méthode d’authentification n’est disponible que programmatiquement, par le biais de l’attribut de connexion SQL_COPT_SS_ACCESS_TOKEN. Il n’y a aucun nom de source de données ou mot clé de chaîne de connexion correspondant. La chaîne de connexion ne doit pas contenir de mots clés UID, PWD, Authentication ni Trusted_Connection.

Exemple de code d’authentification Microsoft Entra

L’exemple suivant illustre le code nécessaire pour se connecter à SQL Server à l’aide de Microsoft Entra ID avec les mots clés de connexion. Vous n’avez pas besoin de changer le code d’application lui-même. La chaîne de connexion, ou le nom de source de données s’il est utilisé, est la seule modification nécessaire pour pouvoir utiliser l’authentification Microsoft Entra ID :

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

L’exemple suivant illustre le code nécessaire pour se connecter à SQL Server à l’aide de l’authentification par jeton d’accès avec Microsoft Entra. Dans ce cas, vous devez modifier le code d’application pour traiter le jeton d’accès et définir l’attribut de connexion associé.

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

Voici un exemple de chaîne de connexion à utiliser avec l’authentification interactive avec Microsoft Entra. Il ne contient pas de champ PWD, car le mot de passe est entré dans l’écran Authentification Azure.

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

L’exemple de chaîne de connexion suivant est utilisé avec l’authentification d’identité gérée par Microsoft Entra. UID est défini sur l’ID objet/ ID client de l’identité d’utilisateur en cas d’utilisation d’une identité affectée par l’utilisateur.

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

Considérations relatives à l’utilisation des comptes fédérés ADFS sur Linux/macOS

À partir de la version 17.6, les pilotes pour Linux et macOS prennent en charge l’authentification à l’aide des comptes fédérés par ADFS Microsoft Entra à l’aide d’un nom d’utilisateur / mot de passe (ActiveDirectoryPassword) ou de Kerberos (ActiveDirectoryIntegrated). Certaines limitations dépendent de la plateforme lorsque vous utilisez le mode intégré.

Quand l’utilisateur qui s’authentifie a un suffixe UPN différent du domaine Kerberos, c’est-à-dire qu’un autre suffixe UPN est utilisé, vous devez utiliser l’option Principal d’entreprise (utilisez l’option -E avec kinit et fournissez le nom du principal au format user@federated-domain) pour obtenir les tickets Kerberos. De cette façon, le pilote peut correctement déterminer le domaine fédéré et le domaine Kerberos.

Vous pouvez vérifier qu’un ticket Kerberos approprié est disponible en inspectant la sortie de la commande klist. Si le domaine fédéré est le même que le domaine Kerberos et le suffixe UPN, le nom du principal a le format user@realm. S’il est différent, le nom du principal doit être au format user@federated-domain@realm.

Linux

Sur SUSE 11, la version 1.6.x par défaut de la bibliothèque Kerberos ne prend pas en charge l’option Principal d’entreprise qui permet d’utiliser d’autres suffixes UPN. Pour utiliser d’autres suffixes UPN avec l’authentification intégrée Microsoft Entra, mettez à niveau la bibliothèque Kerberos au profit de la version 1.7 ou d’une version plus récente.

Sur Alpine Linux, le libcurl par défaut ne prend pas en charge l’authentification SPNEGO/Kerberos nécessaire pour l’authentification intégrée avec Microsoft Entra.

macOS

La bibliothèque Kerberos système kinit prend en charge le Principal d’entreprise avec l’option --enterprise, mais effectue également implicitement une canonicalisation des noms, ce qui empêche d’utiliser d’autres suffixes UPN. Pour utiliser d’autres suffixes UPN avec l’authentification intégrée avec Microsoft Entra, installez une bibliothèque Kerberos plus récente via brew install krb5 et utilisez son kinit avec l’option -E comme décrit ci-dessus.

Contenu connexe

• L'authentification basée sur le jeton prend en charge la base de données Azure SQL à l'aide de l'authentification Microsoft Entra
• Utilisation de l’authentification intégrée