Active Directory Federation Services (ADFS) is a module built on top of Active Directory Windows Server edition and is designed to enable certain Single-Sign-On scenarios using a number of protocols. ADFS supports OpenID Connect, which is what SmartSurvey uses for its SSO protocol and setting it up is not too difficult.
Pre-requisites
This article assumes you have installed ADFS onto a suitable server and understand how to make the https port on the server accessible to the SmartSurvey production system - in most cases, you will open this endpoint to the public internet, otherwise you will need to whitelist a number of IP addresses from our production environment.
Single-Sign-On for SmartSurvey is available as an option on Enterprise accounts.
Add a new Application Group
In ADFS, under Application Groups, click to add a new Application Group and choose "Server application accessing a web API" as the type giving it a suitable display name and click Next.
Make a note of the displayed "client identifier" and for the redirect uri, use the value from the SSO section of My Account in the SmartSurvey application. If you do not have access to the SSO section, you will need to contact your Account Manager to assist with setting it up. You can also add the client identifier into the Client Id box.
With the redirect uri entered into the list in ADFS, click Next.
Choose to "Generate a new secret" and copy the value into your SSO account page on SmartSurvey into the Secret text box. Note that you cannot recover this value later from ADFS if you do not copy it somewhere. With the value recorded or copied, click Next.
In the Identifier box, use the home URL of SmartSurvey (https://app.smartsurvey.co.uk/) as the value to add to the list and click Next.
On the next screen you can choose how you wish to permit people to have access to SmartSurvey via your AD. You can simply allow anyone with an account on your AD to login (the default) but if you have limited users etc. you might want to restrict access to a specific AD group. Click Next.
On the application permissions page, you should select openid, email, profile and allatclaims as the permissions and then click Next.
Click Next on the summary page to create your new application group and then click Close.
Map AD data to returned claims
By default, the data needed for SmartSurvey to login is not returned from ADFS and these claims need to be manually mapped using a rule.
Double-click your new application group and double-click the "Web API" entry in the list. Go to the Issuance Transform Rules tab and click to add a new rule, choosing "Send LDAP Attributes as Claims" and press next.
Give the rule a display name and choose the relevant attribute store (which might just be a single Active Directory entry). In the mapping list, map E-Mail-Addresses to E-Mail Address, Surname to Surname and Given-Name to Given Name. Click Finish and then OK/OK to exit from the edit dialogs.
Email Verification
By default, ADFS does not return the "email_verified" claim when someone logs in. When this happens, SmartSurvey will perform its own verification of the email address to ensure valid entry to the account. If you are confidant that only authorised people have access to your AD accounts, then you can hard-code this claim to bypass email verification at SmartSurvey.
To do this, double-click the application group and then double-click the Web API entry and go to the Issuance Tranform Rules tab. Click to add rule and choose Send Claims Using a Custom Rule as the type. Click Next. Give the rule a suitable name like "Set email verified" and in the content, enter the following:
=> issue(Type = "email_verified", Value = "true");
Click Finish, OK and OK to exit the edit dialogs.
Testing
If you return to the SSO setup page and enter the following in the Discovery origin box:
https://your.server.hosturl/adfs
and then set the threshold and support data that you want to display to your users. Currently, if you test adfs in this page, you might see an error message that it returned 0, which is a current known issue when calling other hostnames from within a browser. This error won't prevent you from saving and using the SSO system. If you want to make completely sure, open the browser developer tools and look for the XHR/Ajax selection in the network tab. You should be able to see the response correctly come back from your server as a json document.
If you see an error other than 0, then you will need to work out why the SmartSurvey browser cannot access the adfs discovery document, probably a firewall issue or something in ADFS is not running to provide the document to the outside world.
You will see your unique login url, you can open this in an incognito window to avoid interfering with the account you are already logged into. This should show you an ADFS login screen and remember that you need to login with the account name and not with the email address that might be associated with that account.