Merge pull request #235332 from jmprieur/jmprieur/webappIdWeb2x

Update web app how to, to IdWeb 2x

Author: v-regandowner

articles/active-directory/develop/includes/web-app-client-credentials.md

@@ -0,0 +1,75 @@
+---
+title: Client credentials for web apps and web APIs calling downstream APIs
+description: Include file with a common configuration in web apps and web APIs calling downstream web APIs (ASP.NET Core and ASP.NET OWIN).
+services: active-directory
+author: jmprieur
+manager: CelesteDG
+
+ms.service: active-directory
+ms.subservice: develop
+ms.workload: identity
+ms.topic: include
+ms.date: 05/08/2023
+ms.author: jmprieur
+ms.reviewer: jmprieur
+ms.custom: aaddev
+---
+
+Given that your web app now calls a downstream web API, provide a client secret or client certificate in the *appsettings.json* file. You can also add a section that specifies:
+
+- The URL of the downstream web API
+- The scopes required for calling the API
+
+In the following example, the `GraphBeta` section specifies these settings.
+
+```JSON
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "ClientId": "[Enter_the_Application_Id_Here]",
+    "TenantId": "common",
+
+   // To call an API
+   "ClientCredentials": [
+    {
+      "SourceType": "ClientSecret",
+      "ClientSecret":"[Enter_the_Client_Secret_Here]"
+    }
+  ]
+ },
+ "GraphBeta": {
+    "BaseUrl": "https://graph.microsoft.com/beta",
+    "Scopes": "user.read"
+    }
+}
+```
+> [!NOTE]
+> You can propose a collection of client credentials, including a credential-less solution like workload identity federation for Azure Kubernetes. 
+> Previous versions of Microsoft.Identity.Web expressed the client secret in a single property "ClientSecret" instead of "ClientCredentials". This is still supported for backwards compatibility but you cannot use both the "ClientSecret" property, and the "ClientCredentials" collection.
+
+Instead of a client secret, you can provide a client certificate. The following code snippet shows using a certificate stored in Azure Key Vault.
+
+```JSON
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "ClientId": "[Enter_the_Application_Id_Here]",
+    "TenantId": "common",
+
+   // To call an API
+   "ClientCredentials": [
+      {
+        "SourceType": "KeyVault",
+        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
+        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
+      }
+   ]
+  },
+  "GraphBeta": {
+    "BaseUrl": "https://graph.microsoft.com/beta",
+    "Scopes": "user.read"
+  }
+}
+```
+
+*Microsoft.Identity.Web* provides several ways to describe certificates, both by configuration or by code. For details, see [Microsoft.Identity.Web - Using certificates](https://github.com/AzureAD/microsoft-identity-web/wiki/Using-certificates) on GitHub.

articles/active-directory/develop/scenario-web-app-call-api-acquire-token.md

@@ -18,7 +18,7 @@ ms.custom: aaddev
 
 # A web app that calls web APIs: Acquire a token for the app
 
-You've built your client application object. Now, you'll use it to acquire a token to call a web API. In ASP.NET or ASP.NET Core, calling a web API is done in the controller:
+You've built your client application object. Now, you use it to acquire a token to call a web API. In ASP.NET or ASP.NET Core, calling a web API is done in the controller:
 
 - Get a token for the web API by using the token cache. To get this token, you call the Microsoft Authentication Library (MSAL) `AcquireTokenSilent` method (or the equivalent in Microsoft.Identity.Web).
 - Call the protected API, passing the access token to it as a parameter.
@@ -27,27 +27,27 @@ You've built your client application object. Now, you'll use it to acquire a tok
 
 *Microsoft.Identity.Web* adds extension methods that provide convenience services for calling Microsoft Graph or a downstream web API. These methods are explained in detail in [A web app that calls web APIs: Call an API](scenario-web-app-call-api-call-api.md). With these helper methods, you don't need to manually acquire a token.
 
-If, however, you do want to manually acquire a token, the following code shows an example of using *Microsoft.Identity.Web* to do so in a home controller. It calls Microsoft Graph using the REST API (instead of the Microsoft Graph SDK). To get a token to call the downstream API, you inject the `ITokenAcquisition` service by dependency injection in your controller's constructor (or your page constructor if you use Blazor), and you use it in your controller actions, getting a token for the user (`GetAccessTokenForUserAsync`) or for the application itself (`GetAccessTokenForAppAsync`) in a daemon scenario.
+If, however, you do want to manually acquire a token, the following code shows an example of using *Microsoft.Identity.Web* to do so in a home controller. It calls Microsoft Graph using the REST API (instead of the Microsoft Graph SDK). Usually, you don't need to get a token, you need to build an Authorization header that you add to your request. To get an authorization header, you inject the `IAuthorizationHeaderProvider` service by dependency injection in your controller's constructor (or your page constructor if you use Blazor), and you use it in your controller actions. This interface has methods that produce a string containing the protocol (Bearer, Pop, ...) and a token. To get an authorization header to call an API on behalf of the user, use (`CreateAuthorizationHeaderForUserAsync`). To get an authorization header to call a downstream API on behalf of the application itself, in a daemon scenario, use (`CreateAuthorizationHeaderForAppAsync`).
 
 The controller methods are protected by an `[Authorize]` attribute that ensures only authenticated users can use the web app.
 
 ```csharp
 [Authorize]
 public class HomeController : Controller
 {
- readonly ITokenAcquisition tokenAcquisition;
+ readonly IAuthorizationHeaderProvider authorizationHeaderProvider;
 
- public HomeController(ITokenAcquisition tokenAcquisition)
+ public HomeController(IAuthorizationHeaderProvider authorizationHeaderProvider)
  {
-  this.tokenAcquisition = tokenAcquisition;
+  this.authorizationHeaderProvider = authorizationHeaderProvider;
  }
 
  // Code for the controller actions (see code below)
 
 }
 ```
 
-The `ITokenAcquisition` service is injected by ASP.NET by using dependency injection.
+ASP.NET Core makes `IAuthorizationHeaderProvider` available by dependency injection.
 
 Here's simplified code for the action of the `HomeController`, which gets a token to call Microsoft Graph:
 
@@ -57,11 +57,11 @@ public async Task<IActionResult> Profile()
 {
  // Acquire the access token.
  string[] scopes = new string[]{"user.read"};
- string accessToken = await tokenAcquisition.GetAccessTokenForUserAsync(scopes);
+ string accessToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(scopes);
 
  // Use the access token to call a protected web API.
  HttpClient client = new HttpClient();
- client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
+ client.DefaultRequestHeaders.Add("Authorization", authorizationHeader);
  string json = await client.GetStringAsync(url);
 }
 ```
@@ -82,40 +82,59 @@ These advanced steps are covered in chapter 3 of the [3-WebApp-multi-APIs](https
 The code for ASP.NET is similar to the code shown for ASP.NET Core:
 
 - A controller action, protected by an [Authorize] attribute, extracts the tenant ID and user ID of the `ClaimsPrincipal` member of the controller. (ASP.NET uses `HttpContext.User`.)
-- From there, it builds an MSAL.NET `IConfidentialClientApplication` object.
-- Finally, it calls the `AcquireTokenSilent` method of the confidential client application.
-- If interaction is required, the web app needs to challenge the user (re-sign in) and ask for more claims.
+*Microsoft.Identity.Web* adds extension methods to the Controller that provide convenience services to call Microsoft Graph or a downstream web API, or to get an authorization header, or even a token. The methods used to call an API directly are explained in detail in [A web app that calls web APIs: Call an API](scenario-web-app-call-api-call-api.md). With these helper methods, you don't need to manually acquire a token.
 
->[!NOTE]
->The scope should be the fully qualified scope name. For example,`({api_uri}/scope)`.
+If, however, you do want to manually acquire a token or build an authorization header, the following code shows how to use *Microsoft.Identity.Web* to do so in a controller. It calls an API (Microsoft Graph) using the REST API instead of the Microsoft Graph SDK. 
 
-The following code snippet is extracted from [HomeController.cs#L157-L192](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect/blob/257c8f96ec3ff875c351d1377b36403eed942a18/WebApp/Controllers/HomeController.cs#L157-L192) in the [ms-identity-aspnet-webapp-openidconnect](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect) ASP.NET MVC code sample:
+To get an authorization header, you get an `IAuthorizationHeaderProvider` service from the controller using an extension method `GetAuthorizationHeaderProvider`. To get an authorization header to call an API on behalf of the user, use `CreateAuthorizationHeaderForUserAsync`. To get an authorization header to call a downstream API on behalf of the application itself, in a daemon scenario, use `CreateAuthorizationHeaderForAppAsync`.
 
-```C#
-public async Task<ActionResult> ReadMail()
-{
-    IConfidentialClientApplication app = MsalAppBuilder.BuildConfidentialClientApplication();
-    AuthenticationResult result = null;
-    var account = await app.GetAccountAsync(ClaimsPrincipal.Current.GetMsalAccountId());
-    string[] scopes = { "Mail.Read" };
-
-    try
-    {
-        // try to get token silently
-        result = await app.AcquireTokenSilent(scopes, account).ExecuteAsync().ConfigureAwait(false);
-    }
-    catch (MsalUiRequiredException)
-    {
-        ViewBag.Relogin = "true";
-        return View();
-    }
+The controller methods are protected by an `[Authorize]` attribute that ensures only authenticated users can use the web app.
+
+
+The following snippet shows the action of the `HomeController`, which gets an authorization header to call Microsoft Graph as a REST API:
 
-    // More code here
-    return View();
+
+```csharp
+[Authorize]
+public class HomeController : Controller
+{
+ [AuthorizeForScopes(Scopes = new[] { "user.read" })]
+ public async Task<IActionResult> Profile()
+ {
+  // Get an authorization header.
+  IAuthorizationHeaderProvider authorizationHeaderProvider = this.GetAuthorizationHeaderProvider();
+  string[] scopes = new string[]{"user.read"};
+  string authorizationHeader = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(scopes);
+
+  // Use the access token to call a protected web API.
+  HttpClient client = new HttpClient();
+  client.DefaultRequestHeaders.Add("Authorization", authorizationHeader);
+  string json = await client.GetStringAsync(url);
+ }
 }
 ```
 
-For details see the code for [GetMsalAccountId](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect/blob/257c8f96ec3ff875c351d1377b36403eed942a18/WebApp/Utils/ClaimPrincipalExtension.cs#L38) in the code sample.
+The following snippet shows the action of the `HomeController`, which gets an access token to call Microsoft Graph as a REST API:
+
+```csharp
+[Authorize]
+public class HomeController : Controller
+{
+ [AuthorizeForScopes(Scopes = new[] { "user.read" })]
+ public async Task<IActionResult> Profile()
+ {
+  // Get an authorization header.
+  ITokenAcquirer tokenAcquirer = TokenAcquirerFactory.GetDefaultInstance().GetTokenAcquirer();
+  string[] scopes = new string[]{"user.read"};
+  string token = await await tokenAcquirer.GetTokenForUserAsync(scopes);
+
+  // Use the access token to call a protected web API.
+  HttpClient client = new HttpClient();
+  client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
+  string json = await client.GetStringAsync(url);
+ }
+}
+```
 
 
 # [Java](#tab/java)