커스텀 도메인

노트:

서비스를 배포한 후 도메인을 변경하면 애플리케이션 코드와 통합이 여전히 이전 도메인을 참조할 수 있으므로 문제가 발생할 수 있습니다. 원활한 전환을 위해 프로덕션 테넌트 생성 시 초기에 커스텀 도메인을 설정하는 것을 권장합니다.

Logto 테넌트에는 기본 무료 도메인 {{tenant-id}}.app.logto가 제공됩니다. 하지만, auth.example.com과 같은 커스텀 도메인을 사용하면 사용자 경험과 브랜드 인지도를 높일 수 있습니다.

커스텀 도메인은 여러 기능에 사용됩니다:

• 로그인 및 회원가입 페이지 URL
• 소셜 커넥터 또는 엔터프라이즈 SSO 커넥터의 콜백 URI
• 패스키 및 패스키 로그인 관련 URL (사용자가 패스키를 연결한 후 도메인을 변경하면 해당 자격 증명으로 MFA 및 로그인이 차단될 수 있습니다)
• 애플리케이션과 Logto를 통합하기 위한 SDK 엔드포인트
• 타사 플랫폼(예: WeChat, Apple 또는 도메인에 정적 파일이 필요한 기타 서비스)에서 도메인 소유권을 검증하기 위한 파일

다중 커스텀 도메인

Logto는 이제 하나의 테넌트에 대해 여러 개의 커스텀 도메인을 구성할 수 있어, 여러 브랜드 도메인에서 로그인 페이지에 접근할 수 있습니다.

플랜별 제한:

• Development 테넌트: 최대 2개의 커스텀 도메인을 무료로 추가 (테스트 용도)
• Free 플랜: 1개의 커스텀 도메인을 무료로 추가
• Pro 플랜: 1개의 커스텀 도메인 포함, 애드온을 통해 최대 10개까지 추가 가능
• Enterprise 플랜: 10개 이상의 커스텀 도메인 또는 맞춤 요구 사항이 있는 경우 문의하세요

자세한 내용은 Logto 가격표를 참고하세요.

여러 커스텀 도메인을 사용하면 다음이 가능합니다:

• 지역, 로케일, 애플리케이션, 조직 또는 최상위 도메인별로 다른 도메인 사용
• 로그인 전후에 일관된 브랜드 경험을 유지하여 신뢰 구축
• 커스텀 UI를 통해 지역별 또는 브랜드별 인증 (Authentication) 경험 제공

콘솔에서 커스텀 도메인 구성하기

Logto 콘솔에서 새 커스텀 도메인을 추가하려면 다음 단계를 따르세요:

1. 콘솔 > 설정 > 도메인으로 이동합니다.

2. "커스텀 도메인 추가" 섹션에서 서브도메인(예: auth.example.com, auth.us.example.com)을 입력하고 "도메인 추가"를 클릭합니다.

   

3. 표에 있는 CNAME 값 domains.logto.app를 복사하여, 도메인 DNS 제공업체에서 레코드를 추가합니다.

   

4. 검증 및 SSL 처리를 기다립니다.

   1. 커스텀 도메인이 추가될 때까지 10초마다 자동으로 레코드를 검증합니다. 입력한 도메인 이름 또는 DNS 레코드가 정확한지 확인하세요.
   2. 검증은 일반적으로 몇 분 내에 완료되지만, DNS 제공업체에 따라 최대 24시간이 소요될 수 있습니다. 처리 중에는 다른 페이지로 이동해도 괜찮습니다.

여러 커스텀 도메인을 추가하려면, 위 단계를 각 도메인마다 반복하세요.

도메인 검증 파일

일부 타사 플랫폼에서는 OAuth, SSO 또는 기타 통합을 사용하기 전에 도메인에 작은 텍스트 또는 JSON 파일을 호스팅하여 소유권을 증명해야 합니다. Logto 커스텀 도메인은 Logto Cloud로 연결되므로, 해당 파일을 직접 업로드할 수 없습니다. Logto가 대신 파일을 호스팅해 드립니다.

커스텀 도메인이 활성화된 후, 콘솔 > 설정 > 도메인에서 도메인 카드를 열고 도메인 검증 파일 섹션에서 파일을 추가, 수정 또는 삭제할 수 있습니다.

지원 경로

• 확장자가 있는 루트 레벨 파일명(예: /MP_verify_xxx.txt, /apple-developer-domain-association.txt)
• /.well-known/ 하위 경로(예: /.well-known/apple-developer-domain-association.txt)

