services

platforms

author

level

client

service

endpoint

page_type

languages

products

description

active-directory

dotnet

TiagoBrenck

200

.NET Desktop (Console)

Microsoft Graph

Microsoft identity platform

sample

csharp

azure

microsoft-entra-id

dotnet

office-ms-graph

This sample demonstrates a .NET Desktop (Console) application calling Microsoft Graph leveraging a cross platfrom token cache

Using the Microsoft identity platform to call Microsoft Graph API from a multi-target console application leveraging a cross platform token cache.

About this sample

Overview

This sample demonstrates a .NET Desktop (Console) application leveraging token cache operations.

The .NET Desktop (Console) application uses the Microsoft Authentication Library (MSAL) to obtain a JWT access token from Microsoft Entra ID and cache the access token.
The application displays a menu allowing the user to execute the following cache operations:
- Get an access token from the cache
- List all items in the cache
- Clear the cache

How to run this sample

To run this sample, you'll need:

Visual Studio 2019
An Internet connection
a Microsoft Entra tenant. For more information on how to get a Microsoft Entra tenant, see How to get a Microsoft Entra tenant
A user account in your Microsoft Entra tenant. This sample will not work with a Microsoft account (formerly Windows Live account). Therefore, if you signed in to the Microsoft Entra admin center with a Microsoft account and have never created a user account in your directory before, you need to do that now.

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/ms-identity-dotnet-desktop-tutorial.git

or download and extract the repository .zip file.

Given that the name of the sample is quiet long, and so are the names of the referenced NuGet packages, you might want to clone it in a folder close to the root of your hard drive, to avoid file size limitations on Windows.

Step 2: Register the sample application with your Microsoft Entra tenant

There is one project in this sample. To register it, you can:

either follow the steps Step 2: Register the sample with your Microsoft Entra tenant and Step 3: Configure the sample to use your Microsoft Entra tenant
or use PowerShell scripts that:
- automatically creates the Microsoft Entra applications and related objects (passwords, permissions, dependencies) for you. Note that this works for Visual Studio only.
- modify the Visual Studio projects' configuration files.

Expand this section if you want to use this automation:

On Windows, run PowerShell and navigate to the root of the cloned directory

In PowerShell run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

Run the script to create your Microsoft Entra application and configure the code of the sample application accordingly.
In PowerShell run:
```
cd .\AppCreationScripts\
.\Configure.ps1
```
Other ways of running the scripts are described in App Creation Scripts The scripts also provide a guide to automated application registration, configuration and removal which can help in your CI/CD scenarios.
Open the Visual Studio solution and click start to run the code.

Follow the steps below to manually walk through the steps to register and configure the applications.

Choose the Microsoft Entra tenant where you want to create your applications

As a first step you'll need to:

Sign in to the Microsoft Entra admin center using either a work or school account or a personal Microsoft account.
If your account is present in more than one Microsoft Entra tenant, select your profile at the top right corner in the menu on top of the page, and then switch directory. Change your portal session to the desired Microsoft Entra tenant.

Register the client app (Console-Interactive-MultiTarget-v2)

Navigate to the Microsoft identity platform for developers App registrations page.
Click New registration on top.
In the Register an application page that appears, enter your application's registration information:
- In the Name section, enter a meaningful application name that will be displayed to users of the app, for example Console-Interactive-MultiTarget-v2.
- Change Supported account types to Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com).
Click on the Register button in bottom to create the application.
In the app's registration screen, find the Application (client) ID value and record it for use later. You'll need it to configure the configuration file(s) later in your code.
In the app's registration screen, click on the Authentication blade in the left.
- If you don't have a platform added yet, click on Add a platform and select the Public client (mobile & desktop) option.
- In the Redirect URIs section, enter the following redirect URIs.
  - http://localhost
- In the Redirect URIs | Suggested Redirect URIs for public clients (mobile, desktop) section, select https://login.microsoftonline.com/common/oauth2/nativeclient
Click the Save button on top to save the changes.
In the app's registration screen, click on the API permissions blade in the left to open the page where we add access to the Apis that your application needs.
- Click the Add a permission button and then,
- Ensure that the Microsoft APIs tab is selected.
- In the Commonly used Microsoft APIs section, click on Microsoft Graph
- In the Delegated permissions section, select the User.Read in the list. Use the search box if necessary.
- Click on the Add permissions button at the bottom.

Configure the client app (Console-Interactive-MultiTarget-v2) to use your app registration

Open the project in your IDE (like Visual Studio) to configure the code.

In the steps below, "ClientID" is the same as "Application ID" or "AppId".

Open the Console-Interactive-MultiTarget\appsettings.json file
Find the app key ClientId and replace the existing value with the application ID (clientId) of the Console-Interactive-MultiTarget-v2 application copied from the Microsoft Entra admin center.
Find the app key TenantId and replace the existing value with your Microsoft Entra tenant ID.

Step 4: Run the sample

Clean the solution, rebuild the solution, and run it.

Start the application, sign-in and check the result in the console.

Consider taking a moment to share your experience with us.

About the code

The relevant code for this sample is the cache setup and its operations,located in the Program.cs file:

Import Microsoft.Identity.Client.Extensions.Msal NuGet package for the cross platform token cache.
Build a StorageCreationProperties object, with all the settings for the cross platform cache. We created the static class CacheSettings just to store the settings constants.

// Building StorageCreationProperties
var storageProperties =
      new StorageCreationPropertiesBuilder(CacheSettings.CacheFileName, CacheSettings.CacheDir, appConfiguration.ClientId)
      .WithLinuxKeyring(
         CacheSettings.LinuxKeyRingSchema,
         CacheSettings.LinuxKeyRingCollection,
         CacheSettings.LinuxKeyRingLabel,
         CacheSettings.LinuxKeyRingAttr1,
         CacheSettings.LinuxKeyRingAttr2)
      .WithMacKeyChain(
         CacheSettings.KeyChainServiceName,
         CacheSettings.KeyChainAccountName)
      .Build();

Create a MsalCacheHelper object and register it in the PublicClientApplication.

var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties);
cacheHelper.RegisterCache(app.UserTokenCache);

Since the cache is registered in the PublicClientApplication object, the cache may be accessed many times by MSAL. Some examples are:
- AcquireTokenInteractive will add an account into the cache in case it is not there yet
- AcquireTokenSilent will use the cached token for the account sent as parameter
- GetAccountsAsync will return all account in the cache
- RemoveAsync will remove the account from the cache

Using Embedded View - supported on .NET Framework only

This sample is a multi-target framework (.NET Core and .NET Framework) project, and MSAL has the option to use embedded view when acquiring a token interactively. You can test this functionality by running the project on .NET Framework.

app.AcquireTokenInteractive(scopes)
   .WithUseEmbeddedWebView(true) // currently only supported on .NET framework
   .ExecuteAsync();

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [azure-active-directory msal dotnet].

If you find a bug in the sample, please raise the issue on GitHub Issues.

To provide a recommendation, visit the following User Voice page.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

More information

For more information, see MSAL.NET's conceptual documentation:

MSAL.NET's conceptual documentation
MSAL.NET Extensions
Cross platform token cache
Microsoft identity platform (Microsoft Entra ID for developers)
Quickstart: Register an application with the Microsoft identity platform
Quickstart: Configure a client application to access web APIs
Understanding Microsoft Entra application consent experiences
Understand user and admin consent
Application and service principal objects in Microsoft Entra ID

For more information about how OAuth 2.0 protocols work in this scenario and other scenarios, see Authentication Scenarios for Microsoft Entra ID.