위임된 액세스로 Microsoft Entra ID 앱 등록 설정을 완료한 후, credential overwrites를 사용하여 Client ID와 Client Secret을 n8n 시작 시 주입할 수 있습니다. 이렇게 하면 조직의 사용자들이 자체 OAuth 앱 등록 없이 Microsoft 서비스에 연결할 수 있습니다.

n8n은 credential overwrites를 위한 세 가지 환경 변수를 지원합니다. 이 가이드에서는 CREDENTIALS_OVERWRITE_DATA_FILE을 사용합니다. 전체 변수 참조는 Credentials 환경 변수를 참고하세요.

자격 증명 파일 생성#

n8n이 실행 중인 호스트에서 docker-compose.yaml과 동일한 디렉토리에 credentials-overwrite.json 파일을 생성합니다.

파일에는 n8n credential type 이름을 키로 하는 JSON 객체가 포함됩니다. 예를 들어, Microsoft Outlook을 사전 구성하려면:

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

여러 Microsoft 서비스를 한 번에 사전 구성하려면 각 credential type을 별도의 키로 추가합니다:

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

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

각 Microsoft 서비스의 credential type 이름은 통합별 필수 스코프를 참고하세요.

Docker Compose#

compose.yaml에서 자격 증명 파일을 읽기 전용 볼륨으로 마운트하고 환경 변수를 설정합니다:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=America/New_York
      - TZ=America/New_York
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_LOG_LEVEL=debug
      - N8N_LOG_OUTPUT=file,console
      - N8N_LOG_FILE_COUNT_MAX=5
      - CREDENTIALS_OVERWRITE_DATA_FILE=/run/secrets/credentials-overwrite.json
    volumes:
      - n8n_data:/home/node/.n8n
      - ./credentials-overwrite.json:/run/secrets/credentials-overwrite.json:ro
    networks:
      - default
volumes:
  n8n_data:
    name: ${N8N_VOLUME:-n8n_data}
    external: true

컨테이너를 재시작하여 변경 사항을 적용합니다:

docker compose up -d

덮어쓰기 적용 확인#

n8n이 시작된 후, 사용자에게 사전 구성된 서비스 중 하나(예: Microsoft Outlook)에 대한 새 자격 증명을 생성하도록 합니다. 자격 증명 선택 화면에서 Managed OAuth2 (recommended) 옵션이 표시되어야 합니다.

사용자는 별도의 인증 없이 Connect to Microsoft Outlook을 클릭할 수 있습니다. Account connected 메시지가 표시되어야 합니다.

Managed OAuth 2 옵션이 표시되지 않으면 환경 변수가 올바르게 적용되지 않은 것입니다. 볼륨 마운트의 파일 경로가 CREDENTIALS_OVERWRITE_DATA_FILE 값과 일치하는지 확인하세요.

Kubernetes#

Kubernetes 배포의 경우 Docker 볼륨 마운트를 Kubernetes 네이티브 프리미티브로 교체합니다. 접근 방식은 클라우드 제공업체에 따라 다릅니다. 환경에 맞는 섹션을 선택하세요.

일반 Kubernetes Secret (EKS / AKS / GKE)#

이 방식은 추가 의존성 없이 세 가지 관리형 Kubernetes 제공업체 모두에서 작동합니다.

1. Secret 생성:

apiVersion: v1
kind: Secret
metadata:
  name: n8n-credentials-overwrite
  namespace: your-namespace
type: Opaque
stringData:
  credentials-overwrite.json: '{"microsoftOutlookOAuth2Api":{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}}'

2. Deployment에 Secret 마운트:

spec:
  containers:
    - name: n8n
      image: docker.n8n.io/n8nio/n8n:latest
      env:
        - name: CREDENTIALS_OVERWRITE_DATA_FILE
          value: /run/secrets/credentials-overwrite.json
        # ...다른 환경 변수
      volumeMounts:
        - name: credentials-overwrite
          mountPath: /run/secrets/credentials-overwrite.json
          subPath: credentials-overwrite.json
          readOnly: true
  volumes:
    - name: credentials-overwrite
      secret:
        secretName: n8n-credentials-overwrite

subPath 필드는 중요합니다. 이 필드가 없으면 Kubernetes가 단일 파일만 마운트하는 대신 전체 /run/secrets/ 디렉토리를 교체합니다.

env:
  - name: CREDENTIALS_OVERWRITE_DATA
    valueFrom:
      secretKeyRef:
        name: n8n-credentials-overwrite
        key: credentials-overwrite.json

stringData:
  credentials-json: '{"microsoftOutlookOAuth2Api":{"clientId":"...","clientSecret":"..."}}'

AWS Secrets Manager (EKS)#

이 방식은 AWS Secrets Store CSI Driver를 사용하여 AWS Secrets Manager의 secret을 pod에 직접 마운트합니다. rotation 지원, CloudTrail 감사 로깅, 중앙 집중식 secret 관리를 제공합니다.

