Merging main to demo for saastart.app

README-ADVANCED.md

@@ -0,0 +1,97 @@
+# Advanced Instructions
+This file contains steps that you can take for advanced configuration of your local environment. These instructions assume you've already run the Getting Started instructions located in the project's main README.md file.
+
+## Mimick a production environment locally, with https (using Caddy as an example)
+
+This section guides you through setting up a reverse proxy server to enable local HTTPS development for your project. The process involves installing Caddy, creating a configuration file (Caddyfile), setting up local domain resolution, and running Caddy. 
+
+This setup allows you to access your local development server via HTTPS using a custom domain, mimicking a production environment while working locally. It's particularly useful for testing features that require secure connections or specific domain configurations.
+
+### Instructions:
+
+1. Install Caddy using your operating system's package manager. Check out Caddy's installation instructions for specific steps. For example, on OSX using homebrew, you could use the following command:
+```shell
+brew install caddy nss
+```
+2. Create a file called Caddyfile in the /auth0-b2b-saas-starter/ directory on your local machine. If you have cloned the repo to a different directory, make sure to use that instead.
+
+```shell
+cd ~/Developer/auth0-b2b-saas-starter
+touch Caddyfile
+```
+3. Open the `Caddyfile` in your favorite code editor or IDE.
+4. Enter the following values in the Caddyfile.
+```bash
+fake-production-url.com:443 {
+	reverse_proxy 127.0.0.1:3000
+	tls internal
+}
+```
+5. Add the following line to the end of /etc/hosts 
+NOTE: you have to use superuser to edit the hosts file
+Example: `sudo vi /etc/hosts` or `sudo code /etc/hosts`)
+```shell
+# SaaStart
+127.0.0.1 fake-production-url.com
+```
+6. In a new terminal window, navigate to the repository folder and use the `caddy run` command to start the process.
+```shell
+cd ~/work/assemble
+caddy run # You will have to enter your password or touch ID to approve the keychain addition
+```
+
+In some cases you might get the error message “ERROR pki.ca.local failed to install root certificate”, but that's not an indication that Caddy is not working.
+
+### Testing Caddy
+1. Run the following cURL command:
+```shell
+ curl -vI https://fake-production-url.com
+```
+
+Amongst the overall output, you should be able to see the following lines included:
+```shell
+* Server certificate:
+*  subject: [NONE]
+*  start date: {unix-style timestamp}
+*  expire date: {unix-style timestamp}
+*  subjectAltName: host "fake-production-url.com" matched cert's "fake-production-url.com"
+*  issuer: CN=Caddy Local Authority - ECC Intermediate
+*  SSL certificate verify ok.
+```
+
+---
+
+## Use an email platform for managing transactional email while developing (using Mailtrap as an example)
+
+This section guides you through setting up an email platform for easy local testing and development.
+
+When simulating a production environment on your personal development environment, it can also be helpful to test email delivery and manage transactional emails without actually sending emails to real users. This can be achieved with an email platform of your choice, with this guide focusing on [Mailtrap.io](https://mailtrap.io) as one example. These services can act as a “fake” SMTP email provider, collecting and displaying the email messages it was supposed to send without actually delivering them. This allows you to test email functionality while creating organizations and inviting users while using any email addresses you want, even those that aren't real. This makes a solution like this ideal for troubleshooting and testing SaaStart.
+
+> [!IMPORTANT]
+> You must use an email domain that actually exists and has an MX record for testing. For example, using `acme.com` will work, but `acmeairlines.net` will not, as it lacks a valid MX record.
+
+### Step 1: Set Up a Mailtrap Account
+
+1. **Sign Up:** Go to [Mailtrap.io](https://mailtrap.io) and sign up for an account. You can use your Google account for quick registration.
+2. Choose the **Email Testing** option during the sign-up process.
+3. **Create an Inbox:** Once signed in, go to [Mailtrap Inboxes](https://mailtrap.io/inboxes) and select **My Inbox**. This is where intercepted email messages will be displayed.
+4. **Obtain SMTP Credentials:** Open your inbox and click on **Show Credentials** to reveal the SMTP setup details. You'll need the host, port, username, and password to configure Mailtrap as your SMTP provider in Auth0.
+
+### Step 2: Configure Auth0 to Use Mailtrap
+
+1. **Access Your Auth0 Tenant:** Log in to your Auth0 dashboard and navigate to your tenant.
+2. **Set Up the Email Provider:** Go to **Branding > Email Providers** in the Auth0 dashboard. Enable **Use my own email provider** and select **SMTP**.
+3. **Populate SMTP Details:** Enter the SMTP credentials you obtained from Mailtrap:
+     - **Host:** Use the host provided by Mailtrap.
+     - **Port:** Use port `587` or `2525`.
+     - **Username and Password:** Enter the credentials from Mailtrap.
+4. Click **Save** to apply the settings.
+
+> [!IMPORTANT]
+> When entering the "From" email address in the SMTP Provider Settings, **do not** include `auth0.com` or `okta.com` in the email subdomain, as this will prevent the setup from working.
+
+### Step 3: Test Email Delivery in Auth0
+
+1. **Send a Test Email:** After configuring Mailtrap as your SMTP provider, click on **Send Test Email** in the Auth0 dashboard. You can use any email address for testing, even a fake one.
+2. **Verify Email in Mailtrap:** Go back to your Mailtrap inbox and verify that the test email has been received. You can now inspect the email content, subject, and other details to ensure everything is working correctly.
+

README.md

@@ -1,20 +1,28 @@
 # **SaaStart** from Auth0 by Okta
 
-A secure and high-performance starting point for building B2B SaaS web applications.
+A secure and high-performance starting point for building modern B2B SaaS web applications.
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/auth0-developer-hub/auth0-b2b-saas-starter&repository-name=auth0-saas-starter&external-id=b2b-saas-starter-template&integration-ids=oac_7V7TGP5JUHCpSncpiy3XWwL0)
+## Jump to a section
+* [Target Use Case](#target-use-case)
+* [Deploy to Vercel](#deploy-to-vercel-in-one-click)
+* [Installation for Local Development](#installation-for-local-development)
+* [B2B Identity Features to Explore](#b2b-identity-features-to-explore)
+* [Advanced Topics](#advanced-topics)
+* [Learn More](#advanced-topics)
+* [Contributing](#contributing)
 
 ## Overview
 
 ![image](https://github.com/auth0-developer-hub/auth0-b2b-saas-starter/assets/6372810/e8ab12fe-d95b-4e11-8e9e-242eb9c547b6)
 
+> [!TIP]
 > Ready to begin? Jump ahead to the [Getting Started](#getting-started) section.
 
-This sample application provides developers with a solid foundation to kickstart their journey into building a business-to-business software-as-a-service (B2B SaaS) application. With a carefully selected stack of well-documented and widely adopted technologies, along with seamless integration with Auth0 for identity and login management, this starter kit aims to streamline the development process, enabling you to focus on building out your core product instead of worrying about the complexities of SaaS identity management and secure customer onboarding.
+This sample application provides developers with a solid foundation to kickstart their journey into building a business-to-business software-as-a-service (B2B SaaS) application. With a carefully selected stack of well-documented and widely adopted technologies, along with seamless integration with Auth0 for identity and login management, this starter kit aims to streamline the development process and enable developers to focus on building out their core product instead of worrying about the complexities of SaaS identity management and secure customer onboarding.
 
-It incorporates best practices and industry-standard technologies to provide a robust and scalable solution for building secure software, with all the capabilities you need to be competitive, resilient, and scalable. The project includes the architecture and components you need to get started, authentication and authorization powered by Auth0, and deployment instructions that make it easy to move to staging or production when you're ready.
+It incorporates best practices and industry-standard technologies to provide a robust and scalable solution for building secure software, with all the capabilities needed to be competitive, resilient, and scalable. The project includes the architecture and components you need to get started, authentication and authorization powered by Auth0, and deployment instructions that make it easy to move to staging or production when you're ready.
 
-## Target use case
+## Target Use Case
 
 Use this to bootstrap a SaaS application with the following commonly needed capabilities:
 
@@ -27,27 +35,31 @@ Use this to bootstrap a SaaS application with the following commonly needed capa
   - OIDC
   - SAML
 - Ability for end-users to verify domain ownership before associating their email domains with [home realm discovery](https://auth0.com/docs/authenticate/login/auth0-universal-login/identifier-first#define-home-realm-discovery-identity-providers)
-- Just-in-time user provisioning OR automatic directory sync with SCIM _(coming soon)_
+- Just-in-time user provisioning OR automatic directory sync with SCIM
 - API client management with self-service create/delete capabilities _(coming soon)_
 - Configurable security policies:
   - Enforce MFA
   - Session lifetime _(coming soon)_
   - Break-glass access for admin roles _(coming soon)_
 
-## Getting Started
+## Deploy to Vercel
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/auth0-developer-hub/auth0-b2b-saas-starter&repository-name=auth0-saas-starter&external-id=b2b-saas-starter-template&integration-ids=oac_7V7TGP5JUHCpSncpiy3XWwL0)
+
+## Installation for Local Development
 
 ### Prerequisites
 
 1. Node.js v20 or later is required to run the bootstrapping process. We recommend using [`nvm`](https://github.com/nvm-sh/nvm) to manage node versions in your development environment. Click these links to [learn how to install nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script) or [how to use nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#usage) to make sure you're using Node 20+ in your development environment.
 2. You must have [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) or a comparable package manager installed in your development environment. These instructions assume that you're using `npm`, which is automatically included as part of the Node.js installation from prerequisite 1.
-3. Create a new Auth0 tenant. This tenant will be configured automatically by our bootstrapping command during the installation process. You can sign up for a free Auth0 account at [https://auth0.com/signup](https://auth0.com/signup?utm_source=github&utm_medium=thirdpartyutm_campaign=saastart). See [Create Tenants](https://auth0.com/docs/get-started/auth0-overview/create-tenants) in the Auth0 docs if you need help.
+3. Create a new Auth0 tenant. **This is important!** Using a new Auth0 tenant for this sample application ensures you don't encounter any conflicts due to existing configuration in an existing tenant.
+
+   The tenant you create will be configured automatically by our bootstrapping command during the installation process. You can sign up for a free Auth0 account at [https://auth0.com/signup](https://auth0.com/signup?utm_source=github&utm_medium=thirdpartyutm_campaign=saastart). See [Create Tenants](https://auth0.com/docs/get-started/auth0-overview/create-tenants) in the Auth0 docs if you need help.
 
-> [!IMPORTANT]
-> Creating a new tenant before you continue is **highly recommended** so that you don't accidentally change the configuration in any existing Auth0 projects you might have.
+   Once you've created a tenant, nothing else needs to be done inside Auth0 - you can return to this README.md and begin completing the steps below.
 
 ### Step One: Clone and install dependencies
 
-1. Clone this repo to your development environment. Navigate to a directory where you want to work in a terminal program, and run the following command:
+1. Clone this repo to your development environment. To do this, navigate to a directory where you want to work in a terminal program, and run the following command:
 
    ```shell
    git clone https://github.com/auth0-developer-hub/auth0-b2b-saas-starter.git
@@ -59,24 +71,40 @@ Use this to bootstrap a SaaS application with the following commonly needed capa
    cd auth0-b2b-saas-starter
    ```
 
-3. Install dependencies for the project using your favorite package manager. For example, if you're using npm, type:
+3. Install dependencies for the project using your favorite package manager. For example, if you're using npm, check that you're on the correct version of node:
+
+   ```shell
+   node -v
+   ```
+   This should return a version number higher than v20. If you have an earlier version installed, return to the prerequisites and follow step 1. 
+
+   Otherwise, continue:
 
    ```shell
    npm install
    ```
 
-### Step Two: Install and Log in with the Auth0 CLI
+### Step Two: Install and log in with the Auth0 CLI
 
-This project uses the Auth0 CLI to make setting up your tenant a lot easier, by scripting away as much manual work as possible. If you want to familiarize yourself with the Auth0 CLI, read [Auth0 CLI Basics](https://developer.auth0.com/resources/labs/tools/auth0-cli-basics).
+This project uses the [Auth0 CLI](https://github.com/auth0/auth0-cli) to make setting up your tenant a lot easier, by scripting away as much manual work as possible. If you want to familiarize yourself with the Auth0 CLI, read [Auth0 CLI Basics](https://developer.auth0.com/resources/labs/tools/auth0-cli-basics).
 
 1. You will need to install the Auth0 CLI. It will be used by the bootstrap script to create the resources needed for this sample in your Auth0 tenant. Instructions for installation are available at the [Auth0 CLI github repo](https://github.com/auth0/auth0-cli).
 
-   **For example**, users on OSX using [Homebrew](https://brew.sh/) can run the following command to install the CLI:
+
+   **For example**, users on **Linux or OSX** using [Homebrew](https://brew.sh/) can run the following command to install the CLI:
 
    ```shell
    brew tap auth0/auth0-cli && brew install auth0
    ```
 
+   **For example**, users on **Windows** using [Scoop](https://scoop.sh/) can run the following commands to install the CLI:
+   ```powershell
+   scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
+   ```
+   ```powershell
+   scoop install auth0
+   ```
+
    You can confirm whether or not the CLI is correctly installed by running the following command:
 
    ```shell
@@ -95,11 +123,10 @@ This project uses the Auth0 CLI to make setting up your tenant a lot easier, by
    auth0 login --scopes "update:tenant_settings,create:connections,create:client_grants,create:email_templates,update:guardian_factors"
    ```
 
-   Be sure to select `As a user` when prompted: `How would you like to authenticate?`. This will take you through a flow that will securely retrieve a Management API token for your Auth0 tenant.
+   This will take you through a flow that will securely retrieve a Management API token for your Auth0 tenant.
 
-   > **Warning**
-   >
-   > At the **Authorize App** step, be sure to select the correct tenant. This is the tenant that will be bootstrapped in the next steps.
+> [!WARNING]
+> At the **Authorize App** step, be sure to select the same NEW tenant that you created in the prerequisites. Whatever you choose during this step will be the tenant that will be bootstrapped in the next steps, so it's important to make sure it's a newly created tenant without existing configuration.
 
 ### Step Three: Bootstrap the Auth0 tenant
 
@@ -113,10 +140,8 @@ This step will create and update entities in your Auth0 tenant. The provided scr
 
 Finally, it will save environment variables for your tenant in the application directory.
 
-> **Warning**
->
+> [!WARNING]
 > Only run the following command on a newly created tenant to avoid changing existing configuration or introducing conflicting elements to your existing Auth0 tenants!
->
 > If you are creating a new Auth0 tenant at this point in the process, go back to step 2 in order to ensure you're logged into the correct Auth0 tenant.
 
 Run the following command:
@@ -136,7 +161,41 @@ Once the script has successfully completed, a `.env.local` file containing the e
 
    You can proceed to interact with the app as if you were a user: create an account, navigate to the settings, explore the identity capabilities.
 
-3. Start editing to build your own SaaS application - for example, modify `app/page.tsx`. The browser will hot-reload to show changes as you edit the file.
+Now you're ready to start editing to build your own SaaS application! To see this in action, modify `app/page.tsx` in some way and save the file. The browser will hot-reload to show any changes you've made each time you save.
+
+---
+
+## B2B Identity Features to Explore
+
+By clicking through the application's front-end, you can explore the management experience that your customers would have. This sample application comes preconfigured with key identity workflows that are crucial for anyone that wants their application to be adopted by business customers, so that you can focus on coding your own functionality instead.
+
+### Sign up with Organziations
+Each user that creates an account from scratch will be prompted to enter an organization name as part of their sign-up flow. Once an organization is created, users with admin roles can invite additional users who will automatically be added to the organization.
+
+### User Management
+Invite additional users, change users' roles (and thus what they have permission to do in the application), and delete users. You'll notice as you perform these operations in SaaStart, you're changing the user database and organizations in your Auth0 tenant.
+
+### Connections
+Use the SSO tab in the settings section to connect an external IDP (eg, Okta WIC, Google Workforce, Azure AD, etc) via SAML or OIDC. This allows your business customers to set up their own Single Sign On connections right in your application. You can also optionally enable SCIM provisioning using the same connections.
+
+### Security Policies
+Configure multi-factor authentication (MFA) policies for your organization, including a selection of which MFA providers (eg, One-time Password, or Security Keys) your users are allowed to use. Optionally, you can configure email domains for which users be exempted from having to MFA in your app. This is useful when using SSO, and users are already completing MFA when they sign in to their workforce identity provider, so that they won't be prompted for a second MFA when they log in to your application.
+
+### Organization Switching
+Users can be invited to a company organization, but can also create their own hobby or personal organizations. This allows your app to handle scenarios like when contractors or external collaborators need to belong to multiple organizations, or when employees want to have their own personal accounts for experimentation or side projects. Switching contexts is easy.
+
+### User Profile and Security
+Your users can set their own user profile settings, set and reset their own passwords, and manage their own multi-factor authentication (MFA) enrollments. They can also manage and delete their own account data.
+
+---
+
+## Advanced Topics
+
+Reference the [README-ADVANCED.md](README-ADVANCED.md) instructions to learn about:
+* Enabling https:// and production-like URLs while you iterate from within your personal development environment
+* Using an email platform for testing transactional emails (or different workflows that require email verification)
+
+---
 
 ## Learn More