Single sign-on explained
Thanks to SSO (Single sign-on), you can log in using your favorite Service Provider with just a single click. It allows you to securely authenticate with multiple websites or applications using just one set of credentials.
Elastic Email supports any OpenID Connect (OIDC) Identity Provider. The only requirement is that they support the Discovery feature. Most of the Providers do, but it's still worth it to keep this in mind.
After this setup is completed, your Subaccounts will have access to a 'Login via SSO' button on your Log In page that will allow them to log in via the Provider of your choosing, be it Google, Twitter, Facebook, Auth0 or any other that is compatible.
How to get started
You must create an account on your Identity Provider's website in order to continue.
An active SSL certificate on your domain is strongly advised as it will help the Provider to recognize you as a secure and legitimate user. Being secured with SSL will also help you avoid any compatibility issues along the way.
Integrating Elastic Email with your Identity Provider
Configure your Identity Provider with Elastic Email callback URL
Please note: This step might be optional, depending on which Identity Provider you are using.
On your Identity Provider's account settings, you might find fields to be filled with Elastic Email details. These can be called differently, but most commonly they are named 'application Callback URL', 'login URI' or 'redirect URL'.
Use your Custom Branding URL as a value for those fields.
If your Provider requires Logout URLs, you can provide them the same Custom Branding URL as mentioned above.
Configure your Elastic Email SSO settings using your Provider's data
On your Custom Branding settings screen, provide this information:
Authority
Client ID
Both can be found on your Provider's website, either in the general documentation (Authority URL) or on your account's settings (Client ID/Authority URL).
Logout URL is optional, as not all Identity Providers support it.
Client ID: Unique identifier of the account you set up on your Provider's site. It should be available on your account's settings screen.
Authority: Also known as "Issuer", it's the URL of the OIDC provider which you can find in your Provider's documentation or settings page.
Logout URL (optional): Providing this URL allows Elastic Email to logout your Sub-Accounts from their authentication session, forcing them to manually log in with a Provider next time. If your Provider supports logout, you should be able to find this URL in their documentation.
Hide the traditional login - This feature allows you to hide the traditional login method, leaving only the Single sign-on as an available option.
Save and see the result
After you save your changes, any Sub-Account that visits your Log In page should see a "Login via SSO" button. Clicking this button will result in them being redirected to your Provider's login view where they can use their credentials or login with a single click and be redirected back for Elastic Email to login them automatically.
Automatic login with SSO
It is possible to skip logging in via the login page. Elastic Email provides a function that enables this feature:
window.ee.sso.login(token)
This function allows you to log in your user automatically to the dashboard. You just have to pass an authorization token, which you can get from the provider when the user logs into your site.
When you call the login method, the default login page disappears and the user is redirected to the dashboard after the login process is completed. It is possible that an error may occur during login – you can catch any of these errors and present them to your users.
If you use Elastic Email dashboard inside iframe, it will be necessary to call the function by iframe contentWindow, e.g.:
document.getElementById(‘ee-iframe’).contentWindow.ee.sso.login(token)
To correctly log out your user and end their session, we provide a logout function:
window.ee.sso.logout()
FAQ
Q: My Callback URL does not work.
A: Make sure to include 'https://' protocol in the URL and ensure that you have a correct SSL certificate installed.
Q: Can I have multiple providers set up?
A: No, that's not possible. You can, however, use a provider that works as a "middleman" that displays multiple login options on their login page – via Google, Twitter, etc.
Q: Can I register new Sub-Accounts with this method?
A: No. Currently, our SSO solution for Custom Branding works as a login method for existing Sub-Accounts only.