Używanie Microsoft Entra ID ze sterownikiem ODBC

pobierz sterownika ODBC

Uwaga / Notatka

Chociaż identyfikator Entra firmy Microsoft jest nową nazwą usługi Azure Active Directory (Azure AD), aby zapobiec zakłócaniu działania istniejących środowisk, usługa Azure AD nadal pozostaje w niektórych zakodowanych na stałe elementach, takich jak pola interfejsu użytkownika, dostawcy połączeń, kody błędów i polecenia cmdlet. W tym artykule dwie nazwy są wymienne.

Przeznaczenie

Sterownik MICROSOFT ODBC dla programu SQL Server w wersji 13.1 lub nowszej umożliwia aplikacjom ODBC łączenie się z usługą Azure SQL Database lub wystąpieniem zarządzanym Azure SQL przy użyciu tożsamości w usłudze Microsoft Entra ID. Uwierzytelnianie można przeprowadzić przy użyciu nazwy użytkownika i hasła, tokenu dostępu firmy Microsoft Entra, tożsamości zarządzanej firmy Microsoft (17.3 lub nowszej) lub zintegrowanego uwierzytelniania systemu Windows w środowisku federacyjnym, przyłączonym do domeny (17.6 lub nowszym w systemie Linux/macOS). Dla sterownika ODBC w wersji 13.1 uwierzytelnianie za pomocą tokenu dostępu Microsoft Entra jest dostępne tylko na systemie Windows. Sterownik ODBC w wersji 17 lub nowszej obsługuje to uwierzytelnianie na wszystkich platformach (Windows, Linux i macOS). Nowa metoda uwierzytelniania interakcyjnego firmy Microsoft Entra, która obsługuje uwierzytelnianie wieloskładnikowe, jest wprowadzana w sterowniku ODBC w wersji 17.1 dla systemu Windows. W wersji 17.3.1.1.1 dodano nową metodę uwierzytelniania tożsamości zarządzanej firmy Microsoft Entra dla tożsamości zarządzanych przypisanych przez system i przypisanych przez użytkownika. Wszystkie te opcje są realizowane przy użyciu nowych słów kluczowych łańcucha połączenia DSN oraz atrybutów połączenia.

Aby korzystać z uwierzytelniania w usłudze Microsoft Entra, musisz skonfigurować źródło danych usługi Azure SQL. Więcej informacji można znaleźć w temacie Konfigurowanie uwierzytelniania usługi Microsoft Entra i zarządzanie nim za pomocą usługi Azure SQL.

Uwaga / Notatka

Sterownik ODBC w systemach Linux i macOS przed wersją 17.6 obsługuje tylko uwierzytelnianie Microsoft Entra bezpośrednio przy użyciu Microsoft Entra ID. Jeśli używasz uwierzytelniania nazwy użytkownika/hasła firmy Microsoft z klienta systemu Linux lub macOS, a konfiguracja firmy Microsoft Entra wymaga uwierzytelnienia klienta względem punktu końcowego usług Microsoft Entra Federation Services, uwierzytelnianie może zakończyć się niepowodzeniem. Od wersji sterownika 17.6 to ograniczenie zostało usunięte.

Nowe i/lub zmodyfikowane nazwy DSN i słowa kluczowe parametrów połączenia

Słowo Authentication kluczowe może być używane podczas nawiązywania połączenia z DSN lub ciągiem połączenia w celu kontrolowania trybu uwierzytelniania. Wartość ustawiona w łańcuchu połączenia zastępuje tę w DSN, jeśli zostanie podana. Wartość przed-atrybutuAuthentication ustawienia to wartość obliczona na podstawie ciągu połączenia i wartości DSN.

