Single-sign-on with ADFS

The Syncplicity support for Active Directory (AD) / LDAP single sign-on (SSO) is built on top of the industry-standard SAML 2.0 protocol. This widely supported protocol enables federated authentication between SaaS applications, like Syncplicity, and directory systems, like Active Directory and LDAP.

In this article we cover an example of how to configure Microsoft Active Directory to work with Syncplicity authentication for SSO. The instructions here to configure Microsoft Active Directory Federation Services (ADFS) compliments the article Configuring single sign-on.

Checking the ADFS Configuration

The Syncplicity application supports Microsoft ADFS versions 2.0 and 3.0. The ADFS configuration is assumed to have the following:

• A custom subdomain for your company. This subdomain is the point of entry for your SSO-enabled users, and is 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 customers, and must be at least four characters long.
• A special service account called a Globally Managed Service Account or GSMA.
• An active Directory Federation Service role, no special features are required.
• Users’ AD profiles with an email address, where this email address is the same as the address identifying the users’ Syncplicity accounts.
• Updated client machines as follows:
  • Internet Explorer browser has enabled Windows Integrated Authentication on the client computers.
  • ADFS communication certificate has been installed on the client machine (Local Computer - Trusted certificate store).
  • Your organization has been added to the trusted local intranet/internet web sites.

Change Authentication Policies (Applicable only if using ADFS3.0): If using ADFS 3.0, the Syncplicity application requires a change in the authentication policies to enable authentication from mobile devices as follows:

1. Open the ADFS management console. 
2. Click Authentication Policies in the left pane.
3. In the right pane, find Global Settings then click the Edit link besides Authentication methods. 
4. Check the Forms Authentication checkbox for Intranet. 
5. Save the settings.

NOTE: This setting is implicit if using ADFS 2.0.

Adding Syncplicity as a Relying Party Trust

1. In the ADFS management console, 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, such as Syncplicity, and click Next.
4. At the Choose Profile screen, select the ADFS profile option to enable SAML 2.0 authentication; click Next.
5. At the Configure Certificate screen, there is nothing to change; click Next. 
6. At the Configure URL screen, check Enable support for the SAML 2.0 WebSSO protocol then 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

For example, if your custom subdomain was mycompany, the URL would be:

https://mycompany.syncplicity.com/Auth/AssertionConsumerService.aspx

When done, click Next.

7. At the Configure Identifiers screen, add a relying party trust identifier. This is text (usually a URL) that serves as a name that accompanies 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 mycompany for a subdomain, the identifier would be:

https://mycompany.syncplicity.com/sp

Once entered, click the Add button then click Next.

8. At the Choose Issuance Authorization Rules screen, choose to have ADFS allow all domain users access by default, or none. In either case, 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, review the selections you have made in the previous screens. If satisfied, click Next.
10. At the Finish screen, check the box, Open the Edit Claim Rules dialog for this relying party trusts when the wizard closes, and click Close.
11. In the Edit Claim Rules dialog, click the Add Rule The purpose of this rule is to cause the user’s email address to be sent to the Syncplicity application when a user has successfully authenticated; this email address is how we identify the user in our system.
12. At the Choose Rule Type screen, you are prompted to select a Claim rule template. Leave the default value, Send LDAP Attributes as Claims, selected; click Next.
13. At the Configure Claim Rule screen, you are prompted for a rule name, an attribute store, and a set of LDAP attributes. Enter an appropriate claim rule name, such as Send Email Address. For an Attribute store, select Active Directory (assuming that Active Directory is what you are using for authentication). Below this option is a table with two columns, LDAP Attribute and 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 done, click Finish.
14. Click Add Rule to add a second rule, which is the final rule. The purpose of this second rule is to give the email address claim a specific emphasis in the SAML response sent to the Syncplicity application; 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, enter a descriptive name for the rule, 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. 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.

Completing the Relying Party Trust configuration

This procedure completes the RPT configuration.

