커스텀 도메인

노트:

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

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

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

• 로그인 및 회원가입 페이지 URL
• 소셜 커넥터 또는 엔터프라이즈 SSO 커넥터의 콜백 URI
• 패스키 연결 URL (사용자가 패스키를 연결한 후 도메인을 변경하면 인증이 차단될 수 있습니다)
• 애플리케이션과 Logto를 통합하기 위한 SDK 엔드포인트

다중 커스텀 도메인 지원

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시간이 소요될 수 있습니다. 진행 중에는 다른 페이지로 이동해도 괜찮습니다.

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

문제 해결

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 Hold" 상태로 설정되어 있음을 의미합니다. 자세한 내용은 Cloudflare 문서를 참고하세요.

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

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 커넥터의 경우, 여러 redirect URI를 지원하는 GitHub Apps를 사용하세요. 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. SAML 아이덴티티 제공자 설정에 이 ACS URL을 추가하세요.

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

MFA용 패스키

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

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