Accelerator supports different methods of Single Sign-On (SSO) such as Okta or Google. The SSO in Accelerator follows SAML 2.0 protocol. This document describes the basics of how SSO works within Accelerator and how to set up SSO within Accelerator.
Before we get into the details of SSO, let's first cover how MessageGears handles authentication without SSO. MessageGears has two primary components of software:
- Accelerator is the on-premise software that is installed behind your firewall or in your private cloud next to your marketing database.
- There is also a MessageGears' Cloud component which is where we render and send your messages to the various ISPs.
In a typical authentication scenario, all users (and their roles) live in the MessageGears cloud. When logging into Accelerator, it checks Cloud to see if the username is valid and what roles that user has.
|Roles determine the permissions that the user has within Accelerator. Read more about Roles in the Admin Guide.|
When enabling SSO in Accelerator, Accelerator will instead call the Identity Provider (IdP) to determine if the user is a valid user. Accelerator stores the roles of the various users, so part of the set-up of SSO is to create users that are local to Accelerator. It is recommended that you create all new local users after enabling SSO (rather than trying to migrate any of the users in Cloud to the local Accelerator instance). Please contact support at email@example.com for more details.
Once the Accelerator administrative setup is complete and the local Accelerator users have been properly created, the login flow will look like this (using Okta as the example IdP).
In the case where SAML is having issues, there will continue to be a separate URL where the user can login to Accelerator (using Cloud to authenticate the user) that we'll cover at the end of this document.
Both Okta and Google are currently the supported identity providers; however, because SAML is an industry standard, the MessageGears SSO may be compatible with others as well. To check MessageGears SSO compatibility, contact firstname.lastname@example.org for more information.
Tomcat Configuration Updates for SSO with SSL
When configuring SSO for an environment that uses SSL, three configuration updates are required for Tomcat.
- This change tells Tomcat that any connection over the connector should be treated as secure, which in turn tells Accelerator to make the cookies as secure.
<Connector port=..... secure="true"/>
This tells Tomcat to mark the JSESSIONID cookie as secure. Note: doing this will break non-SSL/unsecure connections.
Add to conf/web.xml just after the opening
<!-- cookie-config is the new/pertinent part →
This tells Tomcat to mark ALL cookies with
SameSite=None. Chrome will ignore these cookies if they are not also marked as secure, so be sure to make all of these changes at the same time or logins could be disabled entirely.
Add to conf/context.xml just after the opening
<CookieProcessor sameSiteCookies="none" />
Using Single Sign On
Once the SAML is setup, users access Accelerator using the typical URL and they will follow the flow outlined below.
- The user tries to access a page within an instance of Accelerator.
- Accelerator sends a redirect message back to the user’s browser and includes the URL that the user was trying to access.
- The user’s browser forwards the redirect on to Okta / Google.
- If the user doesn’t have a valid session, the corresponding login page is displayed.
- Once the user logs in, Okta / Google generates the SAML Assertion for that particular user.
- When the SAML Assertion reaches Accelerator, Accelerator looks to see if the Username is valid and unlocked. The user is logged in at that point.
- Finally, Accelerator determines whether the user has access to the resource defined by the URL and if so, serves the page.
If there are issues with the communication or configuration of the IdP, there is an additional URL available to access Accelerator as a Cloud user.
|When using a Cloud user, refrain from editing Audiences, Templates, Campaigns, etc. The Cloud interface is designed to make administrative changes and halt campaigns in emergency situations.|