Single Sign-on (SSO): Getting Started


Userlevel 1

This article outlines the basics of how to get started with setting up SSO on the inSided platform, including:

  • Supported SSO schemes and how to set them up
  • A step-by-step guide to how SSO works for end users on the inSided platform
  • The various SSO configuration options offered by inSided

What is Single Sign-on (SSO?)

Single sign-on (SSO) enables your end-users to authenticate onto the Community through an Identity Provider of your choice, using a single ID and password.

Supported SSO schemes & how to set them up

Supported identify providers & how to set them up

Key Terms

  • Community - Gainsight Platform
  • Identity Provider - third-party service that creates, maintains, and manages users identity information
  • User - end user of the Community

Community SSO diagram

Click ‘learn more’ to see a diagram describing the generic interaction between Community & Identity Provider. 

 

 

Community SSO detailed explanation

Independent of your chosen Community SSO scheme, the interaction between Community and Identity Provider can be described as a sequence of main three steps:

  1. User visits Community Home page
    • If the session already exists, the User is successfully logged in.
    • If the session does not exist, the User can start SSO Login by clicking on the Login button, and then clicking the relevant SSO button in the modal.
    • It’s also possible to setup SSO Login without requiring a click on the Login button

      Instead of clicking on the Login button, it is possible to initiate SSO Login by calling this GET endpoint directly: https://sso.api.insided.com/auth/[SSO_SCHEME]?customer=[CUSTOMER_ID]

      • CUSTOMER ID: this is the first part of the URL of your Control environment (e.g. customer-id.insided.com)
      • SSO_SCHEME : can be oauth2, openidconnect, saml, token, google
  2. User is redirected to Identity Provider site

    • The User simply needs to be authenticated here according to the rules of the Identity Provider.
  3. User is redirected back to Community along with Profile data
    • The Profile data is used for registration or login. 
    • To be automatically parsed and mapped the Profile data should be sent as follows:
      • id (required) string (e.g. "kd2fj09234ls8"), case insensitive ("qwerty123" is the same as "QWERTY123")
      • email string (e.g. "bob@gmail.com")
      • username string (e.g. "bob")
      • avatar string in HTTP URL format (e.g."http://foo.bar/image.jpg")
      • customRoles comma separated string (e.g. "1,2,3") 
    • If the id field is not provided the User sees an Authentication failed error.

    • Automatic login
        • If a user with provided id already exists in the Community the User is automatically logged in
        • If a user with provided id doesn't exist and email field is provided, Community checks if there is a user with a matching email already registered then the User is automatically logged in.
        • Additional automatic login options
          • If update user attributes* feature is configured and custom roles update is enabled and customRoles field is provided, all current custom roles that the User has are replaced.
          • If update user attributes* feature is configured and email update is enabled and email field is provided the email that the User has is replaced.
    • Automatic registration
        • If Automatic login fails, the Community checks if the auto register* option is enabled.
        • If the auto register option is enabled, Community checks if both email and username fields are provided.
          • If the fields are provided, the User is automatically registered, a login session created and the User is logged in (any separately configured required profile fields are ignored).
          • If the avatar field is provided, the image is downloaded and attached to the User’s profile.​​​​​
        • Additional automatic registration options
          • If Use left part of email as username is enabled, the local-part of the email field is used as the username (if username field is provided it’s ignored).
          • E.g. if email is john.doe@mail.com then john.doe is used.
    • Normal registration
        • If Automatic registration failed or is not configured, the User sees Registration form  filled with least Profile fields.
        • The User edits them if needed, and submits the form.
        • The User is registered, a login session is created and the User is logged in.
        • If the avatar field is provided, the image is downloaded and attached to registered User profile

         

Logout

  • If User clicks Log out and logout url is configured the User is redirected to that url 

Profile data fields may vary per SSO scheme
E.g. OpenID Connect’s IdToken.sub will be recognised as id automatically.

The details of these interactions differ slightly per SSO scheme.

