ODBC ドライバードライバー で Microsoft Entra ID を使用する
Note
Microsoft Entra ID はAzure Active Directory (Azure AD) の新しい名前ですが、既存の環境の中断を防ぐために、UI フィールド、接続プロバイダー、エラー コード、コマンドレットなど、ハードコーディングされた一部の要素でAzure AD が残ります。 この記事では、2 つの名前は交換可能です。
目的
Microsoft ODBC Driver for SQL Server バージョン 13.1 以上を使用すると、Microsoft Entra ID の ID を使用して ODBC アプリケーションで Azure SQL データベースまたは Azure SQL Managed Instance に接続できるようになります。 認証は、ユーザー名とパスワード、Microsoft Entra アクセス トークン、Microsoft Entra マネージド ID (17.3 以降)、またはフェデレーション、ドメイン参加済み環境 (Linux/macOS 17.6 以降) の統合 Windows 認証で行うことができます。 ODBC ドライバー バージョン 13.1 の場合、Microsoft Entra アクセス トークン認証は Windows のみです。 ODBC ドライバー バージョン 17 以降では、すべてのプラットフォーム (Windows、Linux、macOS) でこの認証がサポートされます。 多要素認証をサポートする新しい Microsoft Entra 対話型認証方法が、ODBC ドライバー バージョン 17.1 for Windows で導入されました。 Microsoft Entra マネージド ID 認証メソッドは、ODBC ドライバー バージョン 17.3.1.1 で、システム割り当てとユーザー割り当ての両方の マネージド ID に対して追加されました。 これらすべてのオプションは、新しい DSN と接続文字列のキーワード、および接続属性を使用すると実現します。
Microsoft Entra 認証を使用するには、Azure SQL データ ソースを構成する必要があります。 詳細については、Azure SQL による Microsoft Entra 認証の構成と管理を参照してください。
Note
バージョン 17.6 より前の Linux および macOS 上の ODBC ドライバーでは、Microsoft Entra ID に対する Microsoft Entra 認証のみが直接サポートされています。 Linux または macOS クライアントから Microsoft Entra のユーザー名とパスワード認証を使用しており、Microsoft Entra 構成によって、クライアントに Microsoft Entra フェデレーション サービス エンドポイントに対する認証が要求されている場合は、認証が失敗する可能性があります。 ドライバー バージョン 17.6 の時点でこの制限は削除されました。
新しいまたは変更された DSN と接続文字列のキーワード
DSN または接続文字列を使用して接続する場合、Authentication キーワードを使用して認証モードを制御できます。 接続文字列で設定された値は、DSN の値 (指定されている場合) をオーバーライドします。 Authentication 設定の "事前属性値" は、接続文字列および DSN の値から計算された値です。
| 名前 | 値 | 既定 | 説明 | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Authentication |
(未設定)、(空の文字列)、SqlPassword、ActiveDirectoryPassword、ActiveDirectoryIntegrated、ActiveDirectoryInteractive、ActiveDirectoryMsi、ActiveDirectoryServicePrincipal |
(未設定) | 認証モードを制御します。
|
||||||||||||||||||
Encrypt |
(設定なし)、Yes/Mandatory (18.0 以降)、OptionalNo/ (18.0 以降)、Strict (18.0 以降) |
(説明を参照) | 接続の暗号化を制御します。 DSN または接続文字列で Authentication 設定の事前属性値が none でない場合、既定値は Yes です。 バージョン 18.0.1 以降でも、既定値は Yesです。 それ以外の場合、既定値は No です。 属性 SQL_COPT_SS_AUTHENTICATION によって Authentication の事前属性値がオーバーライドされる場合は、DSN か接続文字列または接続属性で暗号化の値を明示的に設定します。 暗号化の事前属性値は、その値が DSN または接続文字列のいずれかで Yes に設定されている場合は Yes です。 |
新しいまたは変更された接続属性
次の接続前接続属性は、Microsoft Entra 認証をサポートするために導入または変更されています。 接続属性に対応する接続文字列または DSN キーワードがあり、接続属性が設定されている場合は、接続属性が優先されます。
| 属性 | Type | 値 | 既定 | 説明 |
|---|---|---|---|---|
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 |
(未設定) | 上記の Authentication キーワードの説明を参照してください。 SQL_AU_NONE は、DSN または接続文字列で設定された Authentication 値を明示的にオーバーライドするために用意されています。それに対し、SQL_AU_RESET では、属性が設定されている場合にそれを設定解除し、DSN または接続文字列の値を優先できるようにします。 |
SQL_COPT_SS_ACCESS_TOKEN |
SQL_IS_POINTER |
ACCESSTOKEN へのポインターまたは NULL |
NULL | null 以外の場合は、使用する Microsoft Entra アクセス トークンを指定します。 アクセス トークンを指定し、同時に UID、PWD、Trusted_Connection、または Authentication 接続文字列キーワードあるいはそれらと同等の属性を指定すると、エラーになります。 注: ODBC ドライバー バージョン 13.1 では、Windows でのみこの設定がサポートされます。 |
SQL_COPT_SS_ENCRYPT |
SQL_IS_INTEGER |
SQL_EN_OFF、SQL_EN_ON |
(説明を参照) | 接続の暗号化を制御します。 SQL_EN_OFF を指定すると暗号化が無効になり、SQL_EN_ON を指定すると有効になります。 Authentication 設定の事前属性値が none ではないか、または SQL_COPT_SS_ACCESS_TOKEN が設定されていて、DSN または接続文字列のいずれかで Encrypt が指定されていなかった場合、既定値は SQL_EN_ON です。 それ以外の場合、既定値は SQL_EN_OFF です。 接続属性 SQL_COPT_SS_AUTHENTICATION が none 以外に設定されていて、DSN または接続文字列で Encrypt が指定されていなかった場合は、SQL_COPT_SS_ENCRYPT を必要な値に明示的に設定してください。 この属性の有効な値によって、接続に暗号化を使用するかどうかが制御されます。 |
SQL_COPT_SS_OLDPWD |
- | - | - | Microsoft Entra プリンシパルに対するパスワードの変更は ODBC 接続ではできないため、Microsoft Entra ID ではサポートされていません。 SQL Server 2005 では、SQL Server 認証におけるパスワードの期限切れが導入されました。 クライアントから接続の古いパスワードと新しいパスワードの両方を提供できるようにするために、 SQL_COPT_SS_OLDPWD 属性が追加されました。 このプロパティが設定されている場合、接続文字列には変更された "古いパスワード" が含まれているので、プロバイダーでは最初の接続または今後の接続で接続プールが使用されません。 |
SQL_COPT_SS_INTEGRATED_SECURITY |
SQL_IS_INTEGER |
SQL_IS_OFF、SQL_IS_ON |
SQL_IS_OFF |
"非推奨" です。代わりに SQL_COPT_SS_AUTHENTICATION を SQL_AU_AD_INTEGRATED に設定して使用してください。 サーバー ログインでのアクセス検証に Windows 認証 (Linux と macOS では Kerberos) を使用するように強制します。 Windows 認証を使用すると、ドライバーでは SQLConnect、SQLDriverConnect、または SQLBrowseConnect の処理の一環として提供されるユーザー ID とパスワードが無視されます。 |
Microsoft Entra ID の UI の追加 (Windows ドライバーのみ)
ドライバーの DSN セットアップと接続の UI が拡張され、Microsoft Entra ID による認証を使用するために必要なオプションが追加されました。
UI で DSN を作成および編集する
ドライバーのセットアップ UI を使用して既存の DSN を作成または編集する際に、Microsoft Entra 認証オプションを使用できます。
Azure SQL への Microsoft Entra 統合認証のための Authentication=ActiveDirectoryIntegrated
Azure SQL への Microsoft Entra ユーザー名/パスワード認証のための Authentication=ActiveDirectoryPassword
Azure SQL への Microsoft Entra 対話型認証のための Authentication=ActiveDirectoryInteractive
Note
ドライバー バージョン 17.9 より、対話型の認証動作が変更されました。 有効なアクセス トークンがドライバーにキャッシュされていない限り、ユーザーは常に資格情報の入力を求められます。 この変更により、ActiveDirectoryInteractive 認証を使用するときに、Microsoft Entra 参加済みデバイスのユーザーがプロンプトをスキップし、キャッシュされた認証情報で自動的にサインインできなくなります。
SQL Server および Azure SQL に対するユーザー名/パスワード認証のための Authentication=SqlPassword
Windows レガシ SSPI 統合認証の場合: Trusted_Connection=Yes
Microsoft Entra マネージド ID 認証のための Authentication=ActiveDirectoryMsi
Microsoft Entra サービス プリンシパル認証のための Authentication=ActiveDirectoryServicePrincipal
7 つのオプションは、それぞれ Trusted_Connection=Yes (既存のレガシ Windows SSPI のみの統合認証) と Authentication= ActiveDirectoryIntegrated、SqlPassword、ActiveDirectoryPassword、ActiveDirectoryInteractive、ActiveDirectoryMsi、ActiveDirectoryServicePrincipal に対応しています。
SQLDriverConnect プロンプト (Windows ドライバーのみ)
SQLDriverConnect が表示する、接続を完了するために必要な情報を要求するプロンプト ダイアログには、Microsoft Entra 認証に関する 4 つの新しいオプションが含まれています。
これらのオプションは、上記の DSN セットアップ UI で使用できるものと同じ 6 つのオプションに対応しています。
接続文字列の例
SQL Server 認証 - レガシ構文。 サーバー証明書は検証されず、暗号化はサーバーで適用される場合にのみ使用されます。 ユーザー名/パスワードは接続文字列内で渡されます。
server=Server;database=Database;UID=UserName;PWD=Password;Encrypt=no;TrustServerCertificate=yes;SQL 認証 - 新しい構文。 クライアントによって暗号化が要求されます (
Encryptの既定値はtrue)。サーバー証明書は、暗号化の設定に関係なく検証されます (TrustServerCertificateがtrueに設定されている場合を除く)。 ユーザー名/パスワードは接続文字列内で渡されます。server=Server;database=Database;UID=UserName;PWD=Password;Authentication=SqlPassword;(SQL Server または SQL IaaS に対する) SSPI を使用した統合 Windows 認証 (Linux と macOS では Kerberos) - 現在の構文。 サーバーに暗号化が使用でない限り、サーバー証明書は検証されません。
server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;(Windows ドライバーのみ。)SSPI を使用した統合 Windows 認証 (ターゲット データベースが SQL Server または Azure VM 内のSQL Server にある場合) - 新しい構文。 クライアントによって暗号化が要求されます (
Encryptの既定値はtrue)。サーバー証明書は、暗号化の設定に関係なく検証されます (TrustServerCertificateがtrueに設定されている場合を除く)。server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Microsoft Entra ユーザー名/パスワード認証 (ターゲット データベースが Azure SQL データベースまたは Azure SQL Managed Instance 内にある場合)。 暗号化の設定に関係なく、サーバー証明書は検証されます (
TrustServerCertificateがtrueに設定されている場合を除く)。 ユーザー名/パスワードは接続文字列内で渡されます。server=Server;database=Database;UID=UserName;PWD=Password;Authentication=ActiveDirectoryPassword;Encrypt=yes;(Windows および Linux/macOS 17.6+ ドライバーのみ)。ADAL または Kerberos を使用した統合 Windows 認証。ターゲット データベースが Azure SQL 内にあると想定して、Microsoft Entra によって発行されたアクセス トークンの Windows アカウント認証情報を使用します。 暗号化の設定に関係なく、サーバー証明書は検証されます (
TrustServerCertificateがtrueに設定されている場合を除く)。 Linux または macOS では、適切な Kerberos チケットを使用できる必要があります。 詳細については、以下のフェデレーション アカウントに関するセクションと「統合認証を使用する」を参照してください。server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;(Windows ドライバーのみ。) Microsoft Entra 対話型認証 では、Microsoft Entra 多要素認証テクノロジを使用して接続を設定します。 このモードでは、ログイン ID を指定することで Azure 認証ダイアログがトリガーされ、ユーザーが追加認証を入力して接続を完了できます。 ユーザー名は接続文字列内で渡されます。
server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;
Microsoft Entra マネージド ID 認証では、システム割り当てマネージド ID またはユーザー割り当てマネージド ID を使用できます。 ユーザー割り当て ID の場合は、UID を Azure App Service または Azure Container Instance の ID のクライアント ID に設定します。それ以外の場合は、そのオブジェクト ID を使用します。 システム割り当て ID の場合、UID は必要ありません。
システム割り当て ID の場合:
server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;オブジェクト ID が
myObjectIdであるユーザー割り当て ID の場合:server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;Microsoft Entra サービス プリンシパル認証
server=Server;database=Database;UID=clientId;PWD=clientSecret;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;
解説
バージョン 17.4.2 より前の Windows ODBC ドライバーで Microsoft Entra オプションを使用する場合は、SQL Server 用 Active Directory 認証ライブラリがインストールされていることを確認します。 Linux および macOS ドライバーを使用する場合は、
libcurlがインストールされていることを確認します。 ドライバー バージョン 17.2 以降では、これが明示的な依存関係にはなりません。他の認証方法や ODBC 操作では不要であるためです。Microsoft Entra 構成に条件付きアクセス ポリシーが含まれ、クライアントが Windows 10 または Server 2016 以降である場合は、統合またはユーザー名/パスワードによる認証は失敗する可能性があります。 条件付きアクセス ポリシーでは、Web アカウント マネージャー (WAM) を使用する必要があります。これは、Windows のドライバー バージョン 17.6 以降でサポートされています。 WAM を使用するには、グローバル、ユーザー DSN、またはシステム DSN スコープの構成に対してそれぞれ
ADALuseWAM、HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server、またはHKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name>にHKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name>という名前の新しい文字列値を作成し、値 1 に設定します。 なお、WAM での認証では、runasを使用して別のユーザーとしてアプリケーションを実行することはサポートされていません。 条件付きアクセス ポリシーを必要とするシナリオは、Linux および macOS ではサポートされていません。SQL Server アカウントのユーザー名とパスワードを使用して接続する場合、新しい
SqlPasswordオプションを使用できるようになりました。このオプションは、より安全性の高い接続の既定値が有効になるので、Azure SQL では特にお勧めします。Microsoft Entra アカウントのユーザー名とパスワードを使用して接続するには、接続文字列に
Authentication=ActiveDirectoryPasswordを指定し、ユーザー名とパスワードではそれぞれUIDとPWDキーワードを指定します。Windows 統合または Microsoft Entra 統合 (Windows および Linux/macOS 17.6+ ドライバーのみ) 認証を使用して接続するには、接続文字列に
Authentication=ActiveDirectoryIntegratedを指定します。 ドライバーによって適切な認証モードが自動的に選択されます。 ドライバー バージョン 17.7 以前では、UIDとPWDを指定することはできません。 ドライバー バージョン 17.8 以降では、UIDとPWDは無視されます。Microsoft Entra 対話型認証 (Windows ドライバーのみ) を使用して接続するには、
UIDを指定する必要があります。 ドライバー バージョン 17.7 以前では、PWDを指定することはできません。 ドライバー バージョン 17.8 以降では、PWDは無視されます。バージョン 18.1 以降の
Trusted_Connection=Yesの既定では、Microsoft Entra ID フェデレーション認証は使われなくなり、代わりに SSPI 統合が使われます。 このオプションに Microsoft Entra ID を使用するには、TrustedConnection_UseAAD=Yesを構成する必要があります。ODBC ドライバー バージョン 17.7 以前では、SQL Server インスタンスで Microsoft Entra 認証と強制暗号化が有効になっている場合の接続タイムアウトに関する既知の問題があります。 SQL Server エラー ログには、「エラー: 33155、重大度: 20、状態: 1: サーバーがフェデレーション認証トークンを待機しているときに接続解除イベントが発生しました。この原因としては、クライアントが閉じていたか、サーバーのタイムアウト期限が切れたことが考えられます。」などのエラー メッセージが含まれている場合があります。 Always On 可用性グループやフェールオーバー クラスター インスタンスなどの 高可用性ソリューションを使用している場合、SQL Server の内部クラスター通信は、この動作によってリソースの可用性に影響が生じる可能性があります。 クラスター ログに、次のような
[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)エラー メッセージが表示される場合があります。 ODBC ドライバー バージョン 17.10 以降では、この問題が解決され、SQL Server 2022 GDR KB5021522/CU1 KB5022375 では、この修正プログラムを含む最新のドライバーが SQL Server インストールと共にインストールされます。 ODBC データ ソース管理者を参照することで、インストールした ODBC ドライバーのバージョンを確認できます。ODBC ドライバー バージョン 18.3 以降では、Azure Arc と Azure Cloud Shell でマネージド ID (ActiveDirectoryMSI) 認証がサポートされています。
アクセス トークンを使用した認証
SQL_COPT_SS_ACCESS_TOKEN 接続前属性を使用すると、ユーザー名とパスワードではなく Microsoft Entra ID から取得したアクセス トークンを認証に使用できます。また、ドライバーによるアクセス トークンのネゴシエーションと取得もバイパスされます。 アクセス トークンを使用するには、SQL_COPT_SS_ACCESS_TOKEN 接続属性を ACCESSTOKEN 構造体へのポインターに設定します。
typedef struct AccessToken
{
DWORD dataSize;
BYTE data[];
} ACCESSTOKEN;
ACCESSTOKEN は、4 バイト長と、その後のアクセス トークンを形成する不透明データのバイト長によって構成される、可変長構造体です。 SQL Server によるアクセス トークンの処理方法が原因で、OAuth 2.0 JSON 応答を介して取得されたものを拡張して、ASCII 文字のみを含む UCS-2 文字列のように、各バイトの後にゼロ パディング バイトを続ける必要があります。 しかし、トークンは不透明値であり、バイト単位で指定する長さに null 終端文字を含めることはできません。 この認証方法は、長さと形式の制約が非常に多いため、SQL_COPT_SS_ACCESS_TOKEN 接続属性を使用してプログラムでのみ使用できます。 対応する DSN や接続文字列のキーワードはありません。 接続文字列には、UID、PWD、Authentication、または Trusted_Connection キーワードを含めることはできません。
注意
ODBC ドライバー バージョン 13.1 では、Windows でのみこの認証がサポートされます。 以降のバージョンでは、すべてのプラットフォームでこの認証がサポートされています。
Microsoft Entra 認証サンプル コード
次のサンプルは、Microsoft Entra ID を使用して接続キーワードによって SQL Server に接続するために必要なコードを示しています。 アプリケーション コード自体を変更する必要はありません。 認証に Microsoft Entra ID を使用するために必要な変更は、接続文字列または DSN (使用されている場合) だけです。
...
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);
...
次のサンプルは、Microsoft Entra を使用してアクセス トークン認証によって SQL Server に接続するために必要なコードを示しています。 この場合、アクセス トークンを処理し、関連する接続属性を設定するためにアプリケーション コードの変更が必要です。
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);
以下のサンプルの接続文字列は、Microsoft Entra 対話型認証で使用します。 パスワードは Azure 認証画面で入力されるため、PWD フィールドは含まれていません。
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"
次のサンプル接続文字列は、Microsoft Entra マネージド ID 認証で使用されます。 ユーザーが割り当てた ID を使用する場合、UID はユーザー ID のオブジェクト/クライアント ID に設定されます。
// 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;"
Linux/macOS で ADFS フェデレーション アカウントを使用する場合の考慮事項
バージョン 17.6 以降、Linux および macOS 用のドライバーでは、ユーザー名/パスワード (ActiveDirectoryPassword) または Kerberos (ActiveDirectoryIntegrated) を使用した Microsoft Entra ADFS フェデレーション アカウントによる認証をサポートしています。 統合モードを使用する場合、プラットフォームによって異なるいくつかの制限があります。
UPN サフィックスが Kerberos 領域とは異なるユーザー、つまり、代替 UPN サフィックスが使用されているユーザーで認証する場合は、Kerberos チケットを取得するときに Enterprise Principal オプション (kinit で -E オプションを使用し、user@federated-domain の形式でプリンシパル名を指定) を使用する必要があります。 この方法により、ドライバーでフェデレーション ドメインと Kerberos 領域の両方を正しく判断できます。
klist コマンドの出力を調べることにより、適切な Kerberos チケットが使用可能であることを確認できます。 フェデレーション ドメインが Kerberos 領域と UPN サフィックスと同じ場合、プリンシパル名は user@realm の形式になります。 異なる場合は、プリンシパル名を user@federated-domain@realm の形式にする必要があります。
Linux
SUSE 11 では、既定の Kerberos ライブラリ バージョン 1.6.x で、代替 UPN サフィックスを使用するために必要な Enterprise Principal オプションはサポートされていません。 Microsoft Entra 統合認証で代替 UPN サフィックスを使用するには、Kerberos ライブラリを 1.7 以降にアップグレードします。
Alpine Linux では、既定の libcurl で、Microsoft Entra 統合認証に必要な SPNEGO/Kerberos 認証をサポートされていません。
macOS
システム Kerberos ライブラリ kinit では、--enterprise オプションを使用した Enterprise Principal がサポートされますが、暗黙的に名前の正規化も行われます。これにより、代替 UPN サフィックスを使用できなくなります。 Microsoft Entra 統合認証で代替 UPN サフィックスを使用するには、brew install krb5 を介して新しい Kerberos ライブラリをインストールし、前述のように -E オプションと共に kinit を使用します。