기본 제공 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/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로 설정

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: 계정 설정 흐름에 임베딩

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

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

예시 구현:

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

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

      <div>
        <span>Email: [email protected]</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 protected]&ui_locales=fr&redirect=https://your-app.com/settings

노트:

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

계정 삭제 링크

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

설정하려면 콘솔 > 로그인 & 계정 > Account center로 이동하여 Account deletion 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로 설정) 하면 계정 삭제 항목이 숨겨집니다.

소셜 연결 콜백 URL

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

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

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

주의:

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

보안 고려 사항

기본 제공 Account Center UI에는 다음과 같은 내장 보안 조치가 포함되어 있습니다:

• 아이덴티티 검증: 민감한 변경(이메일, 전화번호, 비밀번호, MFA) 전 사용자는 현재 비밀번호 또는 기존 인증 (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) 설정