クイック スタート:Windows デスクトップ アプリからトークンを取得し、Microsoft Graph API を呼び出すQuickstart: Acquire a token and call Microsoft Graph API from a Windows desktop app

このクイックスタートでは、Windows デスクトップ .NET (WPF) アプリケーションでユーザーをサインインし、アクセス トークンを取得して Microsoft Graph API を呼び出す方法を示すコード サンプルをダウンロードして実行します。In this quickstart, you download and run a code sample that demonstrates how a Windows desktop .NET (WPF) application can sign in users and get an access token to call the Microsoft Graph API.

図については、「このサンプルのしくみ」を参照してください。See How the sample works for an illustration.

前提条件Prerequisites

クイック スタート アプリを登録してダウンロードするRegister and download your quickstart app

クイック スタート アプリケーションを開始する方法としては、次の 2 つの選択肢があります。You have two options to start your quickstart application:

オプション 1: アプリを登録して自動構成を行った後、コード サンプルをダウンロードするOption 1: Register and auto configure your app and then download your code sample

  1. Azure portal のアプリの登録クイックスタート エクスペリエンスに移動します。Go to the Azure portal - App registrations quickstart experience.
  2. アプリケーションの名前を入力し、 [登録] を選択します。Enter a name for your application and select Register.
  3. 画面の指示に従ってダウンロードし、1 回クリックするだけで、新しいアプリケーションが自動的に構成されます。Follow the instructions to download and automatically configure your new application with just one click.

オプション 2:アプリケーションを登録し、アプリケーションとコード サンプルを手動で構成するOption 2: Register and manually configure your application and code sample

手順 1:アプリケーションの登録Step 1: Register your application

アプリケーションを登録し、その登録情報をソリューションに手動で追加するには、次の手順を実行します。To register your application and add the app's registration information to your solution manually, follow these steps:

  1. Azure portal にサインインします。Sign in to the Azure portal.
  2. 複数のテナントにアクセスできる場合は、トップ メニューの [ディレクトリとサブスクリプション] フィルター を使用して、アプリケーションを登録するテナントを選択します。
  3. Azure Active Directory を検索して選択します。Search for and select Azure Active Directory.
  4. [管理][アプリの登録] > [新規登録] の順に選択します。Under Manage, select App registrations > New registration.
  5. アプリケーションの 名前 を入力します (例: Win-App-calling-MsGraph)。Enter a Name for your application, for example Win-App-calling-MsGraph. この名前は、アプリのユーザーに表示される場合があります。また、後で変更することができます。Users of your app might see this name, and you can change it later.
  6. [サポートされているアカウントの種類] セクションで、 [Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com)](任意の組織のディレクトリ内のアカウントと個人用の Microsoft アカウント (例: Skype、Xbox、Outlook.com)) を選択します。In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com).
  7. [登録] を選択して、アプリケーションを作成します。Select Register to create the application.
  8. [管理] で、 [認証] を選択します。Under Manage, select Authentication.
  9. [プラットフォームを追加] > [モバイル アプリケーションとデスクトップ アプリケーション] を選択します。Select Add a platform > Mobile and desktop applications.
  10. [リダイレクト URI] セクションで https://login.microsoftonline.com/common/oauth2/nativeclient を選択し、 [カスタム リダイレクト URI] セクションに ms-appx-web://microsoft.aad.brokerplugin/{client_id} を追加します。{client_id} は、登録するアプリケーションのアプリケーション (クライアント) ID です (msal{client_id}://auth チェック ボックスに表示される GUID)。In the Redirect URIs section, select https://login.microsoftonline.com/common/oauth2/nativeclient and in Custom redirect URIs add ms-appx-web://microsoft.aad.brokerplugin/{client_id} where {client_id} is the application (client) ID of your application (the same GUID that appears in the msal{client_id}://auth checkbox).
  11. [構成] をクリックします。Select Configure.

手順 1:Azure portal でのアプリケーションの構成Step 1: Configure your application in Azure portal

