SMTP 이메일과 SAML SSO 설정
셀프 호스팅한 OpenTickly에서 이메일(초대, 비밀번호 재설정, 이메일 인증용)과 SAML 싱글 사인온을 설정하는 방법입니다.
이메일(SMTP)은 인스턴스 전체에 한 번만 설정하고, 싱글 사인온(SAML 2.0)은 워크스페이스마다 따로 설정합니다. 이메일 속 링크와 SSO 주소가 모두 사이트 URL을 바탕으로 만들어지니, 사이트 URL부터 먼저 설정하세요.
사이트 URL 설정
인스턴스 관리자로 로그인한 뒤 인스턴스 관리 → 설정을 엽니다. 사이트 URL에는 사용자가 브라우저에 입력하는 주소를 넣으세요. 예: https://time.example.com
Docker 내부 호스트 이름은 쓰지 말고, /api 같은 경로도 붙이지 마세요. 나중에 도메인을 바꾸면 이메일 링크가 제대로 열리는지 확인하고, IdP 쪽 SSO 설정도 새 주소로 고쳐 주세요.
SMTP 이메일 설정
인스턴스 관리 → 설정 → 이메일 / SMTP에서 다음 항목을 입력합니다.
| 항목 | 설명 |
|---|---|
| 발신자 이름 | 메일에 표시될 보낸 사람 이름 |
| 발신자 이메일 | 메일 서비스에서 보내는 사람으로 쓸 수 있게 허용된 주소 |
| SMTP 호스트 | 메일 서버 주소 |
| SMTP 포트 | 메일 서비스가 안내하는 포트. 보통 STARTTLS는 587, 처음부터 TLS는 465 |
| SMTP 사용자 이름 | 메일 서버 로그인 아이디 |
| SMTP 비밀번호 | 비밀번호, 또는 메일 서비스에서 발급한 앱 비밀번호 |
465 포트를 쓰면 처음부터 TLS로 연결합니다. 다른 포트에서는 서버가 지원할 경우 STARTTLS로 전환합니다.
저장한 다음 테스트 이메일 보내기에 받을 주소를 넣고 테스트 메일을 보내 보세요. 실패하면 연결이 안 됐는지, 로그인 정보가 틀렸는지, 받는 주소가 거부됐는지, 시간이 초과됐는지 알려 주니 메일 서비스 설정을 볼지 방화벽을 볼지 판단할 수 있습니다.
초대, 비밀번호 재설정, 이메일 인증은 모두 SMTP가 있어야 동작합니다. 테스트 메일이 잘 도착하면 이메일 인증을 켜서 새 사용자가 이메일 주소를 확인하도록 할 수 있습니다.
SMTP 비밀번호가 스크린샷, 이슈, git, 공유되는 셸 기록에 남지 않게 하세요. 유출됐다면 바로 바꾸세요.
워크스페이스 SAML SSO 설정
IdP(아이덴티티 공급자)는 팀이 이미 로그인할 때 쓰고 있는 서비스를 말합니다. Okta, Microsoft Entra ID, Google Workspace, Keycloak 같은 것들입니다.
워크스페이스 관리자로 **워크스페이스 설정 → SSO (싱글 사인온)**을 엽니다.
- 이름과 회사 이메일 도메인(예:
example.com)을 입력합니다. - IdP에서 새 SAML 앱을 만들고, OpenTickly에 표시된 엔터티 ID, ACS URL, 로그인 URL, 메타데이터 URL을 붙여 넣습니다.
- OpenTickly로 돌아와 IdP의 메타데이터 URL을 붙여 넣습니다. IdP가 메타데이터 URL을 주지 않는다면 로그인 URL, 엔터티 ID, X.509 서명 인증서를 직접 입력하세요.
- SSO를 켜기 전에 구성 테스트를 누릅니다.
- 로그인 테스트를 누르고 해당 이메일 도메인을 쓰는 계정으로 로그인해 봅니다. 이메일, 이름 등의 정보가 제대로 들어오는지 확인하세요.
- 저장한 뒤 싱글 사인온을 켭니다.
로그인 화면에서 SSO 버튼을 누르면 OpenTickly는 이메일 도메인을 보고 어느 워크스페이스로 보낼지 정합니다. 그래서 한 도메인은 하나의 워크스페이스에서만 쓸 수 있습니다. IdP는 사용자의 이메일 주소를 이메일 속성이나 NameID로 보내 줘야 합니다.
모두에게 켜기 전에
스스로 로그인이 막히는 일을 피하려면:
- 테스트하는 동안 다른 탭에서 관리자 계정(비밀번호 로그인)으로 로그인한 상태를 유지하세요.
- 팀 전체가 아니라 테스트용 사용자로 먼저 해 보세요.
- IdP에 넣은 엔터티 ID와 ACS URL이 OpenTickly에 표시된 값과 정확히 같은지 확인하세요.
- 사용자와 IdP 모두 HTTPS로 OpenTickly에 접속할 수 있는지 확인하세요.
- 사이트 URL, 리버스 프록시, 인증서, IdP 설정을 바꾼 뒤에는 다시 테스트하세요.
- 다른 관리자가 한 명 이상 SSO로 로그인에 성공할 때까지 비밀번호 로그인은 남겨 두세요.
배포와 리버스 프록시는 셀프호스팅을, API 토큰과 스크립트는 Toggl API 호환성을 참고하세요.