---
title: OpenConnector OAuth 앱 설정 가이드
description: 프로바이더 OAuth 앱을 만들고 리디렉션 URI를 구성한 뒤 자체 호스팅 OOMOL OpenConnector 런타임에 연결하세요.
lang: ko
canonical_url: https://oomol.com/ko/docs/openconnector-oauth-apps/
markdown_url: https://oomol.com/ko/docs/openconnector-oauth-apps.md
---

# OpenConnector OAuth 앱 설정 가이드

OOMOL OpenConnector는 OAuth2 프로바이더가 사용자 인증을 필요로 할 때 사용자의 자체 프로바이더 OAuth 앱을 사용합니다. 프로바이더의 개발자 콘솔에서 앱을 만들고, OpenConnector 런타임에서 정확한 콜백 URL을 복사하여 해당 앱에 입력한 다음, 앱의 클라이언트 구성을 OpenConnector에 저장하세요.

이 가이드는 Gmail, Google Drive, Google Calendar, Slack, HubSpot, GitHub, Microsoft Outlook, Notion, Zoom, Zendesk, Jira, Dropbox 및 OpenConnector 프로바이더 카탈로그에 표시되는 기타 OAuth 프로바이더와 같은 OAuth2 프로바이더에 사용하세요.

이 가이드는 OAuth 앱 설정을 다룹니다. 다른 인증 유형을 사용하는 프로바이더의 경우 OpenConnector 프로바이더 페이지에 표시된 자격 증명 필드를 사용하세요.

## 필요한 사항

- 실행 중인 OOMOL OpenConnector 런타임.
- OpenConnector 웹 콘솔에 대한 접근 권한.
- `OOMOL_CONNECT_ADMIN_TOKEN`이 설정된 경우 관리자 토큰.
- 프로바이더의 개발자 또는 관리자 콘솔에서 OAuth 앱을 만들 수 있는 권한.
- 연결하려는 프로바이더 워크스페이스, 테넌트, 조직 또는 포털의 테스트 계정.

런타임이 공개 도메인, 터널 또는 Cloudflare Worker URL을 통해 접근 가능한 경우, 프로바이더 OAuth 앱을 만들기 전에 `OOMOL_CONNECT_ORIGIN`을 설정하세요. 리디렉션 URI는 이 오리진에서 파생됩니다.

```bash
OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build
```

## 1단계: OpenConnector 콜백 URL 설정

브라우저에서 사용자가 여는 오리진에서 콜백 URL을 구성하세요:

```text
<openconnector-origin>/oauth/callback
```

기본 로컬 런타임을 사용하는 경우 다음을 사용하세요:

```text
http://localhost:3000/oauth/callback
```

`OOMOL_CONNECT_ORIGIN`이 공개 오리진으로 설정된 경우 콜백 URL은 해당 오리진을 사용합니다:

```text
https://connect.example.com/oauth/callback
```

프로바이더 OAuth 앱에 이 정확한 콜백 URL을 입력하세요. OpenConnector 오리진 자체에 슬래시가 포함되어 있지 않는 한 끝에 슬래시를 추가하지 마세요.

## 2단계: 프로바이더 OAuth 앱 만들기

프로바이더의 개발자 콘솔을 열고 OAuth 앱, 통합, 연결된 앱, 공개 앱 또는 애플리케이션 등록을 만드세요. 프로바이더마다 명칭은 다르지만 필요한 필드는 대개 동일합니다.

| 프로바이더 앱 필드 | 입력할 내용 |
| --- | --- |
| 앱 이름 | `OpenConnector Local` 또는 내부 도구 이름과 같이 알아볼 수 있는 이름. |
| 홈페이지 또는 웹사이트 URL | 제품, 내부 도구, 저장소 또는 런타임 URL. 사용자와 관리자가 알아볼 수 있는 값을 사용하세요. |
| 리디렉션 URI, 콜백 URL 또는 회신 URL | `https://connect.example.com/oauth/callback`과 같은 정확한 OpenConnector 콜백 URL. |
| 스코프 또는 권한 | OpenConnector 프로바이더에 필요한 스코프. 프로바이더 페이지 또는 프로바이더 액션 가이드에서 복사하세요. |
| 배포, 설치 또는 가시성 | 프로바이더가 허용하고 자체 계정만 필요한 경우 앱을 비공개, 테스트 전용, 내부 또는 비공개로 유지하세요. |

