커넥터 데이터 구조

소개

커넥터란 무엇인가요?

Logto에서 커넥터는 매우 중요한 역할을 합니다. 커넥터의 도움으로 Logto는 최종 사용자가 비밀번호 없는 회원가입 또는 로그인, 그리고 소셜 계정으로 로그인하는 기능을 사용할 수 있도록 합니다. 웹사이트와 애플리케이션의 인기가 높아짐에 따라, 비밀번호 없는 로그인과 소셜 로그인을 통해 사용자는 수많은 계정과 비밀번호를 관리하는 번거로움을 피할 수 있습니다.

기존 커넥터를 설정하려면 커넥터 가이드를 따라주세요. 원하는 커넥터가 없다면, 커넥터 개발 가이드를 참고하여 직접 개발할 수 있습니다.

구성 요소

커넥터 데이터에는 다양한 속성이 있습니다.

데이터의 로딩 및 업데이트 효율성을 높이기 위해, 자주 변경되는 일부 커넥터 데이터는 DB에 저장하고, 나머지는 로컬에 저장합니다.

• 로컬 저장소는 ConnectorMetadata라고도 하며, 로고, 커넥터 타입 등과 같은 고정 속성을 포함하는 객체입니다. (:face_with_monocle: 이러한 속성이 이해되지 않으시나요? 걱정하지 마세요, 자세한 설명이 이어집니다!)
• 원격 저장소는 해당 데이터가 비교적 자주 변경되기 때문에 DB에 저장됩니다.

커넥터의 로컬 저장소: ConnectorMetadata

id

id는 Logto에서 커넥터를 식별하는 고유한 문자열 타입의 키입니다.

각 커넥터 개발자가 할당하며, DB에 업로드됩니다.

target (아이덴티티 제공자 이름)

target은 소셜 커넥터의 소셜 아이덴티티 소스를 구분하는 소문자 문자열입니다.

Logto 사용자들은 이 변수를 "아이덴티티 제공자 (IdP) 이름"으로 이해할 수 있습니다.

예를 들어, 구글 계정으로 Logto에 로그인한다면 target은 google이어야 합니다. target 값은 임의의 비어 있지 않은 문자열이 될 수 있지만, 변경이 불가능하므로 직관적으로 지정하는 것을 권장합니다. 동일한 target과 플랫폼을 가진 여러 커넥터의 존재는 허용되지 않습니다. 반면, 서로 다른 플랫폼에 대해 동일한 target을 가진 소셜 커넥터를 가질 수 있습니다. 예를 들어, 사용자가 휴대폰에서 WeChat으로 로그인하려면 WeChat의 TOU에 따라 네이티브 WeChat 앱이 필요하며, 동시에 웹 애플리케이션에서 로그인을 가능하게 하려면 웹 WeChat 앱도 필요합니다. 이 두 WeChat 앱은 동일한 아이덴티티 제공자를 공유하므로 동일한 target을 가져야 합니다.

target이 복잡한 개념이기 때문에 다양한 사용 사례와 권장 사항을 정리했습니다.

	예시	시나리오	결과	권장 여부
서로 다른 IdP, 서로 다른 target	1. GitHub 커넥터 (target: github) 2. Google 커넥터 (target: google)	GitHub 및 Google 계정 모두로 로그인을 지원하는 앱.	가장 일반적인 사용 사례.	✅
서로 다른 IdP, 동일한 target	1. GitHub 커넥터 (target: github) 2. Google 커넥터 (target: github)	N/A	다른 사용자의 GitHub 계정으로 생성된 Logto 계정에 로그인할 수 있습니다.	❌
동일한 IdP, 서로 다른 target	1. GitHub 커넥터 (target: github) 2. OAuth GitHub 커넥터 (target: github_oauth)	GitHub 커넥터는 애플리케이션 A에서 사용되고, OAuth GitHub 커넥터는 애플리케이션 B를 위해 별도로 생성됨.	이 두 커넥터로 Logto에 로그인하면, 동일한 GitHub 계정을 사용하더라도 항상 별도의 Logto 계정이 생성됩니다.	사용자 풀을 분리해야 하는 경우에만 두 커넥터를 모두 사용해야 합니다. 그러나 이 경우에는 두 개의 별도 테넌트를 만드는 것이 일반적으로 더 좋은 방법입니다.
동일한 IdP, 동일한 target	1. GitHub 커넥터 (target: github) 2. OAuth GitHub 커넥터 (target: github)	N/A	두 커넥터 중 어느 것을 사용해도 결과는 동일합니다.	본질적으로 동일한 기능을 하는 두 커넥터를 만드는 것은 최종 사용자에게 혼란을 줄 수 있으며, 큰 의미가 없습니다. 특정 사용 사례에 맞는 하나의 커넥터를 사용하는 것이 더 좋습니다.

type

type은 커넥터의 유형을 기록하는 속성입니다.

기능에 따라 커넥터를 세 가지 유형으로 구분합니다:

• 소셜: 최종 사용자의 인가를 받아 임의의 서드파티 소셜 미디어에서 사용자 정보를 가져올 수 있는 커넥터.
• SMS: 최종 사용자가 휴대폰으로 문자 메시지를 받을 수 있도록 하는 커넥터.
• 이메일: 최종 사용자에게 이메일을 보낼 수 있도록 도와주는 커넥터.

platform

platform은 커넥터가 어떤 플랫폼을 위해 만들어졌는지 식별하는 데 사용됩니다.

