feat(providers): Add ssoready-saml provider

.github/ISSUE_TEMPLATE/2_bug_provider.yml

@@ -76,6 +76,7 @@ body:
         - "SimpleLogin"
         - "Slack"
         - "Spotify"
+        - "SSOReady SAML"
         - "Strava"
         - "Threads"
         - "Tiktok"

docs/pages/getting-started/providers/ssoready-saml.mdx

@@ -0,0 +1,136 @@
+---
+title: SSOReady SAML
+---
+
+import { Callout } from "nextra/components"
+import { Code } from "@/components/Code"
+
+<img
+  align="right"
+  src="/img/providers/ssoready-saml.svg"
+  height="64"
+  width="64"
+/>
+
+# SSOReady SAML Provider
+
+## Resources
+
+- [SSOReady SAML over OAuth documentation](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration)
+
+## Setup
+
+Add SSOReady SAML login to your page.
+
+SSOReady SAML is a set of open-source dev tools for enterprise SSO. You can use SSOReady to add [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) support to your product this afternoon, for free, forever.
+
+This provider integrates with the SSOReady [SAML over OAuth](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#creating-organizations) integration, which abstracts away enterprise single sign-on / SAML into an OAuth flow. There are conceptual differences between ordinary OAuth and SAML. See ["SAML"](#saml) for details.
+
+SSOReady is MIT-licensed and available at [github.com/ssoready/ssoready](https://github.com/ssoready/ssoready).
+
+### Callback URL
+
+<Code>
+  <Code.Next>
+
+```bash
+https://example.com/api/auth/callback/ssoready-saml
+```
+
+  </Code.Next>
+  <Code.Svelte>
+
+```bash
+https://example.com/auth/callback/ssoready-saml
+```
+
+  </Code.Svelte>
+</Code>
+
+### Environment Variables
+
+```
+AUTH_SSOREADY_SAML_ID
+AUTH_SSOREADY_SAML_SECRET
+```
+
+`AUTH_SSOREADY_SAML_ID` should start with `oauth_saml_client_...`. `AUTH_SSOREADY_SAML_SECRET` should start with `ssoready_oauth_client_secret_...`. They correspond to the ID and secret value of a SSOReady SAML OAuth Client. Creating such a client is documented under ["Creating SAML OAuth clients"](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#creating-saml-oauth-clients) in the SSOReady docs.
+
+### Configuration
+
+<Code>
+  <Code.Next>
+
+```ts filename="/auth.ts"
+import NextAuth from "next-auth"
+import SSOReadySAML from "next-auth/providers/ssoready-saml"
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [SSOReadySAML],
+})
+```
+
+  </Code.Next>
+  <Code.Svelte>
+
+```ts filename="/src/auth.ts"
+import { SvelteKitAuth } from "@auth/sveltekit"
+import SSOReadySAML from "@auth/sveltekit/providers/ssoready-saml"
+
+export const { handle, signIn, signOut } = SvelteKitAuth({
+  providers: [SSOReadySAML],
+})
+```
+
+  </Code.Svelte>
+  <Code.Express>
+
+```ts filename="/src/app.ts"
+import { ExpressAuth } from "@auth/express"
+import SSOReadySAML from "@auth/express/providers/ssoready-saml"
+
+app.use("/auth/*", ExpressAuth({ providers: [SSOReadySAML] }))
+```
+
+  </Code.Express>
+</Code>
+
+### SAML
+
+SAML logins require configuration ahead of time. The process for setting these up is documented in ["Onboarding customers"](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#onboarding-customers) in the SSOReady docs.
+
+Once a customer is configured for SAML, your code needs to determine which configuration to use at runtime. You'll do this by passing an `organizationExternalId`:
+
+```ts
+import { signIn } from "next-auth/react"
+
+// ...
+
+signIn("ssoready-saml", {}, { organizationExternalId: "..." })
+```
+
+An `organizationExternalId` is an ID you configure in SSOReady (see ["Creating organizations"](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#creating-organizations) in the SSOReady docs). A common pattern for Auth.js-based apps is to use a company's domain as the external ID of their SSOReady organizations. In that case, your "log in with SAML" code will look like this:
+
+```ts
+import { signIn } from "next-auth/react";
+
+// ...
+
+const [email, setEmail] = useState("")
+
+// Map email to organizationExternalId. This will work only if you configure
+// your SSOReady organizations to have domains (e.g. "example.com") as their
+// external ID.
+//
+// See: https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#creating-organizations
+const organizationExternalId = email.split("@")[1];
+
+// ...
+
+<Button
+  onClick={async (event) => {
+    event.preventDefault();
+    signIn("ssoready-saml", {}, { organizationExternalId });
+  }}
+>
+```

packages/core/src/providers/ssoready-saml.ts

@@ -0,0 +1,138 @@
+/**
+ * <div style={{backgroundColor: "#000", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
+ * <span>Built-in <b>SSOReady SAML</b> integration.</span>
+ * <a href="https://ssoready.com/">
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/ssoready-saml.svg" height="48" width="48"/>
+ * </a>
+ * </div>
+ *
+ * @module providers/ssoready-saml
+ */
+import type { OAuthConfig, OAuthUserConfig } from "./index.js"
+
+export interface SSOReadySAMLProfile extends Record<string, any> {
+  id: string
+  email: string
+  organizationId: string
+  organizationExternalId: string
+}
+
+/**
+ * Add SSOReady SAML login to your page.
+ *
+ * ### Setup
+ *
+ * #### Callback URL
+ * ```
+ * https://example.com/api/auth/callback/ssoready-saml
+ * ```
+ *
+ * #### Configuration
+ *
+ *```ts
+ * import { Auth } from "@auth/core"
+ * import SSOReadySAML from "@auth/core/providers/ssoready-saml"
+ *
+ * const request = new Request(origin)
+ * const response = await Auth(request, {
+ *   providers: [
+ *     SSOReadySAML({
+ *       clientId: SSOREADY_SAML_CLIENT_ID,
+ *       clientSecret: SSOREADY_SAML_CLIENT_SECRET,
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * ### Resources
+ *
+ * - [SSOReady SSO OAuth
+ *   documentation](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration)
+ *
+ * ### Notes
+ *
+ * By default, Auth.js assumes that the SSOReady SAML provider is based on the
+ * [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification.
+ *
+ * [SAML](https://en.wikipedia.org/wiki/SAML_2.0) is not a single identity
+ * provider but rather a decentralized family of identity providers which all
+ * implement the SAML protocol. You can't just "log in via SAML". You always log
+ * in to a particular instance of SAML.
+ *
+ * To specify which instance of SAML to use, you provide to the SSOReadySAML
+ * provider an `organizationExternalId`. How you determine the appropriate
+ * `organizationExternalId` to provide is covered in [the SSOReady
+ * docs](https://ssoready.com/docs/saml-over-oauth-saml-nextauth-integration#creating-organizations).
+ *
+ * If your product's notion of an organization maps one-to-one with a company's
+ * domain, then you might implement SAML sign-ons like so:
+ *
+ * ```ts
+ * const [email, setEmail] = useState("")
+ *
+ * // ...
+ *
+ * <input
+ *   type="email"
+ *   value={email}
+ *   placeholder="Email"
+ *   onChange={(event) => setEmail(event.target.value)}
+ * />
+ * <button
+ *   onClick={() =>
+ *     signIn("ssoready-saml", undefined, {
+ *       organizationExternalId: email.split("@")[1],
+ *     })
+ *   }
+ * >
+ *   Sign in with SSO
+ * </button>
+ * ```
+ *
+ * The setup above presumes that you configure your organizations in SSOReady to
+ * have domains (e.g. "example.com") as their external IDs.
+ *
+ * :::tip
+ *
+ * The SSOReady SAML provider comes with a [default
+ * configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/ssoready-saml.ts).
+ * To override the defaults for your use case, check out [customizing a built-in
+ * OAuth provider](https://authjs.dev/guides/configuring-oauth-providers).
+ *
+ * :::
+ *
+ * :::info **Disclaimer**
+ *
+ * If you think you found a bug in the default configuration, you can [open an
+ * issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take
+ * responsibility for any deviation from the spec by the provider. You can open
+ * an issue, but if the problem is non-compliance with the spec, we might not
+ * pursue a resolution. You can ask for more help in
+ * [Discussions](https://authjs.dev/new/github-discussions).
+ *
+ * :::
+ */
+export default function SSOReadySAML<P extends SSOReadySAMLProfile>(
+  options: OAuthUserConfig<P>
+): OAuthConfig<P> {
+  return {
+    id: "ssoready-saml",
+    name: "SSOReady SAML",
+    type: "oidc",
+    issuer: "https://auth.ssoready.com/v1/oauth",
+    profile(profile) {
+      return {
+        id: profile.sub,
+        email: profile.sub,
+        organizationId: profile.organizationId,
+        organizationExternalId: profile.organizationExternalId,
+      }
+    },
+    client: {
+      token_endpoint_auth_method: "client_secret_post",
+    },
+    options,
+  }
+}