DOCSEARCHbyAlgolia
Submit Docs

SaaStart: Auth0 B2B SaaS Starter

repository·main·Indexed 42 days ago

https://github.com/auth0-developer-hub/auth0-b2b-saas-starter

A secure, high-performance starter kit from Auth0 for building modern B2B SaaS web applications. It provides a pre-configured foundation for multi-tenancy, organization management, and enterprise identity features, including Enterprise SSO (OIDC and SAML), SCIM provisioning, RBAC roles, and configurable MFA policies.

Tokens
5.8K
Snippets
16
Records
23
Agent score
53%

What's inside SaaStart

  1. Explore B2B Identity Features in SaaStart

    main

    The SaaStart application is preconfigured with several key identity workflows designed for B2B SaaS applications. You can explore these features through the application's front-end to understand how they impact the customer management experience:

    • Sign up with Organizations: New users are prompted to enter an organization name during sign-up. Admins can then invite additional users to that organization.
    • User Management: Admins can invite users, change user roles (and permissions), and delete users. These actions directly modify the user database and organizations within your Auth0 tenant.
    • Connections (SSO & SCIM): Use the SSO tab in the settings section to connect external Identity Providers (IdPs) like Okta, Google Workspace, or Azure AD via SAML or OIDC. You can also enable SCIM provisioning through these connections.
    • Security Policies: Configure Multi-Factor Authentication (MFA) policies per organization. This includes selecting allowed MFA providers (e.g., One-time Password, Security Keys) and optionally exempting specific email domains from MFA (useful when users have already performed MFA at their IdP).
    • Organization Switching: Supports scenarios where users belong to multiple organizations (e.g., contractors or collaborators) by allowing them to switch contexts easily.
    • User Profile and Security: Users can manage their own profiles, reset passwords, manage MFA enrollments, and delete their own account data.

  2. SaaStart Target Use Cases and B2B Identity Features

    main

    SaaStart is designed to bootstrap B2B SaaS applications with the following built-in capabilities:

    Multi-tenancy & Organizations

    • Multi-tenancy using a single pool of users in a shared database.
    • Sign up workflows that include Organization creation.

    User & Identity Management

    • User Management: Invitation workflows, RBAC roles, and user creation/deletion.
    • Self-Service: Profile management, password resets, and MFA configuration.
    • Enterprise SSO: Support for OIDC and SAML.
    • Domain Verification: Ability for users to verify domain ownership before associating email domains with home realm discovery.
    • Provisioning: Just-in-time user provisioning or automatic directory sync via SCIM.

    Security Policies

    • Enforced MFA.
    • Configurable session lifetimes (coming soon).
    • Break-glass access for admin roles (coming soon).

  3. Configure SSO and SCIM via Connections

    main

    To allow your business customers to set up their own Single Sign-On (SSO) connections, navigate to the SSO tab within the application's settings section.

    From here, you can:

    1. Connect an external Identity Provider (IdP) such as Okta, Google Workspace, or Azure AD.
    2. Use protocols like SAML or OIDC.
    3. Optionally enable SCIM provisioning using the same connections to automate user lifecycle management.

  4. Learn about Advanced Configuration

    main

    For more complex setup requirements, refer to the README-ADVANCED.md file in the repository. Advanced topics include:

    • Production-like URLs: Enabling https:// and production-style URLs while iterating in a local development environment.
    • Transactional Email Testing: Using an email platform to test transactional emails and workflows requiring email verification.

  5. Configure MFA and Security Policies

    main

    You can manage security requirements at the organization level within the application. Key capabilities include:

    • MFA Provider Selection: Define which MFA methods (e.g., One-time Password, Security Keys) are permitted for a specific organization.
    • MFA Exemptions: Configure specific email domains to be exempt from MFA requirements. This is a recommended pattern when using SSO, as it prevents 'MFA fatigue' by not prompting users for a second MFA if they have already authenticated with their workforce identity provider.

  6. Mimic a production environment locally with HTTPS using Caddy

    main

    To test features requiring secure connections or specific domain configurations, you can set up a local reverse proxy using Caddy. This allows you to access your local development server (typically running on 127.0.0.1:3000) via a custom HTTPS domain like fake-production-url.com.

    # 1. Install Caddy (Example for OSX via Homebrew)
brew install caddy nss

# 2. Create a Caddyfile in the project root
cd ~/Developer/auth0-b2b-saas-starter
touch Caddyfile

# 3. Configure the Caddyfile with these contents:
# fake-production-url.com:443 {
# 	reverse_proxy 127.0.0.1:3000
# 	tls internal
# }

# 4. Add the domain to your /etc/hosts file (requires sudo)
# 127.0.0.1 fake-production-url.com

