Manage instance settings using environment variables#

You can manage a subset of instance settings from environment variables, instead of configuring them through the UI. This is useful when you provision n8n instances automatically, such as through an internal deployment pipeline.

Each supported area has a dedicated environment variable named <AREA>_MANAGED_BY_ENV. Set this variable to true to activate environment variable management for that area. n8n then applies the related environment variables and locks the matching UI controls.

How it works#

When you set <AREA>_MANAGED_BY_ENV to true:

n8n reapplies the settings from environment variables on every startup.
The matching UI controls become read-only.

When <AREA>_MANAGED_BY_ENV is false (the default), n8n ignores the related environment variables, even if you set them.

Values persist when you turn off *_MANAGED_BY_ENV

Setting *_MANAGED_BY_ENV back to false restores UI write access but keeps the values that were last applied. Edit them through the UI afterward if you want to change them.

Unexpected read-only UI controls

If a setting appears as read-only and you didn't expect it, check whether the matching *_MANAGED_BY_ENV variable is true in your environment.

The four supported areas and their activating variables:

Instance owner: N8N_INSTANCE_OWNER_MANAGED_BY_ENV
SSO: N8N_SSO_MANAGED_BY_ENV
Security policy: N8N_SECURITY_POLICY_MANAGED_BY_ENV
Log streaming: N8N_LOG_STREAMING_MANAGED_BY_ENV

Set <AREA>_MANAGED_BY_ENV to activate the group

The other environment variables for an area have no effect unless <AREA>_MANAGED_BY_ENV is true. Set it to true to activate the group.

Instance owner#

Available from n8n v2.17.0

Pre-provision the instance owner from environment variables instead of going through the in-app setup.

N8N_INSTANCE_OWNER_PASSWORD_HASH must be a bcrypt hash

This variable expects a pre-hashed bcrypt value. Setting a plaintext password breaks login.

Variable	Type	Default	Description
`N8N_INSTANCE_OWNER_MANAGED_BY_ENV`	Boolean	`false`	Set to `true` to manage the instance owner from environment variables. When `true`, n8n overwrites the instance owner details below on every startup, locks the UI control for that user, and rejects API writes.
`N8N_INSTANCE_OWNER_EMAIL`	String	-	Email address for the instance owner.
`N8N_INSTANCE_OWNER_FIRST_NAME`	String	-	First name for the instance owner.
`N8N_INSTANCE_OWNER_LAST_NAME`	String	-	Last name for the instance owner.
`N8N_INSTANCE_OWNER_PASSWORD_HASH`	String	-	Bcrypt hash of the instance owner's password. Setting a plaintext password breaks login.

SSO#

Available from n8n v2.18.0

Feature availability

Single sign-on is available on Business and Enterprise plans.

Configure single sign-on from environment variables.

Activation and shared settings#

Variable	Type	Default	Description
`N8N_SSO_MANAGED_BY_ENV`	Boolean	`false`	Set to `true` to manage SSO from environment variables. When `true`, n8n applies the SSO variables on every startup and locks the matching UI controls.
`N8N_SSO_USER_ROLE_PROVISIONING`	Enum string: `disabled`, `instance_role`, `instance_and_project_roles`	`disabled`	How n8n provisions roles for users who sign in through SSO. `disabled` doesn't provision any roles. `instance_role` provisions the instance-level role only. `instance_and_project_roles` provisions both instance and project roles.

OIDC#

Variable	Type	Default	Description
`N8N_SSO_OIDC_LOGIN_ENABLED`	Boolean	`false`	Whether to enable OIDC login.
`N8N_SSO_OIDC_CLIENT_ID`	String	-	OIDC client ID issued by your identity provider.
`N8N_SSO_OIDC_CLIENT_SECRET`	String	-	OIDC client secret issued by your identity provider.
`N8N_SSO_OIDC_DISCOVERY_ENDPOINT`	String	-	OIDC discovery endpoint URL (the `.well-known/openid-configuration` URL for your identity provider).
`N8N_SSO_OIDC_PROMPT`	String	-	Optional OIDC `prompt` parameter to send with the authorization request, for example `login` or `consent`.
`N8N_SSO_OIDC_ACR_VALUES`	String	-	Optional OIDC `acr_values` parameter. Use this to request a specific authentication context, for example a step-up MFA flow.

