Printed from: SurveyCTO Product Documentation
Source URL: https://docs.surveycto.com/04-monitoring-and-management/01-the-basics/05.external-authentication.html
Last updated: 2024-03-27
  1. Home
  2. Monitoring and management - The basics

Configuring external authentication (single-sign-on, or SSO)

Previous Next

Rather than setting user passwords directly in SurveyCTO, you can configure SurveyCTO to authenticate some or all users via an external authentication provider. SurveyCTO currently supports authentication via Google, Okta, or Microsoft Azure Active Directory – though other providers may be supported via the OpenID Connect authentication standard.

Here's how it works. You always manage your SurveyCTO user accounts (logins) within SurveyCTO, including managing which users are in which roles. Normally, this includes managing users' passwords so that SurveyCTO can securely authenticate each user. But, if you configure external authentication for one or more email domains, then you can basically outsource the password/authentication part to another system. You would only do that if you already had some kind of enterprise authentication provider like Google (typically GSuite), Okta, or Microsoft Azure Active Directory. So, for example, at SurveyCTO we authenticate the @surveycto.com domain via Google, because that's where we manage all of our official email accounts.

Once you configure external authentication for a domain, SurveyCTO will stop worrying about passwords for the users in that domain, and will instead hand off the authentication process to the provider you configure. This can make your SurveyCTO system more secure, because those users won't need to worry about managing a separate password, your external provider might provide strong, multi-factor authentication options, and, importantly: when those users leave your organization, there is a single place where you can disable their logins. If we're authenticating @surveycto.com logins via Google, for example, and we disable one of those logins in Google, then the user will instantly be unable to log in to SurveyCTO as well, even if their user account still exists on the SurveyCTO server.

