SaaS용 Connector 가이드

SaaS용 Connector는 SaaS 제품을 위한 계정 연결 레이어입니다. 각 최종 사용자가 자신의 Gmail, Slack, Notion 또는 기타 타사 계정을 연결해야 하고, 권한 부여 후 백엔드에서 Connector 작업을 실행해야 할 때 사용합니다. OOMOL Console은 프로젝트, 제공자 구성, API 키, 연결된 계정을 관리하며, 백엔드는 권한 부여 링크 생성, 콜백 처리, 계정 선택, 작업 호출 시작을 담당합니다.

완전한 통합은 두 부분으로 구성됩니다. OOMOL Console에서 프로젝트와 서비스를 구성한 다음, 백엔드에서 권한 부여 링크를 생성하고 콜백을 처리하며 계정을 선택하고 작업을 실행합니다.

주요 주제:

관리자가 OOMOL Console에서 준비하는 리소스.
백엔드에 저장해야 하는 ID와 비밀 값.
최종 사용자가 계정을 연결할 때 프런트엔드와 백엔드가 수행하는 작업.
연결된 계정을 선택하고 작업을 실행하는 방법.
문제 해결에 도움이 되는 Console 페이지, 상태, 로그 및 사용량 보기.

통합 모델

SaaS 통합에는 설정 단계와 런타임 단계가 있습니다.

관리자는 최종 사용자 흐름 전에 OOMOL Console에서 설정 단계를 완료합니다. 이 단계에서 프로젝트, 제공자 구성, 백엔드 API 키를 준비하고 런타임에 필요한 ID와 비밀 값을 기록합니다.

런타임 단계는 제품 백엔드에서 발생합니다. 계정 권한 부여 요청 생성, 요청 상태 읽기, 작업 실행 시 SaaS 프로젝트를 나타냅니다. 런타임 요청에는 프로젝트 API 키가 포함됩니다.

authorization: Bearer <project-api-key>

프로젝트 API 키는 백엔드에만 보관합니다. 최종 사용자는 제품 UI를 사용하거나 Connector가 반환한 OAuth 권한 부여 URL을 여는 것만으로 충분합니다.

저장할 데이터

일반적인 통합은 다음 값을 저장합니다.

값	저장 위치	중요한 이유
`projectId`	백엔드 구성 또는 데이터베이스	하나의 SaaS 프로젝트를 식별합니다.
`providerConfigId`	백엔드 구성 또는 데이터베이스	프로젝트 내의 제공자 구성을 식별합니다. 런타임 호출은 이를 선호해야 합니다.
`projectApiKey`	백엔드 비밀 관리자	Connector 런타임 호출을 인증합니다. 평문 키는 한 번만 반환됩니다.
`userId`	제품 데이터베이스	제품의 최종 사용자 ID입니다. Connector는 이를 `externalUserId`로 저장합니다.
`connectedAccountId` 또는 `alias`	제품 데이터베이스	작업 실행 시 최종 사용자의 연결된 계정을 선택합니다.

사용자가 여러 Gmail 계정을 연결할 수 있는 경우, 각 계정의 connectedAccountId 또는 alias를 저장하여 런타임 호출이 기본 “최신 계정” 선택에 의존하지 않도록 합니다.

1단계: 프로젝트 생성

프로젝트는 SaaS 통합의 격리 경계입니다. 제공자 구성, API 키, 연결된 계정, 실행 로그 및 사용량을 격리합니다.

OOMOL Console에서:

메인 패널에 프로젝트 생성 항목이 있는 OOMOL Console 프로젝트 페이지

왼쪽 사이드바에서 Projects를 엽니다.
Create project를 클릭합니다.
프로젝트 이름을 입력합니다.
생성 후 프로젝트를 열고 프로젝트 ID를 PROJECT_ID로 저장합니다.

프로젝트 이름 입력란과 생성 버튼이 있는 프로젝트 생성 대화상자

프로젝트 페이지에는 Provider configs, API Keys, Connected accounts, Execution logs, Usage와 같은 항목이 있습니다. 나머지 설정은 이 프로젝트 내에서 이루어집니다.

프로젝트 이름은 OAuth 권한 부여 진입 페이지에 표시됩니다. 프로덕션 통합은 최종 사용자가 인식할 수 있는 제품 이름을 사용하여 권한 부여 대상을 명확하게 해야 합니다.

2단계: 제공자 구성 생성

제공자 구성은 이 프로젝트가 하나의 Connector 서비스에 연결하는 방법을 정의합니다. 런타임 요청은 이를 providerConfigId로 전달합니다. Gmail OAuth의 경우:

프로바이더 구성 생성 버튼이 있는 프로젝트 프로바이더 구성 페이지

프로젝트 사이드바에서 Provider configs를 엽니다.
Create provider config를 클릭합니다.
다음 필드를 선택하거나 입력합니다.
Create를 클릭합니다.

서비스, 인증 유형, 구성 식별자, 표시 이름 및 클라이언트 구성 소스 필드가 있는 프로바이더 구성 생성 대화상자

