본문으로 건너뛰기

소셜 커넥터 개발 단계별 가이드

가장 빠르게 시작하는 방법은 기존 공식 커넥터의 코드를 복사하여 필요에 맞게 수정하는 것입니다. 예시로 GitHub 커넥터를 살펴보겠습니다.

1단계: 기존 커넥터 패키지 복제하기​

커넥터 소스 폴더에는 다음과 같은 파일들이 있습니다:

  • index.ts: 커넥터의 메인 엔트리 파일.
  • constant.ts: 커넥터에서 사용하는 상수들.
  • types.ts: 커넥터에서 사용하는 TypeScript 타입들.
  • index.test.ts: 커넥터의 테스트 케이스.
  • mock.ts: 커넥터 테스트 케이스에서 사용하는 목 데이터.

이 파일들 외에도, 커넥터를 설명하는 README.md 파일, logo.svg (더 나은 다크 모드 경험을 위해 선택적으로 logo-dark.svg), 그리고 npm 패키지 정보를 정의하는 package.json 파일을 제공해야 합니다.

2단계: 메인 엔트리 파일(index.ts) 수정하기​

index.ts 파일에는 대부분의 커넥터 로직이 들어 있습니다. 일반적으로 구현해야 할 4가지 함수가 있습니다:

  • getAuthorizationUri: 서드파티 소셜 플랫폼의 인가 (Authorization) URI를 생성합니다. GitHub의 경우: https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}. 올바른 URI는 대상 소셜 플랫폼의 개발자 문서를 참고하세요.
  • authorizationCallbackHandler: 인가 콜백 URI에서 반환된 파라미터 값을 보호하고, 인가 code를 추출하며, 발생할 수 있는 오류를 처리합니다.
  • getAccessToken: 인가 code를 액세스 토큰 (Access token)으로 교환합니다.
  • getUserInfo: 액세스 토큰 (Access token)으로 서드파티 소셜 플랫폼에서 사용자 정보를 가져옵니다.

기타 공통 로직 대부분은 Logto 커넥터 킷에서 처리하므로 작업이 더 쉬워집니다.

마지막으로, 파일 끝에서는 GitHub 커넥터와 동일한 코드 구조로 커넥터 객체를 export 하면 됩니다.

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

3단계: 커넥터 테스트하기​

단위 테스트​

먼저, 몇 가지 단위 테스트 케이스를 작성하여 기본 기능이 정상적으로 동작하는지 확인하세요.

로컬 테스트​

  • 로컬 환경에서 Logto를 설정하세요: Logto는 로컬에서 실행할 수 있는 여러 방법을 제공합니다. CLI, docker, 또는 소스 코드에서 직접 빌드할 수 있습니다. 자세한 내용은 문서를 참고하세요.
  • 커스텀 커넥터를 Logto 인스턴스에 연결하세요: CLI를 사용하여 커넥터의 심볼릭 링크를 Logto 인스턴스에 생성합니다. 자세한 내용을 참고하세요. 
    cd logto
    npx @logto/cli connector link -p .
  • 커넥터를 연결한 후, <logto-root-path>/packages/core/connectors 폴더에서 확인할 수 있습니다.
  • Logto 인스턴스를 재시작하고, Logto Admin Console로 이동하면 소셜 커넥터 목록에서 확인할 수 있습니다.

  • Console > Sign-in & account > Sign-up and sign-in

    소셜 로그인에서 커넥터를 설정하세요. 그리고 "Live preview" 기능이 있는 데모 앱에서 직접 시도해 보세요.