사전 제작된 Account Center UI로 계정 설정하기

사전 제작된 Account Center UI란?

Logto는 최종 사용자가 자신의 계정 설정을 관리할 수 있도록 준비된 페이지를 제공하는 사전 제작된 Account Center UI를 제공합니다. 이 사전 제작 UI는 Logto에서 호스팅되며 다음과 같은 일반적인 계정 관리 작업을 처리합니다:

사용자 프로필 보기 및 편집 (이름, 아바타, 사용자 정의 프로필 필드)
이메일 주소 및 전화번호 업데이트
사용자 이름 업데이트
비밀번호 설정 또는 업데이트
소셜 계정 연결 및 해제 (소셜 연결 관리)
MFA 설정 관리 (TOTP 인증 앱, 패스키, 백업 코드)
2단계 인증 켜기 / 끄기
활성 세션 및 인가된 앱 관리

사전 제작된 Account Center UI는 애플리케이션과 원활하게 작동하도록 설계되어, 별도의 맞춤형 계정 관리 페이지를 만들 필요 없이 일관된 사용자 경험을 제공합니다.

사전 제작 UI 사용의 이점

개발 작업 불필요: 바로 사용할 수 있는 페이지 제공
일관된 경험: Logto의 로그인 경험과 동일한 스타일 및 느낌 제공
내장된 보안: 모든 인증 (Authentication) 플로우 및 보안 조치가 자동으로 처리됨
항상 최신 상태: 새로운 기능과 보안 개선 사항이 자동으로 적용됨

제공되는 페이지

사전 제작된 Account Center UI는 Logto 테넌트 엔드포인트의 /account 경로 아래에서 접근 가능한 다음과 같은 페이지를 제공합니다:

경로	설명
`/account/profile`	사용자 프로필 페이지 (이름, 아바타, 사용자 정의 프로필 필드)
`/account/security`	보안 설정 허브 (2단계 인증, 소셜 계정, 세션)
`/account/email`	기본 이메일 주소 업데이트 또는 제거
`/account/phone`	기본 전화번호 업데이트 또는 제거
`/account/username`	사용자 이름 업데이트
`/account/password`	비밀번호 설정 또는 업데이트
`/account/passkey/add`	새 패스키 추가 (WebAuthn)
`/account/passkey/manage`	기존 패스키 보기 및 관리
`/account/authenticator-app`	TOTP 인증 앱 설정
`/account/authenticator-app/replace`	기존 TOTP 인증 앱 교체
`/account/backup-codes/generate`	새 백업 코드 생성
`/account/backup-codes/manage`	백업 코드 보기 및 관리

예를 들어, 테넌트 엔드포인트가 https://example.logto.app라면, 이메일 업데이트 페이지는 https://example.logto.app/account/email에서 접근할 수 있습니다.

사전 제작 UI 사용 방법

1단계: Account API 활성화

사전 제작된 Account Center UI는 Account API에 의존합니다. 콘솔 > 로그인 & 계정 > Account center로 이동하여 Account API를 활성화하세요.

필드 권한을 필요에 따라 구성하세요:

사용자가 수정할 수 있도록 하려면 필드를 Edit로 설정
사용자가 보기만 할 수 있도록 하려면 필드를 ReadOnly로 설정
완전히 숨기려면 필드를 Off로 설정

프로필 필드 구성하기

Account Center는 최종 사용자가 자신의 프로필 정보를 보고 관리할 수 있는 프로필 페이지를 표시합니다. 이 페이지에 표시할 프로필 필드를 제어하려면:

Account security / User profile 섹션에서 이름, 아바타, 프로필, 또는 사용자 정의 데이터 필드 권한이 Edit 또는 ReadOnly로 설정되어 있는지 확인하세요.
사전 제작 UI 통합 카드에서 프로필 필드 선택기에서 노출하고자 하는 프로필 필드를 추가하세요. 이 필드는 사용자 프로필 수집에서 사용하는 카탈로그와 동일하게 가져옵니다 — 거기서 정의된 모든 필드는 Account Center에서도 표시할 수 있습니다.
드래그 앤 드롭으로 필드 순서를 원하는 대로 조정하세요.