Name	Wartości	Default	Description
Authentication	(nie ustawiono), (pusty ciąg), SqlPassword, ActiveDirectoryPassword, ActiveDirectoryIntegrated, ActiveDirectoryInteractive, , ActiveDirectoryMsiActiveDirectoryServicePrincipal	(nie ustawiono)	Steruje trybem uwierzytelniania. Wartość Description (nie ustawiono) Tryb uwierzytelniania określany przez inne słowa kluczowe (istniejące starsze opcje połączenia). (pusty ciąg) (Tylko parametry połączenia). Zastąp parametr Authentication oraz usuń wartość ustawioną w DSN. SqlPassword Bezpośrednie uwierzytelnianie w usłudze SQL przy użyciu nazwy użytkownika i hasła. ActiveDirectoryPassword Uwierzytelnij się za pomocą tożsamości Microsoft Entra, używając nazwy użytkownika i hasła. ActiveDirectoryIntegrated Tylko sterowniki dla systemów Windows oraz Linux/Mac 17.6 lub nowszych. Uwierzytelnianie za pomocą federacyjnych poświadczeń Windows poprzez Microsoft Entra ID z użyciem zintegrowanego uwierzytelniania. ActiveDirectoryInteractive Tylko sterownik systemu Windows. Uwierzytelnij się przy użyciu tożsamości Microsoft Entra za pomocą uwierzytelniania interakcyjnego. ActiveDirectoryMsi Uwierzytelnij się tożsamością zarządzaną przez Microsoft Entra. W przypadku tożsamości przypisanej przez użytkownika ustaw identyfikator UID na identyfikator klienta tej tożsamości w usłudze Azure App Service lub w usłudze Azure Container Instance. W przeciwnym razie użyj identyfikatora obiektu. W przypadku tożsamości przypisanej przez system identyfikator UID nie jest wymagany. ActiveDirectoryServicePrincipal (17.7+) Uwierzytelnij się za pomocą jednostki usługi Microsoft Entra. Identyfikator UID jest ustawiony na identyfikator klienta jednostki usługi. Element PWD jest ustawiony na klucz tajny klienta.
Encrypt	(nie ustawiono), Yes/Mandatory(18.0+),No/Optional (18.0+), Strict(18.0+)	(zobacz opis)	Steruje szyfrowaniem połączenia. Jeśli wartość pre-atrybutu Authentication ustawienia nie none znajduje się w nazwie DSN lub parametrach połączenia, wartość domyślna to Yes. Wartość domyślna jest również Yes w wersjach 18.0.1 lub nowszych. W przeciwnym razie wartość domyślna to No. Jeśli atrybut SQL_COPT_SS_AUTHENTICATION zastępuje predefiniowaną wartość atrybutu Authentication, jawnie ustaw wartość szyfrowania w DSN, w ciągu połączenia lub w atrybucie połączenia. Wartość preatrybutu szyfrowania to Yes, jeśli wartość jest ustawiona na Yes w łańcuchu DSN lub w parametrach połączenia.

Nowe i/lub zmodyfikowane atrybuty połączenia

Następujące atrybuty połączenia wstępnego zostały wprowadzone lub zmodyfikowane w celu obsługi uwierzytelniania firmy Microsoft Entra. Gdy atrybut połączenia ma odpowiednie parametry połączenia lub słowo kluczowe DSN i jest ustawiony, atrybut połączenia ma pierwszeństwo.

