서비스 인증을 위한 증명서

인증 정보란

인증 정보(Credentials)는 외부 서비스에 접속하기 위한 비밀 키와 설정값의 묶음입니다.

워크플로우의 노드가 외부 API(OpenAI, Google, AWS 등)와 통신하려면, 해당 서비스에 허가된 사용자임을 증명해야 합니다. 이때 사용하는 것이 인증 정보입니다.

[노드] ──(인증 정보)──→ [외부 서비스 API]
                         "이 API 키는 유효합니다"
                         → 요청 승인

비유하자면, 인증 정보는 외부 서비스에 들어가기 위한 출입증과 같습니다. 한 번 등록해 두면 해당 서비스를 사용하는 모든 노드에서 재사용할 수 있습니다.

인증 정보가 필요한 이유

보안

API 키나 비밀번호를 워크플로우 설정에 직접 입력하면 유출 위험이 있습니다. 인증 정보 시스템은 민감한 값을 암호화하여 별도 저장하고, 워크플로우 실행 시에만 복호화하여 사용합니다.

재사용

하나의 인증 정보를 등록하면 여러 워크플로우, 여러 노드에서 공유하여 사용할 수 있습니다.

[워크플로우 A] ──┐
                 ├──→ [OpenAI 인증 정보] ──→ OpenAI API
[워크플로우 B] ──┘

관리 편의성

API 키가 변경되거나 만료된 경우, 인증 정보 한 곳만 수정하면 해당 인증을 사용하는 모든 워크플로우에 즉시 반영됩니다.

인증 방식의 종류

API 키 방식

가장 간단한 인증 방식입니다. 서비스 제공자가 발급한 API 키(문자열)를 입력하면 됩니다.

사용하는 서비스 예시:

• OpenAI, Gemini, Grok — AI 텍스트 생성

• ElevenLabs, Typecast AI — 음성 합성(TTS)

• Tavily, Brave Search — 검색

• Creatomate, Flux Kontext, Kling AI — 이미지/영상 생성

• AWS S3 — 파일 저장소 (Access Key + Secret Key)

특징:

• 설정이 간단함 (키 하나만 입력)

• 서비스 제공자 웹사이트에서 키를 발급받아 복사·붙여넣기

• 키가 노출되면 즉시 재발급 필요

OAuth2 방식

사용자가 외부 서비스에 직접 로그인하여 권한을 부여하는 방식입니다. Google 서비스들이 대표적입니다.

사용하는 서비스 예시:

• Gmail — 이메일 읽기/보내기

• Google Sheets — 스프레드시트 읽기/쓰기

• Google Drive — 파일 업로드/다운로드

• YouTube — 영상 업로드/채널 관리

• 기타 Google 서비스 전체 (Calendar, Docs, Slides 등)

특징:

• Google 등 서비스에 로그인하여 "이 앱에 권한을 허용합니다" 버튼을 클릭

• 액세스 토큰이 자동 발급되며, 만료 시 자동 갱신

• 비밀번호를 직접 입력하지 않으므로 더 안전

• Client ID와 Client Secret 설정이 필요 (관리자가 미리 설정해 둘 수 있음)

OAuth2 인증 흐름:

1. [사용자] ──(인증 시작)──→ [워크플로우 시스템]
2. [워크플로우 시스템] ──(리다이렉트)──→ [Google 로그인 페이지]
3. [사용자] ──(로그인 & 권한 허용)──→ [Google]
4. [Google] ──(인증 코드)──→ [워크플로우 시스템]
5. [워크플로우 시스템] ──(인증 코드로 토큰 교환)──→ [Google]
6. [Google] ──(액세스 토큰 + 리프레시 토큰)──→ [워크플로우 시스템]
7. 이후 API 호출 시 액세스 토큰 사용 (만료 시 자동 갱신)

인증 정보 등록하기

API 키 인증 등록

1. 워크플로우 관리 화면에서 인증 정보 메뉴로 이동합니다.

2. 새 인증 정보 추가를 클릭합니다.

3. 인증 유형을 선택합니다 (예: OpenAI API).

4. 인증 정보 이름을 입력합니다 (예: my-openai).

5. 서비스에서 발급받은 API 키를 입력합니다.

6. 저장을 클릭합니다.

팁: 인증 정보 이름은 용도를 알 수 있게 지정하세요. 예: production-openai, test-gemini

OAuth2 인증 등록

1. 인증 유형에서 OAuth2 방식의 서비스를 선택합니다 (예: Gmail OAuth2).

2. Client ID와 Client Secret을 입력합니다.

   • 시스템 인증 정보로 미리 설정된 경우 이 단계는 생략됩니다.

3. OAuth 연결 버튼을 클릭합니다.

