UserGems offers SAML 2.0 authentication for Enterprise customers. This is not limited to specific providers; all providers which support SAML 2.0 are supported. The authentication allows customers to have complete control over the access to UserGems from their authentication provider (IdP). If customers add users to the UserGems application within their SSO provider, they will able to login directly to UserGems. The same applies to disabling users; when users are deactivated in the SSO provider, they will lose access to UserGems.
We will go through the setup process with Microsoft as an example (the same concept works for Google, Okta and other providers).
Configuration of SSO
Once you have access to the feature (available in our Enterprise package) you can access it via the navigation in the top right:
The first step is to configure certificates and metadata. Make sure you are an Administrator in your company and have access to the SSO configuration from your Identity Provider (IdP). Let's choose the IdP first (Microsoft Azure in our case):
Once we click “Continue” we will get all the required information that needs to be added to Microsoft:
Within Microsoft, go to Microsoft Entra ID, select Enterprise applications, and click “New application”:
On the next screen, select “Create your own application,” give it a meaningful name such as “Usergems Application - SSO” and click “Create”:
As soon as your new application is created, you will be able to add all the details from Step 2 (URLs which were shown on the UserGems platform). To enter the URLs, go to “Single sign-on” in the navigation and select SAML as the method:
This will open up the following screen where you can edit the Basic SAML configuration and add the URLs:
By default, your SSO application will not allow any users to login to UserGems. Therefore you have to either add specific users or groups (which should be able to login to UserGems) to the application, which are typically members of your Go-to-market team (Sales, Marketing, Customer Success, & Operations). This is done by “Assign users and groups”:
This will lead to a next screen where you can see all users/groups which are allowed to login via this application. You can add more users or groups with “Add user/group”. We have added a user called “Access” which is allowed to login to Usergems.
You can now continue with the setup of UserGems. Download the metadata.xml file from Microsoft and upload it to UserGems. All fields on the screen will automatically be populated with the correct values if you upload the correct file. If values are not automatically populating, please create a support ticket and include your metadata.xml as well as the provider you are using.
Press “Save & Continue” to get to the next screen.
Now that you have setup the configuration for SSO, you can test it by enabling it. This will create a company specific test url to try out the new authentication with your IdP. Enter the shown URL into your browser.
You should automatically get redirected to the authentication provider (in our case Microsoft). Now you need to add your username and password and you will automatically signed-up (if you don't have an account yet) or logged-in (if you already have an account matching your email address).
A UserGems user was automatically created and is now able to login into your UserGems account.
Configuring OKTA
Within OKTA, go to Applications and click “Create App Integration”.
Select “SAML 2.0” for your application.
On the next screen, give your app a meaningful name such as “Usergems Platform - SSO”, upload our logo and press “Next”.
On the next screen you need to start configuring your SSO application. To make sure that your users will show up with their names in UserGems, you need to add two attribute statements.
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname -> URI Reference -> users.firstName
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname -> URI Reference -> user.lastName
Once this is done, just finish up the process. You should now be able to see the Application in your Overview. Two more steps before your users can use the login.
Click into the App and go to “Sign-On”
Copy the Metadata URL and open it in the browser. Then save the content as metadata.xml on your local machine. Go to the usergems platform and upload the metadata.xml to the last step of the process:
Press “Save & Continue” and we are done on the Usergems Platform. Last but not least you need to activate the application for your users. To do this, go back to the application overview in OKTA. You can now assign individual users or groups to your application.