Attribute	Typ	Wartości	Default	Description
SQL_COPT_SS_AUTHENTICATION	SQL_IS_INTEGER	SQL_AU_NONE, SQL_AU_PASSWORD, , SQL_AU_AD_INTEGRATED, SQL_AU_AD_PASSWORDSQL_AU_AD_INTERACTIVE, , SQL_AU_AD_MSI, , SQL_AU_AD_SPASQL_AU_RESET	(nie ustawiono)	Zobacz opis słowa kluczowego Authentication powyżej. SQL_AU_NONE Parametr jest udostępniany w celu jawnego zastąpienia wartości ustawionej Authentication w parametrach DSN i/lub połączenia, podczas gdy SQL_AU_RESET nie ustawia atrybutu, jeśli został ustawiony, zezwalając na pierwszeństwo wartości DSN lub parametrów połączenia.
SQL_COPT_SS_ACCESS_TOKEN	SQL_IS_POINTER	Wskaźnik do ACCESSTOKEN lub NULL	ZERO	Jeśli nie ma wartości null, określa token dostępu Microsoft Entra do wykorzystania. Jest to błąd podczas określania tokenu dostępu, a także UIDsłów kluczowych parametrów połączenia lub PWDTrusted_ConnectionAuthentication ich równoważnych atrybutów. UWAGA: Sterownik ODBC w wersji 13.1 obsługuje tylko to ustawienie w systemie Windows.
SQL_COPT_SS_ENCRYPT	SQL_IS_INTEGER	SQL_EN_OFF, SQL_EN_ON	(zobacz opis)	Steruje szyfrowaniem połączenia. SQL_EN_OFF i SQL_EN_ON odpowiednio włączają i wyłączają szyfrowanie. Jeśli wartość pre-atrybutu ustawienia Authentication nie jest none lub Encrypt nie została określona ani w parametrach DSN, ani w parametrach połączenia, wartość domyślna wynosi SQL_EN_ON. W przeciwnym razie wartość domyślna to SQL_EN_OFF. Jeśli atrybut SQL_COPT_SS_AUTHENTICATION połączenia nie jest ustawiony na none, ustaw jawnie SQL_COPT_SS_ENCRYPT na żądaną wartość, jeśli Encrypt nie został określony w nazwie DSN lub ciągu połączenia. Efektywna wartość tego atrybutu określa , czy szyfrowanie jest używane dla połączenia.
SQL_COPT_SS_OLDPWD	-	-	-	Nieobsługiwane w przypadku Microsoft Entra ID, ponieważ nie można wykonać zmian haseł do encji Microsoft Entra za pośrednictwem połączenia ODBC. Wygaśnięcie hasła dla uwierzytelniania programu SQL Server zostało wprowadzone w programie SQL Server 2005. Atrybut SQL_COPT_SS_OLDPWD został dodany, aby umożliwić klientowi podanie zarówno starego, jak i nowego hasła dla połączenia. Po ustawieniu tej właściwości dostawca nie będzie używać puli połączeń dla pierwszego połączenia lub dla przyszłych połączeń, ponieważ parametry połączenia zawierają "stare hasło", które zostało zmienione.
SQL_COPT_SS_INTEGRATED_SECURITY	SQL_IS_INTEGER	SQL_IS_OFF,SQL_IS_ON	SQL_IS_OFF	Przestarzałe; użyj SQL_COPT_SS_AUTHENTICATION ustawionego na SQL_AU_AD_INTEGRATED zamiast tego. Wymusza użycie uwierzytelniania systemu Windows (Kerberos w systemie Linux i macOS) w celu weryfikacji dostępu podczas logowania do serwera. Gdy jest używane uwierzytelnianie systemu Windows, sterownik ignoruje identyfikator użytkownika i wartości hasła podane w ramach SQLConnect, SQLDriverConnectlub SQLBrowseConnect przetwarzania.

Dodatkowe elementy interfejsu użytkownika dla Entra ID Microsoft (tylko dla sterownika Windows)

Ustawienia DSN oraz interfejsy użytkownika połączeń sterownika zostały ulepszone, dodając dodatkowe opcje niezbędne do uwierzytelniania za pomocą Microsoft Entra ID.

Tworzenie i edytowanie DSN w interfejsie użytkownika

Istnieje możliwość użycia opcji uwierzytelniania Microsoft Entra podczas tworzenia lub edytowania istniejącego DSN w interfejsie konfiguracji sterownika.

Authentication=ActiveDirectoryIntegrated w przypadku uwierzytelniania zintegrowanego Microsoft Entra do Azure SQL

Authentication=ActiveDirectoryPassword w przypadku uwierzytelniania przy użyciu nazwy użytkownika i hasła Microsoft Entra do usługi Azure SQL

Authentication=ActiveDirectoryInteractive dla interaktywnego uwierzytelniania Microsoft Entra do usługi Azure SQL

Uwaga / Notatka

Od wersji sterownika 17.9 zachowanie uwierzytelniania interakcyjnego uległo zmianie. Użytkownicy będą zawsze monitowani o poświadczenia, chyba że sterownik ma prawidłowy token dostępu w pamięci podręcznej. Ta zmiana uniemożliwia użytkownikom urządzeń dołączonych do Microsoft Entra pomijanie monitu i automatyczne logowanie się przy użyciu zapamiętanych poświadczeń podczas korzystania z ActiveDirectoryInteractive uwierzytelniania.

