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

[アーティクル]
03/25/2023

Azure Digital Twins のインスタンスと認証を設定した後、インスタンスとのやりとりに使用するクライアントアプリケーションを作成できます。スタータークライアントプロジェクトを設定した後、Azure Digital Twins のインスタンスに対して認証を行うためのコードをそのクライアントアプリに書き込む必要があります。

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

この記事では、Azure.Identity クライアントライブラリを使用して資格情報を取得する方法について説明します。この記事では C# のコードサンプルを示していますが (.NET (C#) SDK 用に記述するコードなど)、使用する 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 クライアントを作成するために使用できます

この記事の残りの部分で、.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);
        }
    }
}

Note

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

この問題の詳細については、Azure Digital Twins の既知の問題に関する記事を参照してください。

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

このサンプルでは、DefaultAzureCredential を使用して、ローカル環境から資格情報が検索されます。たとえば、ローカルの DefaultAzureCredential や Visual Studio または Visual Studio Code での Azure サインインなどです。このため、サンプルの資格情報を設定するために、これらのメカニズムのいずれかを使用して、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 をパラメーターに渡します。

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

Note

前述のように、クライアント 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 に Azure Digital Twins API へのアクセス許可があることを確認します。これを行う方法については、「アクセスロールを割り当てる」に進んでください。
ローカル変数 DigitalTwinsClient。 関数の内部にこの変数を追加して Azure Digital Twins クライアントインスタンスを保持します。クラス内でこの変数を static に "しないでください"。
```
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 で次のコマンドを実行します。

Note

このセクションは、アクセス許可の付与や委任を含む、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 サブドメインが見つかりませんでした" というエラーメッセージが返されます。このエラーは、ユーザーまたはサービスプリンシパルに 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 は https://digitaltwins.azure.net Microsoft Entra リソースに対して発行されたトークンを受け取ります。このトークンには、Azure Digital Twins インスタンスと一致するテナント ID 要求が含まれます。 API 要求または Azure.Identity コードでこのトークンを使用すると、フェデレーション ID が Azure Digital Twins リソースにアクセスできるようになります。

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

次の例は、DefaultAzureCredential オプションで InteractiveBrowserTenantId のサンプルテナント 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 モデルを管理する

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

前提条件

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

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

DefaultAzureCredential メソッド

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

ManagedIdentityCredential メソッド

InteractiveBrowserCredential メソッド

Azure Functions を認証する

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

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

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

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

テナントをまたいだ認証

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

次のステップ

その他のリソース

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

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

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