mirror of
https://github.com/n8n-io/n8n-docs.git
synced 2026-03-27 09:28:43 +07:00
New docs section for OIDC protocol (#3349)
Co-authored-by: Justin Ellingwood <justin@n8n.io>
This commit is contained in:
jcn8n
@@ -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.
|
||||
5
_snippets/user-management/sso-oidc-availability.md
Normal file
5
_snippets/user-management/sso-oidc-availability.md
Normal file
@@ -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.
|
||||
///
|
||||
|
||||
4
_snippets/user-management/sso-saml-availability.md
Normal file
4
_snippets/user-management/sso-saml-availability.md
Normal file
@@ -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.
|
||||
///
|
||||
@@ -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"
|
||||
|
||||
16
docs/user-management/oidc/index.md
Normal file
16
docs/user-management/oidc/index.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4
|
||||
contentType: overview
|
||||
---
|
||||
|
||||
# OpenID Connect (OIDC)
|
||||
|
||||
--8<-- "_snippets/user-management/sso-oidc-availability.md"
|
||||
|
||||
<!-- vale from-microsoft.Contractions = NO -->
|
||||
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.
|
||||
<!-- vale from-microsoft.Contractions = NO -->
|
||||
|
||||
* [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.
|
||||
|
||||
81
docs/user-management/oidc/setup.md
Normal file
81
docs/user-management/oidc/setup.md
Normal file
@@ -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
|
||||
```
|
||||
32
docs/user-management/oidc/troubleshooting.md
Normal file
32
docs/user-management/oidc/troubleshooting.md
Normal file
@@ -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
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
6
nav.yml
6
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:
|
||||
|
||||
Reference in New Issue
Block a user