Configure SMTP Email and SAML SSO
Set up email (for invites, password resets, and verification) and SAML single sign-on on a self-hosted OpenTickly instance.
Email (SMTP) is set up once for the whole instance. Single sign-on (SAML 2.0) is set up separately for each workspace. Set the Site URL first, because links in emails and the SSO addresses are built from it.
Configure the public Site URL
Sign in as an instance admin and open Instance Admin → Configuration. Set Site URL to the address your users type into the browser, for example https://time.example.com.
Don't use an internal Docker hostname, and don't add /api or any other path. If you change the domain later, check that email links still work and update the SSO settings in your identity provider.
Configure outgoing SMTP email
In Instance Admin → Configuration → Email / SMTP, enter:
| Field | Meaning |
|---|---|
| Sender Name | Display name shown on messages |
| Sender Email | From address your mail provider allows you to send as |
| SMTP Host | Mail server hostname |
| SMTP Port | Provider port; commonly 587 for STARTTLS or 465 for implicit TLS |
| SMTP Username | Login for the mail server |
| SMTP Password | Password or provider-issued app password |
On port 465 OpenTickly connects with TLS from the start. On other ports it switches to STARTTLS if the server supports it.
Save, enter an address under Send Test Email, and send a test. If it fails, the error tells you whether it couldn't connect, the login was wrong, the recipient was rejected, or it timed out, so you know whether to look at your provider settings or your firewall.
Invites, password resets, and email verification all need SMTP. Once the test email arrives, you can turn on Email Verification to make new users confirm their email address.
Keep your SMTP password out of screenshots, issues, git, and shared shell history. If it leaks, change it.
Configure workspace SAML SSO
Your identity provider (IdP) is the service your team already logs in with, such as Okta, Microsoft Entra ID, Google Workspace, or Keycloak.
As a workspace admin, open Workspace Settings → Single Sign-On.
- Enter a name and your company's email domain (for example
example.com). - In your IdP, create a new SAML app and paste in the Entity ID, ACS URL, Sign-in URL, and Metadata URL that OpenTickly shows.
- Back in OpenTickly, paste the IdP's metadata URL. If your IdP doesn't give you one, enter its sign-in URL, entity ID, and X.509 signing certificate by hand.
- Click Test configuration before turning SSO on.
- Click Test login and sign in as someone with that email domain. Check that the email, name, and other details come back correctly.
- Save, then turn on single sign-on.
When someone uses the SSO button on the login page, OpenTickly looks at their email domain to decide which workspace to send them to. So each domain can only be used by one workspace. Your IdP must send the user's email address, either as an email attribute or as the NameID.
Before you turn it on for everyone
So you don't lock yourself out:
- Stay logged in as an admin (with your password) in another tab while you test.
- Try it with a test user first, not the whole team.
- Make sure the Entity ID and ACS URL in your IdP match exactly what OpenTickly shows.
- Make sure both your users and your IdP can reach OpenTickly over HTTPS.
- Test again after changing the Site URL, reverse proxy, certificate, or IdP settings.
- Keep password login available until at least one other admin has signed in with SSO.
For deployment and reverse proxies, see Self-Hosting. For API tokens and scripts, see Toggl API Compatibility.
Toggl API Compatibility
Point your existing Toggl scripts, CLIs, and agents at OpenTickly. Which URLs to use, how to authenticate with an API token, and what to test before you switch.
Self-Hosting
Run OpenTickly on your own machine with Docker Compose. One command starts the app, PostgreSQL, and Redis. Also covers CasaOS, ZimaOS, Synology, fnOS, and other NAS platforms.