Administrative User Setup:

Single Sign-On User Management

Single sign-on (SSO) is an authentication method that allows a user to log in with a single ID to multiple independent software systems. Envysion supports single sign-on via the SAML2 protocol. Envysion acts as the Service Provider (SP) and delegates authentication to the Identity Provider (IdP). Each customer who integrates SSO with Envysion will be required to maintain at least one bypass user, who authenticates using traditional username and password, in the event that the SSO integration fails. Customers may maintain multiple such bypass users if they choose.

Preparing to Integrate with Envysion

To begin an integration, Envysion needs to be provided IdP metadata, including the IdP certificate used to sign requests. This information can be entered into the web application by using our Authentication interface under the gear menu, and selecting SAML2 as your authentication method.

Once complete and saved, you can use the provided SP information to finish the configuration of your IdP system. By default, users are matched via username or email to existing Envysion users, and Envysion requires that the nameid format for the SAML2 integration be set to “urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress”.

If a user does not exist, the integration fails with an error until a corresponding user (identified by username or email) is created in the Envysion system. Reuse of an email address across multiple user accounts within the Envysion system may lead to non-deterministic behavior, so it is recommended that an audit be performed prior to launching single sign-on to verify that each Envysion user is unique.

The Envysion application allows the authentication administrator to configure a number of single sign-on related features in the application, including:

  • Soft Launch
  • Bypass Users

Envysion supports additional features for single sign-on customers, that must be configured outside of the application, including:

  • Automatic User Provisioning
  • Test Environment
  • Franchise Support

All of these features are described below in greater detail.

Supported Features

Our system supports several features beyond basic login. 

Automatic User Provisioning

The Envysion SSO system is capable of dynamically creating users as part of the login flow if sufficient claims are available on the IdP payload. Each of our claims can be configured to read from any assertion in the SAML payload.

Required claims

  • username: Represents the user’s internal Envysion user name. This may be the same as their email.
  • email: The user’s email address.
  • first_name: The user’s first name
  • last_name: The user’s last name
  • site_list OR all_sites: The site_list claim is a comma-separated list of store codes to grant the user access to. A custom access list for this user will be created based on this claim. If the user needs access to all sites, the all_sites claim should contain a “1” or “true” value, and the site_list claim will be ignored. 

Optional claims

  • role_name: The name of the role to assign the user. If the role name does not exist, the user will not be allowed to log in. At least one of role_name or default_role is required.
  • display_name: The name displayed on the menu, when the user has logged in.

Other configuration

  • default_role: The name of a role to assign to a user if there is no role_name claim in the assertion. At least one of role_name or default_role is required.

Test Environment

We support setting up SSO within our test environment as well (never dev). This is useful if the user is experimenting with the Automatic User Provisioning feature.


We can perform a soft-launch of an SSO integration. If a soft-launch is enabled, from the Envysion login page, the user would continue to supply their Envysion username and password credentials. However, users would be able to log in using SSO from the customer’s IdP login page. This gives customers time to make an announcement to their users about the change.

Franchise Support

Authentication at one Envysion domain can be delegated to a different domain’s SAML configuration. This is most common for franchisee who leverage a corporate single sign-on system, already integrated with Envysion. If such a system is in place with your organization, please inform your Sales Engineer. 

SSO Bypass

When a domain is set up for Single Sign-On, a list of users can be provided that will continue to use the username/password credentials. It is recommended that customers have at least 1 user set up in our bypass list. 

Was this post helpful?