Expand authentication documentation

docs/features/authentication/components.mdx

@@ -0,0 +1,12 @@
+---
+title: Components
+description: Components provided by the authentication package.
+---
+
+The `@repo/auth` package exposes an `AuthProvider`, however you don't need to use this directly. The [`DesignSystemProvider`](/features/design-system/provider) includes all relevant providers and higher-order components.
+
+From here, you can use all the pre-built components and hooks provided by Clerk. To demonstrate this, we've added the `<OrganizationSwitcher>` and `<UserButton>` components to the sidebar, as well as built out the Sign In and Sign Up pages.
+
+<Frame>
+  <img src="/images/sign-in.png" alt="Sign In Page" />
+</Frame>

docs/features/authentication/middleware.mdx

@@ -0,0 +1,28 @@
+---
+title: Middleware
+description: How authentication middleware is configured in next-forge.
+---
+
+Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
+
+## Default configuration
+
+next-forge's Authentication package includes a middleware component called `authMiddleware` that is used to handle authentication and authorization in the Next.js app. By default, this middleware is simply a wrapper around Clerk's `clerkMiddleware` function.
+
+The authentication middleware is setup in the `middleware.ts` file in the root of the app. This file is used to define the middleware for the app, and is used to handle authentication and authorization in the Next.js app.
+
+## Advanced configuration
+
+Clerk's Middleware is a powerful tool that allows you to customize the authentication process. If you want to take it further, check out the following resources:
+
+<Card title="createRouteMatcher()" icon="route" href="https://clerk.com/docs/references/nextjs/clerk-middleware#create-route-matcher" horizontal>
+  A Clerk helper function that allows you to protect multiple routes.
+</Card>
+
+<Card title="Protecting routes" icon="shield" href="https://clerk.com/docs/references/nextjs/clerk-middleware#protect-routes" horizontal>
+  You can protect routes by user authentication and/or authorization status.
+</Card>
+
+<Card title="Debugging Middleware" icon="ban-bug" href="https://clerk.com/docs/references/nextjs/clerk-middleware#debug-your-middleware" horizontal>
+  If you are having issues getting your Middleware dialed in, you can use their debugging feature.
+</Card>

docs/features/authentication/overview.mdx

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: How authentication is configured in next-forge.
+---
+
+<Frame>
+  <img src="/images/authentication.png" alt="" />
+</Frame>
+
+next-forge manages authentication through the use of a `auth` package. By default, this package is a wrapper around [Clerk](https://clerk.com/) which provides a complete authentication and user management solution that integrates seamlessly with Next.js applications.
+
+It also provides a series of helpful utilities, components and middleware for managing authentication in your application. next-forge is configured by default to support Users and Organizations.
+
+## User Management
+
+Through the use of the `UserButton`, `SignIn` and `SignUp` [components](/features/authentication/components), as well as the pre-configured [middleware](/features/authentication/middleware), next-forge allows users to sign up, sign in, sign out, and manage their account on your application.
+
+Clerk only enables email / password authentication by default. You can enable other authentication methods including Social Login, Passwordless Login and Passkeys in your Clerk dashboard.
+
+## Organization Management
+
+Through the use of the `OrganizationSwitcher` [component](/features/authentication/components), next-forge allows authenticated users to create and switch between organizations.
+
+<Tip>You need to manually enable organizations in your Clerk dashboard.</Tip>
+
+

docs/features/authentication/roles.mdx

@@ -0,0 +1,6 @@
+---
+title: Roles
+description: How roles are managed in next-forge.
+---
+
+TBD.

docs/features/authentication/security.mdx

@@ -0,0 +1,6 @@
+---
+title: Security
+description: How authentication security is managed in next-forge.
+---
+
+TBD.

docs/features/authentication/webhooks.mdx

@@ -0,0 +1,40 @@
+---
+title: Webhooks
+description: How authentication webhooks are handled in next-forge.
+---
+
+next-forge has a built-in webhook handler for authentication events. This is handled in the `/app/webhooks/clerk` route handler in the `api` app. We can receive webhooks events from Clerk whenever a key event occurs, such as a user being created, an organization being deleted or a membership invite being sent.
+
+In their dashboard, Clerk uses Svix to configure webhooks. They can send an HTTP POST request to our webhook endpoint configured for the event type. The payload carries a JSON object. We can then use the information from the request's JSON payload to trigger actions in our app, such as sending a notification or updating a database.
+
+## Setting up webhooks
+
+In your Clerk dashboard, you can configure webhooks for your project.
+
+<Frame>
+  <img src="/images/clerk-webhooks.png" style={{ borderRadius: '0.5rem' }} />
+</Frame>
+
+You'll need to add the URL of your `api` app to the webhook settings. For instance, if we're deploying to `api.acme.com`, we'll add the following URL to the webhook settings:
+
+```
+https://api.acme.com/webhooks/clerk
+```
+
+## Enabling webhook events
+
+After our webhooks are configured, we need to enable the specific events we want to receive. By default, next-forge is configured to receive the following events and perform the following actions with the [Analytics](/features/analytics/product) package:
+
+| Event | Analytics Event |
+| ----- | ------ |
+| User created | Identify the user and capture the `User Created` event. |
+| User updated | Identify the user and capture the `User Updated` event. |
+| User deleted | Identify the user and capture the `User Deleted` event. |
+| Organization created | Identify the organization, associate it with the user and capture the `Organization Created` event. |
+| Organization deleted | Identify the organization, associate it with the user and capture the `Organization Deleted` event. |
+| Organization membership created | Associate the new user with the organization and capture the `Organization Membership Created` event. |
+| Organization membership deleted | Capture the `Organization Membership Deleted` event. |
+
+## Local Development
+
+Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying your app to a "production" state Vercel project with development environment variables e.g. `staging-api.example.com`. Then you can add this URL to your Clerk project's webhook settings.

docs/mint.json

@@ -81,7 +81,17 @@
           "group": "Analytics",
           "pages": ["features/analytics/web", "features/analytics/product"]
         },
-        "features/authentication",
+        {
+          "group": "Authentication",
+          "pages": [
+            "features/authentication/overview",
+            "features/authentication/components",
+            "features/authentication/middleware",
+            "features/authentication/roles",
+            "features/authentication/security",
+            "features/authentication/webhooks"
+          ]
+        },
         "features/bundle-analysis",
         "features/collaboration",
         "features/cms",