Active Directory Single-Sign-On with LiveSurvey

What is it?

LiveSurvey offers single-sign-on (SSO) authentication via Active Directory (AD). This provides the ability for an organization's staff to browse to an intranet site and be automatically logged into LiveSurvey based on their intranet credentials. To use SSO, LiveSurvey needs a way to indirectly communicate with a credit union's Active Directory system. To accomplish this, we provide a simple ASP.NET 4.5 website to be hosted on the credit union's local intranet. The following occurs when a user browses to this intranet site:

  1. Windows authentication with Active Directory is used to obtain the current user's username, name, email address, title, and department name. This is the only user information given to LiveSurvey - no passwords or other sensitive information is ever exchanged.
  2. These fields are placed in an encrypted token. The token is encrypted using the organization's key, which is provided by LiveSurvey.
  3. The user is redirected to 'subdomain.livecusurvey.com', where 'subdomain' is specific to the organization. LiveSurvey uses the fields in the token to authenticate and identify the user and to enable the appropriate functionality inside the website.  

How do I install it?

LiveSurvey provides a ZIP file containing two directories:

  • Source which contains the source code of the SSO website
  • Publish which contains the compiled version of the site, to publish in IIS

LiveSurvey requires the following:

  • The organization is a LiveSurvey client, already set up with a LiveSurvey subdomain
  • The organization has a Windows Server with IIS capable of running an ASP.NET website with .NET CLR version 4.0 or above
  • A website can be hosted on this server with:
    • Permission to access Windows Authentication and Active Directory
    • A new DNS entry to point staff to the website

The following steps must be taken to enable Single-Sign-On. LiveSurvey support can assist with this process.

Installation Video

LiveSurvey Setup - SSO Tutorial

Installation Steps
  1. Create a new directory to contain the website. For instance, create C:\inetpub\surveys.yourdomain.com1
  2. Extract the Publish folder from the zip and place its contents2 into the new directory

  3. IMPORTANT: Once you have copied the files to C:\inetpub\surveys.yourdomain.com, the SsoSettings.config file must be modified before starting the site. Its location is C:\inetpub\surveys.yourdomain.com\SsoSettings.config

    • Here is what the SsoSettings.config looks like:

      <appSettings>
  <add key="Url" value="https://yoursubdomain.livecusurvey.com/account/" />
  <add key="Key" value="123456789key" />
</appSettings>

    • Replace yoursubdomain in the 'Url' value with the LiveSurvey subdomain for your organization.

    • Input the 'Key' value. This is a value provided by LiveSurvey3. This key is known by both LiveSurvey and the organization; it is used to encrypt and decrypt the token containing the user's information.

  4. Create an IIS website named surveys.yourdomain.com with the following settings:

    • Point its physical path to C:\inetpub\surveys.yourdomain.com
    • Bind it to https://surveys.yourdomain.com domain
    • Use the organization domain's SSL certificate for HTTPS as appropriate (for instance, it may be a wildcard *.yourdomain.com certificate).
    • Set the IIS Application Pool to .NET 4.0 or greater
    • Change the IIS Application Pool Identity from ApplicationPoolIdentity to NetworkService to ensure that it has read access to Active Directory and Windows Authentication.
  5. Add a DNS entry to bind surveys.yourdomain.com to the server's IP address.

Once the steps above are complete, staff members can browse to the intranet URL and be redirected to yoursubdomain.livecusurvey.com. If you encounter any problems, contact the team at LiveSurvey.

To test the installation and view the data that LiveSurvey receives from Active Directory, browse to surveys.yourdomain.com/ping.

  • 1 This is an example URL; the path of the website on the server and the intranet URL of the website may be customized by the organization.
  • 2 Alternately, build and publish the website with the Visual Studio 2015 solution provided in the Source folder.
  • 3 This key can have an arbitrary value, but both LiveSurvey and the organization must know it. The organization may select its own key and communicate it to the LiveSurvey team.

Troubleshooting

Problem: When I browse to the /ping page, each time I enter my password, I get prompted for my credentials again.

First, verify that your username and password are valid in your Active Directory store, and that your user is not locked. Next, verify that the site is running on HTTPS, and that the certificate is trusted by your computer. Last, be sure to browse from a computer that is not hosting the Single-Sign-On website.

Problem: When I browse to the /ping page, I see a yellow screen with Runtime Error at the top.

To view the error details, add the line <compilation debug="true"/> after the <system.web> opening tag of the Web.Config file inside the site folder. Be sure to remove this line after installation is complete, for optimal performance.

Problem: When I debug the /ping page, I see the error, The specified directory service attribute or value does not exist.

Open the Application Pools list in IIS. Right-click the site's pool, and select Advanced Settings. Ensure that the site is running under the Network Service user. If this does not resolve the issue, create a new user in Active Directory, and run the site under this user's credentials. Give the new user READ access to all containers within Active Directory.

Problem: The /ping page works, but some of my users get a 401 Not Authorized response from LiveSurvey.

  • If everyone gets a LiveSurvey 401 Not Authorized response, check your Key in SsoSettings.config to make sure it is correct. There should be no extra spaces in the value, and the value is case sensitive.
  • If a user gets a 401 Not Authorized response, but /ping works, check the EmployeeKey value of the response. This value should not be null, as it is required for authorization with LiveSurvey. If <add key="EmployeeKeyIsEmailAddress" /> is in SsoSettings.config and your users do not have email addresses, you can remove this line, restart the site and try again.