Single Sign On Provider Setup

Conveyor provides Single Sign On (SSO) for Growth and Enterprise tier customers to control access to their Conveyor Organization’s resources through a separate, single authentication service. This empowers those customers to centrally manage Conveyor from their primary SSO provider, also called an Identity Provider (IdP).

Conveyor supports the industry-standard SAML 2.0 protocol for using an external provider. Most SSO Providers support SAML, including Okta and Google’s GSuite. SAML provides a secure method to transfer identity and authentication information between the SSO provider and Conveyor.

Each Organization may have only one SSO provider configured. Many SSO providers allow for federation to other SSO providers using SAML. For example, allowing Google GSuite to provide login to Okta. If you need to support multiple SSO providers, you can use federation to enable login from the other providers to the one configured with Conveyor.

To use SSO, you must configure both the SSO provider and Conveyor with metadata related to the SAML protocol. This documentation covers the process in general terms applicable to any SSO provider. Then, it covers in detail the setup process in Okta.

📘
Interested in enabling SSO?
Only Account Owners for Organizations with Growth and Enterprise subscriptions can currently enable SSO. Please contact your account representative or Conveyor support for more information about enabling SSO features on your Organization.

Generic SSO Provider Configuration

To setup the SSO provider, it needs the following four pieces of information unique to Conveyor. The values for each are available in your Organization’s Single Sign On settings page, accessible only by Account Owners, if you do not yet have SSO configured.

You should reference your SSO Provider’s walkthrough for setting up a SAML application alongside this documentation.

Single Sign On URL

The SAML protocol relies on a series of redirects to pass information back and forth between the SSO provider and Conveyor. The SSO provider needs the Conveyor URLs set ahead of time to securely complete this process. This URL is also called the Assertion Consumer Service (ACS) or SAML Consume URL by some providers.

Google uses the term SSO URL to refer to the redirect URL on their server. This value is called the ACS URL in their guide.

This is the first URL provided on the Conveyor settings page. It should end in saml/consume

Audience URI

This is a unique identifier used by the SSO provider to match incoming login requests to your specific account with them. This may also be referred to as the Service Provider (SP) Entity ID.

Google uses the term Entity ID to refer to this value in their guide.

This is the second value on the Conveyor information page. It should end in saml/metadata

📘
Automating SSO Setup
This URL provides all the metadata needed by an SSO provider to setup SAML for your account with Conveyor. If your SSO provider, has an option to use this metadata, you can provide this URL to automate setup. Neither Okta nor Google allow for setup this way.

Name ID Format

SAML requires a special “name” field that is to uniquely identify the same user in both the SSO Provider and Conveyor. Conveyor requires that this field be the user’s email address. That is how users are uniquely identified in our system.

There are several standard formats for this field. If your SSO supports the EmailAddress, emailAddress, or Email formats, one of those should be selected. If not, the Unspecified format, should be used. If none of those are available, Persistent format is also acceptable.

Some SSO providers so not require manual setting of the Name ID format and will automatically assign one based on the attribute selected in the next step.

Application Attribute or Name ID Attribute

This tells the SSO provider want information to include as the required Name ID. The information it stores about your users is generally called attributes but may also be called fields or other names. This must be set so that is the same email address as used on the Conveyor account. Most SSO providers have an email attribute that can be selected here. If not, you may have to create a custom attribute in your SSO provider.

You may optionally configure the SSO provider to send additional attributes, such as the user’s full name. Conveyor currently ignores any additional attributes sent.

🚧
Make sure emails exactly match
If the email address sent by the SSO provider does not exactly match the email address associated with their Conveyor account, the user will not be able to login via your SSO provider. If users are having issues logging in, you should confirm those email addresses match.

Other configuration fields

Your SSO provider may have many other configuration fields. You should be able to leave these at their default settings. We provide some general guidance if you do want to customize your settings. However, your SSO provider’s documentation should supersede any information here as these values can vary from provider to provider.

Default RelayState or Start URL: This allows you to set a default page on Conveyor that your users will be taken to when logging in. Details on this field are below.
Encryption, Signature, Digest Algorithms: Prefer options with
SHA-256 over those with SHA-1.

RelayState values

By default, we direct the user to the product they were using when they started logging in. You can override that behavior by setting a RelayState value in your SSO provider. This will change the all users will be directed to upon a successful SSO login.

account - direct users to organization account management (https://account.conveyor.com)
comply - direct users to the main app (https://app.conveyor.com)
rooms_preview - direct users to a preview of your room (https://app.conveyor.com/my-room/preview)
vendor_trust - direct users to the vendor trust side of the application (https://app.conveyor.com/vendor-trust)

Conveyor SSO Configuration

Once your have completed the SSO provider configuration, they should provide you with XML Metadata either as a URL or via file download.

Return to the Single Sign On settings page for your Organization, where you copied the values for setting up your SSO provider. Then click on the “Configure an SSO Provider”

In the resulting modal box, enter either the URL or the XML contents of the file. You only need to enter one. If you enter both, Conveyor will use the URL to retrieve the metadata. Conveyor will then complete our setup automatically.

🚧
Enable HTTPS
When you retrieve the metadata, you should ensure the SSO provider’s site is an HTTPS site. This ensure that the metadata is not tampered with during download. If an attacker could alter that metadata, they could substitute their own information and hi-jack your SSO configuration.

Once processing is complete, you should see data from your SSO provider. You can confirm these with the SSO provider’s website to ensure they are correct.

You can optionally enable additional SSO feature within Conveyor at this point:

Okta Walkthrough

As a complement to the generic guide, we will present a detailed walkthrough for configuring Okta as an SSO provider to a Conveyor Organization.

Click Applications in the main menu.
Click Add Application and then Create New App.

Setup a Web application with SAML 2.0

The default platform should be Web. If not, select that option.
Select SAML 2.0 as the Sign on method.

Create SAML Integration

Enter Conveyor or another name of your choice.
You may download and use our logo for an image.

Enter SAML Settings from Conveyor Single Sign On Settings Page

Open the Organization settings in Conveyor Dashboard
Select the Single Sign On settings in the sidebar

Copy and paste the Single Sign On URL
Copy and paste the Audience URI
Select EmailAddress for the Name ID format dropdown
Select Email in the Application username dropdown
Leave all other values as their defaults
Click Next

Fill-in Okta’s Feedback Page

Okta will prompt you for feedback on the SAML setup.
Select “I’m an Okta customer adding an internal app”
Optionally, provide additional feedback.
When complete, click Finish.

Copy URL for Identity Provider metadata

Copy the link for Identity Provider metadata

Enter metadata URL in Conveyor SSO Settings

Open the Single Sign On settings page for your Organization in Conveyor
Click “Configure an SSO Provider”
Paste the metadata URL into the box

Assign Users to Conveyor

Follow Okta’s guide to assign users to the new application.

Frequently Asked Questions

What happens if my SSO provider suffers downtime?
Users can continue to use their Conveyor credentials to login even after SSO is enabled. If you also enabled SSO enforcement then your Account Owners can still login with their Conveyor credentials and disable enforcement until the SSO provider is back online.

Does Conveyor offer automated provisioning of SSO users?
Yes! We support user provisioning via SCIM. Please see our guide on here on how to enable it.

Does Conveyor support Single Logout?
We do not at this time. If this would be helpful for your Organization, please let us know.

How can I learn more about SAML?
There are many good references available on the Internet. We suggest the following starting points:

Single Sign On Provider Setup