많은 프로바이더는 마켓플레이스 등록 전에 자체 계정, 테스트 사용자, 워크스페이스 또는 조직을 인증할 수 있게 합니다. 일부 프로바이더는 민감한 스코프, 프로덕션 사용, 광범위한 고객 배포 또는 관리형 워크스페이스에 대해 검증, 관리자 승인 또는 검토를 요구합니다. 프로바이더의 인증 화면과 관리자 콘솔이 기준입니다.

## 3단계: 클라이언트 구성 복사

프로바이더 앱을 만든 후 OpenConnector에 필요한 클라이언트 값을 복사하세요.

| 값 | 필수 여부 | 비고 |
| --- | --- | --- |
| `clientId` | 예 | 일반적으로 Client ID, App ID, Application ID 또는 Consumer Key라고 합니다. |
| `clientSecret` | 대개 | 일부 프로바이더는 퍼블릭 클라이언트 흐름을 사용하며 시크릿이 필요하지 않습니다. OpenConnector가 프로바이더 시크릿을 선택 사항으로 표시하는 경우, 프로바이더도 선택 사항으로 취급할 때만 비워 두세요. |
| 추가 필드 | 때때로 | 일부 프로바이더는 `tenant`, `subdomain`, `developerToken` 또는 계정별 식별자와 같은 추가 OAuth 클라이언트 구성이 필요합니다. 해당 프로바이더에 필요한 필드를 노출하는 콘솔 버전을 사용하세요. |

OAuth 클라이언트 시크릿을 브라우저 코드, 공개 저장소, 스크린샷, 이슈 보고서 또는 에이전트 프롬프트에 넣지 마세요.

## 4단계: OpenConnector에 OAuth 클라이언트 저장

일반적인 설정 경로에는 OpenConnector 웹 콘솔을 사용하세요:

1. `http://localhost:3000`와 같은 OpenConnector 웹 콘솔을 여세요.
2. **Providers**를 열고 연결하려는 프로바이더를 선택하세요.
3. **Configure OAuth Client** 또는 **Edit OAuth Client**를 선택하세요.
4. 프로바이더 앱의 **Client ID**와 **Client Secret**을 붙여넣으세요.
5. **Save OAuth Client**를 선택하세요.

프로바이더에 추가 클라이언트 필드가 필요하면 동일한 OAuth 클라이언트 양식에 입력하세요. 예를 들어 Microsoft 프로바이더에는 `tenant` 값이 필요합니다. 콘솔에 프로바이더가 요구하는 필드가 표시되지 않으면 계속하기 전에 해당 프로바이더의 전체 OAuth 클라이언트 양식을 지원하는 OpenConnector 버전으로 업그레이드하세요.

저장 후 프로바이더 페이지에는 OAuth 클라이언트가 구성된 것으로 표시되고 클라이언트 시크릿은 숨겨진 상태로 유지됩니다.

## 5단계: 테스트 계정 연결

OAuth 클라이언트를 저장한 후 프로바이더 페이지에 머물면서 **Connect**를 선택하여 인증을 시작하세요. 프로바이더 인증 화면을 승인하세요. 프로바이더가 OpenConnector로 다시 리디렉션한 후 프로바이더 페이지에 계정이 연결된 것으로 표시되는지 확인하세요.

## 6단계: 액션 테스트

프로바이더 페이지 또는 콘솔 액션 목록을 사용하여 연결한 프로바이더에 대해 위험도가 낮은 읽기 액션을 실행하세요. 액션 세부 정보에는 입력 스키마, 필요한 스코프 및 현재 연결 ID가 표시됩니다.

쓰기 액션을 테스트할 때는 데모 데이터를 사용하세요.

## 프로바이더 참고 사항

다음 프로바이더 문서는 OAuth 앱을 만들 때 유용합니다:

