From bbeda346b1fc8e06d8aa2d775a078d4e2fd78f67 Mon Sep 17 00:00:00 2001 From: jcn8n <145542301+jcn8n@users.noreply.github.com> Date: Mon, 1 Sep 2025 23:46:16 +0100 Subject: [PATCH] New docs section for OIDC protocol (#3349) Co-authored-by: Justin Ellingwood --- _snippets/user-management/saml-overview.md | 14 ---- .../user-management/sso-oidc-availability.md | 5 ++ .../user-management/sso-saml-availability.md | 4 + docs/hosting/securing/set-up-sso.md | 17 +++- docs/user-management/oidc/index.md | 16 ++++ docs/user-management/oidc/setup.md | 81 +++++++++++++++++++ docs/user-management/oidc/troubleshooting.md | 32 ++++++++ docs/user-management/saml/index.md | 10 ++- docs/user-management/saml/managing.md | 2 + docs/user-management/saml/setup.md | 9 +-- nav.yml | 6 +- 11 files changed, 168 insertions(+), 28 deletions(-) delete mode 100644 _snippets/user-management/saml-overview.md create mode 100644 _snippets/user-management/sso-oidc-availability.md create mode 100644 _snippets/user-management/sso-saml-availability.md create mode 100644 docs/user-management/oidc/index.md create mode 100644 docs/user-management/oidc/setup.md create mode 100644 docs/user-management/oidc/troubleshooting.md diff --git a/_snippets/user-management/saml-overview.md b/_snippets/user-management/saml-overview.md deleted file mode 100644 index a92e295b3..000000000 --- a/_snippets/user-management/saml-overview.md +++ /dev/null @@ -1,14 +0,0 @@ -/// info | Feature availability -* Available on Enterprise plans. -* You need access to the n8n instance owner account to enable and configure SAML - -Available from version 0.225.0. -/// - - -This section provides guidance on using SAML SSO (single sign-on) with n8n. It assumes you're familiar with SAML. If you're not, [SAML Explained in Plain English](https://www.onelogin.com/learn/saml) can help you understand how SAML works, and its benefits. - -* [Set up SAML](/user-management/saml/setup.md): a general guide to setting up SAML in n8n, and links to resources for common IdPs. Start here. -* [Okta Workforce Identity SAML setup](/user-management/saml/okta.md): step-by-step guidance to configuring Okta. -* [Troubleshooting](/user-management/saml/troubleshooting.md): a list of things to check if you encounter issues. -* [Managing users with SAML](/user-management/saml/managing.md): performing user management tasks with SAML enabled. \ No newline at end of file diff --git a/_snippets/user-management/sso-oidc-availability.md b/_snippets/user-management/sso-oidc-availability.md new file mode 100644 index 000000000..1f0fcec94 --- /dev/null +++ b/_snippets/user-management/sso-oidc-availability.md @@ -0,0 +1,5 @@ +/// info | Feature availability +* Available on Enterprise plans. +* You need to be an instance owner or admin to enable and configure OIDC. +/// + diff --git a/_snippets/user-management/sso-saml-availability.md b/_snippets/user-management/sso-saml-availability.md new file mode 100644 index 000000000..7b882808a --- /dev/null +++ b/_snippets/user-management/sso-saml-availability.md @@ -0,0 +1,4 @@ +/// info | Feature availability +* Available on Enterprise plans. +* You need to be an instance owner or admin to enable and configure SAML. +/// diff --git a/docs/hosting/securing/set-up-sso.md b/docs/hosting/securing/set-up-sso.md index 1559b5798..4040d28cc 100644 --- a/docs/hosting/securing/set-up-sso.md +++ b/docs/hosting/securing/set-up-sso.md @@ -1,10 +1,19 @@ --- #https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 -title: Set up SAML SSO -description: "Set up SAML Single Sign-On for your self-hosted n8n instance." +title: Set up Single Sign-On (SSO) +description: "Set up SAML or OIDC Single Sign-On for your self-hosted n8n instance." contentType: howto --- -# Set up SAML Single Sign-On (SSO) +# Set up Single Sign-On (SSO) + +/// info | Feature availability +* Available on Enterprise plans. +* You need to be an instance owner or admin to enable and configure SAML or OIDC. +/// + +n8n supports the SAML and OIDC authentication protocols for single sign-on (SSO). See [OIDC vs SAML](https://www.onelogin.com/learn/oidc-vs-saml) for more general information on the two protocols, the differences between them, and their respective benefits. + +* [Set up SAML](/user-management/saml/setup.md): a general guide to setting up SAML in n8n, and links to resources for common identity providers (IdPs). +* [Set up OIDC](/user-management/oidc/setup.md): a general guide to setting up OpenID Connect (OIDC) SSO in n8n. ---8<-- "_snippets/user-management/saml-overview.md" diff --git a/docs/user-management/oidc/index.md b/docs/user-management/oidc/index.md new file mode 100644 index 000000000..89d73d107 --- /dev/null +++ b/docs/user-management/oidc/index.md @@ -0,0 +1,16 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +contentType: overview +--- + +# OpenID Connect (OIDC) + +--8<-- "_snippets/user-management/sso-oidc-availability.md" + + +This section covers how to enable and manage OpenID Connect (OIDC) for single sign-on (SSO). You can learn more about how OIDC works by visiting [what is OpenID Connect](https://openid.net/developers/how-connect-works/) by the OpenID Foundation. + + +* [Set up OIDC](/user-management/oidc/setup.md): a general guide to setting up OpenID Connect (OIDC) SSO in n8n. +* [Troubleshooting](/user-management/oidc/troubleshooting.md): a list of things to check if you encounter issues with OIDC. + diff --git a/docs/user-management/oidc/setup.md b/docs/user-management/oidc/setup.md new file mode 100644 index 000000000..7046290ef --- /dev/null +++ b/docs/user-management/oidc/setup.md @@ -0,0 +1,81 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +title: Set up OIDC +description: Set up instructions for enabling OIDC SSO with n8n. +contentType: howto +--- + +# Set up OIDC + +--8<-- "_snippets/user-management/sso-oidc-availability.md" + +## Setting up and enabling OIDC + + +1. In n8n, go to **Settings** > **SSO**. +1. Under **Select Authentication Protocol**, choose **OIDC** from the dropdown. +1. Copy the **redirect URL** shown (for example, `https://yourworkspace.app.n8n.cloud/rest/sso/oidc/callback`). + + /// note | Extra configuration for load balancers or proxies + If you are running n8n behind a load balancer, make sure you set the [`N8N_EDITOR_BASE_URL` environment variable](/hosting/configuration/environment-variables/deployment.md). + /// + +1. Set up OIDC with your identity provider (IdP). You'll need to: + - Create a new OIDC client/application in your IdP. + - Configure the redirect URL from the previous step. + - Note down the **Client ID** and **Client Secret** provided by your IdP. +1. In your IdP, locate the **Discovery Endpoint** (also called the well-known configuration endpoint). It typically has the following format: + ``` + https://your-idp-domain/.well-known/openid-configuration + ``` +1. In n8n, complete the OIDC configuration: + - **Discovery Endpoint**: Enter the discovery endpoint URL from your IdP. + - **Client ID**: Enter the client ID you received when registering your application with your IdP. + - **Client Secret**: Enter the client secret you received when registering your application with your IdP. +1. Select **Save settings**. +1. Set OIDC to **Activated**. + +## Provider-specific OIDC setup + +### Auth0 + +1. **Create an application in Auth0**: + - Log in to your Auth0 Dashboard. + - Go to **Applications** > **Applications**. + - Click **Create Application**. + - Enter a name (for example, "n8n SSO") and select **Regular Web Applications**. + - Click **Create**. +1. **Configure the application**: + - Go to the **Settings** tab of your new application. + - **Allowed Callback URLs**: Add your n8n redirect URL from **Settings** > **SSO** > **OIDC**. + - **Allowed Web Origins**: Add your n8n base URL (for example, `https://yourworkspace.app.n8n.cloud`). + - Click **Save Changes**. +1. **Get your credentials**: + - **Client ID**: Found in the **Settings** tab. + - **Client Secret**: Found in the **Settings** tab. + - **Discovery Endpoint**: `https://{your-auth0-domain}.auth0.com/.well-known/openid-configuration`. +1. **In n8n, complete the OIDC configuration:** + - **Discovery Endpoint**: Enter the discovery endpoint URL from Auth0. + - **Client ID**: Enter the client ID you found in your Auth0 settings. + - **Client Secret**: Enter the client secret you found in your Auth0 settings. +1. Select **Save settings**. +1. Set OIDC to **Activated**. + +## Discovery endpoints reference + +- **Google discovery endpoint example**: +``` +https://accounts.google.com/.well-known/openid-configuration +``` +- **Microsoft Azure AD discovery endpoint example**: +``` +https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration +``` +- **Auth0 discovery endpoint example**: +``` +https://{your-domain}.auth0.com/.well-known/openid-configuration +``` +- **Okta discovery endpoint example**: +``` +https://{your-domain}.okta.com/.well-known/openid-configuration +``` diff --git a/docs/user-management/oidc/troubleshooting.md b/docs/user-management/oidc/troubleshooting.md new file mode 100644 index 000000000..ae04bbcfe --- /dev/null +++ b/docs/user-management/oidc/troubleshooting.md @@ -0,0 +1,32 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +title: Troubleshooting for OIDC SSO +description: Things to be aware of and troubleshooting OIDC within n8n +contentType: howto +--- + +# Troubleshooting OIDC SSO + +## Known issues + +### State parameter not supported + +When using OIDC providers that enforce the use of the `state` CSRF token parameter, authentication fails with the error: + +```json +{"code":0,"message":"authorization response from the server is an error"} +``` + +n8n's current OIDC implementation doesn't handle the `state` parameter that some OIDC providers send as a security measure against CSRF attacks. + +For now, the only work around is to configure your OIDC provider to disable the `state` parameter if possible. + +n8n is working on adding full support for the OIDC `state` parameter in a future release. + +### PKCE not supported + +OIDC providers that require PKCE (Proof Key for Code Exchange) may fail authentication or reject n8n's authorization requests. n8n's current OIDC implementation doesn't support PKCE. + +The only work around is to configure your OIDC provider to not require PKCE for the n8n client if this option is available in your providers settings. + +n8n plans on adding PKCE support in a future release diff --git a/docs/user-management/saml/index.md b/docs/user-management/saml/index.md index 2dcfdfaee..2a5a2e4e6 100644 --- a/docs/user-management/saml/index.md +++ b/docs/user-management/saml/index.md @@ -5,4 +5,12 @@ contentType: overview # Security Assertion Markup Language (SAML) ---8<-- "_snippets/user-management/saml-overview.md" +--8<-- "_snippets/user-management/sso-saml-availability.md" + +This section tells you how to enable SAML SSO (single sign-on) in n8n. It assumes you're familiar with SAML. If you're not, [SAML Explained in Plain English](https://www.onelogin.com/learn/saml) can help you understand how SAML works, and its benefits. + +* [Set up SAML](/user-management/saml/setup.md): a general guide to setting up SAML in n8n, and links to resources for common IdPs. +* [Okta Workforce Identity SAML setup](/user-management/saml/okta.md): step-by-step guidance to configuring Okta. +* [Troubleshooting](/user-management/saml/troubleshooting.md): a list of things to check if you encounter issues. +* [Managing users with SAML](/user-management/saml/managing.md): performing user management tasks with SAML enabled. + diff --git a/docs/user-management/saml/managing.md b/docs/user-management/saml/managing.md index 40644efe9..7f4383fda 100644 --- a/docs/user-management/saml/managing.md +++ b/docs/user-management/saml/managing.md @@ -7,6 +7,8 @@ contentType: howto # Manage users with SAML +--8<-- "_snippets/user-management/sso-saml-availability.md" + There are some user management tasks that are affected by SAML. ## Exempt users from SAML diff --git a/docs/user-management/saml/setup.md b/docs/user-management/saml/setup.md index 757fe96f2..63cba135c 100644 --- a/docs/user-management/saml/setup.md +++ b/docs/user-management/saml/setup.md @@ -7,14 +7,7 @@ contentType: howto # Set up SAML -/// info | Feature availability -* Available on Enterprise plans. -* You need access to the n8n instance owner account to enable and configure SAML - -Available from version 0.225.0. -/// - -This page tells you how to enable SAML SSO (single sign-on) in n8n. It assumes you're familiar with SAML. If you're not, [SAML Explained in Plain English](https://www.onelogin.com/learn/saml) can help you understand how SAML works, and its benefits. +--8<-- "_snippets/user-management/sso-saml-availability.md" ## Enable SAML diff --git a/nav.yml b/nav.yml index 09630c9f3..dbfba063c 100644 --- a/nav.yml +++ b/nav.yml @@ -81,12 +81,16 @@ nav: - Best practices: user-management/best-practices.md - 2FA: user-management/two-factor-auth.md - LDAP: user-management/ldap.md + - OIDC: + - user-management/oidc/index.md + - Set up OIDC: user-management/oidc/setup.md + - Troubleshooting: user-management/oidc/troubleshooting.md - SAML: - user-management/saml/index.md - Set up SAML: user-management/saml/setup.md - Okta Workforce Identity SAML setup: user-management/saml/okta.md - - Troubleshooting: user-management/saml/troubleshooting.md - Manage users with SAML: user-management/saml/managing.md + - Troubleshooting: user-management/saml/troubleshooting.md - Keyboard shortcuts: keyboard-shortcuts.md - Key concepts: - Flow logic: