page_type

languages

products

description

urlFragment

sample

csharp

powershell

microsoft-entra-id

This sample demonstrates how to use MSAL.NET from apps that run on a domain joined or Microsoft Entra joined Windows machine.

active-directory-dotnet-iwa-v2

Invoking an API protected by Microsoft identity platform with Integrated Windows Authentication, on a Windows domain joined or Microsoft Entra joined machine

We have renamed the default branch to main. To rename your local repo follow the directions here.

About this sample

Overview

This sample demonstrates how to use MSAL.NET from apps that run on a domain joined or Microsoft Entra joined Windows machine. It enables these apps to:

authenticate the user signed-in on the Windows machine
and call to a web API (in this case, the Microsoft Graph)

If you would like to get started immediately, skip this section and jump to How To Run The Sample.

Scenario

The application obtains tokens through Integrated Windows Authentication (Kerberos):

Developers who wish to gain good familiarity of programming for Microsoft Graph are advised to go through the An introduction to Microsoft Graph for developers recorded session.

How to run this sample

To run this sample, you'll need:

Visual Studio 2017
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/active-directory-dotnet-iwa-v2.git

or download and exact the repository .zip file.

Given that the name of the sample is pretty long, and so are the name of the referenced NuGet pacakges, 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: Run the sample

Open the solution in Visual Studio, restore the NuGet packages, select the project, and start it in the debugger.

Operating the sample

When you run the sample, if you are running on a domain joined or Microsoft Entra joined Windows machine, it will display your information as well as the information about your manager.

Step 2:(Optional): Configure the sample as an app in your directory tenant

The instructions so far used the Microsoft Entra ID entry for the app in a Microsoft test tenant: given that the app is multi-tenant, anybody can run the sample against that app registration. To register your project in your own Microsoft Entra tenant, you can find instructions to manually provision the sample in your own tenant, so that you can exercise complete control on the app settings and behavior.

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
- modify the Visual Studio projects' configuration files.

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.
```
.\AppCreationScripts\Configure.ps1
```
Other ways of running the scripts are described in App Creation Scripts
Open the Visual Studio solution and click start

If you don't want to use this automation, follow the steps below

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 Directory + Subscription at the top right corner in the menu on top of the page, and switch your portal session to the desired Microsoft Entra tenant.
In the left-hand navigation pane, select the Microsoft Entra ID service, and then select App registrations.

Register the client app (iwa-console)

In App registrations (Preview) page, select New registration.
When the Register an application page 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 iwa-console.
- In the Supported account types section, select Accounts in any organizational directory.
- Select Register to create the application.
On the app Overview page, find the Application (client) ID value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.
In the list of pages for the app, select Manifest, and:
- In the manifest editor, set the allowPublicClient property to true
- Select Save in the bar above the manifest editor.
In the list of pages for the app, select API permissions
- 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, ensure that the right permissions are checked: User.Read, User.ReadBasic.All. Use the search box if necessary.
- Select the Add permissions button
At this stage permissions are assigned correctly but the client app does not allow interaction. Therefore no consent can be presented via a UI and accepted to use the service app. Click the Grant/revoke admin consent for {tenant} button, and then select Yes when you are asked if you want to grant consent for the requested permissions for all account in the tenant. You need to be a Microsoft Entra tenant admin to do this.

Step 3: Configure the sample to use your Microsoft Entra tenant

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

Open the solution in Visual Studio to configure the projects

Configure the client project

Note: if you used the setup scripts, the changes below will have been applied for you

Open the iwa-console\appsettings.json file
Find the line where clientId is set and replace the existing value with the application ID (clientId) of the iwa-console application copied from the Microsoft Entra admin center.
[optionally] Find the line where Tenant is set and replace the existing value with your tenant ID.

Clean the solution, rebuild the solution, and start it in the debugger.

About the code

The code for handling the token acquisition process is simple, as it boils down to calling the AcquireTokenByIntegratedWindowsAuthAsync method of PublicClientApplication. See the GetTokenForWebApiUsingIntegratedWindowsAuthenticationAsync method in PublicAppUsingIntegratedWindowsAuthentication.cs.

private async Task<AuthenticationResult> GetTokenForWebApiUsingIntegratedWindowsAuthenticationAsync(IEnumerable<string> scopes)
{
    AuthenticationResult result=null;
    try
    {
        result = await App.AcquireTokenByIntegratedWindowsAuthAsync(scopes);
    }
    catch() 
        ...
        // error handling omitted here (see sample for details)

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 [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 [email protected] with any additional questions or comments.

More information

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

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
Integrated Windows Authentication
Customizing Token cache serialization (was not done in this sample, but you might want to add a serialized cache)

For more information about the Microsoft identity platform endpoint see:

https://aka.ms/aadv2

ehtick / active-directory-dotnet-iwa-v2 Goto Github PK

active-directory-dotnet-iwa-v2's Introduction