feat(providers): add BoxyHQ SAML provider (#3782)

* added saml-jackson provider

* incorporated code review changes

* fixed SAMLJacksonProfile type

* trying to adjust code for monorepo

* cleanup from merge with main

* updated docs link

* added example

* consistent naming

* Incorporated code review changes:
- env var default values moved to env.local.example
- consistent naming and use of id

* email is guaranteed to be present

apps/dev/.env.local.example

@@ -46,3 +46,7 @@ EMAIL_FROM=user@gmail.com
 # MySQL:    DATABASE_URL=mysql://nextauth:password@127.0.0.1:3306/nextauth?synchronize=true
 # MongoDB:  DATABASE_URL=mongodb://nextauth:password@127.0.0.1:27017/nextauth?synchronize=true
 DATABASE_URL=
+
+BOXYHQSAML_ISSUER="https://jackson-demo.boxyhq.com"
+BOXYHQSAML_ID="tenant=boxyhq.com&product=saml-demo.boxyhq.com"
+BOXYHQSAML_SECRET="dummy"

apps/dev/pages/api/auth/[...nextauth].ts

@@ -30,6 +30,7 @@ import AppleProvider from "next-auth/providers/apple"
 import PatreonProvider from "next-auth/providers/patreon"
 import TraktProvider from "next-auth/providers/trakt"
 import WorkOSProvider from "next-auth/providers/workos"
+import BoxyHQSAMLProvider from "next-auth/providers/boxyhq-saml"
 
 // import { PrismaAdapter } from "@next-auth/prisma-adapter"
 // import { PrismaClient } from "@prisma/client"
@@ -200,6 +201,11 @@ export const authOptions: NextAuthOptions = {
       clientId: process.env.WORKOS_ID,
       clientSecret: process.env.WORKOS_SECRET,
     }),
+    BoxyHQSAMLProvider({
+      issuer: process.env.BOXYHQSAML_ISSUER,
+      clientId: process.env.BOXYHQSAML_ID,
+      clientSecret: process.env.BOXYHQSAML_SECRET,
+    }),
   ],
   debug: true,
   theme: {

docs/docs/providers/boxyhq-saml.md

@@ -0,0 +1,58 @@
+---
+id: boxyhq-saml
+title: BoxyHQ SAML
+---
+
+## Documentation
+
+BoxyHQ SAML is an open source service that handles the SAML login flow as an OAuth 2.0 flow, abstracting away all the complexities of the SAML protocol.
+
+You can deploy BoxyHQ SAML as a separate service or embed it into your app using our NPM library. [Check out the documentation for more details](https://boxyhq.com/docs/jackson/deploy)
+
+## Configuration
+
+SAML login requires a configuration for every tenant of yours. One common method is to use the domain for an email address to figure out which tenant they belong to. You can also use a unique tenant ID (string) from your backend for this, typically some kind of account or organization ID.
+
+Check out the [documentation](https://boxyhq.com/docs/jackson/saml-flow#2-saml-config-api) for more details.
+
+## Options
+
+The **BoxyHQ SAML Provider** comes with a set of default options:
+
+- [BoxyHQ Provider options](https://github.com/nextauthjs/next-auth/tree/main/packages/next-auth/src/providers/boxyhq-saml.ts)
+
+You can override any of the options to suit your own use case.
+
+## Example
+
+```ts
+import BoxyHQSAMLProvider from "next-auth/providers/boxyhq-saml"
+...
+providers: [
+  BoxyHQSAMLProvider({
+    issuer: "http://localhost:5000",
+    clientId: "dummy", // The dummy here is necessary since we'll pass tenant and product custom attributes in the client code
+    clientSecret: "dummy", // The dummy here is necessary since we'll pass tenant and product custom attributes in the client code
+  })
+}
+...
+```
+
+On the client side you'll need to pass additional parameters `tenant` and `product` to the `signIn` function. This will allow BoxyHQL SAML to figure out the right SAML configuration and take your user to the right SAML Identity Provider to sign them in.
+
+```tsx
+import { signIn } from "next-auth/react";
+...
+
+  // Map your users's email to a tenant and product
+  const tenant = email.split("@")[1];
+  const product = 'my_awesome_product';
+...
+  <Button
+    onClick={async (event) => {
+      event.preventDefault();
+
+      signIn("boxyhq-saml", {}, { tenant, product });
+    }}>
+...
+```

packages/next-auth/src/providers/boxyhq-saml.ts

@@ -0,0 +1,37 @@
+import type { OAuthConfig, OAuthUserConfig } from "."
+
+export interface BoxyHQSAMLProfile {
+  id: string
+  email: string
+  firstName?: string
+  lastName?: string
+}
+
+export default function SAMLJackson<
+  P extends Record<string, any> = BoxyHQSAMLProfile
+>(options: OAuthUserConfig<P>): OAuthConfig<P> {
+  return {
+    id: "boxyhq-saml",
+    name: "BoxyHQ SAML",
+    type: "oauth",
+    version: "2.0",
+    checks: ["pkce", "state"],
+    authorization: {
+      url: `${options.issuer}/api/oauth/authorize`,
+      params: {
+        provider: "saml",
+      },
+    },
+    token: `${options.issuer}/api/oauth/token`,
+    userinfo: `${options.issuer}/api/oauth/userinfo`,
+    profile(profile) {
+      return {
+        id: profile.id,
+        email: profile.email,
+        name: [profile.firstName, profile.lastName].filter(Boolean).join(" "),
+        image: null,
+      }
+    },
+    options,
+  }
+}