필드	Gmail 예시	참고
Service	`Gmail`	연결할 Connector 서비스입니다.
Auth type	`OAuth2`	Gmail은 OAuth2 권한 부여를 사용합니다.
Config slug	`gmail`	백엔드가 이 구성에 사용하는 읽기 쉬운 식별자입니다. 같은 프로젝트에 한 서비스에 대한 구성이 여러 개 있는 경우 `gmail-work` 또는 `gmail-personal`과 같은 이름을 사용합니다.
Display name	`Gmail`	권한 부여 진입 페이지에서 최종 사용자에게 표시되는 이름입니다.
Client config source	`System Client`	OOMOL에서 제공하는 OAuth 클라이언트를 사용합니다.

생성 후 제공자 구성 ID를 PROVIDER_CONFIG_ID로 저장합니다. 백엔드는 권한 부여 링크를 생성하고 작업을 실행할 때 이를 명시적으로 전달해야 합니다.

각 SaaS 프로젝트가 자체 OAuth 클라이언트를 사용하는 경우 Client config source를 사용자 지정 클라이언트로 변경하고 일치하는 clientId와(과) clientSecret를 제공합니다.

사용자 지정 OAuth 클라이언트를 사용하는 경우 제공자 콘솔에서 Connector 콜백 URL을 구성합니다. OOMOL Console 또는 배포 구성에서 이 관리자용 URL을 제공합니다.

API 키 서비스의 경우 일치하는 API 키 인증 유형을 선택합니다. 최종 사용자가 계정을 연결하면 백엔드에서 사용자의 제공자 API 키를 Connector로 보내 저장합니다.

3단계: 프로젝트 API 키 생성

프로젝트 API 키는 백엔드 비밀 저장소에 보관하고 신뢰할 수 있는 서버 코드에서만 사용합니다.

프로젝트 페이지에서:

프로젝트 사이드바에서 API Keys를 엽니다.
Create API Key를 클릭합니다.
키 이름을 입력합니다. 교체와 문제 해결이 쉬운 이름을 사용하세요. 예: production server key 또는 staging server key.
Create를 클릭합니다.
일회성 대화 상자에서 평문 키를 복사하여 PROJECT_API_KEY로 저장합니다.

전체 키를 다시 볼 수 없다는 안내가 있는 일회성 키 대화상자

평문 키는 한 번만 반환됩니다. 이후 목록에는 키 접두사, 생성 시간, 최근 사용 시간 및 유사한 메타데이터만 표시됩니다. 키가 유출된 경우 Console에서 키를 취소하고 새로 생성하세요.

4단계: 최종 사용자가 계정을 연결하도록 허용

이제 제품 런타임 흐름으로 이동합니다. 제품에 ID가 customer-1인 사용자가 있고 Gmail을 연결하려 한다고 가정합니다.

백엔드에서 OAuth 권한 부여 링크를 생성합니다.

CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "alias": "work",
    "returnUri": "https://app.example/connector/callback"
  }'

응답에는 data.id와(과) data.authorizationUrl가 포함됩니다. 최종 사용자를 리디렉션하기 전에 data.id를 예상 프로젝트, 제공자 구성 및 제품 사용자와 함께 신뢰할 수 있는 백엔드에 저장합니다. 그런 다음 사용자를 Connector가 소유한 data.authorizationUrl로 리디렉션합니다.

해당 페이지는 프로젝트 표시 제목, 프로젝트 아이콘 및 제공자 구성 표시 이름을 잠시 보여준 다음 실제 제공자 OAuth 페이지로 리디렉션합니다. 사용자가 권한을 부여하면 제공자가 Connector로 콜백하고, Connector는 제공한 returnUri로 리디렉션합니다.

성공하면 returnUri는 다음과 같은 쿼리 매개변수를 받습니다.

status=success
service=gmail
providerConfigId=pc-1
externalUserId=customer-1
connectedAccountId=ca-1

이 쿼리 매개변수는 탐색 피드백으로만 취급하세요. 브라우저가 제공한 connectedAccountId를 계정 바인딩으로 사용하지 마세요. 프로젝트 API 키를 사용하여 백엔드에서 저장된 연결 요청을 쿼리하세요. API 경로는 connection-requests 이름을 유지합니다.

curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \
  -H "authorization: Bearer $PROJECT_API_KEY"

응답의 data.connectedAccountId는 data.status가 connected이고 해당 projectId, providerConfigId, externalUserId이(가) 백엔드가 해당 요청에 대해 저장한 값과 일치할 때만 유지하세요. failed와(과) expired는 계정 바인딩을 생성하지 않고 최종 상태로 처리하세요.

사용자가 취소하거나 제공자가 오류를 반환하면 returnUri는 다음을 받습니다.

status=error
code=<connector-error-code>
message=<human-readable-message>

returnUri는 http 또는 https를 사용해야 합니다. OAuth 링크는 기본적으로 10분 후에 만료됩니다.