프로필 필드에 나열되어 있고 해당 필드 권한이 Off가 아닌 필드만 프로필 페이지에 표시됩니다.

2단계: 애플리케이션에서 사전 제작 페이지로 연결하기

사전 제작된 Account Center UI를 사용하려면, 애플리케이션에서 적절한 Logto 페이지로 사용자를 리디렉션해야 합니다. 두 가지 접근 방식이 있습니다:

접근 방식 A: 리디렉션 파라미터를 이용한 직접 연결

애플리케이션에 사전 제작 페이지로 리디렉션하는 링크를 추가하세요. 작업 완료 후 사용자를 다시 앱으로 돌려보내기 위해 redirect 쿼리 파라미터를 포함하세요:

https://[tenant-id].logto.app/account/email?redirect=https://your-app.com/settings

사용자가 이메일 업데이트를 완료하면 https://your-app.com/settings로 다시 리디렉션됩니다.

접근 방식 B: 계정 설정 플로우에 임베딩

기존 계정 설정 워크플로우에 사전 제작 페이지를 통합할 수 있습니다:

앱의 계정 설정 페이지에서 사용자의 현재 정보를 표시
해당 사전 제작 페이지로 연결되는 "수정" 또는 "업데이트" 버튼 제공
사용자가 작업을 완료하면 다시 앱으로 리디렉션

예시 구현:

function AccountSettings() {
  const tenantEndpoint = 'https://example.logto.app';
  const redirectUrl = encodeURIComponent(window.location.href);

  return (
    <div>
      <h2>Account Settings</h2>

      <div>
        <span>Email: user@example.com</span>
        <a href={`${tenantEndpoint}/account/email?redirect=${redirectUrl}`}>Update Email</a>
      </div>

      <div>
        <span>Password: ••••••••</span>
        <a href={`${tenantEndpoint}/account/password?redirect=${redirectUrl}`}>Change Password</a>
      </div>

      <div>
        <span>MFA: Not configured</span>
        <a href={`${tenantEndpoint}/account/authenticator-app?redirect=${redirectUrl}`}>
          Set up Authenticator
        </a>
      </div>
    </div>
  );
}

3단계: 성공 리디렉션 처리하기

사용자가 작업을 완료하면, 선택적으로 show_success 쿼리 파라미터와 함께 지정한 URL로 리디렉션됩니다. 이를 활용해 성공 메시지를 표시할 수 있습니다:

function SettingsPage() {
  const searchParams = new URLSearchParams(window.location.search);
  const showSuccess = searchParams.get('show_success');

  return (
    <div>
      {showSuccess === 'email' && <div>Email updated successfully!</div>}
      {showSuccess === 'password' && <div>Password updated successfully!</div>}
      {/* ... 나머지 설정 페이지 */}
    </div>
  );
}

지원되는 URL 파라미터

Account Center URL에 다음 쿼리 파라미터를 추가하여 경험을 맞춤화할 수 있습니다:

파라미터	설명
`redirect`	사용자가 작업을 완료한 후 다시 보낼 절대 URL. 오직 `http(s)` URL만 허용됩니다.
`show_success`	`true`로 설정하면, 성공 목적지(예: `redirect` URL)로 `show_success` 쿼리 파라미터가 전달되어 확인 메시지를 표시할 수 있습니다.
`identifier`	대상 페이지(`/account/email`, `/account/phone`, `/account/username`)에서 식별자 입력을 미리 채웁니다. 이미 사용자의 식별자를 알고 있을 때 딥링크에 유용합니다.
`ui_locales`	Account Center UI 언어를 제어하는 BCP-47 언어 태그(예: `fr-CA fr en`)의 공백 구분 목록. 생략 시 사용자의 브라우저 언어로 대체됩니다.

예시 — 현재 이메일을 미리 채우고 프랑스어 UI로 이메일 업데이트 페이지에 딥링크:

https://[tenant-id].logto.app/account/email?identifier=user@example.com&ui_locales=fr&redirect=https://your-app.com/settings

노트:

identifier 값은 로그인 리디렉션 전 세션 스토리지에 저장되며, 대상 페이지에서 한 번만 사용됩니다.

계정 삭제 링크