경로 세그먼트에는 영문자, 숫자, 점, 하이픈, 밑줄만 허용됩니다. /.well-known/ 외의 중첩 경로는 지원하지 않습니다.

제한 사항

• 커스텀 도메인당 최대 10개의 검증 파일
• 파일당 최대 16,384자까지 내용 입력 가능
• 콘텐츠 타입: 일반 텍스트(text/plain) 또는 JSON(application/json)

저장 후, Logto는 커스텀 도메인에서 GET 및 HEAD 요청에 대해 정확히 일치하는 파일을 제공합니다. 예시:

https://auth.example.com/MP_verify_xxx.txt
https://auth.example.com/.well-known/apple-developer-domain-association.txt

기존 Logto 라우트가 항상 우선 적용됩니다. 검증 파일은 다른 Logto 핸들러와 경로가 일치하지 않을 때만 제공됩니다.

문제 해결

SSL 인증서 문제

커스텀 도메인 설정 시 SSL 인증서 문제를 겪는 경우, DNS 설정의 CAA 레코드와 관련이 있을 수 있습니다. CAA 레코드는 어떤 인증 기관(CA)이 도메인에 대한 인증서를 발급할 수 있는지 지정합니다. CAA 레코드를 사용하는 경우, Logto가 SSL 인증서를 발급할 수 있도록 "letsencrypt.org"와 "pki.goog" 모두를 허용해야 합니다.

CAA 레코드 관련 SSL 인증서 문제 해결 방법은 Cloudflare 문서를 참고하세요.

"The hostname is associated with a held zone" 오류

커스텀 도메인 추가 시 "The hostname is associated with a held zone, please contact the owner to have the hold removed"라는 오류 메시지가 나타나면, 해당 도메인이 이미 Cloudflare zone에 있으며 "Zone Hold" 상태임을 의미합니다. 자세한 내용은 Cloudflare 문서를 참고하세요.

이 문제를 해결하려면 zone hold를 해제해야 합니다. 위 링크에서 Cloudflare에서 zone hold를 해제하는 방법을 확인하세요.

Cloudflare 호스팅 도메인에서 연결 시간 초과 (오류 코드 522)

도메인이 Cloudflare에 호스팅되어 있다면, CNAME 레코드에 대해 Cloudflare 프록시를 비활성화하세요.

커스텀 도메인 설정 후 "Redirect URI does not match" 오류

커스텀 도메인 추가 후 "redirect URI does not match" 오류가 발생하면, SDK 설정에서 엔드포인트로 커스텀 도메인을 사용하도록 업데이트해야 합니다.

"기본 도메인"에 대하여:

Logto에는 별도의 "기본 도메인" 설정이 없습니다. 커스텀 도메인을 추가하면, 커스텀 도메인과 기본 {tenant-id}.logto.app 도메인 모두 유효하게 남아 있습니다. SDK의 endpoint 파라미터에 어떤 도메인을 입력하느냐에 따라 인증 (Authentication) 플로우에 사용되는 도메인이 결정됩니다.

해결 방법:

SDK 초기화 시 endpoint 파라미터를 커스텀 도메인으로 업데이트하세요:

const client = new LogtoClient({
  endpoint: 'https://auth.example.com', // 커스텀 도메인 사용
  appId: 'your-app-id',
  // ... 기타 옵션
});

또한, 콘솔 → 애플리케이션에서 등록된 redirect URI가 사용하는 도메인과 일치하는지 확인하세요.

참고: Logto는 커스텀 도메인에 대해 SSL 인증서를 자동으로 발급 및 관리합니다. 별도의 인증서 설정은 필요하지 않습니다.

커스텀 도메인 사용하기

설정을 완료하면, 커스텀 도메인과 기본 Logto 도메인 모두 테넌트에서 사용할 수 있습니다. 단, 커스텀 도메인 활성화를 위해 몇 가지 추가 설정이 필요합니다.

노트:

이 문서에서는 커스텀 도메인을 auth.example.com으로 가정합니다.

애플리케이션용 SDK 엔드포인트 업데이트

Logto SDK 초기화 코드에서 엔드포인트 도메인명을 수정하세요.

const client = new LogtoClient({
  ...,// 기타 옵션
  endpoint: 'https://auth.example.com',
});

