.NET 用 Azure Mixed Reality 認証クライアント ライブラリ - バージョン 1.2.0

Azure Spatial Anchors、Azure Remote Rendering などのMixed Reality サービスでは、認証に Mixed Reality セキュリティ トークン サービス (STS) を使用します。 このパッケージは、Mixed Reality サービスへのアクセスに使用できる STS からのアクセス トークンのMixed Realityアカウント資格情報の交換をサポートしています。

ソースコード | パッケージ (NuGet)

• .NET 用 Azure Mixed Reality 認証クライアント ライブラリ
  • 作業の開始
    • パッケージをインストールする
    • 前提条件
    • クライアントを認証する
      • 認証の例
        • アカウント キー認証を使用した認証
        • AAD クライアント シークレットを使用した認証
        • デバイス コード認証を使用したユーザーの認証
        • DefaultAzureCredential を使用した対話型認証
  • 主要な概念
    • MixedRealityStsClient
    • スレッド セーフ
    • その他の概念
  • 使用例
    • アクセス トークンを取得する
      • Mixed Reality クライアント ライブラリでのアクセス トークンの使用
  • トラブルシューティング
  • 次の手順
    • Mixed Reality認証を使用した認証をサポートするクライアント ライブラリ
  • 寄与

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Azure Mixed Reality Authentication クライアント ライブラリをインストールします。

dotnet add package Azure.MixedReality.Authentication

パッケージ参照を追加します。

<PackageReference Include="Azure.MixedReality.Authentication" Version="1.0.0" />

前提条件

• Azure サブスクリプションが必要です。
• Azure Mixed Reality サービスを持つアカウントが必要です。
  • Azure Remote Rendering
  • Azure Spatial Anchors
• Azure.Identity からの認証と資格情報の概念に関する知識。

クライアントを認証する

Mixed Reality サービスでは、いくつかの異なる形式の認証がサポートされています。

• アカウント キー認証
  • アカウント キーを使用すると、Mixed Reality サービスの使用をすばやく開始できます。 ただし、アプリケーションを運用環境にデプロイする前に、Azure AD 認証を使用するようにアプリを更新することをお勧めします。
• Azure Active Directory (AD) トークン認証
  • エンタープライズ アプリケーションをビルドしていて、会社の ID システムとして Azure AD を使用している場合は、アプリ内でユーザーベースの Azure AD 認証を使用できます。 その後、既存の Azure AD セキュリティ グループを使用して、Mixed Reality アカウントへのアクセス権を付与します。 組織内のユーザーに直接アクセス権を付与することもできます。
  • それ以外の場合は、アプリをサポートしている Web サービスから Azure AD トークンを取得することをお勧めします。 運用アプリケーションでは、クライアント アプリケーションでMixed Reality サービスにアクセスするための資格情報を埋め込むのを避けるため、この方法をお勧めします。

詳細な手順と情報については、 こちらを 参照してください。

認証の例

一般的な認証シナリオの例をいくつか次に示しますが、その他の例と情報については 、「Azure.Identity」を参照してください。

アカウント キー認証を使用した認証

MixedRealityStsClientを受け入れるコンストラクター オーバーロードをAzureKeyCredential使用して、Mixed Reality STS でアカウント キー認証を構成します。

AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey);
MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, keyCredential);

注: 運用アプリケーションでは、アカウント キー認証は 推奨されません 。

AAD クライアント シークレットを使用した認証

TokenCredential aadCredential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, aadCredential);

デバイス コード認証を使用したユーザーの認証

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential deviceCodeCredential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, deviceCodeCredential);

AccessToken token = await client.GetTokenAsync();

デバイス コード認証フローの使用の詳細については、 こちらを 参照してください。

DefaultAzureCredential を使用した対話型認証

を使用して、既定の DefaultAzureCredential 対話型認証フローを使用します includeInteractiveCredentials: true 。

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, credential);

主要な概念

MixedRealityStsClient

MixedRealityStsClientは、Mixed Reality STS にアクセスしてアクセス トークンを取得するために使用されるクライアント ライブラリです。

Mixed Reality STS から取得されたトークンの有効期間は 24 時間です。

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、スレッド間であっても、クライアント インスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

例

アクセス トークンを取得する

AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey);
MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, keyCredential);

AccessToken token = await client.GetTokenAsync();

より複雑な認証シナリオについては、 上記 の認証例を参照してください。

Mixed Reality クライアント ライブラリでのアクセス トークンの使用

一部のMixed Realityクライアント ライブラリでは、資格情報の代わりにアクセス トークンを受け入れる場合があります。 たとえば次のような点です。

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
AccessToken accessToken = await GetMixedRealityAccessTokenFromWebService();

SpatialAnchorsAccount account = new SpatialAnchorsAccount(accountId, accountDomain);
SpatialAnchorsClient client = new SpatialAnchorsClient(account, accessToken);

注: 上記の SpatialAnchorsClient 使用法は架空のものであり、実際のライブラリを反映していない可能性があります。 使用しているクライアント ライブラリのドキュメントを参照して、これがサポートされるかどうかとその方法を確認してください。

トラブルシューティング

• エラー処理
• 診断

次の手順

Mixed Reality認証を使用した認証をサポートするクライアント ライブラリ

Mixed Reality認証をサポートするライブラリは近日公開予定です。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。