기본 제공 Account Center UI로 계정 설정

기본 제공 Account Center UI란?

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

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

기본 제공 Account Center UI는 애플리케이션과 원활하게 연동되도록 설계되어, 별도의 계정 관리 페이지를 직접 구축하지 않아도 일관된 사용자 경험을 제공합니다.

기본 제공 UI 사용의 장점

개발 작업 불필요: 즉시 사용할 수 있는 페이지 제공
일관된 경험: Logto의 로그인 경험과 동일한 디자인 및 UX
내장된 보안: 모든 인증 흐름 및 보안 조치가 자동으로 처리됨
항상 최신 상태: 새로운 기능과 보안 개선 사항이 자동으로 적용됨

제공되는 페이지

기본 제공 Account Center UI는 Logto 테넌트 엔드포인트의 /account 경로 아래에서 다음과 같은 페이지를 제공합니다:

Path	설명
`/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로 다시 리디렉션됩니다. 사용자가 뒤로 가기 버튼으로 페이지를 나가도 동일한 URL로 돌아갑니다.

접근 방식 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단계: 앱으로 돌아오는 처리

사용자는 작업을 완료한 후와 뒤로 가기 버튼으로 나간 경우 모두 동일한 redirect URL로 돌아옵니다. 단순히 돌아온 것만으로 변경이 성공했다고 간주하지 말고, Account API 등으로 최신 사용자 데이터를 다시 가져오세요.

작업 완료 후 사용자에게 성공 메시지를 보여주고 싶다면 Account Center URL에 show_success=true를 추가하세요. 그러면 Account Center가 자체 성공 페이지를 보여주고, 사용자가 완료를 클릭하면 redirect URL로 돌아갑니다:

https://[tenant-id].logto.app/account/password?redirect=https://your-app.com/settings&show_success=true

지원되는 URL 파라미터

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

파라미터	설명
`redirect`	사용자가 작업을 완료하거나 뒤로 가기 버튼으로 나갔을 때 다시 보낼 절대 URL. `http(s)` URL만 허용됩니다.
`show_success`	`true`로 설정하면, Account Center가 작업 후 성공 페이지를 보여주고 사용자가 완료를 클릭하면 `redirect` URL로 돌아갑니다. 없으면 바로 돌아갑니다.
`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에서 소셜 계정을 연결할 때 커넥터의 콜백 URL을 사용합니다:

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

여기서 {connectorId}는 소셜 커넥터의 ID입니다. 이는 콘솔 > 커넥터 > 소셜 커넥터의 커넥터 상세 페이지에 표시되는 Callback URI이며, 커넥터 설정 시 소셜 제공자에 등록합니다.

보안 고려 사항

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

OIDC 단계 상승 인증: 민감한 변경(이메일, 전화번호, 사용자 이름, 비밀번호, 소셜 계정, MFA, 세션, 신뢰 기기)은 테넌트에 설정된 최근 인증 윈도우(기본 10분, 1~120분까지 콘솔 > 로그인 & 계정 > Account center에서 설정 가능) 내에 최근 사용자 인증(urn:logto:acr:1fa 이상)이 필요합니다. 사용자가 적격한 방식으로 방금 로그인/가입했다면 추가 프롬프트가 없고, 1fa가 부족하거나(예: 소셜 로그인) 윈도우를 초과했다면 Account Center가 자동으로 OIDC 단계 상승 인증을 실행하고 대기 중인 작업을 이어갑니다.
인증 코드: 이메일 및 전화번호 업데이트 시 새 주소/번호로 인증 코드 전송 필요
세션 검증: 모든 작업에서 사용자의 세션을 검증하여 무단 접근 방지

커스터마이징 옵션

기본 제공 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​

관련 리소스​