diff --git a/.github/ISSUE_TEMPLATE/2_bug_provider.yml b/.github/ISSUE_TEMPLATE/2_bug_provider.yml index a5c8041863..50242e1738 100644 --- a/.github/ISSUE_TEMPLATE/2_bug_provider.yml +++ b/.github/ISSUE_TEMPLATE/2_bug_provider.yml @@ -76,6 +76,7 @@ body: - "SimpleLogin" - "Slack" - "Spotify" + - "SSOReady SAML" - "Strava" - "Threads" - "Tiktok" diff --git a/docs/pages/getting-started/providers/ssoready-saml.mdx b/docs/pages/getting-started/providers/ssoready-saml.mdx new file mode 100644 index 0000000000..23b76d0aeb --- /dev/null +++ b/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" + + + +# 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 + + + + +```bash +https://example.com/api/auth/callback/ssoready-saml +``` + + + + +```bash +https://example.com/auth/callback/ssoready-saml +``` + + + + +### 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 + + + + +```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], +}) +``` + + + + +```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], +}) +``` + + + + +```ts filename="/src/app.ts" +import { ExpressAuth } from "@auth/express" +import SSOReadySAML from "@auth/express/providers/ssoready-saml" + +app.use("/auth/*", ExpressAuth({ providers: [SSOReadySAML] })) +``` + + + + +### 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]; + +// ... + + + * ``` + * + * 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

( + options: OAuthUserConfig

+): OAuthConfig

{ + 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, + } +}