クライアントアプリの認証コードを書き込む

2025-04-24

Azure Digital Twins インスタンスと認証を設定したら、インスタンスと対話するクライアントアプリケーションを作成できます。この記事では、 そのクライアントアプリでコードを記述して 、Azure Digital Twins インスタンスに対して認証する方法について説明します。

Azure Digital Twins は、 OAUTH 2.0 に基づいて Microsoft Entra セキュリティトークンを使用して認証します。 SDK を認証するには、Azure Digital Twins に対する適切なアクセス許可を持つベアラートークンを取得し、API 呼び出しと共に渡します。

この記事では、Azure.Identity クライアントライブラリを使用して資格情報を取得する方法について説明します。この記事では、 .NET (C#) SDK 用に記述するコード例など、C# のコード例を示しますが、使用している SDK に関係なく、 Azure.Identity のバージョンを使用できます。 Azure Digital Twins で使用できる SDK の詳細については、 Azure Digital Twins API と SDK に関するページを参照してください。

前提条件

まず、「インスタンスと認証を設定する」のセットアップ手順を完了します。このセットアップにより、Azure Digital Twins インスタンスがあり、ユーザーにアクセス許可があることが確保されます。このセットアップが完了すると、クライアントアプリのコードを記述することができます。

続行するには、コードを記述するクライアントアプリプロジェクトが必要です。クライアントアプリプロジェクトをまだ設定していない場合は、このチュートリアルで使用する基本的なプロジェクトを、選択した言語で作成します。

Azure.Identity ライブラリを使用して認証する

Azure.Identity は、ベアラートークンを取得して SDK で認証するために使用できる、資格情報を取得するためのメソッドをいくつか提供するクライアントライブラリです。この記事では C# の例を示していますが、次のようないくつかの言語で Azure.Identity を表示できます。

Azure.Identity で資格情報を取得するための一般的な 3 つのメソッドは次のとおりです。

DefaultAzureCredential は、Azure にデプロイされるアプリケーションの既定の TokenCredential 認証フローを提供します。この方法は、 ローカル開発に推奨される選択肢です。また、この記事で推奨される他の 2 つの方法を試すこともできます。 ManagedIdentityCredential をラップし、構成変数を使用して InteractiveBrowserCredential にアクセスできます。
ManagedIdentityCredential は、マネージド ID (MSI) が必要な場合に適切に機能します。この方法は、Azure Functions を使用する、Azure サービスにデプロイする場合に適しています。
InteractiveBrowserCredential は、対話型アプリケーションを対象としています。これは、認証された SDK クライアントを作成する方法の 1 つです。

この記事の残りの部分では、 .NET (C#) SDK でこれらのメソッドを使用する方法を示します。

.NET プロジェクトに Azure.Identity を追加する

Azure.Identity を使用して認証するように .NET プロジェクトを設定するには、次の手順を完了します。

プロジェクトに SDK パッケージ Azure.DigitalTwins.Core と Azure.Identity パッケージを含めます。選択するツールによっては、Visual Studio パッケージマネージャーまたは dotnet コマンドラインツールを使用して、パッケージを含めることができます。
次の using ステートメントをプロジェクトコードに追加します。
```
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;
```

次に、Azure.Identity のメソッドの 1 つを使用して、資格情報を取得するコードを追加します。以降のセクションでは、各メソッドの使用方法について詳しく説明します。

DefaultAzureCredential メソッド

DefaultAzureCredential は、Azure にデプロイされるアプリケーションの既定の TokenCredential 認証フローを提供します。この方法は、 ローカル開発に推奨される選択肢です。

既定の Azure 資格情報を使用するには、Azure Digital Twins インスタンスの URL (検索手順) が必要です。

DefaultAzureCredential をご自分のプロジェクトに追加するためのコードサンプルを次に示します。

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

注

現在、認証中にエラーが発生する可能性がある DefaultAzureCredential ラッパークラスに影響する既知の問題があります。この問題が発生した場合は、次の省略可能なパラメーターを使用して DefaultAzureCredential のインスタンス化を試して解決することができます: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

この問題の詳細については、「 Azure Digital Twins の既知の問題」を参照してください。

ローカルの Azure 資格情報を設定する

DefaultAzureCredentialでは、サンプルはローカル環境で資格情報を探します。具体的には、Azure のサインイン情報を、ローカルの Azure CLI、Visual Studio、または Visual Studio Code で検索します。このため、これらのメカニズムのいずれかを使用して Azure にローカルでサインイン し、サンプルの資格情報を設定する必要があります。

Visual Studio または Visual Studio Code を使用してコードサンプルを実行する場合は、Azure Digital Twins インスタンスへのアクセスに使用するのと同じ Azure 資格情報を使用して、そのエディターにサインインしていることを確認します。ローカル CLI ウィンドウを使用している場合は、az login コマンドを実行して Azure アカウントにサインインします。サインイン後、コードサンプルを実行すると、自動的に認証処理が行われます。

ManagedIdentityCredential メソッド

ManagedIdentityCredential メソッドは、マネージド ID (MSI) が必要な場合 (たとえば、Azure Functions で認証する場合) に適しています。

ManagedIdentityCredentialまたはDefaultAzureCredentialと同じプロジェクトでInteractiveBrowserCredentialを使用して、プロジェクトの別の部分を認証できます。

既定の Azure 資格情報を使用するには、Azure Digital Twins インスタンスの URL (検索手順) が必要です。アプリの登録と登録のアプリケーション (クライアント) ID が必要な場合もあります。

Azure 関数で、次のようにマネージド ID の資格情報を使用できます。

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

前の例に示すように、パラメーターを指定せずに資格情報を作成すると、関数アプリのシステム割り当て ID の資格情報 (存在する場合) が返されます。代わりにユーザー割り当て ID を指定するには、ユーザー割り当て ID の クライアント ID を コンストラクターの id パラメーターに渡します。

InteractiveBrowserCredential メソッド

InteractiveBrowserCredential メソッドは、対話型アプリケーションを対象とし、認証用の Web ブラウザーを起動します。対話型認証が必要な場合は、 DefaultAzureCredential の代わりに、この方法を使用します。

対話型ブラウザーの資格情報を使用するには、Azure Digital Twins API へのアクセス許可を持つ アプリの登録 が必要です。このアプリ登録を設定する手順については、「 Azure Digital Twins アクセスを使用してアプリ登録を作成する」を参照してください。アプリの登録が設定されたら、次の値が必要です:

InteractiveBrowserCredential を使用して認証された SDK クライアントを作成するコードの例を次に示します。

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

注

上記の例では、クライアント ID、テナント ID、およびインスタンス URL をコードに直接配置しますが、代わりに構成ファイルまたは環境変数からこれらの値を取得することをお勧めします。

Azure Functions を認証する

このセクションでは、Azure Functions で認証するための重要な構成の選択肢について説明します。最初に、関数から Azure Digital Twins にアクセスできるようにするためのお勧めのクラスレベルの変数と認証コードについて確認します。次に、コードが Azure に発行された後に、関数の完了に必要な最終的な構成手順についていくつか確認します。

アプリケーションコードを記述する

Azure 関数を記述するときは、次の変数とコードを関数に追加することを検討してください。

Azure Digital Twins サービスの URL を環境変数または構成設定として読み取るコード。 関数でハードコーディングするのではなく、アプリケーション設定/環境変数からサービス URL を読み取ることをお勧めします。 Azure 関数で、環境変数を読み取るコードは次のようになります。
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
後で関数を発行した後、このコードが読み取る環境変数の値を作成して設定します。その方法については、「アプリケーション設定の構成」を参照してください。
HttpClient インスタンスを保持する静的変数。 HttpClient の作成には比較的コストがかかります。そのため、認証コードを使用して 1 回作成し、すべての関数呼び出しに対して作成されないようにすることをお勧めします。
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
マネージド ID 資格情報。 関数で Azure Digital Twins にアクセスするために使用するマネージド ID 資格情報を作成します。
```
// To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");
```
前の例に示すように、パラメーターを指定せずに資格情報を作成すると、関数アプリのシステム割り当て ID の資格情報 (存在する場合) が返されます。代わりにユーザー割り当て ID を指定するには、ユーザー割り当て ID の クライアント ID を コンストラクターの id パラメーターに渡します。

後で関数を発行した後、関数の ID に Azure Digital Twins API へのアクセス許可があることを確認します。その方法については、「アクセスロールの割り当て」を参照してください。
ローカル変数 DigitalTwinsClient。 関数の内部にこの変数を追加して Azure Digital Twins クライアントインスタンスを保持します。この変数をクラス内で静的にしないでください。
```
var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });
```
adtInstanceUrl の null チェック。例外をすべてキャッチするには、adtInstanceUrl の null チェックを追加し、関数のロジックを、try/catch ブロックで囲んでください。

これらの変数を関数に追加すると、関数コードは次の例のようになります。

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

認証と関数のロジックの追加など、関数コードが完了したら、アプリを Azure に発行します。

発行されたアプリを構成する

最後に、発行された Azure 関数に対して次の構成手順を完了して、Azure Digital Twins インスタンスにアクセスできることを確認します。

Azure Cloud Shell またはローカルの Azure CLI で次のコマンドを実行します。

注

アクセス許可の付与や委任など、Azure リソースへのユーザーアクセスを管理するアクセス許可を持つ Azure ユーザーは、このセクションを完了する必要があります。この要件を満たす一般的なロールは、 所有者、 アカウント管理者、または ユーザーアクセス管理者 と 共同作成者の組み合わせです。 Azure Digital Twins ロールのアクセス許可要件の詳細については、「インスタンスと認証の設定」を参照してください。

アクセスロールを割り当てる

Azure 関数には、ベアラートークンを渡す必要があります。ベアラートークンが確実に渡されるようにするには、関数アプリに Azure Digital Twins インスタンスの Azure Digital Twins データ所有者 ロールを付与します。このロールにより、インスタンスでデータプレーンアクティビティを実行するアクセス許可が関数アプリに付与されます。

次のコマンドを使用して、関数のシステムマネージド ID を作成します (関数に既に存在する場合、このコマンドはその詳細を出力します)。出力内の principalId フィールドをメモします。この ID は、次の手順でアクセス許可を付与できるように、関数を参照するために使用します。
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
次のコマンドの principalId 値を使用して、Azure Digital Twins インスタンスの Azure Digital Twins データ所有者 ロールを関数に付与します。
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

アプリケーション設定の構成

次に、関数の環境変数を設定して、Azure Digital Twins インスタンスの URL に関数からアクセスできるようにします。

ヒント

Azure Digital Twins インスタンスの URL は、インスタンスのホスト名の先頭に https:// を追加することによって作成されます。インスタンスのすべてのプロパティと共にホスト名を表示するには、az dt show --dt-name <your-Azure-Digital-Twins-instance> を実行します。

次のコマンドは、インスタンスにアクセスする必要があるときに関数が使用するインスタンスの URL の環境変数を設定します。

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

テナントをまたいだ認証

Azure Digital Twins は、1 つの Microsoft Entra テナント (Azure Digital Twins インスタンスが配置されているサブスクリプションのメインテナント) のみをサポートするサービスです。

結果として、Azure Digital Twins API への要求には、Azure Digital Twins インスタンスが存在するのと同じテナントの一部であるユーザーまたはサービスプリンシパルが必要です。 Azure Digital Twins エンドポイントの悪意のあるスキャンを防ぐために、送信元テナントの外部からのアクセストークンを使用した要求では、"404 Sub-Domain が見つかりません" というエラーメッセージが返されます。このエラーは、ユーザーまたはサービスプリンシパルに Microsoft Entra B2B コラボレーションによって Azure Digital Twins データ所有者または Azure Digital Twins データ閲覧者ロールが付与された場合でも返されます。

インスタンスとは異なるテナントに属するサービスプリンシパルまたはユーザーアカウントを使用して Azure Digital Twins インスタンスにアクセスする必要がある場合は、別のテナントから各フェデレーション ID に Azure Digital Twins インスタンスの "ホーム" テナントからの トークン を要求させることができます。

これを実行する方法の 1 つとして、次の CLI コマンドを使用します。ここで、<home-tenant-ID> は、Azure Digital Twins インスタンスを含む Microsoft Entra テナントの ID です。

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

この要求の後、ID は、Azure Digital Twins インスタンスに対して一致するテナント ID 要求を持つ、 https://digitaltwins.azure.net Microsoft Entra リソースに対して発行されたトークンを受け取ります。 API 要求または Azure.Identity コードでこのトークンを使用すると、フェデレーション ID が Azure Digital Twins リソースにアクセスできるようになります。

また、コードの資格情報オプションでホームテナントを指定することもできます。

次の例は、InteractiveBrowserTenantId オプションで DefaultAzureCredential のサンプルテナント ID 値を設定する方法を示しています。

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Visual Studio と Visual Studio Code での認証のためにテナントを設定する場合にも、同様のオプションが用意されています。使用できるオプションの詳細については、 DefaultAzureCredentialOptions のドキュメントを参照してください。

その他の資格情報のメソッド

この記事で説明されている強調表示された認証シナリオでアプリのニーズが満たされていない場合は、 Microsoft ID プラットフォームで提供される他の種類の認証について調べます。このプラットフォームのドキュメントでは、その他の認証シナリオが取り上げられており、アプリケーションの種類別に整理されています。

次のステップ

Azure Digital Twins でのセキュリティのしくみの詳細については、次を参照してください。

Azure Digital Twins ソリューションのセキュリティ

または、認証が設定されたので、インスタンスでのモデルの作成および管理に進みます。

DTDL モデルの管理