1. In the ADFS management console, select the new RPT and click the Properties link to open the properties dialog; alternately, double-click on the new RPT’s name.
2. Click on the Signature tab, and click the Add button.
3. In the resulting Open File dialog, select the Syncplicity token-signing certificate. If you have not received the certificate, please contact Syncplicity support.
4. Click the Advanced tab then select SHA-256 as the Secure hash algorithm.
5. Click the Endpoints. Verify that there are only two URLs; one for SAML Assertion Consumer Endpoints (specified in step 6 of the previous procedure) and one for SAML Logout Endpoints.
             
6. Verify that the SAML Assertion Consumer Endpoints URL Index is 0 and Binding is POST. If not, click the Edit button and set these values appropriately.
7. When you are satisfied, click OK to close the properties dialog.

At this point, all RPT-specific configurations are complete!

Setting the ADFS SAML NotBeforeSkew parameter

If the system clock of the server running ADFS is ahead of the system clock of the Syncplicity cloud-based servers, your users might receive a login error, “Invalid Single-Sign-On response (NotBefore)”.  To correct this, ADFS provides an ability to add a skew to the SAML NotBefore parameter.

To change the ADFS NotBeforeSkew setting:

1. Using PowerShell on the ADFS server load up the ADFS PowerShell plug-in:

Add-PSSnapin Microsoft.Adfs.PowerShell

2. Check the existing NotBeforeSkew parameter value by entering the following command and finding the NotBeforeSkew parameter setting in the command output:

Get-ADFSRelyingPartyTrust –identifier “<relying_party_identifier>”

For example:

Get-ADFSRelyingPartyTrust –identifier “https://<custom_subdomain>.syncplicity.com/sp"

3. Add 1 or 2 minutes to the existing NotBeforeSkew parameter value and set that as the new value by entering the following command:

Set-ADFSRelyingPartyTrust –TargetIdentifier “<relying_party_identifier>" –NotBeforeSkew <mins>

For example:

Set-ADFSRelyingPartyTrust –TargetIdentifier “https://<custom_subdomain>.syncplicity.com/sp" –NotBeforeSkew 2

4. Check that the new NotBeforeSkew parameter value has been set by entering the following command and finding the NotBeforeSkew parameter setting in the command output:

Get-ADFSRelyingPartyTrust –identifier “<relying_party_identifier>”

For example:

Get-ADFSRelyingPartyTrust –identifier https://<custom_subdomain>.syncplicity.com/sp

Configuring the Syncplicity application

Enabling SSO with the Syncplicity application requires configuring both the SAML IDP (your identify provider, ADFS in this case) and your Syncplicity Business Edition, Department Edition or Enterprise 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 the ADFS management console.
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 Copy to File button.
6. Complete the certificate-export wizard, selecting Base-64 encoded as the certificate format, and ensuring that the file name has a .pem 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 the Syncplicity application.

 FAQs and Tips 

ADFS is stringent in its requirements. If settings are not correct, SSO does not work, and the error message shown does not indicate what might be the problem. The steps above 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 a very useful tool. 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.

For finer-grained diagnostics, enable the ADFS Trace logs. Steps to enable ADFS Trace logs can be found in the following article from Microsoft: http://blogs.msdn.com/b/card/archive/2010/01/21/diagnostics-in-ad-fs-2-0.aspx

Here is a list of potential issues that can occur when configuring ADFS:

• ADFS has a “Federation service name” which must match the domain name of the server; e.g., if the ADFS system is exposed at https://idp.yourcompany.com, then the Federation service name must be "idp.yourcompany.com".
• ADFS requires at least three SSL certificates – one for token signing, one for token encryption (optional), and one for actual SSL communications. The 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.
• For ADFS 2.0 or 2.1 only, by default only Internet Explorer authenticates 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 can cause ADFS to reject all SSO requests from the Syncplicity application. 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. 

For additional details, please review the video: Syncplicity's SSO using Microsoft ADFS