사전 요구 사항:

• 클러스터에 Secrets Store CSI Driver와 ASCP(AWS Secrets and Configuration Provider) 설치
• 클러스터에 IAM OIDC 제공자 구성(IRSA 필요)
• secretsmanager:GetSecretValue 및 secretsmanager:DescribeSecret 권한이 있는 IAM 역할

1. AWS Secrets Manager에 secret 생성:

aws secretsmanager create-secret \
  --name n8n/credentials-overwrite \
  --description "n8n credential overwrites for Microsoft OAuth" \
  --secret-string '{"microsoftOutlookOAuth2Api":{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}}'

2. IAM 정책 생성:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:n8n/credentials-overwrite-*"
    }
  ]
}

aws iam create-policy \
  --policy-name n8n-credentials-overwrite-read \
  --policy-document file://policy.json

3. IRSA로 서비스 계정 생성:

eksctl create iamserviceaccount \
  --name n8n-sa \
  --namespace your-namespace \
  --cluster your-cluster \
  --attach-policy-arn arn:aws:iam::ACCOUNT_ID:policy/n8n-credentials-overwrite-read \
  --approve

4. SecretProviderClass 생성:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: n8n-credentials-overwrite
  namespace: your-namespace
spec:
  provider: aws
  parameters:
    objects: |
      - objectName: "n8n/credentials-overwrite"
        objectType: "secretsmanager"
        objectAlias: "credentials-overwrite.json"

5. n8n Deployment 업데이트:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n
  namespace: your-namespace
spec:
  template:
    spec:
      serviceAccountName: n8n-sa
      containers:
        - name: n8n
          image: docker.n8n.io/n8nio/n8n:latest
          env:
            - name: CREDENTIALS_OVERWRITE_DATA_FILE
              value: /run/secrets/credentials-overwrite.json
          volumeMounts:
            - name: credentials-overwrite
              mountPath: /run/secrets/credentials-overwrite.json
              subPath: credentials-overwrite.json
              readOnly: true
      volumes:
        - name: credentials-overwrite
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: n8n-credentials-overwrite

Secret 교체:

Secrets Manager에서 값을 업데이트합니다:

aws secretsmanager update-secret \
  --secret-id n8n/credentials-overwrite \
  --secret-string '{"microsoftOutlookOAuth2Api":{"clientId":"NEW_CLIENT_ID","clientSecret":"NEW_CLIENT_SECRET"}}'

CSI driver는 폴링 간격(기본값: 2분)마다 업데이트된 값을 동기화합니다. n8n은 시작 시 자격 증명 파일을 읽으므로, 업데이트된 파일을 읽으려면 n8n pod를 재시작하세요.

Azure Key Vault (AKS)#

이 방식은 Azure Key Vault Provider for the Secrets Store CSI Driver를 사용하여 Azure Key Vault의 secret을 pod에 마운트합니다.

사전 요구 사항:

• AKS 클러스터에 Secrets Store CSI Driver와 Azure Key Vault Provider 애드온 활성화
• Azure Key Vault 인스턴스
• 볼트에 접근 권한이 있는 managed identity 또는 service principal
• 클러스터에 Workload Identity 활성화(pod identity보다 권장)

1. 기존 Key Vault 생성 또는 사용:

az keyvault create \
  --name n8n-credentials-vault \
  --resource-group your-resource-group \
  --location your-region

2. Key Vault에 secret 생성:

az keyvault secret set \
  --vault-name n8n-credentials-vault \
  --name n8n-credentials-overwrite \
  --value '{"microsoftOutlookOAuth2Api":{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}}'

3. Workload Identity 설정:

managed identity를 생성하고 federated credential을 설정합니다:

# managed identity 생성
az identity create \
  --name n8n-workload-identity \
  --resource-group your-resource-group \
  --location your-region

# identity client ID 가져오기
CLIENT_ID=$(az identity show \
  --name n8n-workload-identity \
  --resource-group your-resource-group \
  --query clientId -o tsv)

# Key Vault에 identity 접근 권한 부여
az keyvault set-policy \
  --name n8n-credentials-vault \
  --secret-permissions get \
  --spn "$CLIENT_ID"

