Merge pull request #232360 from henrymbuguakiarie/msid-gtd-combine-howto-set

[msid][gtd][staging-release] Combining tutorial sets for web app, web API and SPA (ADO-80411)

Author: Court72

articles/active-directory/develop/TOC.yml

@@ -56,6 +56,14 @@
         href: single-page-app-tutorial-03-sign-in-users.md
       - name: 4 - Get user data from web API
         href: single-page-app-tutorial-04-call-api.md
+  - name: Web API
+    items:
+    - name: 1 - Register the API
+      href: web-api-tutorial-01-register-app.md
+    - name: 2 - Create and configure project 
+      href: web-api-tutorial-02-prepare-api.md
+    - name: 3 - Protect API endpoint
+      href: web-api-tutorial-03-protect-endpoint.md
   - name: Web app
     items:
     - name: ASP.NET
@@ -450,6 +458,10 @@
       href: sample-v2-code.md#web-api
     - name: How-to
       items:
+        - name: Call an ASP.NET API with cURL
+          href: howto-call-a-web-api-with-curl.md
+        - name: Call an ASP.NET API with Postman
+          href: howto-call-a-web-api-with-postman.md
         - name: Protected web API
           items:
             - name: Overview

articles/active-directory/develop/howto-call-a-web-api-with-curl.md

