You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
#Customer intent: As an application developer, I want to know how to write a Web app that signs-in users using the Microsoft identity platform for developers.
@@ -31,20 +31,33 @@ The libraries used to protect a Web App (and a Web API) are:
31
31
| Platform | Library | Description |
32
32
|----------|---------|-------------|
33
33
||[Identity model extensions for .NET](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki)| Used directly by ASP.NET and ASP.NET Core, Microsoft Identity Extensions for .NET proposes a set of DLLs running both on .NET Framework and .NET Core. From an ASP.NET/ASP.NET Core Web app, you can control token validation using the **TokenValidationParameters** class (in particular in some ISV scenarios) |
34
+
||[msal4j](https://github.com/AzureAD/microsoft-authentication-library-for-java/wiki)| MSAL for Java - currently in public preview |
35
+
||[MSAL Python](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki)| MSAL for Python - currently in public preview |
34
36
35
-
## ASP.NET Core configuration
37
+
Code snippets in this article and the following are extracted from:
36
38
37
-
Code snippets in this article and the following are extracted from the [ASP.NET Core Web app incremental tutorial, chapter 1](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-1-MyOrg). You might want to refer to that tutorial for full implementation details.
39
+
- the [ASP.NET Core Web app incremental tutorial, chapter 1](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-1-MyOrg).
40
+
- the [ASP.NET Web app sample](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect)
41
+
- the [Java web application calling Microsoft graph](https://github.com/Azure-Samples/ms-identity-java-webapp) msal4j web app sample
42
+
- the [Python web application calling Microsoft graph](https://github.com/Azure-Samples/ms-identity-python-webapp) MSAL.Python web app sample
38
43
39
-
### Application configuration files
44
+
You might want to refer to these tutorials and sample for full implementation details.
40
45
41
-
In ASP.NET Core, a Web application signing-in users with the Microsoft identity platform is configured through the `appsettings.json` file. The settings that you need to fill in are:
46
+
## Configuration files
42
47
43
-
- the cloud `Instance` if you want your app to run in national clouds
48
+
Web applications that sign in users with the Microsoft identity platform are usually configured through configuration files. The settings that you need to fill in are:
49
+
50
+
- the cloud `Instance` if you want your app to run (for instance in national clouds)
44
51
- the audience in `tenantId`
45
52
- the `clientId` for your application, as copied from the Azure portal.
46
53
47
-
```JSon
54
+
Sometimes, applications can be parametrized by the `authority`, which is the concatenation of the `instance` and the `tenantId`
55
+
56
+
# [ASP.NET Core](#tab/aspnetcore)
57
+
58
+
In ASP.NET Core, these settings are located in the `appsettings.json` file, in the "AzureAD" section.
59
+
60
+
```Json
48
61
{
49
62
"AzureAd": {
50
63
// Azure Cloud instance among:
@@ -69,9 +82,9 @@ In ASP.NET Core, a Web application signing-in users with the Microsoft identity
69
82
}
70
83
```
71
84
72
-
In ASP.NET Core, there's another file that contains the URL (`applicationUrl`) and the SSL Port (`sslPort`) for your application as well as various profiles.
85
+
In ASP.NET Core, there's another file (`properties\launchSettings.json`) that contains the URL (`applicationUrl`) and the SSL Port (`sslPort`) for your application and various profiles.
73
86
74
-
```JSon
87
+
```Json
75
88
{
76
89
"iisSettings": {
77
90
"windowsAuthentication": false,
@@ -103,42 +116,9 @@ In ASP.NET Core, there's another file that contains the URL (`applicationUrl`) a
103
116
104
117
In the Azure portal, the reply URIs that you need to register in the **Authentication** page for your application needs to match these URLs; that is, for the two configuration files above, they would be `https://localhost:44321/signin-oidc` as the applicationUrl is `http://localhost:3110` but the `sslPort` is specified (44321), and the `CallbackPath` is `/signin-oidc` as defined in the `appsettings.json`.
105
118
106
-
In the same way, the sign out URI would be set to `https://localhost:44321/signout-callback-oidc`.
107
-
108
-
### Initialization code
109
-
110
-
In ASP.NET Core Web Apps (and Web APIs), the code doing the application initialization is located in the `Startup.cs` file, and, to add authentication with the Microsoft identity platform (formerly Azure AD v2.0), you'll need to add the following code. The comments in the code should be self-explanatory.
111
-
112
-
> [!NOTE]
113
-
> If you start your project with default ASP.NET core web project within Visual studio or using `dotnet new mvc` the method `AddAzureAD` is available by default because the related packages are automatically loaded.
114
-
> However if you build a project from scratch and are trying to use the below code we suggest you to add the NuGet Package **"Microsoft.AspNetCore.Authentication.AzureAD.UI"** to your project to make the `AddAzureAD` method available.
In ASP.NET, the application is configured through the `Web.Config` file
144
124
@@ -162,6 +142,149 @@ In ASP.NET, the application is configured through the `Web.Config` file
162
142
</appSettings>
163
143
```
164
144
145
+
In the Azure portal, the reply URIs that you need to register in the **Authentication** page for your application needs to match these URLs; that is `https://localhost:44326/`.
146
+
147
+
# [Java](#tab/java)
148
+
149
+
In Java, the configuration is located in the `application.properties` file located under `src/main/resources`
In the Azure portal, the reply URIs that you need to register in the **Authentication** page for your application needs to match the redirectUris defined by the application, that is `http://localhost:8080/msal4jsample/secure/aad` and `http://localhost:8080/msal4jsample/graph/users`
160
+
161
+
# [Python](#tab/python)
162
+
163
+
Here is the Python configuration file in [app_config.py](https://github.com/Azure-Samples/ms-identity-python-webapp/blob/web_app_sample/app_config.py)
The initialization code is different depending on the platform. For ASP.NET Core and ASP.NET, signing in users is delegated to the OpenIDConnect middleware. Today the ASP.NET / ASP.NET Core template generate web applications for the Azure AD v1.0 endpoint. Therefore, a bit of configuration is required to adapt them to the Microsoft identity platform (v2.0) endpoint. In the case of Java, it's handled by Spring with the cooperation of the application.
178
+
179
+
# [ASP.NET Core](#tab/aspnetcore)
180
+
181
+
In ASP.NET Core Web Apps (and Web APIs), the application is protected because you have a `[Authorize]` attribute on the controllers or the controller actions. This attribute checks that the user is authenticated. The code doing the application initialization is located in the `Startup.cs` file, and, to add authentication with the Microsoft identity platform (formerly Azure AD v2.0), you'll need to add the following code. The comments in the code should be self-explanatory.
182
+
183
+
> [!NOTE]
184
+
> If you start your project with default ASP.NET core web project within Visual studio or using `dotnet new mvc` the method `AddAzureAD` is available by default because the related packages are automatically loaded.
185
+
> However if you build a project from scratch and are trying to use the below code we suggest you to add the NuGet Package **"Microsoft.AspNetCore.Authentication.AzureAD.UI"** to your project to make the `AddAzureAD` method available.
186
+
187
+
The following code is available from [Startup.cs#L33-L34](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/faa94fd49c2da46b22d6694c4f5c5895795af26d/1-WebApp-OIDC/1-1-MyOrg/Startup.cs#L33-L34)
188
+
189
+
```CSharp
190
+
publicclassStartup
191
+
{
192
+
...
193
+
194
+
// This method gets called by the runtime. Use this method to add services to the container.
The `AddMicrosoftIdentityPlatformAuthentication` is an extension method defined in [Microsoft.Identity.Web/WebAppServiceCollectionExtensions.cs#L23](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/faa94fd49c2da46b22d6694c4f5c5895795af26d/Microsoft.Identity.Web/WebAppServiceCollectionExtensions.cs#L23). It:
213
+
214
+
- adds the authenticationservice
215
+
- configure options to read the configfile
216
+
- configures the OpenID connect options so that the used authority is the Microsoft identityplatform (formerlyAzureADv2.0) endpoint
217
+
- the issuer of the token is validated
218
+
- the claims corresponding to name is mapped from the "preferred_username" claim in the ID Token
219
+
220
+
In addition to the configuration, you can specify, when calling `AddMicrosoftIdentityPlatformAuthentication`:
221
+
222
+
- the name of the configuration section (bydefault AzureAD)
223
+
- if you want to trace the OpenIdConnect middleware events, which can help you troubleshooting your Web application if authentication doesn't work: setting `subscribeToOpenIdConnectMiddlewareDiagnosticsEvents` to `true` will show you how information gets elaborated by the set of ASP.NET Core middleware as it progresses from the HTTP response to the identity of the user in the `HttpContext.User`.
224
+
225
+
```CSharp
226
+
/// <summary>
227
+
/// Add authentication with Microsoft identity platform.
228
+
/// This method expects the configuration file will have a section named "AzureAd" with the necessary settings to initialize authentication options.
229
+
/// </summary>
230
+
/// <paramname="services">Service collection to which to add this authentication scheme</param>
The `AadIssuerValidator` classenables that the issuer of the token is validated in many cases (v1.0 orv2.0 token, single-tenant, ormulti-tenantapplicationorapplicationthatsignsinuserswiththeirpersonalMicrosoftaccounts, intheAzurepubliccloudornational clouds). It's available from [Microsoft.Identity.Web/Resource/AadIssuerValidator.cs](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/master/Microsoft.Identity.Web/Resource/AadIssuerValidator.cs)
285
+
286
+
# [ASP.NET](#tab/aspnet)
287
+
165
288
The code related to authentication in ASP.NET Web app / Web APIs is located in the `App_Start/Startup.Auth.cs` file.
166
289
167
290
```CSharp
@@ -186,7 +309,66 @@ The code related to authentication in ASP.NET Web app / Web APIs is located in t
186
309
}
187
310
```
188
311
312
+
# [Java](#tab/java)
313
+
314
+
The Java sample uses the Spring framework. The application is protected because you implement a `Filter`, which gets each HTTP response. In the Java Web appquickstart, thisis `AuthFilter` in `src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java`. ThefilterprocesstheOAuth 2.0 authorizationcodeflowandtherefore:
See [MicrosoftidentityplatformandOAuth 2.0 authorizationcodeflow](v2-oauth2-auth-code-flow.md) fordetailsabouttheauthorizationcodeflowtriggeredbythismethod
ThisisMSAL.Pythonthatwilltakecareoflettingtheusersign-in. See [app.py#L74-84](https://github.com/Azure-Samples/ms-identity-python-webapp/blob/e1199b4c3cdcb637cf0d8306832efbd85492e123/app.py#L74-84)
0 commit comments