Set Up SAML Single Sign-On
Setting up SAML 2.0 with an identity provider will enable single sign-on for your help center.
Once authenticated in one of your applications, your users will be able to access your Scroll Viewport help center without having to authenticate again (as long as their session is not expired).
Choosing SAML as your site’s 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 your Scroll 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 party 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 Scroll Viewport site, you will need to make sure that you have a working setup with an identity provider of your choice. This includes:
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.
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 Scroll Viewport
Starting the SAML setup
By default, all Scroll Viewport sites are set to public access. You can set up authenticated access with SAML under Site settings:
Select your site in your site overview screen (if you have multiple sites).
Click Settings from the top right of the single site overview screen.
Click Set up authentication under Site access.
Select SAML as your authentication method:
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 Scroll Viewport configuration.
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 Scroll 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 Scroll 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 Scroll 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 Scroll 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:
Select your site in your site overview screen (if you have multiple sites).
Click Settings from the top right of the single site overview screen.
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.
Switching SAML Authentication
If you would like to keep your SAML authentication but switch your identify providers, please make sure to take your site offline first. This will ensure that your site remains private during the switch.
Select your site in your site overview screen (if you have multiple sites).
Click ••• → Take offline from the top right of the single site overview screen. Your site will be unavailable until you complete all steps.
Click Settings → Remove authentication (under Site access). You will see a ‘removal in progress’ message pop up. This removal should take less than 10 minutes.
Click Set up authentication. The completion will take a few minutes.
Click Generate Preview → Go live once done. Your authenticated site will be live again with your new identity provider.
Accessing a Site with Single Sign-On
After successful setup of SAML single sign-on, any user who accesses your site and is already logged on in related applications, will be seamlessly redirected to your help center.
All other users will be directed to a login page and asked to enter valid credentials (usually a username/email and password) to access your site. Users who attempt to log in without valid credentials will not be able to access your site and see an error message.
The login page is provided and styled by your identity provider and might look as follows:
Accessing an authenticated site will work exactly the same way when using the in-app help parameter.
Once your user accesses the site, Scroll Viewport will store a session cookie with signed values in their browser.
The session cookie is deleted after the browser session is completed or the browser closed. Independent of the duration of the browser session, the signed values will expire after one hour. After that, the user will need to log in again to access the site.