5단계: 작업 실행

계정이 연결되면 백엔드는 저장된 계정 선택기를 사용하여 작업을 실행할 수 있습니다.

curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -H "x-request-id: req-saas-action-1" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "connectedAccountId": "ca-1",
    "input": {
      "to": "someone@example.com",
      "subject": "Hello",
      "body": "Hello from My SaaS"
    }
  }'

규칙:

providerConfigId 또는 service 중 정확히 하나를 전달하세요. 프로덕션 통합은 providerConfigId를 선호해야 합니다.
connectedAccountId 또는 alias 중 최대 하나를 전달하세요. 프로덕션 통합은 그중 하나를 명시적으로 전달해야 합니다.
계정 선택기가 없으면 Connector는 동일한 projectId + providerConfigId + userId 아래에서 최신 활성 연결 계정을 선택합니다.
작업 ID의 서비스 접두사는 제공자 구성 서비스와 일치해야 합니다. 예를 들어 gmail.send_email는 Gmail 제공자 구성을 사용해야 합니다.

성공 응답에는 executionId, actionId 및 작업 출력이 포함됩니다. 지원 및 문제 해결을 위해 자체 운영 로그에 executionId를 저장하세요.

6단계: 사용자 연결 관리

제품은 일반적으로 사용자에게 어떤 계정이 연결되어 있는지 보여줘야 합니다. 권장 접근 방식은 성공적인 콜백 후 제품 데이터베이스에 connectedAccountId, alias, service, providerConfigId 및 자체 userId를 저장한 다음 해당 데이터에서 계정 목록을 렌더링하는 것입니다.

Connector 측 상태를 확인하려면 OOMOL Console에서 Connected accounts를 사용하여 현재 프로젝트 아래의 연결된 계정을 확인하세요.

available 필드는 계정이 현재 작업을 실행할 수 있는지 여부를 나타냅니다. 제공자 구성이 활성 상태이고, 연결된 계정이 활성 상태이며, 기본 앱이 활성 상태이고, 자격 증명이 존재할 때만 true입니다.

제품에서 사용자가 계정 이름을 바꿀 수 있는 경우 먼저 제품 데이터베이스에서 표시 이름을 업데이트하세요. 관리자가 Connector 측 상태를 확인해야 하는 경우 Console을 사용하여 일치하는 계정을 검사하세요.

사용자가 계정 연결을 해제하면 제품 백엔드에서 연결 해제 흐름을 실행하고 제품 데이터베이스를 업데이트하도록 하세요. 관리자는 Console을 사용하여 계정을 계속 사용할 수 있는지 확인할 수 있습니다.

연결 해제는 연결된 계정 레코드를 유지하지만 기본 자격 증명을 제거합니다. 기록 로그는 여전히 해당 계정을 참조할 수 있지만 향후 작업에서는 사용할 수 없습니다.

7단계: 문제 해결 및 운영

사용자의 작업을 문제 해결할 때 OOMOL Console에서 Execution logs를 엽니다. 일반적인 필터로는 providerConfigId, userId, appId, status=success|error, action가 있습니다.

문제 해결 시 먼저 서비스 또는 제공자 구성별로 보기를 좁히세요. 운영 로그에 executionId를 저장하는 경우 이를 사용하여 제품 측 작업 하나를 Connector 측 로그와 연결하세요.

운영의 경우 Usage를 사용하여 일일 사용량 추세와 서비스별로 그룹화된 사용량을 검토하세요. 일반적인 기간은 7일, 30일 또는 90일입니다.

days는 7, 30 또는 90만 지원합니다.

백엔드가 런타임에 호출하는 항목

이 가이드의 Gmail OAuth 흐름에서 백엔드는 세 가지 작업을 처리합니다.

권한 부여 링크를 생성하고 사용자를 Connector 권한 부여 진입점으로 보냅니다.
콜백 후 권한 부여 요청을 확인한 다음 connectedAccountId를 저장합니다.
사용자가 제품 기능을 트리거할 때 저장된 계정으로 작업을 실행합니다.

프로젝트 생성, 제공자 구성 생성, 프로젝트 API 키 생성, 연결된 계정 검토, 실행 로그 읽기, 사용량 확인과 같은 설정 및 운영에는 OOMOL Console을 선호하세요.

문제 해결

계정 연결 또는 작업 실행이 실패하면 다음 순서로 확인하세요.

백엔드가 현재 프로젝트의 PROJECT_API_KEY를 사용하고 있으며 이를 백엔드 비밀 저장소에 보관하고 있는지 확인합니다.
요청이 생성한 제공자 구성의 providerConfigId를 사용하는지 확인합니다.
동일한 사용자의 각 계정에 고유한 alias가 있는지 확인합니다.
Console에서 Connected accounts를 열고 계정을 계속 사용할 수 있는지 확인합니다.
Console에서 Execution logs를 열고 제공자 구성, 사용자 ID 또는 executionId로 필터링합니다.