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는 이 오리진에서 파생됩니다.

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을 구성하세요:

<openconnector-origin>/oauth/callback

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

http://localhost:3000/oauth/callback

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

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 웹 콘솔을 사용하세요:

http://localhost:3000와 같은 OpenConnector 웹 콘솔을 여세요.
Providers를 열고 연결하려는 프로바이더를 선택하세요.
Configure OAuth Client 또는 Edit OAuth Client를 선택하세요.
프로바이더 앱의 Client ID와 Client Secret을 붙여넣으세요.
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	웹 애플리케이션 OAuth 클라이언트를 사용하세요. 정확한 OpenConnector 리디렉션 URI를 승인된 리디렉션 URI에 추가하세요. 민감하거나 제한된 스코프는 광범위한 프로덕션 사용 전에 Google 검증이 필요할 수 있습니다.
Slack	Installing with OAuth	정확한 OpenConnector 리디렉션 URI를 앱의 리디렉션 URL에 추가하세요. Slack이 로컬 콜백 URL을 허용하지 않으면 공개 런타임 오리진 또는 HTTPS 터널을 사용하세요.
GitHub	Creating an OAuth app	GitHub OAuth 앱에는 하나의 인증 콜백 URL이 있습니다. 로컬, 스테이징 및 프로덕션 콜백 URL을 별도로 사용해야 하는 경우 별도의 앱을 만드세요.
Microsoft	Register an application with the Microsoft identity platform	웹 플랫폼 리디렉션 URI를 구성하고 클라이언트 시크릿을 만드세요. 일부 OpenConnector Microsoft 프로바이더는 `common`, `organizations` 또는 테넌트 ID와 같은 `tenant` 값이 필요합니다.
HubSpot	Working with OAuth	인증 요청의 스코프는 앱에 구성된 스코프와 일치해야 합니다. 프로덕션 리디렉션 URL은 HTTPS를 사용해야 하며, localhost는 테스트용으로 HTTP를 사용할 수 있습니다.
Notion	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 연결을 제거하세요.