SAML#

SAML metadata variables are mutually exclusive

Set either N8N_SSO_SAML_METADATA (inline XML) or N8N_SSO_SAML_METADATA_URL (URL), not both.

Variable	Type	Default	Description
`N8N_SSO_SAML_LOGIN_ENABLED`	Boolean	`false`	Whether to enable SAML login.
`N8N_SSO_SAML_METADATA`	String	-	SAML identity provider metadata as an XML string. Mutually exclusive with `N8N_SSO_SAML_METADATA_URL`; don't set both.
`N8N_SSO_SAML_METADATA_URL`	String	-	URL to fetch SAML identity provider metadata from. Mutually exclusive with `N8N_SSO_SAML_METADATA`; don't set both.

Security policy#

Available from n8n v2.18.0

Manage the instance security policy from environment variables, including MFA enforcement and personal space restrictions.

Variable	Type	Default	Description
`N8N_SECURITY_POLICY_MANAGED_BY_ENV`	Boolean	`false`	Set to `true` to manage the security policy from environment variables. When `true`, n8n applies the security policy variables on every startup and locks the matching UI controls.
`N8N_MFA_ENFORCED_ENABLED`	Boolean	`false`	Whether to enforce two-factor authentication for all users (`true`) or not (`false`).
`N8N_PERSONAL_SPACE_PUBLISHING_ENABLED`	Boolean	`true`	Whether users can publish from their personal space (`true`) or not (`false`).
`N8N_PERSONAL_SPACE_SHARING_ENABLED`	Boolean	`true`	Whether users can share resources from their personal space (`true`) or not (`false`).

Log streaming#

Available from n8n v2.19.0

Manage log streaming destinations from environment variables. See Configure using environment variables for the per-destination JSON shape.

Variable	Type	Default	Description
`N8N_LOG_STREAMING_MANAGED_BY_ENV`	Boolean	`false`	Set to `true` to manage log streaming from environment variables. When `true`, n8n applies the log streaming variables on every startup and locks the matching UI controls.
`N8N_LOG_STREAMING_DESTINATIONS`	JSON string	-	JSON array of log streaming destinations. Each destination is an object with a `type` of `webhook`, `syslog`, or `sentry`, plus the configuration for that type.

Combined example#

The following example configures an instance with all four areas managed by environment variables. It creates the instance owner, configures OIDC SSO, enforces MFA, and registers a webhook log streaming destination.

# Instance owner
export N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true
export N8N_INSTANCE_OWNER_EMAIL=<owner-email>
export N8N_INSTANCE_OWNER_FIRST_NAME=<first-name>
export N8N_INSTANCE_OWNER_LAST_NAME=<last-name>
export N8N_INSTANCE_OWNER_PASSWORD_HASH=<bcrypt-hash>

# SSO using OIDC
export N8N_SSO_MANAGED_BY_ENV=true
export N8N_SSO_USER_ROLE_PROVISIONING=instance_role
export N8N_SSO_OIDC_LOGIN_ENABLED=true
export N8N_SSO_OIDC_CLIENT_ID=<client-id>
export N8N_SSO_OIDC_CLIENT_SECRET=<client-secret>
export N8N_SSO_OIDC_DISCOVERY_ENDPOINT=<discovery-url>

# Security policy
export N8N_SECURITY_POLICY_MANAGED_BY_ENV=true
export N8N_MFA_ENFORCED_ENABLED=true
export N8N_PERSONAL_SPACE_PUBLISHING_ENABLED=false
export N8N_PERSONAL_SPACE_SHARING_ENABLED=false

# Log streaming
export N8N_LOG_STREAMING_MANAGED_BY_ENV=true
export N8N_LOG_STREAMING_DESTINATIONS='[{"type":"webhook","url":"https://logs.example.com/n8n"}]'

Set environment variables#

For the supported ways to set environment variables, see Configuration methods.

This page was