@@ -0,0 +1,72 @@
+---
+title: "Tutorial:  Register a web API with the Microsoft identity platform"
+description: In this tutorial, you learn how to register a web API with the Microsoft identity platform.
+author: cilwerner
+ms.author: cwerner
+manager: CelesteDG
+ms.service: active-directory
+ms.topic: tutorial
+ms.date: 11/1/2022
+#Customer intent: As an application developer, I want to know how to register my application with the Microsoft identity platform so that the security token service can issue access tokens to client applications that request them.
+---
+
+# Tutorial: Register a web API with the Microsoft identity platform 
+
+To interact with the Microsoft identity platform, Azure Active Directory (Azure AD) must be made aware of the application you create. This tutorial shows you how to register an application in a tenant on the Azure portal. 
+
+In this tutorial: 
+
+> [!div class="checklist"] 
+> * Register a web API in a tenant 
+> * Record the web API's unique identifiers 
+> * Expose an API by adding a scope 
+
+## Prerequisites 
+
+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/). 
+* This Azure account must have permissions to manage applications. Use any of the following roles needed to register the application: 
+  * Application administrator 
+  * Application developer 
+  * Cloud application administrator
+
+## Register the application and record identifiers 
+
+To complete registration, provide the application a name and specify the supported account types. Once registered, the application **Overview** page will display the identifiers needed in the application source code. 
+
+1. Sign in to the [Azure portal](https://portal.azure.com/). 
+1. If access to multiple tenants is available, use the **Directories + subscriptions** filter :::image type="icon" source="media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application. 
+1. Search for and select **Azure Active Directory**. 
+1. Under **Manage**, select **App registrations > New registration**. 
+1. Enter a **Name** for the application, such as *NewWebAPI1*. 
+1. For **Supported account types**, select **Accounts in this organizational directory only**. For information on different account types, select **Help me choose** option. 
+1. Select **Register**. 
+
+    :::image type="content" source="./media/web-api-tutorial-01-register-app/register-application.png" alt-text="Screenshot that shows how to enter a name and select the account type."::: 
+
+1. The application's **Overview** pane is displayed when registration is complete. Record the **Directory (tenant) ID** and the **Application (client) ID** to be used in your application source code. 
+
+    :::image type="content" source="./media/web-api-tutorial-01-register-app/record-identifiers.png" alt-text="Screenshot that shows the identifier values on the overview page."::: 
+
+>[!NOTE]
+> The **Supported account types** can be changed by referring to [Modify the accounts supported by an application](howto-modify-supported-accounts.md).
+
+## Expose an API 
+
+Once the API is registered, you can configure its permission by defining the scopes that the API exposes to client applications. Client applications request permission to perform operations by passing an access token along with its requests to the protected web API. The web API then performs the requested operation only if the access token it receives contains the required scopes.
+
+1. Under **Manage**, select **Expose an API > Add a scope**. Accept the proposed **Application ID URI** `(api://{clientId})` by selecting **Save and continue**. The `{clientId}` will be the value recorded from the **Overview** page. Then enter the following information: 
+    1. For **Scope name**, enter `Forecast.Read`. 
+    1. For **Who can consent**, ensure that the **Admins and users** option is selected. 
+    1. In the **Admin consent display name** box, enter `Read forecast data`. 
+    1. In the **Admin consent description** box, enter `Allows the application to read weather forecast data`. 
+    1. In the **User consent display name** box, enter `Read forecast data`. 
+    1. In the **User consent description** box, enter `Allows the application to read weather forecast data`. 
+    1. Ensure that the **State** is set to **Enabled**.
+1. Select **Add scope**. If the scope has been entered correctly, it'll be listed in the **Expose an API** pane. 
+
+    :::image type="content" source="./media/web-api-tutorial-01-register-app/add-a-scope-inline.png" alt-text="Screenshot that shows the field values when adding the scope to an API." lightbox="./media/web-api-tutorial-01-register-app/add-a-scope-expanded.png"::: 
+
+## Next steps 
+
+> [!div class="nextstepaction"] 
+> [Tutorial: Create an ASP.NET Core project and configure the API](web-api-tutorial-02-prepare-api.md) 

articles/active-directory/develop/howto-call-a-web-api-with-postman.md

@@ -0,0 +1,130 @@
+---
+title: "Tutorial: Create and configure an ASP.NET Core project for authentication"
+description: "Create and configure the API in an IDE, add configuration for authentication and install required packages"
+author: cilwerner
+ms.author: cwerner
+manager: CelesteDG
+ms.service: active-directory
+ms.topic: tutorial
+ms.date: 11/1/2022
+#Customer intent: As an application developer, I want to create an ASP.NET Core project in an IDE, then configure it in such a way that I can add authentication with Azure AD.
+---
+
+# Tutorial: Create and configure an ASP.NET Core project for authentication
+
+After registration is complete, a ASP.NET Core project can be created using an integrated development environment (IDE). This tutorial demonstrates how to create an ASP.NET Core project using an IDE and configure for authentication and authorization.
+
+In this tutorial: 
+
+> [!div class="checklist"] 
+> * Create an **ASP.NET Core Empty**
+> * Configure the settings for the application 
+> * Identify and install the required NuGet packages 
+
+## Prerequisites 
+
+* Completion of the prerequisites and steps in [Tutorial: Register web API with the Microsoft identity platform](web-api-tutorial-01-register-app.md).
+* You can download the IDEs used in this tutorial from the [Downloads](https://visualstudio.microsoft.com/downloads) page. 
+  - Visual Studio 2022 
+  - Visual Studio Code 
+  - Visual Studio 2022 for Mac 
+- A minimum requirement of [.NET Core 6.0 SDK](https://dotnet.microsoft.com/download/dotnet). 
+
+## Create an ASP.NET Core project 
+
+Use the following tabs to create an ASP.NET Core project within an IDE. 
+
+### [Visual Studio](#tab/visual-studio) 
+
+1. Open Visual Studio, and then select **Create a new project**.
+1. Search for and choose the **ASP.NET Core Empty** template, and then select **Next**.
+1. Enter a name for the project, such as *NewWebAPILocal*.
+1. Choose a location for the project or accept the default option, and then select **Next**.
+1. Accept the default for the **Framework** and **Configure for HTTPS**.
+1. Select **Create**.
+
+### [Visual Studio Code](#tab/visual-studio-code) 
+
+1. Open Visual Studio Code, select **File > Open Folder...**. Navigate to and select the location in which to create your project. 
+1. Open up a new terminal by selecting **Terminal** in the top bar, then **New Terminal**.
+1. Create a new folder using the **New Folder...** icon in the **Explorer** pane. Provide a name similar to the one registered previously, for example, *NewWebAPILocal*.
+1. Open a new terminal by selecting **Terminal > New Terminal**.
+1. To create an **ASP.NET Core Empty** template, run the following commands in the terminal to change into the directory and create the project:  
+
+    ```powershell
+    cd NewWebAPILocal
+    dotnet new web
+    ```
+
+### [Visual Studio for Mac](#tab/visual-studio-for-mac)
+
+1. Open Visual Studio, and then select **New**.
+1. Under **Web and Console** in the left navigation bar, select **App**.
+1. Under **ASP.NET Core**, select **API** and ensure **C#** is selected in the drop down menu, then select **Continue**.
+1. Accept the default for the **Target Framework** and **Advanced**, then select **Continue**.
+1. Enter a name for the **Project name**, this will be reflected in **Solution Name**. Provide a similar name to the one registered on the Azure portal, such as *NewAPI1*.
+1. Accept the default location for the project or choose a different location, and then select **Create**.
+---
+
+## Configure the ASP.NET Core project
+
+The values recorded earlier will be used in *appsettings.json* to configure the application for authentication. *appsettings.json* is a configuration file that is used to store application settings used during run-time.
+
+1. Open *appsettings.json* and replace the file contents with the following code snippet: 
+
+    ```json
+    {
+      "AzureAd": {
+        "Instance": "https://login.microsoftonline.com/",
+        "ClientId": "Enter the client ID here",
+        "TenantId": "Enter the tenant ID here",
+        "Scopes": "Forecast.Read"
+      },
+      "Logging": {
+        "LogLevel": {
+          "Default": "Information",
+          "Microsoft.AspNetCore": "Warning"
+        }
+      },
+      "AllowedHosts": "*"
+    } 
+    ```
+
+    * `Instance` - The endpoint of the cloud provider. Check with the different available endpoints in [National clouds](authentication-national-cloud.md#azure-ad-authentication-endpoints).
+    * `TenantId` - The identifier of the tenant where the application is registered. Replace the text in quotes with the **Directory (tenant) ID** value that was recorded earlier from the overview page of the registered application.
+    * `ClientId` - The identifier of the application, also referred to as the client. Replace the text in quotes with the **Application (client) ID** value that was recorded earlier from the overview page of the registered application.
+    * `Scopes` - The scope that is used to request access to the application. For this tutorial, the scope is `Forecast.Read`.
+1. Save the changes to the file.
+
+## Install identity packages
+
+Identity related **NuGet packages** must be installed in the project for authentication of users to be enabled.
+
+### [Visual Studio](#tab/visual-studio)
+
+1. In the top menu, select **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. 
+1. With the **Browse** tab selected, search for **Microsoft.Identity.Web**, select the `Microsoft.Identity.Web` package, select the **Project** checkbox, and then select **Install**. 
+1. Select **Ok** or **I Accept** for other windows that may appear. 
+
+### [Visual Studio Code](#tab/visual-studio-code) 
+
+1. In the terminal opened in the previous section, enter the following command: 
+
+    ```powershell
+    dotnet add package Microsoft.Identity.Web 
+    ```
+
+### [Visual Studio for Mac](#tab/visual-studio-for-mac) 
+
+1. In the top menu, select **Tools** > **Manage NuGet Packages**. 
+1. Search for **Microsoft.Identity.Web**, select the `Microsoft.Identity.Web` package, select **Project**, and then select **Add Package**. 
+1. Modify the search to **Microsoft.Identity.Web.UI** and select **Add Packages**. 
+1. In the pop-up, ensure the correct project is selected, then select **Ok**. 
+1. Select **Accept** if other **License Acceptance** windows appear. 
+
+---
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Tutorial: Implement a protected endpoint to your API](web-api-tutorial-03-protect-endpoint.md)