このクイックスタートのコード サンプルを動作させるには、リダイレクト URI (https://login.microsoftonline.com/common/oauth2/nativeclient および ms-appx-web://microsoft.aad.brokerplugin/{client_id}) を追加します。For the code sample in this quickstart to work, add a Redirect URI of https://login.microsoftonline.com/common/oauth2/nativeclient and ms-appx-web://microsoft.aad.brokerplugin/{client_id}.

構成済み アプリケーションはこれらの属性で構成されています。Already configured Your application is configured with these attributes.

手順 2:Visual Studio プロジェクトをダウンロードするStep 2: Download your Visual Studio project

Visual Studio 2019 を使用してプロジェクトを実行します。Run the project using Visual Studio 2019.

ヒント

Windows におけるパスの長さの制限に起因したエラーを防ぐため、ドライブのルートに近いディレクトリをアーカイブの展開先またはリポジトリのクローン先とすることをお勧めします。To avoid errors caused by path length limitations in Windows, we recommend extracting the archive or cloning the repository into a directory near the root of your drive.

手順 3:アプリが構成され、実行準備ができるStep 3: Your app is configured and ready to run

アプリのプロパティの値を使用してプロジェクトを構成したら、実行する準備は完了です。We have configured your project with values of your app's properties and it's ready to run.

注意

Enter_the_Supported_Account_Info_Here

手順 3:Visual Studio プロジェクトの構成Step 3: Configure your Visual Studio project

  1. ディスクのルートに近いローカル フォルダー (例: C:\Azure-Samples) に zip ファイルを展開します。Extract the zip file to a local folder close to the root of the disk, for example, C:\Azure-Samples.

  2. Visual Studio でプロジェクトを開きます。Open the project in Visual Studio.

  3. App.Xaml.cs を編集し、ClientId フィールドと Tenant フィールドの値を次のコードに置き換えます。Edit App.Xaml.cs and replace the values of the fields ClientId and Tenant with the following code:

    private static string ClientId = "Enter_the_Application_Id_here";
    private static string Tenant = "Enter_the_Tenant_Info_Here";
    

各値の説明:Where:

  • Enter_the_Application_Id_here - 登録したアプリケーションの アプリケーション (クライアント) IDEnter_the_Application_Id_here - is the Application (client) ID for the application you registered.

    [アプリケーション (クライアント) ID] の値を見つけるには、Azure portal でアプリの [概要] ページに移動します。To find the value of Application (client) ID, go to the app's Overview page in the Azure portal.

  • Enter_the_Tenant_Info_Here - 次のいずれかのオプションに設定します。Enter_the_Tenant_Info_Here - is set to one of the following options:

    • アプリケーションで この組織のディレクトリ内のアカウント をサポートする場合は、この値を テナント ID または テナント名 に置き換えます (たとえば、contoso.microsoft.com)If your application supports Accounts in this organizational directory, replace this value with the Tenant Id or Tenant name (for example, contoso.microsoft.com)

    • アプリケーションで [任意の組織のディレクトリ内のアカウント] がサポートされる場合は、この値を organizations に置き換えます。If your application supports Accounts in any organizational directory, replace this value with organizations

    • アプリケーションにおいて 任意の組織のディレクトリ内のアカウントと個人用の Microsoft アカウント をサポートする場合は、この値を common に置き換えます。If your application supports Accounts in any organizational directory and personal Microsoft accounts, replace this value with common.

      [ディレクトリ (テナント) ID][サポートされているアカウントの種類] の値を見つけるには、Azure portal でアプリの [概要] ページに移動します。To find the values of Directory (tenant) ID and Supported account types, go to the app's Overview page in the Azure portal.

詳細情報More information

このサンプルのしくみHow the sample works

このクイック スタートで生成されたサンプル アプリの動作の紹介

MSAL.NETMSAL.NET

MSAL (Microsoft.Identity.Client) はユーザーをサインインし、Microsoft ID プラットフォームによって保護されている API へのアクセス用のトークンを要求するために使用するライブラリです。MSAL (Microsoft.Identity.Client) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. MSAL は、Visual Studio の "パッケージ マネージャー コンソール" で次のコマンドを実行してインストールできます。You can install MSAL by running the following command in Visual Studio's Package Manager Console:

Install-Package Microsoft.Identity.Client -IncludePrerelease

MSAL の初期化MSAL initialization

MSAL への参照を追加するには、次のコードを追加します。You can add the reference for MSAL by adding the following code:

using Microsoft.Identity.Client;

続いて、次のコードを使用して MSAL を初期化します。Then, initialize MSAL using the following code:

public static IPublicClientApplication PublicClientApp;
PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();
各値の説明:Where: 説明Description
ClientId Azure portal に登録されているアプリケーションの "アプリケーション (クライアント) ID"。Is the Application (client) ID for the application registered in the Azure portal. この値は、Azure portal のアプリの [概要] ページで確認できます。You can find this value in the app's Overview page in the Azure portal.

トークンの要求Requesting tokens

MSAL には、トークンの取得に使用する 2 つのメソッド AcquireTokenInteractiveAcquireTokenSilent があります。MSAL has two methods for acquiring tokens: AcquireTokenInteractive and AcquireTokenSilent.

ユーザー トークンを対話形式で取得するGet a user token interactively

ユーザーは Microsoft ID プラットフォームの操作を強制される場合があります。その場合、各自の資格情報の検証または同意を行うポップアップ ウィンドウが表示されます。Some situations require forcing users interact with the Microsoft identity platform through a popup window to either validate their credentials or to give consent. 次に例をいくつか示します。Some examples include:

  • ユーザーが初めてアプリケーションにサインインした場合The first time users sign in to the application
  • パスワードの有効期限が切れているため、ユーザーが資格情報を再入力する必要がある場合When users may need to reenter their credentials because the password has expired
  • ご使用のアプリケーションが、ユーザーによる同意が必要なリソースへのアクセスを要求している場合When your application is requesting access to a resource that the user needs to consent to
  • 2 要素認証が必須である場合When two factor authentication is required
authResult = await App.PublicClientApp.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();
各値の説明:Where: 説明Description
_scopes 要求するスコープを含む (Microsoft Graph 用の { "user.read" } またはカスタム Web API 用の { "api://<Application ID>/access_as_user" } など)Contains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom web APIs.

ユーザー トークンを自動で取得するGet a user token silently

リソースへのアクセスが必要になるたびに、ユーザーに自分の資格情報を検証させたくない場合があります。You don't want to require the user to validate their credentials every time they need to access a resource. ほとんどの場合は、ユーザーの操作なしにトークンの取得や更新を行います。Most of the time you want token acquisitions and renewal without any user interaction. 最初に AcquireTokenInteractive メソッドを呼び出した後は、AcquireTokenSilent メソッドを使用して保護されたリソースにアクセス するトークンを取得することができます。You can use the AcquireTokenSilent method to obtain tokens to access protected resources after the initial AcquireTokenInteractive method:

var accounts = await App.PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await App.PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
各値の説明:Where: 説明Description
scopes 要求するスコープを含む (Microsoft Graph 用の { "user.read" } またはカスタム Web API 用の { "api://<Application ID>/access_as_user" } など)Contains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom web APIs.
firstAccount キャッシュ内の最初のユーザーを指定する (MSAL は、1 つのアプリで複数のユーザーをサポート)。Specifies the first user in the cache (MSAL support multiple users in a single app).

ヘルプとサポートHelp and support

サポートが必要な場合、問題をレポートする場合、またはサポート オプションについて知りたい場合は、開発者向けのヘルプとサポートに関するページを参照してください。If you need help, want to report an issue, or want to learn about your support options, see Help and support for developers.

次のステップNext steps

アプリケーションや新機能の構築についての完全なステップ バイ ステップ ガイドは、Windows デスクトップ チュートリアルをお試しください。このクイック スタートの完全な説明も含まれています。Try out the Windows desktop tutorial for a complete step-by-step guide on building applications and new features, including a full explanation of this quickstart.