|
1 | | -In this exercise you learn how to perform the following actions: |
| 1 | +In this exercise, you register an application in Microsoft Entra ID, then create a .NET console application that uses MSAL.NET to perform interactive authentication and acquire an access token for Microsoft Graph. You learn how to configure authentication scopes, handle user consent, and see how tokens are cached for subsequent runs. |
2 | 2 |
|
3 | | -* Register an application with the Microsoft identity platform |
4 | | -* Use the `PublicClientApplicationBuilder` class in MSAL.NET |
5 | | -* Acquire a token interactively in a console application |
6 | | - |
7 | | -## Prerequisites |
8 | | - |
9 | | -* An **Azure account** with an active subscription. If you don't already have one, you can sign up for a free trial at [https://azure.com/free](https://azure.com/free) |
10 | | -* **Visual Studio Code**: You can install Visual Studio Code from [https://code.visualstudio.com](https://code.visualstudio.com/). |
11 | | -* A version of the .NET SDK [https://dotnet.microsoft.com/download/dotnet](https://dotnet.microsoft.com/en-us/download/dotnet) (6.0, 7.0, or 8.0) |
12 | | - |
13 | | -## Register a new application |
14 | | - |
15 | | -1. Sign in to the portal: [https://portal.azure.com](https://portal.azure.com) |
16 | | - |
17 | | -1. Search for and select **Microsoft Entra ID**. |
18 | | - |
19 | | -1. Under **Manage**, select **App registrations** > **New registration**. |
20 | | - |
21 | | -1. When the **Register an application** page appears, enter your application's registration information: |
22 | | - |
23 | | - | Field | Value | |
24 | | - |--|--| |
25 | | - | **Name** | `az204appreg` | |
26 | | - | **Supported account types** | Select **Accounts in this organizational directory only** | |
27 | | - | **Redirect URI (optional)** | Select **Public client/native (mobile & desktop)** and enter `http://localhost` in the box to the right. | |
28 | | - |
29 | | -1. Select **Register**. |
30 | | - |
31 | | -Microsoft Entra ID assigns a unique application (client) ID to your app, and you're taken to your application's **Overview** page. |
32 | | - |
33 | | -## Set up the console application |
34 | | - |
35 | | -1. Launch Visual Studio Code and open a terminal by selecting **Terminal** and then **New Terminal**. |
36 | | - |
37 | | -1. Create a folder for the project and change in to the folder. |
38 | | - |
39 | | - ```ps |
40 | | - md az204-auth |
41 | | - cd az204-auth |
42 | | - ``` |
43 | | -
|
44 | | -1. Create the .NET console app. |
45 | | -
|
46 | | - ```ps |
47 | | - dotnet new console |
48 | | - ``` |
49 | | -
|
50 | | -1. Open the *az204-auth* folder in Visual Studio Code. |
51 | | -
|
52 | | - ```ps |
53 | | - code . -r |
54 | | - ``` |
55 | | -
|
56 | | -## Build the console app |
57 | | -
|
58 | | -In this section, you add the necessary packages and code to the project. |
59 | | -
|
60 | | -### Add packages and using statements |
| 3 | +Tasks performed in this exercise: |
61 | 4 |
|
62 | | -1. Add the `Microsoft.Identity.Client` package to the project in a terminal in Visual Studio Code. |
63 | | -
|
64 | | - ```ps |
65 | | - dotnet add package Microsoft.Identity.Client |
66 | | - ``` |
67 | | -
|
68 | | -2. Open the *Program.cs* file and add `using` statements to include `Microsoft.Identity.Client` and to enable async operations. |
69 | | -
|
70 | | - ```csharp |
71 | | - using System.Threading.Tasks; |
72 | | - using Microsoft.Identity.Client; |
73 | | - ``` |
74 | | -
|
75 | | -3. Change the Main method to enable async. |
76 | | -
|
77 | | - ```csharp |
78 | | - public static async Task Main(string[] args) |
79 | | - ``` |
80 | | -
|
81 | | -### Add code for the interactive authentication |
82 | | -
|
83 | | -1. You need two variables to hold the Application (client) and Directory (tenant) IDs. You can copy those values from the portal. Add the following code and replace the string values with the appropriate values from the portal. |
84 | | -
|
85 | | - ```csharp |
86 | | - private const string _clientId = "APPLICATION_CLIENT_ID"; |
87 | | - private const string _tenantId = "DIRECTORY_TENANT_ID"; |
88 | | - ``` |
89 | | -
|
90 | | -2. Use the `PublicClientApplicationBuilder` class to build out the authorization context. |
91 | | -
|
92 | | - ```csharp |
93 | | - var app = PublicClientApplicationBuilder |
94 | | - .Create(_clientId) |
95 | | - .WithAuthority(AzureCloudInstance.AzurePublic, _tenantId) |
96 | | - .WithRedirectUri("http://localhost") |
97 | | - .Build(); |
98 | | - ``` |
99 | | -
|
100 | | - Code | Description |
101 | | - | - | - | |
102 | | - `.Create` | Creates a `PublicClientApplicationBuilder` from a clientID. |
103 | | - `.WithAuthority` | Adds a known Authority corresponding to an ADFS server. In the code we're specifying the Public cloud, and using the tenant for the app we registered. |
104 | | -
|
105 | | -### Acquire a token |
106 | | -
|
107 | | -When you registered the *az204appreg* app, it automatically generated an API permission `user.read` for Microsoft Graph. You use that permission to acquire a token. |
108 | | -
|
109 | | -1. Set the permission scope for the token request. Add the following code below the `PublicClientApplicationBuilder`. |
110 | | -
|
111 | | - ```csharp |
112 | | - string[] scopes = { "user.read" }; |
113 | | - ``` |
114 | | -
|
115 | | -1. Add code to request the token and write the result out to the console. |
116 | | -
|
117 | | - ```csharp |
118 | | - AuthenticationResult result = await app.AcquireTokenInteractive(scopes).ExecuteAsync(); |
119 | | -
|
120 | | - Console.WriteLine($"Token:\t{result.AccessToken}"); |
121 | | - ``` |
122 | | -
|
123 | | -## Review completed application |
124 | | -
|
125 | | -The contents of the *Program.cs* file should resemble the following example: |
126 | | -
|
127 | | -```csharp |
128 | | -using System; |
129 | | -using System.Threading.Tasks; |
130 | | -using Microsoft.Identity.Client; |
| 5 | +* Register an application with the Microsoft identity platform |
| 6 | +* Create a .NET console app that implements the **PublicClientApplicationBuilder** class to configure authentication. |
| 7 | +* Acquire a token interactively using the **user.read** Microsoft Graph permission. |
131 | 8 |
|
132 | | -namespace az204_auth |
133 | | -{ |
134 | | - class Program |
135 | | - { |
136 | | - private const string _clientId = "APPLICATION_CLIENT_ID"; |
137 | | - private const string _tenantId = "DIRECTORY_TENANT_ID"; |
| 9 | +This exercise takes approximately **15** minutes to complete. |
138 | 10 |
|
139 | | - public static async Task Main(string[] args) |
140 | | - { |
141 | | - var app = PublicClientApplicationBuilder |
142 | | - .Create(_clientId) |
143 | | - .WithAuthority(AzureCloudInstance.AzurePublic, _tenantId) |
144 | | - .WithRedirectUri("http://localhost") |
145 | | - .Build(); |
146 | | - string[] scopes = { "user.read" }; |
147 | | - AuthenticationResult result = await app.AcquireTokenInteractive(scopes).ExecuteAsync(); |
| 11 | +## Before you start |
148 | 12 |
|
149 | | - Console.WriteLine($"Token:\t{result.AccessToken}"); |
150 | | - } |
151 | | - } |
152 | | -} |
153 | | -``` |
| 13 | +To complete the exercise, you need: |
154 | 14 |
|
155 | | -## Run the application |
| 15 | +* An Azure subscription. If you don't already have one, you can sign up for one [https://azure.microsoft.com/](https://azure.microsoft.com/). |
156 | 16 |
|
157 | | -1. In the Visual Studio Code terminal run `dotnet build` to check for errors, then `dotnet run` to run the app. |
| 17 | +## Get started |
158 | 18 |
|
159 | | -1. The app opens the default browser prompting you to select the account you want to authenticate with. If there are multiple accounts listed select the one associated with the tenant used in the app. |
| 19 | +Select the **Launch Exercise** button to open the exercise instructions in a new browser window. When you're finished with the exercise, return here to: |
160 | 20 |
|
161 | | -1. If this is the first time you've authenticated to the registered app you receive a **Permissions requested** notification asking you to approve the app to read data associated with your account. Select **Accept**. |
| 21 | +> [!div class="checklist"] |
| 22 | +> * Complete the module |
| 23 | +> * Earn a badge for completing this module |
162 | 24 |
|
163 | | - :::image type="content" source="../media/permission-consent.png" alt-text="Select **Accept** to grant the permission."::: |
| 25 | +<br/> |
164 | 26 |
|
165 | | -1. You should see the results similar to the example below in the console. |
| 27 | +<a href="https://go.microsoft.com/fwlink/?linkid=2325009" target="_blank"> |
| 28 | + <img src="../media/launch-exercise.png" alt="Button to launch exercise."> |
| 29 | +</a> |
166 | 30 |
|
167 | | - ``` |
168 | | - Token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVhU..... |
169 | | - ``` |
0 commit comments