Setting up SAML 2.0 with an identity provider will enable single sign-on for your help center.

Once authenticated in one application, your users will be able to access the help center without having to authenticate again (as long as their session is not expired).

Choosing SAML as your site authentication method is ideal if you already have an existing user directory that you can integrate with. You will avoid managing additional user credentials just for your help center and you will be able to provide a much more seamless navigation experience for your help center visitors.

What You Need to Know Before Setting up SAML Authentication

Before starting the process of setting up SAML authentication, please make sure you meet the following requirements:

  • You have connected a custom domain to the Viewport site for which you want to set up authenticated access

  • You have an account with an identity management service or access to an identity management tool that supports the SAML protocol. More details below.

SAML is an open standard for Single Sign-On (SSO). The setup of SAML SSO in Scroll Viewport will involve two parties:

  • the relying partner or service provider (in this case Scroll Viewport)

  • the authenticating party or identity provider (in this case the tool or service you select to manage the identities)

The tool or service you choose as an identity provider will need to support the SAML protocol. This could be a service like Okta, OneLogin or Salesforce, a self-built solution or an Active Directory System with a connection through SAML.

Please note that some identity providers are currently not supported as they only allow to sign the response or assertion, not both. Both signatures are required for a successful setup in Scroll Viewport.

The only exceptions to this rule are Auth0 or Google, which will work if only the response is signed.

Setting up SAML Authentication

Requirement: Setting up an Identity Provider

Before you can enable SAML authentication for your Viewport site, you will need to make sure that you have a working setup with an identity provider of your choice. This includes:

  1. An account with an identity management service or access to an identity management tool (e.g. self-built) that supports the SAML protocol. Find a list of all products services that support SAML.

  2. An existing directory with users and/or groups of users

From the identity management tool you will then be able to connect Scroll Viewport as an application.

The Setup in Viewport

Starting the SAML Setup

By default, all Viewport sites are set to public access. You can set up authenticated access with SAML under Site settings:

  1. Select your site in your site overview screen (if you have multiple sites).

  2. Click Settings from the top right of the single site overview screen.

  3. Click Set up authentication under Site access.

  4. Select SAML as your authentication method:

    Step 1 of the SAML authentication setup process
  5. Click Next

Copying the SAML values

Scroll Viewport will generate the following values for you:

  • Relying party identifier (might also be called Entity ID or Audience ID in your identity provider configuration)

  • Assertion consumer service URL (ACS URL)

Click the Copy icon next to the two fields and paste the values into your identity provider setup.

Once the setup in your Identity Provider Tool (see next step) is completed, you will have to come back to your authentication settings in Scroll Viewport, click Next and insert the metadata.

Pasting the Identity Provider metadata

To complete the setup, you will need to get the Identity Provider metadata that your Identity Provider provides to you and paste it into the Viewport configuration.

Step 3 of the SAML authentication setup process

The metadata is usually provided as an XML file from your configuration setup screen.

Make sure you download and open the XML file and copy the metadata from the file, not directly from the view in your browser. Browsers will typically leave out parts of the metadata that are needed by Scroll Viewport.

The Setup in your Identity Provider Tool

Please note that the setup process and terms used in this guide might differ from the ones used in your tool of choice.

Connecting Viewport as an Application

To establish a link between your identity provider and Scroll Viewport, you will first need to create a new app integration in your identity provider setup.

When connecting or adding Viewport as an application, ensure the following:

  • Select SAML/SAML 2.0 as the sign-on method.

  • If asked for an app or display name, choose a name that helps you identify the application and that is meaningful to your end-users (the name will also be used in your login page).

  • Assign the app to users or user groups to define who will be able to access the Viewport site. You might need to create those users or user groups first and create the assignation to the app from there.

Pasting the SAML values

Find the relevant fields in your tool and paste the values provided by Viewport into your configuration:

  • Relying Party identifier (in some tools it might also be called Service Provider Entity ID or Audience ID)

  • Assertion consumer service URL (ACS URL)

Before saving the tool’s default configuration, make sure that the configuration includes the following settings:

Setting

Value

Single Sign-on URL

Same as Assertion consumer service URL

Recipient

Same as Assertion consumer service URL

Response

Signed

Assertion Signature

Signed

Exception: Auth0 and Google won’t allow you to sign both response and assertion. For those IdPs, the assertion can be left unsigned.

Login URL

Your Viewport URL

Depending on your identity provider, you might be able to further customize and style the appearance of the login page. Please refer to your identity provider for more information.

Removing SAML Authentication

You can remove authenticated access with SAML under Site settings:

  1. Select your site in your site overview screen (if you have multiple sites).

  2. Click Settings from the top right of the single site overview screen.

  3. Click Remove authentication under Site access.

If you want to set up site authentication again, please note that your site might become unavailable momentarily and that it might take a few minutes before the authentication option is available again. Close and re-open the dialog to check the status.