Merge pull request #279917 from craigshoemaker/swa/direct-deploy-quickstart

[Static Web Apps] New: Direct deploy quickstart & add authentication tutorial

Author: Jill Grant

articles/static-web-apps/TOC.yml

@@ -13,13 +13,25 @@
       - name: Build your first static web app
         expanded: true
         items:
-          - name: Visual Studio Code
-            href: getting-started.md
-          - name: Azure portal
-            href: get-started-portal.md
-            displayName: github, devops
-          - name: Azure CLI
-            href: get-started-cli.md
+          - name: Web frameworks
+            href: deploy-web-framework.md
+          - name: Developer tools
+            items:
+                - name: Visual Studio Code
+                  href: getting-started.md
+                - name: Azure portal
+                  href: get-started-portal.md
+                  displayName: github, devops
+                - name: Azure CLI
+                  href: get-started-cli.md
+- name: Scenarios
+  items:
+  - name: Build a site with a web framework
+    items:
+    - name: 1 - Pick a web framework
+      href: deploy-web-framework.md
+    - name: 2 - Add authentication
+      href: add-authentication.md
 - name: Frameworks & libraries
   items:
   - name: Overview

articles/static-web-apps/add-authentication.md

@@ -0,0 +1,112 @@
+---
+title: Add authentication to your static site in Azure Static Web Apps
+description: Learn to add authentication to your static site with Azure Static Web Apps.
+services: static-web-apps
+author: craigshoemaker
+ms.service: static-web-apps
+ms.topic: tutorial
+ms.date: 07/02/2024
+ms.author: cshoe
+---
+
+# Add authentication to your static site in Azure Static Web Apps
+
+This article is part two in a series that show you how to deploy your first site to Azure Static Web Apps. Previously, you created and deployed a static site with the [web framework](./deploy-web-framework.md) of your choice.
+
+In this article, you add authentication to your site and run the site locally before deploying to the cloud.
+
+## Prerequisites
+
+This tutorial continues from the previous tutorial, and has the same [prerequisites](deploy-web-framework.md#prerequisites).
+
+## Authentication and authorization
+
+Azure Static Web Apps makes it easy to use common authentication providers like Microsoft Entra and Google without writing security-related code.
+
+> [!NOTE]
+> You can optionally [register a custom provider and assign custom roles](./authentication-custom.md) for more fine-grained control when using backend APIs.
+
+In this article, you configure your site to use Microsoft Entra ID for authentication.
+
+## Add authentication
+
+In the last article, you created a `staticwebapp.config.json` file. This file [controls many features](./configuration.md) for Azure Static Web Apps, including authentication.
+
+1. Update the `staticwebapp.config.json` to match the following configuration.
+
+    ```json
+    {
+      "navigationFallback": {
+        "rewrite": "/index.html"
+      },
+      "routes": [
+        {
+          "route": "/*",
+          "allowedRoles": [ "authenticated" ]
+        }
+      ],
+      "responseOverrides": {
+        "401": {
+          "statusCode": 302,
+          "redirect": "/.auth/login/aad"
+        }
+      }
+    }
+    ```
+
+    The `routes` section allows you to restrict access to named roles. There are two predefined roles: `authenticated` and `anonymous`. If the connected user doesn't have an allowed role, the server returns a "401 Unauthorized" response.
+
+    The values in the `responseOverrides` section configure your site so that instead of an unauthenticated user seeing a server error, their browser is redirected to the sign-in page instead.
+
+1. Run the site locally.
+
+    To launch the site locally, run the [Static Web Apps CLI](https://azure.github.io/static-web-apps-cli) `start` command.
+
+    ```bash
+    npx swa start
+    ```
+
+    This command starts the Azure Static Web Apps emulator on `http://localhost:4280`.
+
+    This URL is shown in your terminal window after the service starts up.
+
+1. Select the URL to go to the site.
+
+    Once you open the site in your browser, the local authentication sign in page is displayed.
+
+    ![A screen shot of the local authentication sign in page.](./media/add-authentication/local-auth-page.png)
+
+    The local authentication sign in page provides an emulation of the real authentication experience without the need for external services. You can create a user ID and select which roles you'd like to apply to the user from this screen.
+
+1. Enter a username, then select **Login**.
+
+    Once you authenticate, your site is displayed.
+
+## Deploy the site to Azure
+
+Deploy your site in the same way as you did in the last tutorial.
+
+1. Build your site:
+
+    ```bash
+    npx swa build
+    ```
+
+1. Deploy your site to the static web app:
+
+    ```bash
+    npx swa deploy --app-name swa-demo-site
+    ```
+
+    The URL for your site is displayed once the deployment is finished. Select the site URL to open the site in the browser. The standard Microsoft Entra ID sign in page is displayed:
+
+    ![Screen shot of the Microsoft authentication sign in page.](./media/add-authentication/remote-auth-page.png)
+
+    Sign in with your Microsoft account.
+
+[!INCLUDE [Clean up resources](../../includes/static-web-apps/quickstart-direct-deploy-clean-up-resources.md)]
+
+## Related content
+
+* [Authentication and authorization](./authentication-authorization.yml)
+* [Custom authentication](./authentication-custom.md)

articles/static-web-apps/deploy-web-framework.md

@@ -0,0 +1,183 @@
+---
+title: Deploy your web app to Azure Static Web Apps.
+description: Learn to deploy your web app to Azure Static Web Apps.
+services: static-web-apps
+author: craigshoemaker
+ms.service: static-web-apps
+ms.topic: article
+ms.date: 07/02/2024
+ms.author: cshoe
+zone_pivot_groups: swa-web-framework
+---
+
+# Deploy your web app to Azure Static Web Apps
+
+In this article, you create a new web app with the framework of your choice, run it locally, then deploy to Azure Static Web Apps.
+
+## Prerequisites
+
+To complete this tutorial, you need:
+
+| Resource | Description |
+|---|---|
+| [Azure subscription][1] | If you don't have one, you can [create an account for free][1]. |
+| [Node.js][2] | Install version 20.0 or later. |
+| [Azure CLI][3] | Install version 2.6x or later. |
+
+You also need a text editor. For work with Azure, [Visual Studio Code][4] is recommended.
+
+You can run the app you create in this article on the platform of your choice including: Linux, macOS, Windows, or Windows Subsystem for Linux.
+
+## Create your web app
+
+1. Open a terminal window.
+
+::: zone pivot="vanilla-js"
+
+2. Select an appropriate directory for your code, then run the following commands.
+
+    ```bash
+    npm create vite@latest swa-vanilla-demo -- --template=vanilla
+    cd swa-vanilla-demo
+    npm install
+    npm run dev
+    ```
+
+    As you run these commands, the development server prints the URL of your website. Select the link to open it in your default browser.
+
+    ![Screen shot of the generated vanilla web application.][img-vanilla-js]
+
+::: zone-end
+
+::: zone pivot="angular"
+
+2. Select an appropriate directory for your code, then run the following commands.
+
+    ```bash
+    npx --package @angular/cli@latest ng new swa-angular-demo --ssr=false --defaults
+    cd swa-angular-demo
+    npm start
+    ```
+
+    As you run these commands, the development server prints the URL of your website. Select the link to open it in your default browser.
+
+    ![Screen shot of the generated angular web application.][img-angular]
+
+::: zone-end
+
+::: zone pivot="react"
+
+2. Select an appropriate directory for your code, then run the following commands.
+
+    ```bash
+    npm create vite@latest swa-react-demo -- --template react
+    cd swa-react-demo
+    npm install
+    npm run dev
+    ```
+
+    As you run these commands, the development server prints the URL of your website. Select the link to open it in your default browser.
+
+    ![Screen shot of the generated react web application.][img-react]
+
+::: zone-end
+
+::: zone pivot="vue"
+
+2. Select an appropriate directory for your code, then run the following commands.
+
+    ```bash
+    npm create vite@latest swa-vue-demo -- --template vue
+    cd swa-vue-demo
+    npm install
+    npm run dev
+    ```
+
+    As you run these commands, the development server prints the URL of your website. Select the link to open it in your default browser.
+
+    ![Screen shot of the generated Vue web application.][img-vue]
+
+::: zone-end
+
+3. Select <kbd>Cmd/Ctrl</kbd>+<kbd>C</kbd> to stop the development server.
+
+[!INCLUDE [Create an Azure Static Web App](../../includes/static-web-apps/quickstart-direct-deploy-create.md)]
+
+[!INCLUDE [Build your site for deployment](../../includes/static-web-apps/quickstart-direct-deploy-build.md)]
+
+::: zone pivot="angular"
+
+> [!WARNING]
+> Angular v17 and later place the distributable files in a subdirectory of the output path that you can choose. The SWA CLI doesn't know the specific location of the directory. The following steps show you how to set this path correctly.
+
+Locate the generated *index.html* file in your project in the *dist/swa-angular-demo/browser* folder.
+
+1. Set the `SWA_CLI_OUTPUT_LOCATION` environment variable to the directory containing the *index.html* file:
+
+    # [bash](#tab/bash)
+
+    ```bash
+    export SWA_CLI_OUTPUT_LOCATION="dist/swa-angular-demo/browser"
+    ```
+
+    # [csh](#tab/csh)
+
+    ```bash
+    setenv SWA_CLI_OUTPUT_LOCATION "dist/swa-angular-demo/browser"
+    ```
+
+    # [PowerShell](#tab/pwsh)
+
+    ```powershell
+    $env:SWA_CLI_OUTPUT_LOCATION="dist/swa-angular-demo/browser"
+    ```
+
+    # [CMD](#tab/cmd)
+
+    ```bash
+    set SWA_CLI_OUTPUT_LOCATION="dist/swa-angular-demo/browser"
+    ```
+
+    ---
+
+::: zone-end
+
+## Deploy your site to Azure
+
+Deploy your code to your static web app:
+
+```bash
+npx swa deploy --env production
+```
+
+It might take a few minutes to deploy the application. Once complete, the URL of your site is displayed.
+
+![Screen shot of the deploy command.][img-deploy]
+
+On most systems, you can select the URL of the site to open it in your default browser.
+
+[!INCLUDE [Clean up resources](../../includes/static-web-apps/quickstart-direct-deploy-clean-up-resources.md)]
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Add authentication](./add-authentication.md)
+
+## Related content
+
+* [Authentication and authorization](./authentication-authorization.yml)
+* [Database connections](./database-overview.md)
+* [Custom Domains](./custom-domain.md)
+
+<!-- Links -->
+[1]: https://azure.microsoft.com/free
+[2]: https://nodejs.org/
+[3]: /cli/azure/install-azure-cli
+[4]: https://code.visualstudio.com
+
+<!-- Images -->
+[img-deploy]: media/deploy-screenshot.png
+[img-vanilla-js]: media/deploy-web-framework/vanilla-js-screenshot.png
+[img-angular]: media/deploy-web-framework/angular-screenshot.png
+[img-react]: media/deploy-web-framework/react-screenshot.png
+[img-vue]: media/deploy-web-framework/vue-screenshot.png