Authentication=SqlPassword w przypadku uwierzytelniania nazwy użytkownika/hasła w programie SQL Server i usłudze Azure SQL

Trusted_Connection=Yes w przypadku starszego uwierzytelniania zintegrowanego z interfejsem SSPI systemu Windows

Authentication=ActiveDirectoryMsi do uwierzytelniania tożsamości zarządzanej Microsoft Entra

Authentication=ActiveDirectoryServicePrincipal w przypadku uwierzytelniania jednostki usługi Entra firmy Microsoft

Siedem opcji odpowiada Trusted_Connection=Yes (istniejącemu starszemu uwierzytelnianiu zintegrowanemu tylko z interfejsem SSPI systemu Windows) oraz Authentication=ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal.

SQLDriverConnect Prompt (tylko sterownik systemu Windows)

Okno dialogowe monitu wyświetlane przez program SQLDriverConnect, gdy żąda informacji wymaganych do ukończenia połączenia, zawiera cztery nowe opcje uwierzytelniania firmy Microsoft Entra:

Te opcje odpowiadają tej samej szóstce dostępnej w interfejsie użytkownika konfiguracji DSN powyżej.

Przykładowe parametry połączenia

1. Uwierzytelnianie programu SQL Server — starsza składnia. Certyfikat serwera nie jest weryfikowany, a szyfrowanie jest używane tylko wtedy, gdy serwer go wymusza. Nazwa użytkownika/hasło są przekazywane w parametrach połączenia.

   server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;

2. Uwierzytelnianie SQL — nowa składnia. Klient żąda szyfrowania (wartość Encrypt domyślna to true) i certyfikat serwera jest weryfikowany, niezależnie od ustawienia szyfrowania (chyba że TrustServerCertificate ustawiono wartość true). Nazwa użytkownika/hasło są przekazywane w parametrach połączenia.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;

3. Zintegrowane uwierzytelnianie systemu Windows (Kerberos w systemach Linux i macOS) przy użyciu SSPI (do programu SQL Server lub SQL IaaS) — bieżąca składnia. Certyfikat serwera nie jest weryfikowany, chyba że szyfrowanie jest wymagane przez serwer.

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

4. (Tylko sterownik systemu Windows). Zintegrowane uwierzytelnianie systemu Windows przy użyciu interfejsu SSPI (jeśli docelowa baza danych znajduje się w programie SQL Server lub programie SQL Server na maszynach wirtualnych platformy Azure) — nowa składnia. Klient żąda szyfrowania (wartość Encrypt domyślna to true) i certyfikat serwera jest weryfikowany, niezależnie od ustawienia szyfrowania (chyba że TrustServerCertificate ustawiono wartość true).

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

5. Uwierzytelnianie za pomocą nazwy użytkownika/hasła Microsoft Entra (jeśli docelowa baza danych znajduje się w usłudze Azure SQL Database lub Azure SQL Managed Instance). Certyfikat serwera jest weryfikowany, bez względu na ustawienie szyfrowania (chyba że TrustServerCertificate jest ustawione na true). Nazwa użytkownika/hasło są przekazywane w parametrach połączenia.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Tylko sterowniki dla systemów Windows i Linux/macOS 17.6 lub nowszych). Zintegrowane uwierzytelnianie systemu Windows przy użyciu ADAL lub Kerberos, obejmujące wymianę poświadczeń konta systemu Windows na token dostępu Microsoft Entra, przy założeniu, że docelowa baza danych znajduje się w usłudze Azure SQL. Certyfikat serwera jest weryfikowany niezależnie od ustawienia szyfrowania (chyba że TrustServerCertificate ustawiono wartość true). W systemie Linux/macOS odpowiedni bilet Kerberos musi być dostępny. Aby uzyskać więcej informacji, zobacz sekcję poniżej dotyczącą kont federacyjnych i Używanie zintegrowanego uwierzytelniania.

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

