この記事では、Kusto クライアント ライブラリで使用できるプライマリ認証方法の概要について説明します。 コード スニペットは、ユーザーとアプリを認証するさまざまな方法を示しています。これにより、Kusto クラスターとのシームレスな対話が可能になります。 各方法は、さまざまなシナリオと要件に適しています。
可能な限り、ユーザー名とパスワードの認証または接続文字列の代わりにマネージド ID を使用します。 マネージド ID は、認証に対するより安全で合理化されたアプローチを提供します。
この記事では、次を使用して認証する方法について説明します。
アプリケーション主要項目
ユーザー プリンシパル
カスタム トークン プロバイダー
[前提条件]
- Kusto クライアント ライブラリを使用するように開発環境を設定する
アプリケーション主体の認証方法
このセクションでは、アプリケーション プリンシパルを使用した認証のさまざまな方法について説明します。
マネージド ID の認証
マネージド ID には、システム割り当てとユーザー割り当ての 2 種類があります。 システム割り当てマネージド ID のライフサイクルは、それらを作成するリソースに関連付けられています。 この ID は 1 つのリソースに制限されます。 ユーザー割り当てマネージド ID は、複数のリソースで使用できます。 詳細については、「 マネージド ID」を参照してください。
|次の例では、 <QueryEndpointUri> と <ManagedIdentityClientId> を実際の値に置き換えます。
システム割り当てマネージド ID:
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadSystemManagedIdentity();ユーザー割り当てマネージド ID。 次のように、ID クライアント ID またはオブジェクト ID を使用します。
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadUserManagedIdentity(<ManagedIdentityClientId>);
Important
- マネージド ID リソースのオブジェクトまたはプリンシパル ID には、Kusto クラスターにアクセスするためのロールが割り当てられている必要があります。 Azure portal の Kusto クラスター リソース ページの [セキュリティとネットワーク>Permissions] でロールを割り当てることができます。 マネージド ID を Kusto クラスターに直接接続しないでください。
- マネージド ID 認証は、ローカル開発環境ではサポートされていません。 マネージド ID 認証をテストするには、アプリケーションを Azure にデプロイするか、ローカルで作業するときに別の認証方法を使用します。
証明書ベースの認証
証明書は、トークンを要求するときにアプリケーションの ID を認証するためのシークレットとして機能します。 証明書を読み込むには、コンピューターのローカル資格情報ストアまたはディスクから証明書を読み込むなど、いくつかの方法があります。
|次の例では、 <QueryEndpointUri>、 <ApplicationId>、 <CertificateSubjectName>、 <CertificateIssuerName>、 <CertificateThumbprint>、 <CertificateObject>、 <AuthorityId>、 <PemPublicCertificate>、 <PemPrivateKey>、 <privateKeyPemFilePath>、 <PemCertificatePath>、 <EnableSubjectAndIssuerAuth> を独自の値に置き換えます。
コンピューターのローカル証明書ストアからの証明書は、C# を使用してのみサポートされます。
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadApplicationSubjectAndIssuerAuthentication(<ApplicationId>, <CertificateSubjectName>, <CertificateIssuerName>, <AuthorityId>);Important
サブジェクト名と発行者を使用する場合は、ローカル コンピューターの証明書ストアに証明書をインストールする必要があります。
ディスク上のファイル、キャッシュ、Azure Key Vault などのセキュリティで保護されたストアなど、任意のソースからの証明書。 証明書オブジェクトには秘密キーが含まれている必要があります。
X509Certificate2 certificate = <CertificateObject>; var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadApplicationCertificateAuthentication(<ApplicationId>, certificate, <AuthorityId>);詳細については、「 Kusto 接続文字列」を参照してください。
Important
Azure Key Vault から証明書を読み込むには、 Azure.Security.KeyVault.Certificatesクライアントを使用できます。
アプリケーション キー認証
アプリケーション キー (アプリケーション パスワードとも呼ばれます) は、アプリケーションがトークンを要求するときに認証してその ID を証明するために使用するシークレット文字列です。 アプリケーションが保護されたリソースにアクセスするための資格情報の形式として機能します。 通常、アプリケーション キーは ID プロバイダーまたは承認サーバーによって生成され、割り当てられます。 機密情報やアクションへの不正アクセスを防ぐために、アプリケーション キーを安全に管理および保護することが重要です。
|次の例では、 <QueryEndpointUri>、 <ApplicationId>、 <ApplicationKey>、 <AuthorityId>、 <AuthorityId> を独自の値に置き換えます。
アプリケーション キー:
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadApplicationKeyAuthentication(<ApplicationId>, <ApplicationKey>, <AuthorityId>);アプリケーション キーを含む接続文字列:
var connectionString = "Data Source=<QueryEndpointUri>;Initial Catalog=NetDefaultDB;AAD Federated Security=True;AppClientId=<ApplicationId>;AppKey=<ApplicationKey>;Authority Id=<AuthorityId>;" var kcsb = new KustoConnectionStringBuilder(connectionString);
Important
コード内のシークレットのハードコーディングは不適切な方法です。 認証資格情報などの機密情報をプレーン テキストで格納すると、セキュリティの脆弱性につながります。 機密情報を暗号化したままにするか、キー コンテナーに安全に格納します。 暗号化またはキー コンテナーを使用すると、シークレットが保護され、承認されたユーザーまたはアプリケーションにのみアクセスできるようになります。
ユーザー プリンシパルの認証方法
このセクションでは、ユーザー プリンシパルを使用した認証のさまざまな方法について説明します。
対話型ユーザー サインイン認証
この認証方法では、ユーザーの資格情報を使用して、Kusto とのセキュリティで保護された接続を確立します。 このメソッドは、認証プロセスを完了するためにユーザー名とパスワードの入力を求めるメッセージが表示される Web ブラウザーを開きます。
|次の例では、 <QueryEndpointUri> 、<AuthorityId>、 <AuthorityId> を独自の値に置き換えます。
対話型ユーザー サインイン:
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>) .WithAadUserPromptAuthentication();
Azure Command-Line インターフェイス (CLI) 認証
この認証方法では、Azure Command-Line インターフェイス (CLI) を使用して、ユーザーの認証とトークンの取得を行います。
az login コマンドを実行すると、ユーザーは安全に接続を確立し、認証のために必要なトークンを取得できます。 トークンが Azure CLI キャッシュで使用できない場合、および interactive パラメーターが true に設定されている場合、ユーザーはサインインを求められる場合があります。 詳細については、「 Azure Command-Line インターフェイス (CLI)」を参照してください。
|次の例では、 <QueryEndpointUri> を独自の値に置き換えます。
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
.WithAadAzCliAuthentication(interactive: true);
Important
このメソッドは、.NET Framework アプリでのみサポートされます。
デバイス コード認証
この方法は、IoT デバイスやサーバーターミナルなど、サインインに適切なユーザー インターフェイスがないデバイス向けに設計されています。 スマートフォンなどの別のデバイスを使用して認証するためのコードと URL をユーザーに提供します。 この対話型の方法では、ユーザーはブラウザーを使用してサインインする必要があります。
|次の例では、 <QueryEndpointUri> を独自の値に置き換えます。
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
.WithAadDeviceCodeAuthentication((msg, uri, code) =>
{
// The callback is used to display instructions to the user on how to authenticate using the device code
Console.WriteLine("Device Code Message: {0}", msg);
Console.WriteLine("Device Code Uri: {0}", uri);
Console.WriteLine("Device Code: {0}", code);
return Task.CompletedTask;
});
Important
デバイス コード認証は、テナントの条件付きアクセス ポリシーによってブロックされる場合があります。 ブロックされている場合は、別の認証方法を選択します。
カスタム トークン プロバイダーの認証方法
このセクションでは、カスタム トークン プロバイダーを使用した認証のさまざまな方法について説明します。
フェデレーションマネージド ID 資格情報認証用のカスタム トークン プロバイダー
カスタム トークン プロバイダーを使用して、認証用の Microsoft Entra ID トークンを取得できます。 次の例では、カスタム トークン プロバイダーを使用して、フェデレーション マネージド ID を使用してトークンを取得する方法を示します。 アプリケーションの要件に合わせてコードを変更できます。
|次の例では、 <AuthorityIdId>、 <ApplicationId>、 <ManagedIdentityClientId>、 <QueryEndpointUri> を独自の値に置き換えます。
public class TokenProvider
{
private ClientAssertionCredential m_clientAssertion;
private TokenRequestContext m_tokenRequestContext;
public TokenProvider(string queryEndpointUri)
{
string resourceId = null;
try
{
// Get the appropiate resource id by querying the metadata
var httpClient = new HttpClient();
var response = httpClient.GetByteArrayAsync($"{queryEndpointUri}/v1/rest/auth/metadata").Result;
var json = JObject.Parse(Encoding.UTF8.GetString(response));
resourceId = json["AzureAD"]?["KustoServiceResourceId"]?.ToString();
// Append scope to resource id
resourceId = !string.IsNullOrWhiteSpace(resourceId) ? $"{resourceId}/.default" : null;
}
catch { /* Handle exception */}
m_tokenRequestContext = new TokenRequestContext(new string[] { resourceId ?? "https://kusto.kusto.windows.net/.default" });
// Create client assertion credential to authenticate with Kusto
m_clientAssertion = new ClientAssertionCredential
(
<AuthorityIdId>,
<ApplicationId>,
async (token) =>
{
// Get Managed Identity token
var miCredential = new ManagedIdentityCredential(<ManagedIdentityClientId>);
var miToken = await miCredential.GetTokenAsync(new TokenRequestContext(new[] {
"api://AzureADTokenExchange/.default"
})).ConfigureAwait(false);
return miToken.Token;
}
);
}
public async Task<string> GetTokenAsync()
{
var accessToken = await m_clientAssertion.GetTokenAsync(m_tokenRequestContext).ConfigureAwait(false);
return accessToken.Token;
}
}
var tokenProvider = new TokenProvider(<QueryEndpointUri>);
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
.WithAadTokenProviderAuthentication(
async () =>
{
return await tokenProvider.GetTokenAsync();
});
Azure TokenCredential 認証の使用
TokenCredentialから継承し、GetToken メソッドを実装するクラスを作成して、カスタム トークン プロバイダーを作成します。 または、 DefaultAzureCredentialなどの既存のトークン プロバイダーを使用することもできます。 この方法では、カスタム トークン プロバイダーが必要な場合に、さまざまな認証シナリオに柔軟に対応できます。
マネージド ID 認証を使用する運用コードをサポートしたり、Visual Studio または Azure CLI を使用してコードをテストしたりするには、 DefaultAzureCredential を使用できます。
DefaultAzureCredential は、さまざまな認証方法を使用するように構成できます。
|次の例では、 <QueryEndpointUri> と <ManagedIdentityClientId> を独自の値に置き換えます。
var credentialProvider = new DefaultAzureCredential(new DefaultAzureCredentialOptions {
ManagedIdentityClientId = <ManagedIdentityClientId>
});
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
.WithAadAzureTokenCredentialsAuthentication(credentialProvider);
注
DefaultAzureCredential は、Azure サービスで認証するために使用されます。
トークンを取得するために複数の認証方法が試行され、マネージド ID、Visual Studio、Azure CLI などを操作するように構成できます。
この資格情報は、さまざまな認証方法を使用するように設定できるため、テスト環境と運用環境の両方に適しています。
詳細については、「DefaultAzureCredential クラス」を参照してください。