사용자 데이터 구조

사용자는 아이덴티티 서비스의 핵심 엔티티입니다. Logto에서는 OpenID Connect 프로토콜을 기반으로 한 기본 인증 (Authentication) 데이터와 사용자 정의 데이터를 포함합니다.

사용자 프로필

각 사용자는 모든 사용자 정보를 포함하는 프로필을 가지고 있습니다.

다음과 같은 유형의 데이터로 구성됩니다:

기본 데이터: 사용자 프로필의 기본 정보입니다. 사용자 ID, 사용자 이름, 이메일, 전화번호, 마지막 로그인 시간 등 소셜 identities 및 custom_data를 제외한 모든 사용자의 속성을 저장합니다.
소셜 아이덴티티: Facebook, GitHub, WeChat과 같은 소셜 커넥터를 통한 소셜 로그인에서 가져온 사용자 정보를 저장합니다.
사용자 정의 데이터: 사용자 선호 색상 및 언어와 같은 사전 정의된 사용자 속성에 나열되지 않은 추가 사용자 정보를 저장합니다.

다음은 Facebook에 로그인하여 가져온 사용자의 데이터 샘플입니다:

{
  "id": "iHXPuSb9eMzt",
  "username": null,
  "primaryEmail": null,
  "primaryPhone": null,
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "customData": {
    "preferences": {
      "language": "en",
      "color": "#f236c9"
    }
  },
  "identities": {
    "facebook": {
      "userId": "106077000000000",
      "details": {
        "id": "106077000000000",
        "name": "John Doe",
        "email": "[email protected]",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

사용자 프로필은 Logto Console 또는 Logto Management API를 사용하여 조회할 수 있습니다. 예를 들어 GET /api/users/:userId.

기본 데이터

사용자의 기본 데이터의 모든 속성을 살펴보겠습니다.

id

id는 Logto에서 사용자를 식별하기 위한 고유하게 자동 생성된 키입니다.

username

username은 username과 비밀번호로 로그인하는 데 사용됩니다.

이 값은 사용자가 처음 등록할 때 입력한 사용자 이름에서 가져옵니다. null일 수 있습니다. null이 아닌 값은 128자를 초과하지 않아야 하며, 문자, 숫자, 밑줄 (_)만 포함해야 하며 숫자로 시작해서는 안 됩니다. 대소문자를 구분합니다.

primary_email

primary_email은 사용자의 이메일 주소로, 이메일과 비밀번호 / 인증 코드로 로그인하는 데 사용됩니다.

이 값은 사용자가 처음 등록할 때 입력한 이메일 주소에서 가져옵니다. null일 수 있습니다. 최대 길이는 128입니다.

primary_phone

primary_phone은 사용자의 전화번호로, 전화번호와 SMS로 받은 비밀번호 / 인증 코드로 로그인하는 데 사용됩니다.

이 값은 사용자가 처음 등록할 때 입력한 전화번호에서 가져옵니다. null일 수 있습니다. null이 아닌 값은 국가 전화 코드로 시작하는 숫자를 포함해야 합니다 (플러스 기호 + 제외).

name

name은 사용자의 전체 이름입니다. 최대 길이는 128입니다.

avatar

avatar는 사용자의 아바타 이미지로 가리키는 URL입니다. 최대 길이는 2048입니다.

사용자가 Google 및 Facebook과 같은 소셜 커넥터로 등록한 경우, 이 값은 소셜 사용자 정보에서 가져올 수 있습니다.

노트:

이 속성은 OpenID Connect 표준의 picture 클레임에 매핑됩니다.

profile

profile은 사용자의 속성에 포함되지 않은 추가 OpenID Connect 표준 클레임을 저장합니다.

그 타입 정의는 이 파일에서 찾을 수 있습니다. 다음은 타입 정의의 복사본입니다:

type UserProfile = Partial<{
  familyName: string;
  givenName: string;
  middleName: string;
  nickname: string;
  preferredUsername: string;
  profile: string;
  website: string;
  gender: string;
  birthdate: string;
  zoneinfo: string;
  locale: string;
  address: Partial<{
    formatted: string;
    streetAddress: string;
    locality: string;
    region: string;
    postalCode: string;
    country: string;
  }>;
}>;

노트:

Partial은 모든 속성이 선택적임을 의미합니다.

다른 표준 클레임과의 차이점은 profile의 속성은 값이 비어 있지 않을 때만 ID 토큰 또는 userinfo 엔드포인트 응답에 포함되며, 다른 표준 클레임은 값이 비어 있으면 null을 반환합니다.

application_id

application_id의 값은 사용자가 처음 로그인한 애플리케이션에서 가져옵니다. null일 수 있습니다.

last_sign_in_at

last_sign_in_at은 사용자가 마지막으로 로그인한 시간대가 포함된 타임스탬프입니다.

created_at

created_at은 사용자가 계정을 등록한 시간대가 포함된 타임스탬프입니다.

updated_at

updated_at은 사용자의 프로필 정보가 마지막으로 업데이트된 시간대가 포함된 타임스탬프입니다.

has_password

has_password는 사용자가 비밀번호를 가지고 있는지를 나타내는 불리언 값입니다. 이 상태는 Console > 사용자 관리의 세부 페이지에서 새 비밀번호 설정 또는 비밀번호 재설정을 포함하여 볼 수 있고 관리할 수 있습니다.

password_encrypted

password_encrypted는 사용자의 암호화된 비밀번호를 저장하는 데 사용됩니다.

이 값은 사용자가 처음 등록할 때 입력한 비밀번호에서 가져옵니다. null일 수 있습니다. 값이 null이 아닌 경우, 암호화 전의 원래 내용은 최소 6자 이상이어야 합니다.

password_encryption_method

password_encryption_method는 사용자의 비밀번호를 암호화하는 데 사용됩니다. 사용자가 사용자 이름과 비밀번호로 등록할 때 초기화됩니다. null일 수 있습니다.

Logto는 기본적으로 Argon2의 구현인 node-argon2를 암호화 방법으로 사용합니다. 자세한 내용은 참조를 확인하세요.

비밀번호가 123456인 사용자의 password_encrypted 및 password_encryption_method 샘플:

{
  "password_encryption_method": "Argon2i",
  "password_encrypted": "$argon2i$v=19$m=4096,t=10,p=1$aZzrqpSX45DOo+9uEW6XVw$O4MdirF0mtuWWWz68eyNAt2u1FzzV3m3g00oIxmEr0U"
}

is_suspended

is_suspended는 사용자가 정지되었는지를 나타내는 불리언 값입니다. 이 값은 Logto Management API를 호출하거나 Logto Console을 사용하여 관리할 수 있습니다.

사용자가 정지되면 사전 부여된 리프레시 토큰이 즉시 취소되며, 사용자는 더 이상 Logto에 의해 인증 (Authentication)될 수 없습니다.

mfa_verification_factors

mfa_verification_factors는 사용자의 계정과 연관된 다단계 인증 (MFA) 방법을 나열하는 배열입니다. 가능한 값은 Totp (인증 앱 OTP), WebAuthn (패스키), BackupCode를 포함합니다.

mfaVerificationFactors: ("Totp" | "WebAuthn" | "BackupCode")[];

identities는 소셜 로그인 (즉, 소셜 커넥터로 로그인)에서 가져온 사용자 정보를 포함합니다. 각 사용자의 identities는 개별 JSON 객체에 저장됩니다.

사용자 정보는 소셜 아이덴티티 제공자 (즉, 소셜 네트워크 플랫폼)에 따라 다르며, 일반적으로 다음을 포함합니다:

아이덴티티 제공자의 target, 예: "facebook" 또는 "google"
이 제공자에 대한 사용자의 고유 식별자
사용자의 이름
사용자의 인증된 이메일
사용자의 아바타

사용자의 계정은 소셜 로그인으로 여러 소셜 아이덴티티 제공자와 연결될 수 있으며, 이러한 제공자로부터 가져온 해당 사용자 정보는 identities 객체에 저장됩니다.

Google과 Facebook으로 로그인한 사용자의 identities 샘플:

{
  "facebook": {
    "userId": "5110888888888888",
    "details": {
      "id": "5110888888888888",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  },
  "google": {
    "userId": "111000000000000000000",
    "details": {
      "id": "111000000000000000000",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  }
}

SSO 아이덴티티

sso_identities는 엔터프라이즈 SSO (즉, 엔터프라이즈 커넥터로 싱글 사인온 (SSO) 로그인)에서 가져온 사용자 정보를 포함합니다. 각 사용자의 ssoIdentities는 개별 JSON 객체에 저장됩니다.

SSO 아이덴티티 제공자로부터 동기화된 데이터는 엔터프라이즈 커넥터에서 요청하도록 구성된 스코프에 따라 다릅니다. 다음은 TypeScript 타입 정의의 복사본입니다:

type SSOIdentity = {
  issuer: string;
  identityId: string;
  detail: JsonObject; // See https://github.com/withtyped/withtyped/blob/master/packages/server/src/types.ts#L12
};

사용자 정의 데이터

custom_data는 사전 정의된 사용자 속성에 나열되지 않은 추가 사용자 정보를 저장합니다.

custom_data를 사용하여 다음 작업을 수행할 수 있습니다:

사용자가 특정 작업을 수행했는지 여부를 기록합니다. 예: 환영 페이지를 본 적이 있는지.
사용자 프로필에 애플리케이션별 데이터를 저장합니다. 예: 애플리케이션별 사용자의 선호 언어 및 외관.
사용자와 관련된 기타 임의의 데이터를 유지합니다.

Logto의 관리자 사용자의 custom_data 샘플:

{
  "adminConsolePreferences": {
    "language": "en",
    "appearanceMode": "system",
    "experienceNoticeConfirmed": true
  },
  "customDataFoo": {
    "foo": "foo"
  },
  "customDataBar": {
    "bar": "bar"
  }
}

각 사용자의 custom_data는 개별 JSON 객체에 저장됩니다.

참고: custom_data에 민감한 데이터를 넣지 마세요.

custom_data가 포함된 사용자 프로필을 Management API를 사용하여 가져와 프론트엔드 앱이나 외부 백엔드 서비스로 보낼 수 있습니다. 따라서 custom_data에 민감한 정보를 넣으면 데이터 유출이 발생할 수 있습니다.

여전히 custom_data에 민감한 정보를 넣고 싶다면, 먼저 암호화할 것을 권장합니다. 신뢰할 수 있는 파티 (예: 백엔드 서비스)에서만 암호화 / 복호화하고, 프론트엔드 앱에서는 피하세요. 이렇게 하면 사용자의 custom_data가 실수로 유출되었을 때 손실을 최소화할 수 있습니다.

사용자의 custom_data는 Logto Console 또는 Logto Management API를 사용하여 업데이트할 수 있습니다. 예를 들어 PATCH /api/users/:userId.

주의해서 업데이트하세요

사용자의 custom_data를 업데이트하면 저장소의 원래 내용이 완전히 덮어쓰여집니다.

예를 들어, custom_data API 업데이트 호출의 입력이 다음과 같다면 (원래 custom_data가 이전에 표시된 샘플 데이터라고 가정):

{
  "customDataBaz": {
    "baz": "baz"
  }
}

업데이트 후 새로운 custom_data 값은 다음과 같아야 합니다:

{
  "customDataBaz": {
    "baz": "baz"
  }
}

즉, 업데이트된 필드 값은 이전 값과 관련이 없습니다.

속성 참조

다음 DB 사용자 테이블 열 ( password_encrypted 및 password_encryption_method 제외)은 사용자 프로필에 표시됩니다. 이는 Management API를 사용하여 조회할 수 있음을 의미합니다.

이름	유형	설명	고유	필수
id	string	고유 식별자	✅	✅
username	string	로그인용 사용자 이름	✅	❌
primary_email	string	기본 이메일	✅	❌
primary_phone	string	기본 전화번호	✅	❌
name	string	전체 이름	❌	❌
avatar	string	사용자의 아바타 이미지를 가리키는 URL	❌	❌
profile	object	사용자 프로필	❌	✅
identities	object	소셜 로그인에서 가져온 사용자 정보	❌	✅
custom_data	object	사용자 정의 가능한 속성의 추가 정보	❌	✅
application_id	string	사용자가 처음 등록한 애플리케이션 ID	❌	✅
last_sign_in_at	date time	사용자가 마지막으로 로그인한 타임스탬프	❌	✅
password_encrypted	string	암호화된 비밀번호	❌	❌
password_encryption_method	string	비밀번호 암호화 방법	❌	❌
is_suspended	bool	사용자 정지 표시	❌	✅
mfa_verifications	object[]	MFA 인증 요소	❌	✅

고유: 데이터베이스 테이블의 속성에 입력된 값의 고유성을 보장합니다.
필수: 데이터베이스 테이블의 속성에 입력된 값이 null이 될 수 없음을 보장합니다.

이동 중인 사용자 데이터를 위한 안전한 허브

사용자 프로필​

기본 데이터​

id​

username​

primary_email​

primary_phone​

name​

avatar​

profile​

application_id​

last_sign_in_at​

created_at​

updated_at​

has_password​

password_encrypted​

password_encryption_method​

is_suspended​

mfa_verification_factors​

소셜 아이덴티티​

SSO 아이덴티티​

사용자 정의 데이터​

속성 참조​

관련 리소스​