platform은 null이거나 다음 문자열 값 중 하나여야 합니다:

• 네이티브: 네이티브 모바일 앱에서만 동작하는 커넥터.
• 웹: 데스크톱 웹 애플리케이션에서만 동작하는 커넥터.
• 유니버설: 모바일 웹 앱과 데스크톱 웹 앱 모두에서 동작하는 커넥터.

노트:

이메일 커넥터와 SMS 커넥터의 platform은 항상 null이어야 합니다.
non-NULL platform 값은 소셜 커넥터에만 허용됩니다.

name

name은 키가 i18n 국가 코드이고 값이 커넥터의 표시 이름인 객체입니다.

description

description도 키가 i18n 국가 코드이고 값이 커넥터의 간단한 설명인 객체입니다.

노트:

클라이언트 측에서 i18n 표시를 지원하기 위해, name (및 description) 속성은 국가 코드를 키로, 현지 언어의 이름(또는 설명)을 값으로 하는 맵 형태로 저장합니다.

logo

logo는 커넥터의 로고 URL 또는 상대 경로입니다.

logoDark

logoDark는 다크 모드용 커넥터 로고의 nullable URL 또는 상대 경로입니다.

노트:

logo는 항상 필수이며, logoDark는 선택 사항입니다.

라이트 모드에서는 logo를, 다크 모드에서는 logoDark가 있으면 logoDark를, 없으면 logo를 표시합니다.

isStandard

isStandard는 소셜 커넥터가 "표준" 커넥터인지 식별하는 선택적 불리언 속성입니다. isStandard 속성이 true이면 "표준" 커넥터로 간주할 수 있습니다.

노트:

Logto는 "표준" 소셜 커넥터만 지원합니다. 즉, Logto의 모든 이메일 또는 SMS 커넥터는 "표준"이 아닙니다.

Logto는 개방적이고 표준화된 프로토콜(예: OAuth, OIDC, SAML 등)을 기반으로 구축된 커넥터를 "표준" 커넥터라고 부릅니다. Logto 사용자는 이 맥락에서 각 표준 커넥터에 대해 여러 인스턴스를 생성할 수 있습니다. 예를 들어, Logto가 이미 OAuth 표준 커넥터를 제공한다면, 사용자는 "OAuth GitHub 커넥터", "OAuth Google 커넥터", "OAuth Facebook 커넥터" 인스턴스를 만들 수 있습니다. 이들은 모두 Logto OAuth 표준 커넥터를 기반으로 합니다.

Logto의 커넥터 설계에 익숙하다면, 동시에 최대 하나의 이메일 또는 SMS 커넥터만 존재할 수 있다는 것을 알 수 있습니다. 즉, 현재 단계에서는 "표준" 이메일 또는 SMS 커넥터가 필요하지 않습니다.

readme

readme는 커넥터의 README 마크다운 파일의 상대 경로이며, 커넥터 설정 중 "관리자 콘솔"에 표시됩니다.

configTemplate

configTemplate은 커넥터 설정 예시의 상대 경로입니다.

커넥터의 원격 저장소: Connector DB {#connectors-remote-storage-connector-db}

id

id는 커넥터 DB의 기본 키 역할을 하며, DB에서 커넥터를 식별하는 무작위로 생성된 문자열 타입의 키입니다.

connectorId

connectorId는 문자열 타입의 키이며, Connector DB와 ConnectorMetadata를 연결하는 유일한 다리입니다. 각 매칭되는 커넥터 DB 데이터와 커넥터 코드 모듈 쌍에서 connectorId는 항상 코드 모듈의 metadata.id와 같습니다.

metadata

metadata는 ConnectorMetadata의 하위 집합으로, logo, logoDark, target, name 등 구성 가능한 속성을 포함합니다.

syncProfile

syncProfile은 사용자 프로필 업데이트 방식을 결정하는 불리언 값이며, 기본값은 FALSE입니다.

syncProfile이 FALSE이면, Logto 사용자의 기본 정보(이름 및 아바타 포함)는 사용자가 이 커넥터를 통해 Logto에 처음 가입할 때만 업데이트됩니다. 그렇지 않으면, 사용자가 이 커넥터를 통해 Logto에 로그인할 때마다 Logto 계정 프로필이 업데이트됩니다.

config

config는 임의의 비어 있지 않은 객체일 수 있습니다.

커넥터의 설정 정보를 저장하는 곳입니다. 각 커넥터는 config에 서로 다른 속성을 가지며, DB에 저장되기 전에 유효해야 합니다(커넥터마다 "유효"의 기준이 다름). 유효성 검사를 통과한 config만 DB에 업데이트할 수 있으며, 그렇지 않으면 오류가 발생합니다.

자체 커넥터를 개발할 때는 config 가드를 구현해야 하며, 자세한 내용은 커넥터 개발 가이드를 참고하세요.

config 샘플을 보고 싶으신가요? 커넥터 또는 각 커넥터의 설정 페이지를 방문하세요.

노트:

현재 Logto 버전에서는 동시에 하나의 이메일/SMS 커넥터만 존재할 수 있으며, 동일한 유형의 다른 커넥터는 자동으로 삭제됩니다.

이메일 또는 SMS 커넥터의 유일 동작 규칙은 소셜 커넥터에는 적용되지 않습니다.
즉, 여러 개의 소셜 커넥터를 추가할 수 있습니다.

createdAt

createdAt은 커넥터가 DB에 생성된 시점을 추적하는 자동 생성 타임스탬프 문자열입니다.