SSO Setup Instructions

Background

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:

1. Accelerator is the on-premise software that is installed behind your firewall or in your private cloud next to your marketing database.
2. 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.

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 support@messagegears.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.

Setup

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 support@messagegears.com for more information.

• Set up SSO with Okta
• Set up SSO with Google / G Suite

Tomcat Configuration Updates for SSO with SSL

When configuring SSO for an environment that uses SSL, three configuration updates are required for Tomcat. Please note that these modifications should occur while Tomcat/Accelerator is stopped, as changes to the config files will cause Tomcat to restart itself if it is currently running. Make sure to make these changes at a time when Accelerator can be offline without interfering with job launches or user actions.

1. 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.
   In conf/server.xml:
   

   <Connector port=..... secure="true"/>

2. This tells Tomcat to mark the JSESSIONID cookie as secure.Note: doing this will break non-SSL/unsecure connections.  The session-timeout value below should match the value set in Accelerator's Max Authentication Age in Hours configuration as well as the timeout value set within the IdP.
   Add to conf/web.xml just after the opening <web-app> tag:

   <session-config>
       <session-timeout>30</session-timeout>
       <!-- cookie-config is the new/pertinent part →
       <cookie-config>
           <http-only>true</http-only>
           <secure>true</secure>
       </cookie-config>
   </session-config>

3. 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 <Context> tag:

   <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.

1. The user tries to access a page within an instance of Accelerator.
2. Accelerator sends a redirect message back to the user’s browser and includes the URL that the user was trying to access.
3. The user’s browser forwards the redirect on to Okta / Google.
4. If the user doesn’t have a valid session, the corresponding login page is displayed.
5. Once the user logs in, Okta / Google generates the SAML Assertion for that particular user.
6. 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.
7. Finally, Accelerator determines whether the user has access to the resource defined by the URL and if so, serves the page.

Troubleshooting

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.

http://<accelerator-hostname>:<accelerator-port>/loginCloud.html