For instance, when implementing Token (JWT) it is as simple as in the diagram, but other schemes are much more “chatty”. i.e. the #Step 3 can be performed with several additional background HTTP requests in the background to the Identity Provider.

In any case, the Community always expects Profile data structured as described above at the end of any SSO journey.


12 replies

Curious to know if there are any other community members here that use SSO for their forums? We are working on implementing ours and would love to hear some pros/cons/implementation issues from others’ experiences! 

Userlevel 1
Badge

Curious to know if there are any other community members here that use SSO for their forums? We are working on implementing ours and would love to hear some pros/cons/implementation issues from others’ experiences! 

 

Yep I’d love to hear from CMs that have recently gone through this implementation, specifically which options were chosen, and how much internal work was required. And of course, the outcome: is it now a better user experience?

We are using SSO between our CRM and the Community. 

Generally it’s been working well but we have a number of membership types which have permissions set on sign-in from the CRM and then a number of custom security groups/roles that get manually set. The custom users roles are being overwritten by the SSO when the user signs in. We’re working on a resolution to this at the moment.

Our SSO integration has been written by our CRM provider.

Where can we find the “hide popup with login buttons” option referred to in this documentation?

Where can I find the auto register option mentioned under Automatic registration?

Badge

Hi all, does InSided support the ability to use multiple identity providers? Our business has just acquired another, who use a different ID provider to the one we use. We’re looking to enable their customers to access our private community asap.

Hi all - We are looking at SAML based integration for SSO (salesforce idp) and wanted to clarify what the “id” field is in the profile data  that gets returned? Is this the id of our community?  Can you share an example?

thanks

 

Answer: ‘id’ is the unique identifier for that user in the SSO identity provider application (e.g. Salesforce, Okta, etc)

Just helping a dev out with this, can I confirm what you mean by “replaced”? 

 


Additional automatic login options

  • If update user attributes* feature is configured and custom roles update is enabled and customRoles field is provided, all current custom roles that the User has are replaced.



If a member already has the custom roles 4, 5, 6

And we we send the following custom roles across

  • customRoles "1,2,3" 

 

Will the user now have the custom roles 1,2,3,4,5,6 ? 

Or will they no longer have 4,5,6 as they have been “replaced” with 1,2,3? 

Userlevel 4
Badge +4

Hi @BenSmokeBall 👋,

It depends if you have the ‘Preserve manually granted custom roles’ configuration turned on. If you don’t then the custom roles will be replaced (1, 2, 3 in your example). However, with this setting turned on, then the custom roles will merge (1, 2, 3, 4, 5, 6 in your example). 

You can read a bit more about it in the following question:

https://community.insided.com/integrations-153/does-sso-setting-preserve-manually-granted-custom-roles-5895

 

Userlevel 1

We are working on launching SSO next month. Want to understand what happens to the already registered accounts 

  • How will the SSO impact already registered customers in community? 
  • In case their community email does not match with their account info they use to log into our products, what happens in that case?
  • Based on Question 2, if it creates a new account for those users, can I merge their old and new account in community?
Userlevel 5
Badge +4

Hey @VarshaAhir - as long as the email is the unique identifier and the emails match, the moment you enable SSO, members will be authenticated using their existing community accounts.  If they log in via SSO with a different email address, their existing account won’t be found and they’ll register a new account.  With cases like that, it’s not possible ‘merge’ their old and new account (from an engineering perspective that’s very complex, is my understanding).  However, what you can always do is update the email address in the existing account with the one that is being used for SSO, thereby providing the member with their previous community account again.  That’s a fairly common workflow and is something we do for our community members when they’ve switched jobs (and have a different company email address) or if for whatever reason have created a new account with a new email address and want their old one back.  This is something I would recommend to weave into the communication around the SSO rollout, so members know who to contact if this needs to happen.

Userlevel 1

This is very helpful @Kenneth R Thank you for that suggestion!

Reply