Difference between revisions of "Docs/Authentication/SAML Configuration"

From Userful Support
Jump to navigationJump to search
Line 9: Line 9:
'''Note:''' This page has been updated in our new Support Portal - [https://docs.userful.com/software/userful-control-center/control-center-on-prem/settings#saml-configuration try it here!]<br>

Latest revision as of 18:02, 9 February 2021

Copyright © 2022 Userful Corporation. All rights reserved.
(Updated 2021.02.09)

To return to the main documentation page, Click Here.

Note: This page has been updated in our new Support Portal - try it here!


SAML (Security Assertion Markup Language) can be used to control access to multiple web sites or applications within an organization via “Single Sign-On”.

Within the Userful Control Center, Command & Control module and Supervisor Dashboard, you can integrate your existing SAML Identity Provider so that new users can be added and authenticated using their existing credentials.

Configuration for this feature requires updates within the Userful application settings as well as on the Identity Provider server. Please contact your SAML ID Provider server administrator for assistance in configuring.

This feature is available only with an “Enterprise” level license. If you are interested in upgrading to take advantage of this feature, please contact your Userful representative or sales@userful.com.

IdP Configuration

As an Admin user, go to Settings → SAML Configuration. Enter details of your SAML server as shown below (Your SAML server administrator, or an IT support person at your organization should be able to assist in locating the correct settings):

  • Single Sign-On URL
    • This is the location of the system you use for website access authentication in your organization
    • Format: https://[server_address]:[port_number]
  • ID Attribute Name
    • This is the field on the Identity Provider system which uniquely identifies a user.
  • ID Provider Signing Certificate:
    • This is a code produced in the SAML server to allow our system to request authentication of users.
    • Please copy and paste this value (including the “-----BEGIN CERTIFICATE----” and “-----END CERTIFICATE-----” text) as a single incorrect character can result in authentication failure.

Since every SAML installation is different, it is extremely important to work with your Administrator to determine the right field values.

SP Configuration

The Userful application is to be set as the Service Provider (SP). To generate the “SP Metadata” required to link to your Identity Provider, two things are required:

  • Userful Server ID
    • This is a name that you can give your server. Using a descriptive name will help with organization and logging within your SAML server.
  • ID Format
    • Defines the format of the User ID that will be used for logging in. Recognized formats are defined in SAML standards.
    • Your administrator should be able to provide the appropriate selection.

Once all data is entered, the contents of the SP Metadata field must be loaded to your Identity Provider system. Again, work with the SAML system administrator in your organization to complete this process.

Finally, click on the “Enabled” checkbox to activate the integration.

Setting up a SAML User

In order to test proper connection to the SAML server, you will need to create a new user which will link to your existing authentication.

  • On the Users screen, click on “Add User”
  • In the User Name field, enter a username which matches a user already configured in SAML.
  • Check the “External User” checkbox, and assign the user to one or more groups. (For testing purposes, ensure this initial user has access to the Control Center application.)
  • Click OK.

Setting up a non-SAML User

With SAML active, you can still create a Local user on the Userful system. This can allow you to set up users that are completely separated from the network-dependent authentication, allowing you to continue working when external network connections are not available.

  • On the Users screen, click on “Add User”
  • In the User Name field, enter a username which does not match a user already configured in SAML.
  • Do not check the “External User” checkbox.
  • Enter a password for the new user and assign the user to one or more groups.
  • Click OK.

Testing the SAML Integration

  • After activating SAML configuration and setting up a user, log out of the Control Center interface, and close the tab of your browser.
  • In a new tab, return to the Userful login screen. You should now see a new link on the page for “Login with SAML”.
  • Clicking on this link will direct you to the SAML login screen provided by your SAML server.
  • Once you submit your login details, you should be returned to the Userful application, and logged in.


If login of the new user fails, there could be several different reasons.

You are not authorized to access this application.

  • This means that authentication for the user was successful, but they do not have access permissions for the interface being used.
    • An example would be if the user only has access to the Command and Control module, and is logging into the Control Center.

Invalid user name or password.

  • This means that authentication failed on the server.
    • Check that the username and password are exactly as expected and try logging in again.
    • If it still does not work, log in as an admin user, and ensure that the user account was set up with a name that exactly matches one in SAML.
    • Next, return to Settings → SAML Configuration and work with your SAML Server administrator to confirm all parameters are correct.