본문으로 건너뛰기

커스텀 도메인

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

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

노트:

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

콘솔에서 커스텀 도메인 설정하기​

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

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

  2. "커스텀 도메인" 섹션에서 도메인 이름을 입력하고 "도메인 추가"를 클릭하세요.

    도메인 추가

  3. 표에 표시된 CNAME 값을 복사한 후, 도메인 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에서 존 홀드를 해제하는 방법은 위 링크를 참고하세요.

커스텀 도메인 사용하기​

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

노트:

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

커스텀 도메인 추가됨

애플리케이션의 SDK 엔드포인트 업데이트하기​

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

const client = new LogtoClient({
  ...,// other options
  endpoint: 'https://auth.example.com',
});

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

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

인증 엔드포인트는 다음과 같은 well-known URL에서 확인할 수 있습니다:

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

소셜 커넥터의 콜백 URI 업데이트하기​

사용자가 커스텀 도메인을 사용하는 경우, 소셜 커넥터의 콜백 URI도 자동으로 새 도메인으로 변경됩니다. 소셜 제공업체의 개발자 콘솔에 접속하여 콜백 URI를 직접 업데이트해야 합니다.

사용자가 커스텀 도메인을 사용하는 경우, 소셜 커넥터의 콜백 URI는 새 도메인을 사용하게 됩니다. 따라서 소셜 제공업체의 개발자 콘솔로 이동하여 콜백 URI를 수동으로 업데이트해야 합니다.