콘솔 > 애플리케이션의 애플리케이션 상세 페이지에서 "엔드포인트 & 자격 증명" 섹션으로 이동하세요. 도메인 드롭다운을 전환하여, 애플리케이션 설정에 사용할 엔드포인트를 확인하고 복사할 수 있습니다.

기타 애플리케이션의 인증 엔드포인트 수정

Logto SDK를 사용하지 않는 애플리케이션이 있다면, 해당 인증 엔드포인트도 업데이트해야 합니다.

well-known URL에서 인증 엔드포인트를 확인할 수 있습니다:

https://auth.example.com/oidc/.well-known/openid-configuration

소셜 커넥터 redirect URI 업데이트

소셜 커넥터는 OIDC/OAuth 프로토콜을 사용합니다. 사용자가 커스텀 도메인으로 로그인할 때, redirect URI도 자동으로 해당 커스텀 도메인을 사용합니다. 소셜 제공업체의 개발자 콘솔에서 redirect URI를 업데이트해야 합니다.

단계:

1. 콘솔 > 커넥터 > 소셜 커넥터로 이동하여 커넥터를 선택합니다.
2. 커넥터 상세 정보에서 표시되는 redirect URI를 복사합니다. Logto는 구성된 모든 커스텀 도메인에 대한 redirect URI를 나열합니다.
3. 이 redirect URI를 소셜 제공업체의 개발자 콘솔(예: Google, GitHub, Facebook)에 추가합니다.

여러 커스텀 도메인 사용 시:

• 구성한 각 커스텀 도메인에 대한 모든 redirect URI를 추가하세요. 이를 통해 사용자가 어떤 도메인으로 접근하더라도 소셜 로그인이 정상 동작합니다.
• 기본 Logto 도메인(*.logto.app)도 여전히 유효합니다. 기본 도메인으로 로그인도 지원하려면 포함하세요.
• GitHub 커넥터의 경우, GitHub 대시보드에서 OAuth 앱 대신 GitHub Apps를 사용하세요. GitHub Apps는 여러 redirect URI를 지원하지만, OAuth 앱은 하나의 redirect URI만 지원합니다.

OIDC 기반 엔터프라이즈 SSO 커넥터 redirect URI 업데이트

OIDC 기반 엔터프라이즈 커넥터는 소셜 커넥터와 동일한 패턴을 따릅니다.

단계:

1. 콘솔 > 엔터프라이즈 SSO로 이동하여 OIDC 커넥터를 선택합니다.
2. 커넥터 상세 정보에서 redirect URI를 복사합니다. Logto는 구성된 모든 커스텀 도메인에 대한 redirect URI를 나열합니다.
3. 아이덴티티 제공자 (IdP) 설정에서 redirect URI를 업데이트하세요.

여러 커스텀 도메인 사용 시: 모든 도메인에 해당하는 redirect URI를 IdP에 추가하여, 모든 도메인에서 엔터프라이즈 SSO가 동작하도록 하세요.

SAML 기반 엔터프라이즈 SSO 커넥터 ACS URL 업데이트

SAML 기반 엔터프라이즈 커넥터는 redirect URI 대신 Assertion Consumer Service (ACS) URL을 사용합니다.

단계:

1. 콘솔 > 엔터프라이즈 SSO로 이동하여 SAML 커넥터를 선택합니다.
2. "IdP에서 구성" 섹션에서 도메인 드롭다운을 전환하여 원하는 커스텀 도메인을 선택합니다.
3. 해당 도메인에 대한 ACS URL을 복사합니다.
4. 이 ACS URL을 SAML 아이덴티티 제공자 설정에 추가하세요.

중요: 선택한 도메인에 따라 SSO 인증 후 사용자가 리디렉션되는 위치가 결정됩니다. 애플리케이션이 SAML 응답을 받을 도메인에 맞게 구성하세요.

MFA 및 로그인용 패스키

다단계 인증 (MFA)용 패스키 및 패스키 로그인은 등록된 도메인에 바인딩됩니다. 사용자는 패스키를 등록한 동일한 도메인으로 로그인해야 패스키를 사용할 수 있습니다.

현재 제한: Logto는 아직 도메인 간 패스키 검증을 지원하지 않습니다. 사용자가 auth.us.example.com에서 패스키를 등록했다면, 해당 패스키로 MFA 인증 또는 패스키 로그인을 하려면 반드시 auth.us.example.com으로 로그인해야 합니다. 한 도메인에서 등록한 패스키는 다른 커스텀 도메인으로 로그인할 때 사용할 수 없습니다.