7. (Tylko sterownik systemu Windows). Usługa Microsoft Entra Interactive Authentication używa technologii uwierzytelniania wieloskładnikowego firmy Microsoft do konfigurowania połączenia. W tym trybie, podając identyfikator logowania, zostanie wyzwolone okno dialogowe uwierzytelniania platformy Azure i umożliwi użytkownikowi wprowadzenie dodatkowej weryfikacji w celu ukończenia połączenia. Nazwa użytkownika jest przekazywana w parametrach połączenia.

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

   

8. Uwierzytelnianie tożsamości zarządzanej przez Microsoft Entra może używać tożsamości zarządzanej przypisanej systemowo lub użytkownikowi. W przypadku tożsamości przypisanej przez użytkownika ustaw identyfikator UID na identyfikator klienta tej tożsamości w usłudze Azure App Service lub w usłudze Azure Container Instance. W przeciwnym razie użyj identyfikatora obiektu. W przypadku tożsamości przypisanej przez system identyfikator UID nie jest wymagany.
   

   W przypadku tożsamości przypisanej przez system:

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

   W przypadku tożsamości przypisanej użytkownikowi z identyfikatorem obiektu równym myObjectId:

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

9. Uwierzytelnianie jednostki usługi Microsoft Entra

server=Server;database=Database;UID=clientId;PWD=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Uwagi

• W przypadku korzystania z opcji Microsoft Entra ze sterownikiem ODBC systemu Windows przed wersją 17.4.2 upewnij się, że biblioteka uwierzytelniania usługi Active Directory dla programu SQL Server została zainstalowana. W przypadku korzystania z sterowników systemu Linux i macOS upewnij się, że libcurl została zainstalowana. W przypadku sterownika w wersji 17.2 lub nowszej nie jest to jawna zależność, ponieważ nie jest wymagana dla innych metod uwierzytelniania ani operacji ODBC.

• Jeśli konfiguracja firmy Microsoft Entra obejmuje zasady dostępu warunkowego, a klient ma system Windows 10 lub Server 2016 lub nowszy, uwierzytelnianie za pomocą zintegrowanej lub nazwy użytkownika/hasła może zakończyć się niepowodzeniem. Zasady dostępu warunkowego wymagają użycia Menedżera kont sieci Web (WAM), który jest obsługiwany w wersji sterownika 17.6 lub nowszej dla systemu Windows. Aby użyć WAM, utwórz nową wartość ciągu o nazwie ADALuseWAM w HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> lub HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> dla konfiguracji o zasięgu globalnym, użytkownika DSN lub systemowym DSN i ustaw ją na wartość 1. Należy pamiętać, że uwierzytelnianie za pomocą WAM nie obsługuje uruchamiania aplikacji jako inny użytkownik z runas. Scenariusze wymagające zasad dostępu warunkowego nie są obsługiwane w systemie Linux lub macOS.

• Aby nawiązać połączenie przy użyciu nazwy użytkownika i hasła konta programu SQL Server, możesz teraz użyć nowej SqlPassword opcji, która jest zalecana szczególnie w przypadku usługi Azure SQL, ponieważ ta opcja włącza bezpieczniejsze ustawienia domyślne połączeń.

• Aby nawiązać połączenie przy użyciu nazwy użytkownika i hasła konta Microsoft Entra, określ Authentication=ActiveDirectoryPassword w parametrze połączenia oraz użyj słów kluczowych UID i PWD dla nazwy użytkownika i hasła, odpowiednio.

• Aby nawiązać połączenie przy użyciu uwierzytelniania zintegrowanego z systemem Windows lub Microsoft Entra Integrated (Windows i Linux/macOS 17.6+, tylko sterownik), w parametrach połączenia podaj Authentication=ActiveDirectoryIntegrated. Sterownik automatycznie wybierze prawidłowy tryb uwierzytelniania. W przypadku sterowników w wersji 17.7 lub starszej nie należy określać UID i PWD. Począwszy od wersji sterownika 17.8, UID oraz PWD są ignorowane.

• Aby nawiązać połączenie przy użyciu interaktywnego uwierzytelniania Microsoft Entra (tylko sterownik systemu Windows), należy określić UID. W przypadku sterowników w wersji 17.7 lub starszej PWD nie można określić. Począwszy od wersji sterownika 17.8, PWD jest ignorowany.

