자격증명 덮어쓰기

자격증명 덮어쓰기 (Credential Overwrites)

출처: 공식문서

셀프호스팅 n8n 인스턴스에서 자격증명 데이터를 전역으로 설정해서, 사용자가 클라이언트 시크릿을 보거나 직접 입력하지 않아도 인증할 수 있게 하는 기능이에요.

자격증명 덮어쓰기란

자격증명 덮어쓰기(Credential overwrites)를 쓰면 자격증명 데이터를 전역으로 미리 설정할 수 있어요. 이 데이터는 사용자에게 보이지 않지만, n8n이 백그라운드에서 자동으로 사용해요. 예를 들어 클라이언트 시크릿을 노출하지 않으면서 Connect 버튼으로 OAuth 로그인을 가능하게 하는 데 쓰죠.

에디터 UI에서 n8n은 덮어쓰기된 필드를 기본적으로 모두 숨깁니다. 그래서 사용자는 자격증명의 Connect 버튼만 눌러 OAuth 인증을 할 수 있어요.

자격증명 덮어쓰기 환경 변수에 대한 내용은 Credentials 환경 변수 문서를 참고하세요.

REST API 활용 예시

자격증명 덮어쓰기를 설정하는 방법(잘 짜여진 워크플로 템플릿과 함께 REST API를 쓰는 방식)에 대한 튜토리얼을 영상으로 볼 수 있어요:

https://www.youtube.com/embed/VtCbCdKrqAE

환경 변수로 설정하기

CREDENTIALS_OVERWRITE_DATA를 { CREDENTIAL_NAME: { PARAMETER: VALUE }} 형태로 설정해요.

⚠️ 이 방식은 권장하지 않아요. 환경 변수는 n8n에서 보호되지 않아서 데이터가 사용자에게 새어 나갈 수 있어요.

REST API로 설정하기

권장하는 방식은 커스텀 REST 엔드포인트로 데이터를 불러오는 거예요.

  1. CREDENTIALS_OVERWRITE_ENDPOINT를 엔드포인트가 제공될 경로로 설정해요.

    export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials

    선택적으로 CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN을 설정하면 엔드포인트 접근에 베어러 토큰을 요구해요.

    인증 토큰이 없으면 보안상 엔드포인트를 한 번만 호출할 수 있어요.

  2. 덮어쓸 자격증명이 담긴 JSON 파일을 준비해요. 예를 들어 Asana와 GitHub용 oauth-credentials.json:

    {
    "asanaOAuth2Api": {
        "clientId": "<id>",
        "clientSecret": "<secret>"
    },
    "githubOAuth2Api": {
        "clientId": "<id>",
        "clientSecret": "<secret>"
    }
}

  3. 파일을 내 n8n 인스턴스로 보내요.

    curl -H "Content-Type: application/json" --data @oauth-credentials.json http://localhost:5678/send-credentials

    CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN이 secure-token으로 설정돼 있다면:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer ***" --data @oauth-credentials.json http://localhost:5678/send-credentials

💡 자격증명은 다른 자격증명을 확장(extend) 할 수 있어요. 예를 들어 googleSheetsOAuth2Api는 googleOAuth2Api를 확장해요. 부모(googleOAuth2Api)에 파라미터를 설정하면 모든 자식 자격증명이 그 값을 사용해요.

OAuth 스코프 필드 보여주기

기본적으로 n8n은 관리형 OAuth(managed OAuth)가 가능하면 스코프 필드를 숨겨요. 특정 관리형 OAuth 자격증명 타입에서 사용자가 스코프를 구성하도록 하려면 N8N_MANAGED_OAUTH_SHOW_SCOPES를 콤마 구분 목록으로 설정해요.

export N8N_MANAGED_OAUTH_SHOW_SCOPES=googleOAuth2Api

이 설정은 목록에 있는 자격증명 타입에만 적용돼요. 목록에 있는 타입을 확장하는 자격증명 타입에는 적용되지 않아요.

⚠️ 사용자가 자기 스코프를 설정하게 두면 검증된(verified) OAuth 앱이 깨질 수 있어요. Google 같은 많은 제공자는 앱 검증 과정에서 앱이 요청하는 모든 스코프를 정의하고 정당화하도록 요구해요. 사용자가 선언하지 않은 스코프를 추가하면 제공자가 앱을 정지하거나 금지(band)할 수 있어요. 사용자가 스코프를 추가해도 앱 검증에 위험이 되지 않는 자격증명 타입에만 이 설정을 켜세요.

영속화 (Persistence)

멀티 인스턴스 또는 큐 모드에서 자격증명 덮어쓰기를 데이터베이스에 저장하고 모든 워커에 전파하려면 다음을 켜요.

export CREDENTIALS_OVERWRITE_PERSISTENCE=true

이 설정을 켜면 n8n은 암호화된 덮어쓰기를 settings 테이블에 저장하고, reload-overwrite-credentials 이벤트를 브로드캐스트해서 워커가 최신 값을 다시 불러오게 해요. 꺼져 있으면 덮어쓰기는 그 값을 불러온 프로세스의 메모리에만 남고, 워커로 전파되지 않으며 재시작 후에도 유지되지 않아요.

더 알아보기 (Learn more)