4. 새 창에서 Google 계정으로 로그인합니다.

5. 요청된 권한을 확인하고 허용을 클릭합니다.

6. 인증이 완료되면 자동으로 돌아옵니다.

인증 정보와 노드의 관계

각 노드는 자신이 사용할 수 있는 인증 정보 유형이 정해져 있습니다.

노드를 워크플로우에 추가하면, 해당 노드의 설정 화면에서 등록된 인증 정보 중 적합한 유형을 선택할 수 있습니다.

[OpenAI 노드 설정]
  인증 정보: [my-openai ▼]    ← 등록된 OpenAI API 인증 중 선택
  모델: gpt-4
  프롬프트: ...

하나의 인증 정보 유형에 여러 인증 정보를 등록할 수도 있습니다. 예를 들어, 프로젝트별로 다른 OpenAI API 키를 사용하고 싶다면:

• project-a-openai (프로젝트 A용 키)

• project-b-openai (프로젝트 B용 키)

시스템 인증 정보와 사용자 인증 정보

시스템 인증 정보

• 관리자가 등록하는 공용 인증 정보입니다.

• 모든 사용자가 공유하여 사용할 수 있습니다.

• 주로 OAuth2의 Client ID/Secret처럼 조직 전체가 공유하는 설정에 사용합니다.

• 관리 화면(/admin)에서 설정합니다.

사용자 인증 정보

• 개별 사용자가 등록하는 인증 정보입니다.

• 해당 사용자의 워크플로우에서만 사용됩니다.

• 개인 API 키, 개인 OAuth2 토큰 등에 사용합니다.

우선순위

같은 유형·같은 이름의 인증 정보가 시스템과 사용자 양쪽에 존재하면, 사용자 인증 정보가 우선 적용됩니다.

OAuth2 토큰 관리

OAuth2 인증 정보는 발급된 토큰의 수명 주기를 관리해야 합니다.

토큰 상태

자동 갱신

액세스 토큰이 만료되면 시스템이 리프레시 토큰을 사용하여 자동으로 새 토큰을 발급합니다. 사용자가 별도로 조치할 필요가 없습니다.

다중 계정 연결

하나의 인증 정보 설정으로 여러 OAuth2 계정을 연결할 수 있습니다. 예를 들어, 하나의 YouTube OAuth2 설정에 여러 YouTube 채널을 연결하여 채널별로 다른 토큰을 사용할 수 있습니다.

지원하는 인증 정보 목록

API 키 방식

OAuth2 방식

보안 안내

암호화 저장

모든 인증 정보는 데이터베이스에 암호화되어 저장됩니다. API 키, Secret, 토큰 등 민감한 값은 평문으로 저장되지 않습니다.

민감 정보 마스킹

API를 통해 인증 정보를 조회할 때, 다음 필드들은 마스킹 처리되어 반환됩니다:

• API Key → sk-****...

• Client Secret → ****...

• Access Token → ****...

• Secret Key → ****...

API 키 관리 원칙

자주 묻는 질문

Q: 인증 정보를 등록했는데 노드에서 선택이 안 됩니다

인증 정보의 유형(type)이 노드가 요구하는 유형과 일치하는지 확인하세요. 예를 들어, Gmail 노드는 Gmail OAuth2 API 유형만 사용할 수 있고, 일반 Google OAuth2 API로는 동작하지 않습니다.

Q: OAuth2 인증이 갑자기 안 됩니다

다음을 확인하세요:

1. 토큰 만료: 대부분 자동 갱신되지만, 리프레시 토큰이 만료된 경우 재인증이 필요합니다.

2. 권한 취소: 사용자가 Google 계정 설정에서 앱 접근 권한을 취소한 경우 재인증이 필요합니다.

3. Client Secret 변경: 관리자가 OAuth2 앱의 Client Secret을 변경한 경우 인증 정보를 업데이트해야 합니다.

Q: 하나의 API 키를 여러 워크플로우에서 사용해도 되나요

네, 하나의 인증 정보를 여러 워크플로우에서 공유하여 사용할 수 있습니다. 이것이 인증 정보 시스템의 핵심 장점입니다.

Q: 시스템 인증 정보와 사용자 인증 정보의 이름이 같으면 어떻게 되나요

사용자 인증 정보가 우선 적용됩니다. 시스템 인증 정보를 덮어쓰고 싶을 때 같은 이름으로 사용자 인증 정보를 등록하면 됩니다.

Q: API 키를 분실했습니다. 워크플로우에서 확인할 수 있나요

보안을 위해 저장된 API 키는 마스킹 처리되어 조회됩니다. 원래 키를 확인할 수 없으므로, 서비스 제공자 사이트에서 새 키를 발급받아 인증 정보를 업데이트하세요.