Account Center는 계정 삭제를 직접 처리하지 않습니다. 대신, Management API로 지원되는 자체 삭제 플로우로 연결되는 계정 삭제 URL을 구성할 수 있습니다. 설정 시, Account Center 보안 페이지에 계정 삭제 항목이 나타나며 사용자를 해당 URL로 안내합니다.

설정하려면 콘솔 > 로그인 & 계정 > Account center로 이동하여 계정 삭제 URL 필드를 입력하세요. Management API를 통해서도 업데이트할 수 있습니다:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"deleteAccountUrl":"https://your-app.com/delete-account"}'

필드를 비워두거나(deleteAccountUrl을 null로 설정) 하면 계정 삭제 항목이 숨겨집니다.

사용자가 Account Center에서 소셜 계정을 연결할 때, Logto는 일반 로그인 플로우와 다른 리디렉션 URI를 사용합니다. Account Center 콜백 URL 형식은 다음과 같습니다:

https://[your-tenant-endpoint]/account/callback/social/{connectorId}

여기서 {connectorId}는 소셜 커넥터의 ID입니다 (콘솔 > 커넥터 > 소셜 커넥터에서 확인 가능).

주의:

이 URL을 소셜 제공자의 개발자 콘솔(Google, GitHub, Facebook 등)의 Authorized redirect URIs(또는 동등 항목) 목록에 일반 로그인 콜백 URL https://[your-tenant-endpoint]/callback/{connectorId}과 함께 추가해야 합니다. 그렇지 않으면 링크 플로우가 리디렉션 URI 불일치 오류로 실패합니다.

보안 고려 사항

사전 제작된 Account Center UI에는 내장된 보안 조치가 포함되어 있습니다:

아이덴티티 검증: 민감한 변경(이메일, 전화, 비밀번호, MFA) 전 사용자는 현재 비밀번호 또는 기존 인증 (Authentication) 방법으로 본인 확인 필요
인증 (Authentication) 코드: 이메일 및 전화번호 업데이트 시 새 주소/번호로 인증 (Authentication) 코드 전송 필요
세션 검증: 모든 작업은 사용자의 세션을 검증하여 무단 접근을 방지합니다

커스터마이징 옵션

사전 제작된 Account Center UI는 로그인 경험 설정에서 브랜딩(로고, 색상, 다크/라이트 모드, 언어 설정 등)을 상속받습니다.

커스텀 CSS

Account Center UI의 외관을 추가로 커스터마이징하려면 콘솔 > 로그인 & 계정 > Account center에서 Custom CSS 에디터에 CSS를 추가하세요.

사전 제작된 Account Center UI는 주요 UI 요소(레이아웃 컨테이너, 페이지 헤더, 섹션, 카드 등)에 logto_ac- 접두사가 붙은 안정적인 CSS 클래스명을 제공합니다. 이를 통해 릴리즈 간 클래스명 변경 걱정 없이 기본 스타일을 쉽게 오버라이드할 수 있습니다.

예시:

/* Logto 시그니처 숨기기 */
.logto_ac-logto-signature {
  display: none;
}

/* 보안 섹션 카드 커스터마이징 */
.logto_ac-security-card {
  border-radius: 12px;
}

사전 제작 UI와 커스텀 CSS로 제공되는 것보다 더 많은 커스터마이징이 필요하다면, Account API를 사용하여 자체 계정 관리 페이지를 구축하는 것을 고려하세요.

Account API로 계정 설정 - 전체 API 제어로 맞춤형 계정 관리 구축
Management API로 계정 설정 - 관리자 수준 계정 관리
MFA 구성 - 다단계 인증 (MFA) 설정

사전 제작된 Account Center UI란?​

사전 제작 UI 사용의 이점​

제공되는 페이지​

사전 제작 UI 사용 방법​

1단계: Account API 활성화​

프로필 필드 구성하기​

2단계: 애플리케이션에서 사전 제작 페이지로 연결하기​

접근 방식 A: 리디렉션 파라미터를 이용한 직접 연결​

접근 방식 B: 계정 설정 플로우에 임베딩​

3단계: 성공 리디렉션 처리하기​

지원되는 URL 파라미터​

계정 삭제 링크​

소셜 연결 콜백 URL​

보안 고려 사항​

커스터마이징 옵션​

커스텀 CSS​

관련 리소스​