| 프로바이더 계열 | 공식 문서 | 일반적인 설정 참고 사항 |
| --- | --- | --- |
| Google APIs | [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server) | 웹 애플리케이션 OAuth 클라이언트를 사용하세요. 정확한 OpenConnector 리디렉션 URI를 승인된 리디렉션 URI에 추가하세요. 민감하거나 제한된 스코프는 광범위한 프로덕션 사용 전에 Google 검증이 필요할 수 있습니다. |
| Slack | [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth) | 정확한 OpenConnector 리디렉션 URI를 앱의 리디렉션 URL에 추가하세요. Slack이 로컬 콜백 URL을 허용하지 않으면 공개 런타임 오리진 또는 HTTPS 터널을 사용하세요. |
| GitHub | [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) | GitHub OAuth 앱에는 하나의 인증 콜백 URL이 있습니다. 로컬, 스테이징 및 프로덕션 콜백 URL을 별도로 사용해야 하는 경우 별도의 앱을 만드세요. |
| Microsoft | [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2) | 웹 플랫폼 리디렉션 URI를 구성하고 클라이언트 시크릿을 만드세요. 일부 OpenConnector Microsoft 프로바이더는 `common`, `organizations` 또는 테넌트 ID와 같은 `tenant` 값이 필요합니다. |
| HubSpot | [Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) | 인증 요청의 스코프는 앱에 구성된 스코프와 일치해야 합니다. 프로덕션 리디렉션 URL은 HTTPS를 사용해야 하며, localhost는 테스트용으로 HTTP를 사용할 수 있습니다. |
| Notion | [Authorization](https://developers.notion.com/guides/get-started/authorization) | 공개 연결을 만들고 OAuth 구성 아래에 OpenConnector 리디렉션 URI를 추가하세요. 자체 워크스페이스 외부에서 앱을 사용하기 전에 Notion의 현재 앱 유형 및 기능 규칙을 검토하세요. |

## 문제 해결

| 증상 | 확인할 사항 |
| --- | --- |
| 프로바이더가 `redirect_uri_mismatch`, 잘못된 리디렉션 URI 또는 잘못된 콜백 URL이라고 말합니다. | 프로바이더 앱이 `<openconnector-origin>/oauth/callback`을 사용하는지 확인하세요. 스킴, 호스트, 포트, 경로 및 끝 슬래시가 브라우저에서 사용자가 여는 오리진과 일치해야 합니다. |
| 프로바이더가 `http://localhost`을 거부합니다. | 테스트용으로 localhost를 지원하는 프로바이더를 사용하거나, HTTPS 터널 또는 공개 도메인을 통해 런타임을 노출하고 OpenConnector를 다시 시작하기 전에 `OOMOL_CONNECT_ORIGIN`을 해당 오리진으로 설정하세요. |
| 프로바이더가 앱이 검증되지 않았거나, 승인되지 않았거나, 워크스페이스에서 허용되지 않는다고 말합니다. | 프로바이더 측 앱 배포, 테스트 사용자, 워크스페이스 앱 승인 및 민감한 스코프 검토 요구 사항을 확인하세요. 마켓플레이스 등록은 비공개 테스트와 별개인 경우가 많지만 프로바이더 규칙은 다양합니다. |
| 인증은 성공하지만 누락되거나 불충분한 스코프로 인해 액션이 실패합니다. | 액션에 필요한 스코프를 프로바이더 앱에 추가하고, 앱을 저장한 뒤, 프로바이더 계정을 다시 연결하여 새 스코프가 부여되도록 하세요. |
| OpenConnector가 `oauth_client_config_not_found`라고 말합니다. | **Connect**를 시작하는 동일한 프로바이더 페이지에서 OAuth 클라이언트를 저장하세요. |
| 나중에 토큰 갱신이 실패합니다. | 프로바이더가 리프레시 토큰을 발급했는지 확인하세요. 일부 프로바이더는 오프라인 액세스 매개변수 또는 재동의가 필요합니다. 리프레시 토큰을 사용할 수 없으면 계정을 다시 연결하세요. |
| 실행 중에 잘못된 계정이 사용됩니다. | 의도한 계정으로 로그인된 브라우저 프로필에서 다시 연결한 다음, 액션을 테스트하기 전에 콘솔에서 의도한 연결을 선택하세요. |

## 보안 체크리스트

- OAuth 클라이언트 시크릿 또는 연결된 계정 자격 증명을 저장하기 전에 `OOMOL_CONNECT_ENCRYPTION_KEY`을 설정하세요.
- `OOMOL_CONNECT_ADMIN_TOKEN`을 비공개로 유지하고 `/v1` 및 `/mcp` 호출자에는 런타임 토큰을 사용하세요.
- 프로바이더와 OpenConnector 액션 집합이 허용하는 경우 최소 권한 스코프를 사용하세요.
- 프로바이더 콜백 규칙이 감사를 더 간단하게 만드는 경우 로컬, 스테이징 및 프로덕션용 OAuth 앱을 별도로 유지하세요.
- 사용하지 않는 프로바이더 앱, 이전 클라이언트 시크릿 및 오래된 OpenConnector 연결을 제거하세요.