- Select a custom subdomain for your company in the Syncplicity web site, or at least have one in mind
- Configure an email address for each one of your users’ AD profiles
- Add Syncplicity as a Relying Party Trust
- Configure Syncplicity
Follow these detailed steps:
Configuring ADFS
These instructions assume that you have selected a custom subdomain for your company in the Syncplicity web site, or at least have one in mind. This subdomain will be the point of entry for your SSO-enabled users, and will be our means of determining how to authenticate your users. We recommend that the subdomain you choose be representative of your company name. It must be unique among Syncplicity’s customers, and must be at least four characters long.
These instructions also assume that your users’ AD profiles:
- Have an email address configured
- This email address is the same as the address identifying the users’ Syncplicity accounts
Adding Syncplicity as a Relying Party Trust
1. In ADFS 2.0 Management, create a new Relying Party Trust (RPT).
2. At the ‘Select Data Source’ screen, select the option labeled “Enter data about the relying party manually’ and click ‘Next’.
3. At the ‘Specify Display Name’ screen, give the RPT a descriptive and unique name (we suggest ‘Syncplicity’), and click ‘Next’.
4. At the ‘Choose Profile’ screen, select the ‘AD FS 2.0 profile’ option to enable SAML 2.0 authentication; click ‘Next’.
5. At the ‘Configure Certificate’ screen, there’s nothing to do; click ‘Next’.
6. At the ‘Configure URL’ screen, check the box labeled ‘Enable support for the SAML 2.0 WebSSO protocol’, and enter the SAML 2.0 SSO service URL.
This URL is unique to your company; it is:
https://<your-custom-subdomain>.syncplicity.com/Auth/AssertionConsumerService.aspx
In other words, if your custom subdomain was ‘mycompany’, the URL would be:
https://mycompany.syncplicity.com/Auth/AssertionConsumerService.aspx
Once this is entered, click ‘Next’.
7. At the ‘Configure Identifiers’ screen, add a ‘Relying party trust identifier’. This is a bit of text (usually a URL) that serves as a name that will accompany all valid authentication requests. This name is also unique to your company; it is:
https://<your-custom-subdomain>.syncplicity.com/sp
Following the prior example of a company with ‘contoso’ for a subdomain, the identifier would be:
https://mycompany.syncplicity.com/sp
Once you’ve typed in this identifier, click the ‘Add’ button. At this point, click ‘Next’ to move on.
8. At the ‘Choose Issuance Authorization Rules’ screen, you may choose to have AD FS allow all domain users access by default, or none. Whichever you choose is up to you, although we recommend that you leave ‘Permit all users to access this relying party’ selected initially while you continue the setup process. When you have made your selection, click ‘Next’.
9. At the ‘Ready to Add Trust’ screen, you have the opportunity to review the selections you’ve made in the previous screens. If you are satisfied, click ‘Next’.
10. At the ‘Finish’ screen, you have the option to ‘Open the Edit Claim Rules dialog for this relying party trust when the wizard closes’; check the box, and click ‘Close’.
11. In the ‘Edit Claim Rules’ dialog, click the button labeled ‘Add Rule’. The purpose of this rule is to cause the user’s email address to be sent to Syncplicity when a user has successfully authenticated; this email address is how we will identify the user in our system.
12. At the ‘Choose Rule Type’ screen, you’ll be prompted to select a ‘Claim rule template’; the default value is ‘Send LDAP Attributes as Claims’, which is what we want for the first rule. Leave it selected, and click ‘Next’.
13. At the ‘Configure Claim Rule’ screen, you’ll be prompted for a rule name, an attribute store, and a set of LDAP attributes. An appropriate claim rule name would be something like ‘Send Email Address’. For an ‘Attribute store’, select Active Directory (assuming that Active Directory is what you’re using for authentication). Below this option you will see a table with two columns, one labeled ‘LDAP Attribute’ and the other ‘Outgoing Claim Type’. In the first row, select an LDAP attribute of ‘E-Mail-Addresses’, and an outgoing claim type of ‘E-Mail Address’. When this is done, click ‘Finish’.
14. Click ‘Add Rule’ to add a second rule (this will be the final rule). The purpose of this second rule is to give the email address claim a specific emphasis in SAML response sent to Syncplicity; specifically, we require that the SAML assertion containing the email address be a NameID assertion with a format describing it as an email address.
15. At the ‘Choose Rule Type’ screen, select the ‘Transform an Incoming Claim’ template, and click ‘Next’.
16. At the ‘Configure Claim Rule’ screen, name the rule something descriptive (such as ‘Email to Name ID’). Select an ‘Incoming claim type’ of ‘E-Mail Address’ from the first dropdown. Select an ‘Outgoing claim type’ of ‘Name ID’. Select an ‘Outgoing name ID format’ of ‘Email’. Leave ‘Pass through all claim values’ selected, and click ‘Finish’.
17. At this point, all of the claim rules needed are in place; click ‘OK’ to exit the claim rules dialog and return to the ADFS Management console.
18. In the ADFS Management console, select the new RPT and click the link labeled ‘Properties’ to open the properties dialog; alternately, double-click on the new RPT’s name.
19. Click on the ‘Signature’ tab, and click the ‘Add’ button. This will cause an ‘Open File’ dialog to appear; use it to select Syncplicity’s token-signing certificate (you should have received this from Syncplicity directly, if not, please contact support).
20. Click on the ‘Advanced’ tab; the sole option is to specify the ‘Secure hash algorithm’; select ‘SHA-256’.
21. Click on the ‘Endpoints’ tab; you should see one entry corresponding to the URL you specified in step 6. Verify that the ‘Index’ is 0 and that the ‘Binding’ is ‘POST’. If not, click the ‘Edit’ button and set the aforementioned values appropriately.
22. When you are satisfied, click ‘OK’ to close the properties dialog.
At this point, all RPT-specific configuration is complete!
Configuring Syncplicity
Enabling SSO with Syncplicity requires configuring both the SAML IdP (our identify provider, ADFS in this case) and your Syncplicity Business Edition account. One element of the latter is uploading the Identity Provider Certificate; this is the certificate that is used to sign SAML assertions, and is known in ADFS as the Token Signing Certificate.
To export the certificate from ADFS:
1. Open ADFS 2.0 Management
2. Expand the “Service” node on the left part of the window, and click the folder titled “Certificates”
3. In the main window, right-click on the certificate labeled “Token-signing”, and select the menu option “View Certificate”.
4. In the resulting window, click the “Details” tab
5. In the “Details” tab, click the button “Copy to File”
6. Complete the certificate-export wizard, selecting “Base-64 encoded” as the certificate format, and ensuring that the file name has a “.cer” extension. You should make sure that the private key is not included.
7. Retrieve the file and use it as the “Identity Provider Certificate” when configuring SSO in Syncplicity.
FAQs & Tips
ADFS is stringent in its requirements – if settings are not *just so*, single sign-on will not work, and the error message shown will betray no indication of what might be the problem. The steps above will yield a reliable Remote Party Trust configuration, but much more than the RPT can go awry when setting up ADFS for the first time.
When troubleshooting ADFS, the Windows Event Viewer is your window into the world. Under the ‘Applications and Services Logs’ section you will find the ‘ADFS Admin’ event log. This log captures high-level events, including late-stage SAML request failures. Unfortunately, most initial configuration errors don’t result in late-stage request failures, and the problem likely manifests itself early in the authentication process making things difficult to troubleshoot.
To get finer-grained diagnostics, it’s necessary to dig into the plumbing of the ADFS application itself and enable the ADFS Trace logs. Steps to enable ADFS “Trace” logs can be found at the following article from Microsoft: http://blogs.msdn.com/b/card/archive/2010/01/21/diagnostics-in-ad-fs-2-0.aspx
Several “gotchas” that we have observed in configuring ADFS:
• ADFS has a “Federation service name” which must match the domain name of the server; e.g. if the ADFS box is exposed at https://idp.yourcompany.com, then the name must be "idp.yourcompany.com".
• ADFS requires at least three SSL certificates – one for token signing, one for token encrypting (optional), and one for actual SSL communications. This latter certificate should not be self-signed, and its name should match the name used to access the server. Following the previous example, a valid certificate named idp.yourcompany.com (or *.yourcompany.com) would suffice.
• By default, only Internet Explorer will authenticate properly. If you wish you use Firefox or Chrome (or another browser):
1. Open IIS Manager
2. Expand the “Default Web Site” (or wherever the ADFS application is exposed)
3. Expand the “adfs” application
4. Click on the “ls” application
5. Double-click on the “Authentication” icon
6. Right-click on the words “Windows Authentication”, and select “Advanced Settings” from the context menu
7. Set “Extended Protection” to “Off”, then click “OK”.
• A common point of failure can be a typo in the RPT’s SAML endpoint URL – even a one-character deviation will cause ADFS to reject all SSO requests from Syncplicity. If your configured subdomain might have changed, this is a good place to look.
• Another common point of failure is a typo in the RPT identifier; similar to the previous tip, look here if your subdomain might have changed.