위임된 액세스로 Microsoft Entra ID 앱 등록을 설정한 후에는 자격 증명 오버라이트를 사용하여 시작 시 Client ID와 Client Secret을 n8n에 주입할 수 있습니다. 이렇게 하면 조직 내 사용자가 자체 OAuth 앱 등록을 완료하지 않고도 Microsoft 서비스에 연결할 수 있습니다.

n8n은 자격 증명 오버라이트를 위해 세 가지 환경 변수를 지원합니다. 이 가이드에서는 CREDENTIALS_OVERWRITE_DATA_FILE을 사용합니다. 전체 변수 참조는 자격 증명 환경 변수를 참고하세요.

자격 증명 파일 생성#

n8n을 실행 중인 호스트에서 docker-compose.yaml과 같은 디렉터리에 credentials-overwrite.json이라는 이름의 파일을 생성합니다.

이 파일에는 n8n 자격 증명 유형 이름을 키로 하는 JSON 객체가 들어 있습니다. 예를 들어 Microsoft Outlook을 사전 구성하려면 다음과 같이 작성합니다.

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

여러 Microsoft 서비스를 한 번에 사전 구성하려면 각 자격 증명 유형을 별도의 키로 추가합니다.

{
  "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 서비스의 자격 증명 유형 이름은 통합별 필수 범위를 참고하세요.

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
        # ...your other env vars
      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 드라이버를 사용하여 AWS Secrets Manager의 시크릿을 파드에 직접 마운트합니다. 로테이션 지원, CloudTrail 감사 로깅, 중앙 집중식 시크릿 관리 기능이 추가됩니다.

전제 조건:

• 클러스터에 Secrets Store CSI 드라이버와 ASCP(AWS Secrets and Configuration Provider)가 설치되어 있어야 함
• 클러스터에 IAM OIDC 공급자가 구성되어 있어야 함(IRSA에 필요)
• secretsmanager:GetSecretValue 및 secretsmanager:DescribeSecret 권한이 있는 IAM 역할

1. AWS Secrets Manager에 시크릿 생성:

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

시크릿 로테이션:

자격 증명을 업데이트하려면 Secrets Manager의 값을 업데이트합니다.

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

CSI 드라이버는 폴링 간격(기본값 2분)에 따라 업데이트된 값을 동기화합니다. n8n은 시작 시 자격 증명 파일을 읽으므로, n8n이 업데이트된 파일을 읽으려면 n8n 파드를 재시작해야 합니다.

Azure Key Vault (AKS)#

이 방식은 Secrets Store CSI 드라이버용 Azure Key Vault 제공업체를 사용하여 Azure Key Vault의 시크릿을 파드에 마운트합니다.

전제 조건:

• AKS 클러스터에 Secrets Store CSI 드라이버와 Azure Key Vault 제공업체 애드온이 활성화되어 있어야 함
• Azure Key Vault 인스턴스
• 볼트에 액세스 권한이 있는 관리 ID 또는 서비스 주체
• 클러스터에 Workload Identity가 활성화되어 있어야 함(파드 ID보다 권장됨)

1. 기존 Key Vault를 생성하거나 사용:

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

2. Key Vault에 시크릿 생성:

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 설정:

관리 ID를 생성하고 페더레이션 자격 증명을 설정합니다.

# Create a managed identity
az identity create \
  --name n8n-workload-identity \
  --resource-group your-resource-group \
  --location your-region

# Get the identity client ID
CLIENT_ID=$(az identity show \
  --name n8n-workload-identity \
  --resource-group your-resource-group \
  --query clientId -o tsv)

# Grant the identity access to the Key Vault
az keyvault set-policy \
  --name n8n-credentials-vault \
  --secret-permissions get \
  --spn "$CLIENT_ID"

# Get the OIDC issuer URL for your cluster
OIDC_ISSUER=$(az aks show \
  --name your-cluster \
  --resource-group your-resource-group \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

# Create the 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

시크릿 로테이션:

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

CSI 드라이버는 폴링 간격(기본값 2분)에 따라 동기화합니다. n8n이 업데이트된 파일을 가져오려면 이후 n8n 파드를 재시작하세요.

Google Secret Manager (GKE)#

이 방식은 Secrets Store CSI 드라이버용 GCP 제공업체를 사용하여 Google Secret Manager의 시크릿을 파드에 마운트합니다.

전제 조건:

• 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. 시크릿 생성:

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 설정:

# Create a Google service account
gcloud iam service-accounts create n8n-secret-reader \
  --display-name="n8n Secret Reader" \
  --project your-project-id

# Grant it access to the 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

# Bind the Kubernetes service account to the Google service account
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 드라이버와 GCP 제공업체 설치:

# Install the 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

# Install the 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

시크릿 로테이션:

시크릿의 새 버전을 생성합니다.

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 드라이버는 다음 동기화 시점에 새 버전을 가져옵니다. n8n이 업데이트된 파일을 읽으려면 n8n 파드를 재시작하세요.