• Począwszy od wersji 18.1, Trusted_Connection=Yes nie używa już domyślnie uwierzytelniania federacyjnego Microsoft Entra ID i zamiast tego używa zintegrowanego interfejsu SSPI. Aby użyć Microsoft Entra ID dla tej opcji, należy skonfigurować TrustedConnection_UseAAD=Yes.

• Sterowniki ODBC w wersji 17.7 i niższej mają znany problem z przekroczeniem limitu czasu połączenia, gdy w instancji SQL Server włączono uwierzytelnianie Microsoft Entra i Wymuszone Szyfrowanie. Dziennik błędów programu SQL Server może zawierać komunikaty o błędach, takie jak: "Błąd: 33155, Ważność: 20, Stan: 1. Zdarzenie rozłączenia zostało zgłoszone, gdy serwer czeka na token uwierzytelniania federacyjnego. Może to być spowodowane wygaśnięciem limitu czasu zamknięcia klienta lub przekroczenia limitu czasu serwera". Jeśli używasz rozwiązań o wysokiej dostępności, takich jak grupy dostępności Always On lub klastry trybu przełączania awaryjnego, wewnętrzna komunikacja klastra dla programu SQL Server może wpłynąć na dostępność zasobów. W dzienniku klastra mogą być wyświetlane komunikaty o błędach, takie jak: [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). Sterowniki ODBC w wersji 17.10 i nowszej rozwiązują ten problem i wraz z programem SQL Server 2022 GDR KB5021522 /CU1 KB5022375 najnowszy sterownik zawierający te poprawki jest instalowany z programem SQL Server. Możesz sprawdzić, która wersja sterownika ODBC została zainstalowana, odwołując się do administratora źródła danych ODBC.

• Począwszy od sterownika ODBC w wersji 18.3, uwierzytelnianie tożsamości zarządzanej (ActiveDirectoryMSI) jest obsługiwane w usługach Azure Arc i Azure Cloud Shell.

Uwierzytelnianie przy użyciu tokenu dostępu

Atrybut SQL_COPT_SS_ACCESS_TOKEN przed połączeniem umożliwia użycie tokenu dostępu uzyskanego z identyfikatora Entra firmy Microsoft do uwierzytelniania zamiast nazwy użytkownika i hasła, a także pomija negocjacje i uzyskiwanie tokenu dostępu przez sterownik. Aby użyć tokenu dostępu, ustaw atrybut połączenia SQL_COPT_SS_ACCESS_TOKEN na strukturę ACCESSTOKEN za pomocą wskaźnika:

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

To ACCESSTOKEN struktura o zmiennej długości składająca się z 4-bajtowej długości, po której następuje długość bajtów nieprzezroczystych danych tworzących token dostępu. Ze względu na sposób obsługi tokenów dostępu przez program SQL Server, token uzyskany za pośrednictwem odpowiedzi OAuth 2.0 JSON należy rozszerzyć tak, aby każdy bajt był rozszerzony o bajt zerowy, podobnie jak w ciągu UCS-2 zawierającym wyłącznie znaki ASCII. Jednak token jest nieprzezroczystą wartością, a określona długość w bajtach nie może zawierać żadnego separatora wartości null. Ze względu na ich znaczną długość i ograniczenia formatu ta metoda uwierzytelniania jest dostępna tylko programowo za pośrednictwem atrybutu SQL_COPT_SS_ACCESS_TOKEN połączenia. Nie ma odpowiedniej nazwy DSN ani słowa kluczowego parametrów połączenia. Parametry połączenia nie mogą zawierać UIDsłów kluczowych , PWD, Authenticationlub Trusted_Connection .

Uwaga / Notatka

Sterownik ODBC w wersji 13.1 obsługuje tylko to uwierzytelnianie w systemie Windows. Kolejne wersje obsługują to uwierzytelnianie na wszystkich platformach.

Przykładowy kod uwierzytelniania firmy Microsoft Entra

