Ctrlk
ForumChangelog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pre-configure Microsoft OAuth credentials

After setting up a Microsoft Entra ID app registration with delegated access, you can use credential overwrites to inject the Client ID and Client Secret into n8n at startup. This means users in your organisation can connect to Microsoft services without completing their own OAuth app registration.

n8n supports three environment variables for credential overwrites. This guide uses CREDENTIALS_OVERWRITE_DATA_FILE. Refer to Credentials environment variables for the full variable reference.

Create the credentials file

On the host running n8n, create a file named credentials-overwrite.json in the same directory as your docker-compose.yaml.

The file contains a JSON object keyed by the n8n credential type name. For example, to pre-configure Microsoft Outlook:

{
  "microsoftOutlookOAuth2Api": {
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }
}

To pre-configure multiple Microsoft services at once, add each credential type as a separate key:

{
  "microsoftOutlookOAuth2Api": {
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  },
  "microsoftOneDriveOAuth2Api": {
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }
}

Minified JSON

n8n requires the JSON to be minified (no spaces or newlines). The examples above are formatted for readability. Make sure your actual file contains no extra whitespace:

Refer to Required scopes by integration for the credential type name of each Microsoft service.

Docker Compose

Mount the credentials file as a read-only volume and set the environment variable in your compose.yaml:

Apply the changes by restarting the container:

Verify the overwrite is applied

After n8n starts, have a user create a new credential for one of the pre-configured services (for example, Microsoft Outlook). They should see a Managed OAuth2 (recommended) option in the credential selection.

Microsoft Entra credentials screen

The user can click Connect to Microsoft Outlook, with no auth required. An Account connected message should appear

If the Managed OAuth 2 option doesn't appear, the environment variable wasn't applied correctly. Check that the file path in the volume mount matches the value of CREDENTIALS_OVERWRITE_DATA_FILE.

Kubernetes

For Kubernetes deployments, replace the Docker volume mount with Kubernetes-native primitives. The approach differs by cloud provider. Choose the section that matches your environment.

Plain Kubernetes Secret (EKS / AKS / GKE)

This approach works across all three managed Kubernetes providers without additional dependencies.

1. Create the Secret:

2. Mount the Secret in your Deployment:

The subPath field is important. Without it, Kubernetes replaces the entire /run/secrets/ directory rather than mounting just the single file.

Alternative: inline environment variable

To skip the volume mount entirely, reference the Secret directly as an environment variable:

This is cleaner for single-service setups, but note that some Kubernetes environments restrict environment variable size (for example, to 128KB per variable). The file-based approach is safer if you have many credential overwrites.

AWS Secrets Manager (EKS)

This approach uses the AWS Secrets Store CSI Driver to mount a secret from AWS Secrets Manager directly into the pod. It adds rotation support, CloudTrail audit logging, and centralised secret management.

Prerequisites:

  • Secrets Store CSI Driver and ASCP (AWS Secrets and Configuration Provider) installed on the cluster

  • IAM OIDC provider configured for the cluster (required for IRSA)

  • An IAM role with secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions

1. Create the secret in AWS Secrets Manager:

2. Create an IAM policy:

3. Create a service account with IRSA:

4. Create the SecretProviderClass:

5. Update your n8n Deployment:

Rotating the secret:

To update the credentials, update the value in Secrets Manager:

The CSI driver syncs the updated value on its polling interval (default two minutes). Restart the n8n pod for n8n to read the updated file, as n8n reads the credentials file at startup.

Azure Key Vault (AKS)

This approach uses the Azure Key Vault Provider for the Secrets Store CSI Driver to mount secrets from Azure Key Vault into the pod.

Prerequisites:

  • Secrets Store CSI Driver and Azure Key Vault Provider addon enabled on the AKS cluster

  • An Azure Key Vault instance

  • A managed identity or service principal with access to the vault

  • Workload Identity enabled on the cluster (recommended over pod identity)

1. Create or use an existing Key Vault:

2. Create the secret in Key Vault:

3. Set up Workload Identity:

Create a managed identity and establish the federated credential:

4. Create the Kubernetes ServiceAccount:

5. Create the SecretProviderClass:

6. Update your n8n Deployment:

Rotating the secret:

The CSI driver syncs on its polling interval (default two minutes). Restart the n8n pod afterward for n8n to pick up the updated file.

Google Secret Manager (GKE)

This approach uses the GCP provider for the Secrets Store CSI Driver to mount secrets from Google Secret Manager into the pod.

Prerequisites:

  • A GKE cluster with Workload Identity Federation enabled

  • The Secret Manager API enabled on the project

  • A Google service account with the secretmanager.secretAccessor role

1. Enable the Secret Manager API:

2. Create the secret:

3. Set up Workload Identity Federation:

4. Create the Kubernetes ServiceAccount:

5. Install the CSI Driver and GCP provider:

6. Create the SecretProviderClass:

7. Update your n8n Deployment:

Rotating the secret:

Create a new version of the secret:

Because the SecretProviderClass references versions/latest, the CSI driver picks up the new version on its next sync. Restart the n8n pod for n8n to read the updated file.

PreviousEnable Prometheus metricsNextConfigure a custom workflow templates library

Last updated

Was this helpful?