---
title: SaaS용 Connector 가이드
description: SaaS 제품이 최종 사용자의 타사 계정을 연결하고 백엔드에서 Connector 작업을 실행하도록 합니다.
lang: ko
canonical_url: https://oomol.com/ko/docs/connector-saas/
markdown_url: https://oomol.com/ko/docs/connector-saas.md
---

# 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 키가 포함됩니다.

```http
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 프로젝트 페이지](/img/docs/connector-saas/en/project-list.png)

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

![프로젝트 이름 입력란과 생성 버튼이 있는 프로젝트 생성 대화상자](/img/docs/connector-saas/en/create-project-dialog.png)

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

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

## 2단계: 제공자 구성 생성

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

![프로바이더 구성 생성 버튼이 있는 프로젝트 프로바이더 구성 페이지](/img/docs/connector-saas/en/service-configs-page.png)

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

![서비스, 인증 유형, 구성 식별자, 표시 이름 및 클라이언트 구성 소스 필드가 있는 프로바이더 구성 생성 대화상자](/img/docs/connector-saas/en/create-service-config-dialog.png)

| 필드 | 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 키는 백엔드 비밀 저장소에 보관하고 신뢰할 수 있는 서버 코드에서만 사용합니다.

프로젝트 페이지에서:

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

![전체 키를 다시 볼 수 없다는 안내가 있는 일회성 키 대화상자](/img/docs/connector-saas/en/api-key-once-dialog.png)

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

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

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

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

```bash
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`는 다음과 같은 쿼리 매개변수를 받습니다.

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

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

```bash
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`는 다음을 받습니다.

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

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

## 5단계: 작업 실행

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

```bash
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을 선호하세요.

## 문제 해결

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

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