# 5. Run Caddy
caddy run

  7. Install SaaStart for Local Development

    main

    Follow these steps to set up the application on your local machine.

    Prerequisites

    • Node.js: v20 or later (use nvm to manage versions).
    • Package Manager: npm or a comparable manager.
    • Auth0 Tenant: Create a new Auth0 tenant to avoid configuration conflicts. The bootstrapping process will configure this tenant automatically.

    Step 1: Clone and Install

    1. Clone the repository:
      git clone https://github.com/auth0-developer-hub/auth0-b2b-saas-starter.git
    2. Navigate to the directory:
      cd auth0-b2b-saas-starter
    3. Install dependencies:
      npm install

    Step 2: Setup Auth0 CLI

    This project uses the Auth0 CLI to automate tenant provisioning.

    1. Install the CLI:
      • macOS/Linux (Homebrew):
        brew tap auth0/auth0-cli && brew install auth0
      • Windows (Scoop):
        scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0
    2. Verify installation:
      auth0 --version
    3. Login to Auth0: Run the following command and ensure you select the newly created tenant during the authorization step:
      auth0 login --scopes "update:tenant_settings,create:connections,create:client_grants,create:email_templates,update:guardian_factors"

    Step 3: Bootstrap the Auth0 Tenant

    This command provisions Auth0 resources (Applications, Roles, Actions, Templates, MFA) and creates a .env.local file in your project root.

    Warning: Only run this on a fresh tenant.

    npm run auth0:bootstrap

    Step 4: Run the Application

    Start the development server:

    npm run dev

    Access the app at http://localhost:3000.

    # Summary of commands
```shell
# Clone
git clone https://github.com/auth0-developer-hub/auth0-b2b-saas-starter.git

# Install
cd auth0-b2b-saas-starter
npm install

# Auth0 Login
auth0 login --scopes "update:tenant_settings,create:connections,create:client_grants,create:email_templates,update:guardian_factors"

# Bootstrap
npm run auth0:bootstrap

# Run
npm run dev

  8. Configure Mailtrap for local transactional email testing

    main

    To test email functionality (like user invitations or organization creation) without sending real emails to users, you can use an email testing service like Mailtrap. This acts as a fake SMTP provider that intercepts emails in a virtual inbox.

    Prerequisites

    • A Mailtrap account with an active Email Testing inbox.
    • An email domain that actually exists and has a valid MX record (e.g., acme.com).

    Setup Steps

    1. Get Mailtrap Credentials: In your Mailtrap inbox, click Show Credentials to find your SMTP Host, Port, Username, and Password.

    2. Configure Auth0:

      • Log in to your Auth0 dashboard.
      • Navigate to Branding > Email Providers.
      • Enable Use my own email provider and select SMTP.
      • Enter the Mailtrap credentials:
        • Host: (from Mailtrap)
        • Port: 587 or 2525
        • Username/Password: (from Mailtrap)
      • Important: When setting the "From" email address, do not include auth0.com or okta.com in the subdomain.

    3. Test Delivery:

      • In the Auth0 dashboard, click Send Test Email.
      • Check your Mailtrap inbox to verify receipt.

  9. Deploy SaaStart to Vercel

    main

    You can deploy this starter kit to Vercel in one click using the provided Vercel deployment button. This will clone the repository and set up the environment for you.

    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

  10. Verify Caddy HTTPS configuration

    main

    After running Caddy, verify that the local HTTPS proxy is working correctly by inspecting the server certificate via curl.

    curl -vI https://fake-production-url.com

    Look for these indicators in the output:

    * 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.

  11. Configure import sorting with @ianvs/prettier-plugin-sort-imports

    main

    The project enforces a strict import order using the @ianvs/prettier-plugin-sort-imports plugin. Imports are grouped in the following order:

    1. React (react/ or react)
    2. Next.js (next/ or next)
    3. <THIRD_PARTY_MODULES>
    4. (Empty line)
    5. ^types$
    6. @/env(.*)
    7. @/types/(.*)
    8. @/config/(.*)
    9. @/lib/(.*)
    10. @/utils/(.*)
    11. @/hooks/(.*)
    12. @/components/ui/(.*)
    13. @/components/(.*)
    14. @/styles/(.*)
    15. @/app/(.*)
    16. (Empty line)
    17. Relative imports (^[./])

    Configuration details:

    • importOrderTypeScriptVersion: "5.3.0"
    • importOrderParserPlugins: ["typescript", "jsx", "decorators-legacy"]
    importOrder: [
  "^(react/(.*)$)|^(react$)",
  "^(next/(.*)$)|^(next$)",
  "<THIRD_PARTY_MODULES>",
  "",
  "^types$",
  "^@/env(.*)$",
  "^@/types/(.*)$",
  "^@/config/(.*)$",
  "^@/lib/(.*)$",
  "^@/utils/(.*)$",
  "^@/hooks/(.*)$",
  "^@/components/ui/(.*)$",
  "^@/components/(.*)$",
  "^@/styles/(.*)$",
  "^@/app/(.*)$",
  "",
  "^[./]",
],
importOrderTypeScriptVersion: "5.3.0",
importOrderParserPlugins: ["typescript", "jsx", "decorators-legacy"],

  12. Configure Prettier for the SaaStart project

    main

    The project uses Prettier for code formatting with specific rules for line endings, quotes, and indentation. It also utilizes plugins to enforce a specific import order and to sort Tailwind CSS classes.

    Key formatting rules:

    • endOfLine: Set to "lf" (Unix-style line endings).
    • semi: Set to false (no semicolons).
    • singleQuote: Set to false (uses double quotes).
    • tabWidth: Set to 2.
    • trailingComma: Set to "es5".
    const config = {
  endOfLine: "lf",
  semi: false,
  singleQuote: false,
  tabWidth: 2,
  trailingComma: "es5",
  // ...
}