# 클러스터의 OIDC issuer URL 가져오기
OIDC_ISSUER=$(az aks show \
  --name your-cluster \
  --resource-group your-resource-group \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

# federated credential 생성
az identity credential create \
  --name n8n-workload-identity \
  --resource-group your-resource-group \
  --issuer "$OIDC_ISSUER" \
  --subject system:serviceaccount:your-namespace:n8n-sa \
  --audience api://AzureADTokenExchange

4. Kubernetes ServiceAccount 생성:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: n8n-sa
  namespace: your-namespace
  annotations:
    azure.workload.identity/client-id: "YOUR_MANAGED_IDENTITY_CLIENT_ID"
  labels:
    azure.workload.identity/use: "true"

5. SecretProviderClass 생성:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: n8n-credentials-overwrite
  namespace: your-namespace
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    useWorkloadIdentity: "true"
    clientID: "YOUR_MANAGED_IDENTITY_CLIENT_ID"
    keyvaultName: "n8n-credentials-vault"
    objects: |
      array:
        - |
          objectName: n8n-credentials-overwrite
          objectType: secret
          objectAlias: credentials-overwrite.json
    tenantId: "YOUR_TENANT_ID"

6. n8n Deployment 업데이트:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n
  namespace: your-namespace
spec:
  template:
    spec:
      serviceAccountName: n8n-sa
      containers:
        - name: n8n
          image: docker.n8n.io/n8nio/n8n:latest
          env:
            - name: CREDENTIALS_OVERWRITE_DATA_FILE
              value: /run/secrets/credentials-overwrite.json
          volumeMounts:
            - name: credentials-overwrite
              mountPath: /run/secrets/credentials-overwrite.json
              subPath: credentials-overwrite.json
              readOnly: true
      volumes:
        - name: credentials-overwrite
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: n8n-credentials-overwrite

Secret 교체:

az keyvault secret set \
  --vault-name n8n-credentials-vault \
  --name n8n-credentials-overwrite \
  --value '{"microsoftOutlookOAuth2Api":{"clientId":"NEW_CLIENT_ID","clientSecret":"NEW_CLIENT_SECRET"}}'

CSI driver는 폴링 간격(기본값: 2분)마다 동기화합니다. 업데이트된 파일을 읽으려면 그 후 n8n pod를 재시작하세요.

Google Secret Manager (GKE)#

이 방식은 GCP provider for the Secrets Store CSI Driver를 사용하여 Google Secret Manager의 secret을 pod에 마운트합니다.

사전 요구 사항:

• Workload Identity Federation이 활성화된 GKE 클러스터
• 프로젝트에서 Secret Manager API 활성화
• secretmanager.secretAccessor 역할이 있는 Google 서비스 계정

1. Secret Manager API 활성화:

gcloud services enable secretmanager.googleapis.com \
  --project your-project-id

2. Secret 생성:

echo -n '{"microsoftOutlookOAuth2Api":{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}}' | \
  gcloud secrets create n8n-credentials-overwrite \
    --data-file=- \
    --project your-project-id

3. Workload Identity Federation 설정:

# Google 서비스 계정 생성
gcloud iam service-accounts create n8n-secret-reader \
  --display-name="n8n Secret Reader" \
  --project your-project-id

# secret에 접근 권한 부여
gcloud secrets add-iam-policy-binding n8n-credentials-overwrite \
  --member="serviceAccount:n8n-secret-reader@your-project-id.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor" \
  --project your-project-id

# Kubernetes 서비스 계정을 Google 서비스 계정에 바인딩
gcloud iam service-accounts add-iam-policy-binding \
  n8n-secret-reader@your-project-id.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="serviceAccount:your-project-id.svc.id.goog[your-namespace/n8n-sa]"

4. Kubernetes ServiceAccount 생성:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: n8n-sa
  namespace: your-namespace
  annotations:
    iam.gke.io/gcp-service-account: n8n-secret-reader@your-project-id.iam.gserviceaccount.com

5. CSI Driver와 GCP provider 설치:

# CSI driver 설치
helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts
helm install csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver \
  --namespace kube-system

# GCP provider 설치
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/secrets-store-csi-driver-provider-gcp/main/deploy/provider-gcp-plugin.yaml

6. SecretProviderClass 생성:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: n8n-credentials-overwrite
  namespace: your-namespace
spec:
  provider: gcp
  parameters:
    secrets: |
      - resourceName: "projects/your-project-id/secrets/n8n-credentials-overwrite/versions/latest"
        path: "credentials-overwrite.json"

7. n8n Deployment 업데이트:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n
  namespace: your-namespace
spec:
  template:
    spec:
      serviceAccountName: n8n-sa
      containers:
        - name: n8n
          image: docker.n8n.io/n8nio/n8n:latest
          env:
            - name: CREDENTIALS_OVERWRITE_DATA_FILE
              value: /run/secrets/credentials-overwrite.json
          volumeMounts:
            - name: credentials-overwrite
              mountPath: /run/secrets/credentials-overwrite.json
              subPath: credentials-overwrite.json
              readOnly: true
      volumes:
        - name: credentials-overwrite
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: n8n-credentials-overwrite

Secret 교체:

새 버전의 secret을 생성합니다:

echo -n '{"microsoftOutlookOAuth2Api":{"clientId":"NEW_CLIENT_ID","clientSecret":"NEW_CLIENT_SECRET"}}' | \
  gcloud secrets versions add n8n-credentials-overwrite \
    --data-file=- \
    --project your-project-id

SecretProviderClass가 versions/latest를 참조하므로 CSI driver는 다음 동기화 시 새 버전을 가져옵니다. n8n이 업데이트된 파일을 읽으려면 n8n pod를 재시작하세요.