커넥터 데이터 구조

소개

커넥터란 무엇인가요?

커넥터는 Logto에서 중요한 역할을 합니다. 이를 통해 Logto는 최종 사용자가 비밀번호 없이 등록하거나 로그인하고, 소셜 계정으로 로그인할 수 있는 기능을 제공합니다. 웹사이트와 애플리케이션의 인기가 증가함에 따라, 비밀번호 없는 로그인과 소셜 로그인을 통해 사용자는 수많은 계정과 비밀번호를 관리하는 것을 피할 수 있습니다.

기존 커넥터를 설정하려면 커넥터 가이드를 따르세요. 설정하려는 커넥터를 찾을 수 없는 경우, 커넥터 개발 가이드를 따라 커넥터를 개발할 수 있습니다.

구성 요소

커넥터 데이터에는 많은 속성이 있습니다.

데이터 로딩 및 업데이트를 더 효율적으로 만들기 위해, 자주 수정될 부분의 커넥터 데이터를 DB에 저장하고 나머지는 로컬에 저장합니다.

• 로컬 저장소, ConnectorMetadata라고도 하며, 로고, 커넥터 유형 등과 같은 고정 속성을 포함하는 객체입니다. (:face_with_monocle: 이러한 속성을 이해하는 데 어려움이 있나요? 걱정하지 마세요, 자세한 설명이 이어집니다!)
• 원격 저장소는 이러한 데이터의 상대적으로 빈번한 변경을 위해 DB에 저장됩니다.

커넥터의 로컬 저장소: ConnectorMetadata {#connectors-local-storage-connectormetadata}

id

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

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

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

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

Logto 사용자는 이 변수를 "아이덴티티 제공자 이름"으로 간주할 수 있습니다.

예를 들어, Google 계정으로 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에 로그인하면 항상 별도의 Logto 계정이 생성됩니다 - 사용자가 동일한 GitHub 계정을 사용하더라도.	사용자 풀을 분할하는 것이 두 커넥터를 모두 사용해야 하는 유일한 시나리오입니다. 그러나 일반적으로 이 사용 사례를 처리하기 위해 두 개의 별도 테넌트를 생성하는 것이 최선의 방법으로 간주됩니다.
동일한 IdP 및 동일한 target	1. GitHub 커넥터 (target: github) 2. OAuth GitHub 커넥터 (target: github)	N/A	이 두 커넥터 중 하나를 사용하면 동일한 결과가 나올 수 있습니다.	동일한 작업을 수행하는 두 개의 커넥터를 만드는 것은 최종 사용자에게 혼란을 줄 수 있으며 큰 의미가 없습니다. 특정 사용 사례에 맞는 하나의 커넥터를 사용하는 것이 좋습니다.

type

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

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

• 소셜: 최종 사용자의 인가를 통해 임의의 제3자 소셜 미디어에서 사용자 정보를 액세스할 수 있는 커넥터.
• SMS: 최종 사용자가 휴대폰으로 문자 메시지를 받을 수 있도록 하는 커넥터.
• 이메일: 최종 사용자에게 이메일을 보낼 수 있도록 도와주는 커넥터.

platform

platform은 커넥터가 구축된 플랫폼을 식별하는 데 사용됩니다.

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

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

노트:

이메일 커넥터와 SMS 커넥터의 platform은 항상 null이어야 합니다.
오직 소셜 커넥터만이 NULL이 아닌 platform 값을 가질 수 있습니다.

name

name은 i18n 국가 코드를 키로 하고 커넥터의 표시 이름을 값으로 하는 객체입니다.

description

description도 i18n 국가 코드를 키로 하고 커넥터의 간단한 설명을 값으로 하는 객체입니다.

노트:

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

logo

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

logoDark

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

노트:

logo는 항상 필요하며, logoDark는 선택 사항입니다.

light 모드에서는 _logo를 표시하고, dark 모드에서는 _logoDark가 존재할 경우 logoDark를 표시합니다. 그렇지 않으면 dark 모드에서도 _logo를 표시합니다.

isStandard

isStandard는 소셜 커넥터가 "표준" 커넥터인지 식별하기 위한 선택적 불리언 속성입니다. isStandard 속성이 참인 경우 "표준" 커넥터로 식별할 수 있습니다.

노트:

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

Logto는 개방적이고 표준화된 프로토콜 (예: OAuth, OIDC, SAML 등)을 기반으로 구축된 커넥터를 "표준" 커넥터라고 부릅니다. Logto의 사용자는 이 컨텍스트를 기반으로 각 표준 커넥터에 여러 인스턴스를 구성할 것으로 예상됩니다. 예를 들어, Logto가 이미 OAuth 표준 커넥터를 제공한 경우, 사용자는 "OAuth GitHub 커넥터", "OAuth Google 커넥터" 및 "OAuth Facebook 커넥터" 인스턴스를 구축할 수 있습니다. 이들은 모두 Logto OAuth 표준 커넥터를 기반으로 합니다.

Logto의 커넥터 설계에 익숙하다면, 동시에 존재할 수 있는 이메일 또는 SMS 커넥터는 최대 하나뿐이며, 이는 Logto가 현재 단계에서 "표준" 이메일 또는 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에서 커넥터가 생성된 시간을 추적하기 위한 자동 생성된 타임스탬프 문자열입니다.