ODBC ドライバードライバー で Microsoft Entra ID を使用する

ODBC ドライバーのダウンロード

目的

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 認証の構成と管理を参照してください。

新しいまたは変更された DSN と接続文字列のキーワード

DSN または接続文字列を使用して接続する場合、Authentication キーワードを使用して認証モードを制御できます。 接続文字列で設定された値は、DSN の値 (指定されている場合) をオーバーライドします。 Authentication 設定の "事前属性値" は、接続文字列および DSN の値から計算された値です。

新しいまたは変更された接続属性

次の接続前接続属性は、Microsoft Entra 認証をサポートするために導入または変更されています。 接続属性に対応する接続文字列または DSN キーワードがあり、接続属性が設定されている場合は、接続属性が優先されます。

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

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 つのオプションに対応しています。

接続文字列の例

1. SQL Server 認証 - レガシ構文。 サーバー証明書は検証されず、暗号化はサーバーで適用される場合にのみ使用されます。 ユーザー名/パスワードは接続文字列内で渡されます。

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

2. SQL 認証 - 新しい構文。 クライアントによって暗号化が要求されます (Encrypt の既定値は true)。サーバー証明書は、暗号化の設定に関係なく検証されます (TrustServerCertificate が true に設定されている場合を除く)。 ユーザー名/パスワードは接続文字列内で渡されます。

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

3. (SQL Server または SQL IaaS に対する) SSPI を使用した統合 Windows 認証 (Linux と macOS では Kerberos) - 現在の構文。 サーバーに暗号化が使用でない限り、サーバー証明書は検証されません。

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

4. (Windows ドライバーのみ。)SSPI を使用した統合 Windows 認証 (ターゲット データベースが SQL Server または Azure VM 内のSQL Server にある場合) - 新しい構文。 クライアントによって暗号化が要求されます (Encrypt の既定値は true)。サーバー証明書は、暗号化の設定に関係なく検証されます (TrustServerCertificate が true に設定されている場合を除く)。

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

5. Microsoft Entra ユーザー名/パスワード認証 (ターゲット データベースが Azure SQL データベースまたは Azure SQL Managed Instance 内にある場合)。 暗号化の設定に関係なく、サーバー証明書は検証されます (TrustServerCertificate が true に設定されている場合を除く)。 ユーザー名/パスワードは接続文字列内で渡されます。

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

6. (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;

7. (Windows ドライバーのみ。) Microsoft Entra 対話型認証 では、Microsoft Entra 多要素認証テクノロジを使用して接続を設定します。 このモードでは、ログイン ID を指定することで Azure 認証ダイアログがトリガーされ、ユーザーが追加認証を入力して接続を完了できます。 ユーザー名は接続文字列内で渡されます。

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

   

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

9. 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 キーワードを含めることはできません。

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 を使用します。

関連するコンテンツ

• Microsoft Entra 認証を使用して Azure SQL データベースのトークン ベース認証をサポート
• 統合認証を使用する