본문으로 이동

문서

OpenConnector 자격 증명, Runtime Token 및 OAuth

자체 호스팅 OpenConnector에서 앱 자격 증명, runtime 접근, OAuth 콜백과 이름 있는 연결을 설정하세요.

유지 관리: OOMOL·

소스 확인일: 2026-09-09. 예제는 링크된 소스 리비전과 대조했습니다. 실제 외부 API 검증을 의미하지 않으며, 배포된 버전과 다를 수 있습니다.

runtime 접근과 앱 자격 증명 구분

관리자 자격 증명은 콘솔과 /api를 보호합니다. Runtime Token은 /v1 및 /mcp 클라이언트를 승인합니다. 앱 자격 증명은 연결된 앱 계정에 속하며 runtime 내부에 보관됩니다. 서로 대신 사용할 수 없습니다.

자신의 OAuth 앱 등록

자체 호스팅에서는 서비스 제공자에 OAuth 앱을 등록하고 /api/oauth/configs의 정확한 expectedRedirectUri를 복사하세요. 원격 콜백을 설정하기 전에 OOMOL_CONNECT_ORIGIN을 공개 출처 주소로 설정하고 필요한 범위를 선택하세요.

사용할 계정 연결 선택

별칭을 지정하지 않으면 제공자의 기본 연결을 사용합니다. x-oo-connector-alias로 이름 있는 연결을 선택하세요. Runtime Token의 연결 권한에 따라 사용할 수 있는 계정이 제한될 수 있습니다.

자격 증명 보존과 보호

Docker 이미지는 로컬 runtime 데이터를 /app/data에 저장합니다. 영구 볼륨을 연결하세요. OOMOL_CONNECT_ENCRYPTION_KEY로 저장된 자격 증명을 암호화하고 복구에 필요한 키를 보관하세요. 공개 배포 전에 배포 가이드를 확인하세요.

OAuth 계정 연결 완료

  1. 먼저 OOMOL_CONNECT_ORIGIN을 브라우저에서 사용하는 주소로 설정하세요. /api/oauth/configs를 읽고 해당 공급자의 expectedRedirectUri를 OAuth 앱에 정확히 등록하세요. 관리자 인증을 사용하는 경우 관리자 Bearer 토큰을 추가하세요.
  2. 로컬 콘솔에서 공급자의 OAuth Client ID와 Secret을 저장하세요. 필요하면 공급자가 선언한 scopes 중 일부를 선택한 다음 인증을 시작하고 공급자의 브라우저 화면에서 접근을 승인하세요.
  3. 콜백 후 /api/connections에서 계정과 연결 이름을 확인한 뒤 Action을 호출하세요. 이름이 있는 연결은 미리 존재해야 하며 별칭 선택만으로 연결이 생성되지는 않습니다.

첫 요청은 관리자 토큰으로 계정 연결을 확인합니다. 두 번째 요청은 런타임 토큰과 기존 work 연결을 사용해 읽기 전용 Action을 호출합니다. 연결 이름을 자신의 것으로 바꾸고 기본 연결을 사용할 때는 별칭 헤더를 생략하세요.

GET /api/connections
curl -s http://localhost:3000/api/connections \
  -H "Authorization: Bearer $OOMOL_CONNECT_ADMIN_TOKEN"
HTTP · GitHub
curl -s -X POST \
  http://localhost:3000/v1/actions/github.get_current_user \
  -H "Authorization: Bearer $OOMOL_CONNECT_RUNTIME_TOKEN" \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

결과 읽기

HTTP 런타임 응답에는 success, message, data, meta가 포함됩니다. HTTP 상태만 보지 말고 success와 Action 출력 스키마를 확인하세요. 실행 메타데이터에 executionId가 있으면 해당 식별자로 민감 정보가 가려진 로그를 찾을 수 있습니다. 아래는 응답 구조 예시이며 실제 API 실행 결과가 아닙니다.

응답 구조 예시
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

호출 실패 시 확인 사항

  • 인증 실패 시 엔드포인트와 자격 증명 유형을 확인하세요. 관리자 자격 증명은 /api를 보호하고 런타임 Bearer 토큰은 /v1과 /mcp에 사용됩니다. 공급자 API 키는 런타임 토큰을 대체하지 못합니다.
  • 권한 거부 시 Action의 필수 scopes, 런타임 Action 규칙과 연결 권한을 확인하세요. 유효한 토큰이라도 선택한 계정에 접근하지 못할 수 있습니다.
  • 결과가 비어 있거나 리소스가 없다면 연결 계정과 해당 리소스 접근 권한을 확인하세요. 인증 성공이 모든 워크스페이스, 채널, 문서의 접근을 보장하지는 않습니다.
  • 재시도 전에 오류와 실행 로그를 확인하세요. 공급자 데이터를 변경하는 Action은 이미 완료되었는지 확인하고 무조건 반복 요청하지 마세요.
Markdown으로 읽기