Before we get to how to set up external authentication, there are a few more high-level details to consider:

  • SurveyCTO Collect on mobile devices does not support external authentication. What this means is that you will need to create separate logins for data collection that are not within the domain(s) configured for external authentication. (Data-collection-only users aren't even required to have an email address, so you can easily add users outside your externally-authenticated domains.)

  • Once you configure external authentication, you may want to require that your more powerful or sensitive logins (those in administrative or form-management roles, or just those with access to sensitive data) be authenticated externally. To do so, all you need to do is edit any user role and check the box to require external authentication.

Authenticating with Google

Authenticating domains with Google is easy, because you can use SurveyCTO's default settings and credentials to interact with Google's systems. (See the instructions further below if you would prefer to configure Google authentication manually.)

To authenticate one or more domains with Google using SurveyCTO's default settings, just do the following:

  1. Go to the Configure tab of your SurveyCTO console, scroll down to Server settings, and choose Login. Then scroll down and select to edit the external authentication settings, under the password requirements.

  2. Enter the domain(s) that you would like to authenticate (e.g., "@surveycto.com" or "@surveycto.com, @dobility.com"), then click Next.

  3. On the next page, select Use default settings (authenticate with Google), then click Next again.

  4. Then enter an email address within one of the covered domains and click to test the external authentication. This should pop up an authentication window that you can use to authenticate.

  5. Presuming that the authentication test succeeded, click Save to save your settings.

  6. Finally, log out and log in again, to confirm that everything is working as expected. If you have trouble logging in now – or at any point in the future – there will be an option to have a "rescue link" emailed to you, which will let you log in and fix the configuration.

Manually configuring external authentication

If you don't want to use the default Google integration described above, you'll need to follow two basic steps to set up external authentication:

  1. First, you'll need to configure your external provider to allow SurveyCTO users to authenticate. As part of this process, you'll be able to retrieve the OpenID Connect configuration settings that you'll need to set on the SurveyCTO side.

  2. Then, you'll need to configure the SurveyCTO server to authenticate one or more domains using that provider.

This kind of configuration requires administrator access to both SurveyCTO and the external provider, and it is a bit technical. Misconfiguration can also interfere with users' ability to log in to SurveyCTO, which can be extremely disruptive. For these reasons, it is generally best to embark on such a configuration only if and when you have the requisite IT skills on-hand.

For the steps necessary to configure external authentication, please scroll down to the appropriate section, depending on your external provider.

Use your SurveyCTO server name as "servername"
Your server name is the x in the x.surveycto.com you see in the browser address bar after you log in to your server console. Wherever you see "servername" in the instructions below, you will need to use your server name.

Manual integration with Okta

First, configure the Okta side and copy the client ID, client secret, and organization URL:

  1. Log in to the Okta console.

  2. Select to add a new application, then click Create New App to create a new application integration. When prompted, select "Web" as the Platform and "OpenID Connect" as the Sign on method.

  3. On the next screen to create the OpenID Connect integration, enter "SurveyCTO" as the Application name and then, for the Login redirect URI, enter: https://servername.surveycto.com/console/openid_login

  4. From the new application's General Settings screen, you will find both a Client ID and a Client secret. Copy both to a safe location, as you will need them when setting up the SurveyCTO side.

  5. Now go to Okta's Developer Console and find the Org URL in the top-right. Note that URL, as you will need it to configure the SurveyCTO side.

Then, configure the SurveyCTO side as follows:

  1. Go to the Configure tab of your SurveyCTO console, scroll down to Server settings, and choose Login. Then scroll down and select to edit the external authentication settings, under the password requirements.

  2. Enter the domain(s) that you would like to authenticate (e.g., "@surveycto.com" or "@surveycto.com, @dobility.com"), then click Next.

  3. On the next page, select Use my own configuration (advanced).

  4. For Name of the authentication provider, enter the name of the external provider that users will see (e.g., "Okta").

  5. For Client ID, enter the client ID that you earlier copied from Okta.

  6. For Client secret, enter the client secret that you earlier copied from Okta.

  7. For Authentication endpoint, enter the following, replacing ORGURL with the Org URL you copied earlier from Okta: ORGURL/oauth2/v1/authorize?prompt=login

  8. For Token endpoint, enter the following, replacing ORGURL with the Org URL you copied earlier from Okta: ORGURL/oauth2/v1/token

  9. For User-info endpoint, enter the following, replacing ORGURL with the Org URL you copied earlier from Okta: ORGURL/oauth2/v1/userinfo

  10. For Revocation endpoint (optional), enter the following, replacing ORGURL with the Org URL you copied earlier from Okta: ORGURL/oauth2/default/v1/revoke

  11. Then enter an email address within one of the covered domains and click to test the external authentication using the settings you just entered. This should pop up an authentication window that you can use to authenticate.

  12. Presuming that the authentication test succeeded, click Save to save your settings.

  13. Finally, log out and log in again, to confirm that everything is working as expected. If you have trouble logging in now – or at any point in the future – there will be an option to have a "rescue link" emailed to you, which will let you log in and fix the configuration.

See Okta's documentation on OpenID Connect integration for more details.

Manual integration with Microsoft Azure Active Directory

First, configure the Microsoft side and copy the client ID, client secret, and directory ID:

  1. Log in to the Azure portal and select Azure Active Directory.

  2. Click to register a new application under App registrations.

  3. When prompted, enter "SurveyCTO" as the Name, "Web app / API" as the Application type, and then, for the Sign-on URL, enter: https://servername.surveycto.com/console/openid_login

  4. From the Registered app panel that appears, you will find an Application ID. Copy that to a safe location, as that will be the "client ID" that you will need on the SurveyCTO side.

  5. Still within the Registered app panel, click Settings and then Keys. There, add a new password with "Client secret" as the description and an expiration date appropriate to your authentication-management policies. Once you click Save, note the value that displays for the password and copy that to a safe location, as that will serve as the "client secret" that you will need on the SurveyCTO side.

  6. Go back to the main Azure Active Directory screen and click Properties. Copy the Directory ID that you find there, as you will also need that to configure the SurveyCTO side.

Then, configure the SurveyCTO side as follows:

  1. Go to the Configure tab of your SurveyCTO console, scroll down to Server settings, and choose Login. Then scroll down and select to edit the external authentication settings, under the password requirements.

  2. Enter the domain(s) that you would like to authenticate (e.g., "@surveycto.com" or "@surveycto.com, @dobility.com"), then click Next.

  3. On the next page, select Use my own configuration (advanced).

  4. For Name of the authentication provider, enter the name of the external provider that users will see (e.g., "Microsoft Azure Active Directory").

  5. For Client ID, enter the client ID that you earlier copied from Azure (they called it Application ID).

  6. For Client secret, enter the client secret that you earlier copied from Azure (they called it a password).

  7. For Authentication endpoint, enter the following, replacing DIRECTORYID with the Directory ID you copied earlier from Azure: https://login.microsoftonline.com/DIRECTORYID/oauth2/authorize?prompt=login

  8. For Token endpoint, enter the following, replacing DIRECTORYID with the Directory ID you copied earlier from Azure: https://login.microsoftonline.com/DIRECTORYID/oauth2/token

  9. For User-info endpoint, enter the following, replacing DIRECTORYID with the Directory ID you copied earlier from Azure: https://login.microsoftonline.com/DIRECTORYID/openid/userinfo

  10. You can just leave Revocation endpoint (optional) blank.

  11. Then enter an email address within one of the covered domains and click to test the external authentication using the settings you just entered. This should pop up an authentication window that you can use to authenticate.

  12. Presuming that the authentication test succeeded, click Save to save your settings.

  13. Finally, log out and log in again, to confirm that everything is working as expected. If you have trouble logging in now – or at any point in the future – there will be an option to have a "rescue link" emailed to you, which will let you log in and fix the configuration. (If you set your client secret to expire, then expect authentication to stop working at that point of expiration. At that point – or ideally before! – you will want to reset the credentials.)

See Microsoft's documentation on OpenID Connect integration for more details.

Manual integration with Google

Automatic Google integration available
See the Authenticating with Google sub-section toward the top of this help topic for details on painlessly integrating with Google. That integration uses shared SurveyCTO credentials to interact with Google, however, and you are free to manually integrate with your own credentials if you wish. Just follow the instructions below.

First, configure the Google side and copy the authentication client ID and client secret:

  1. Log in to the Google API console.

  2. Create a new project to hold SurveyCTO-related authentication credentials.

  3. Select the new project. On the left side of the screen, click the Credentials link, then select the OAuth consent screen tab and type "SurveyCTO" in the Application name field. In the same tab, under Authorized domains, enter "surveycto.com".

  4. Also within the project's Credentials tab, click to create new credentials with OAuth client ID as the type of credentials. When prompted, select "Web application" as the Application type, enter "SurveyCTO" as the Name, and, for the Authorized redirect URI, enter: https://servername.surveycto.com/console/openid_login

  5. Once you click to create the credentials, Google will give you a client ID and a client secret. Copy both to a safe location, as you will need them when setting up the SurveyCTO side.

Then, configure the SurveyCTO side as follows:

  1. Go to the Configure tab of your SurveyCTO console, scroll down to Server settings, and choose Login. Then scroll down and select to edit the external authentication settings, under the password requirements.

  2. Enter the domain(s) that you would like to authenticate (e.g., "@surveycto.com" or "@surveycto.com, @dobility.com"), then click Next.

  3. On the next page, select Use my own configuration (advanced).

  4. For Name of the authentication provider, enter the name of the external provider that users will see (e.g., "Google").

  5. For Client ID, enter the client ID that you earlier copied from Google.

  6. For Client secret, enter the client secret that you earlier copied from Google.

  7. For Authentication endpoint, enter: https://accounts.google.com/o/oauth2/v2/auth?prompt=select_account

  8. For Token endpoint, enter: https://www.googleapis.com/oauth2/v4/token

  9. For User-info endpoint, enter: https://www.googleapis.com/oauth2/v3/userinfo

  10. For Revocation endpoint (optional), enter: https://accounts.google.com/o/oauth2/revoke

  11. Then enter an email address within one of the covered domains and click to test the external authentication using the settings you just entered. This should pop up an authentication window that you can use to authenticate.

  12. Presuming that the authentication test succeeded, click Save to save your settings.

  13. Finally, log out and log in again, to confirm that everything is working as expected. If you have trouble logging in now – or at any point in the future – there will be an option to have a "rescue link" emailed to you, which will let you log in and fix the configuration.

See Google's documentation on OpenID integration for more details, or this page for the current list of Google authentication endpoints.

Manual integration with another provider

The SurveyCTO team has only tested integration with the specific providers discussed above. If you'd like to try configuring another system that supports the OpenID Connect standard, you're free to do so – but it is likely to require a bit more experimentation, and the SurveyCTO support team will be of limited assistance. To guide your work, you can review the instructions for other providers above.

Previous Next
Support Center