Poniższy przykład przedstawia kod wymagany do nawiązania połączenia z programem SQL Server przy użyciu identyfikatora Entra firmy Microsoft ze słowami kluczowymi połączenia. Nie trzeba zmieniać samego kodu aplikacji. Parametry połączenia lub nazwa DSN, jeśli jest używana, są jedynymi modyfikacjami wymaganymi do użycia Microsoft Entra ID do uwierzytelniania.

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

Poniższy przykład przedstawia kod wymagany do nawiązania połączenia z programem SQL Server przy użyciu uwierzytelniania tokenu dostępu firmy Microsoft Entra. W takim przypadku należy zmodyfikować kod aplikacji w celu przetworzenia tokenu dostępu i ustawienia skojarzonego atrybutu połączenia.

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

Następujący przykładowy ciąg połączenia jest używany z interaktywnym uwierzytelnianiem Microsoft Entra. Nie zawiera pola PWD, ponieważ hasło zostanie wprowadzone na ekranie uwierzytelniania platformy Azure.

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

Poniższy przykładowy łańcuch połączenia jest przeznaczony do użycia z uwierzytelnianiem tożsamości zarządzanej Microsoft Entra. UID jest ustawiany na identyfikator obiektu/klienta tożsamości użytkownika podczas korzystania z przypisanej tożsamości użytkownika.

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

Zagadnienia dotyczące korzystania z kont federacyjnych usług AD FS w systemie Linux/macOS

Począwszy od wersji 17.6, sterowniki dla systemów Linux i macOS obsługują uwierzytelnianie przy użyciu kont federacyjnych Microsoft Entra ADFS przy użyciu nazwy użytkownika/hasła (ActiveDirectoryPassword) lub Kerberos (ActiveDirectoryIntegrated). Istnieją pewne ograniczenia zależne od platformy w przypadku korzystania z trybu zintegrowanego.

W przypadku uwierzytelniania użytkownika, którego sufiks nazwy UPN różni się od obszaru Protokołu Kerberos, to znaczy, że używany jest alternatywny sufiks UPN, należy użyć opcji Podstawowa tożsamość przedsiębiorstwa (użyj -E opcji z kinit, a następnie podaj nazwę główną w formularzu user@federated-domain) podczas uzyskiwania biletów Kerberos. Dzięki temu sterownik może poprawnie określić zarówno domenę federacyjną, jak i obszar protokołu Kerberos.

Aby zweryfikować dostępność odpowiedniego biletu protokołu Kerberos, przeanalizuj dane wyjściowe polecenia klist. Jeśli domena federacyjna jest taka sama jak dziedzina Kerberos i sufiks UPN, nazwa główna ma postać user@realm. Jeśli jest inna, główna nazwa powinna mieć postać user@federated-domain@realm.

Linux

W systemie SUSE 11 domyślna wersja 1.6.x biblioteki Kerberos nie obsługuje opcji Głównego użytkownika przedsiębiorstwa, która jest niezbędna do korzystania z alternatywnych sufiksów UPN. Aby użyć alternatywnych sufiksów nazwy UPN z zintegrowanym uwierzytelnianiem firmy Microsoft, uaktualnij bibliotekę Kerberos do wersji 1.7 lub nowszej.

W systemie Alpine Linux wartość domyślna libcurl nie obsługuje uwierzytelniania SPNEGO/Kerberos wymaganego do zintegrowanego uwierzytelniania firmy Microsoft Entra.

macOS

Biblioteka systemu Kerberos kinit obsługuje Principal Enterprise z opcją --enterprise, ale także niejawnie przeprowadza kanonizację nazw, co uniemożliwia użycie alternatywnych sufiksów UPN. Aby używać alternatywnych sufiksów UPN z zintegrowanym uwierzytelnianiem Microsoft Entra, zainstaluj nowszą bibliotekę Kerberos za pomocą brew install krb5 i użyj jej kinit z opcją -E, jak opisano powyżej.

Treści powiązane

• Obsługa uwierzytelniania opartego na tokenach dla usługi Azure SQL Database przy użyciu uwierzytelniania firmy Microsoft Entra
• Korzystanie ze zintegrowanego uwierzytelniania