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.

This topic provides an example of how to configure Microsoft Active Directory to work with Syncplicity authentication for SSO. The following instructions on how to configure Microsoft Active Directory Federation Services (ADFS) can be used with the Configuring single sign-on information.

To watch a video on this process, open this link →  Syncplicity's SSO using Microsoft ADFS

Check the ADFS Configuration

The Syncplicity application supports Microsoft ADFS versions 2.0, 3.0 and 4.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 for ADFS 3.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.

Change Authentication Policies for ADFS 4.0

If using ADFS 4.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. Expand Service => Authentication Methods in the left pane.
3. In the right pane, find Edit Primary Authentication Methods then click the 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.

Add Syncplicity as a Relying Party Trust

Within this procedures, you will create two rules for the configuration of the incoming attributes. The first rule is used to send the email address back to Syncplicity, and the second rule is used to map an incoming claim type to an outgoing claim type. 

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 then select Next.
3. At the Specify Display Name screen, give the RPT a descriptive and unique name, such as Syncplicity, then select Next.
4. At the Choose Profile screen, select the ADFS profile option to enable SAML 2.0 authentication, then select Next.
5. At the Configure Certificate screen, there is nothing to change. Select 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:
   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.
   Once entered, select 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 unique to your company:
   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, select Add then select 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, select Next.
9. At the Ready to Add Trust screen, review the selections you have made in the previous screens. If satisfied, select 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 select Close.
11. In the Edit Claim Rules dialog, select Add Rule. This rule forces the user's email address to be sent to the Syncplicity application after 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, then select Next.
13. At the Configure Claim Rule screen, you are prompted for the following:
    • Rule name: Enter an appropriate claim rule name, such as Send Email Address
    • Attribute store: Select Active Directory (assuming that Active Directory is what you are using for authentication)
    • Set of LDAP attributes: This 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, select Finish.
14. Select Add Rule to add a second rule (this is the final rule). This rule gives 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 Email Address from the first drop down.
    • Select an Outgoing claim type of Name ID.
    • Select an Outgoing name ID format of Email.
    • Leave Pass through all claim values.
      When done, select Finish.
17. Select OK to exit the claim rules dialog and return to the ADFS management console.

At this point, all of the required claim rules are in place.

Complete the Relying Party Trust (RPT) configuration

This procedure completes the RPT configuration.

1. In the ADFS management console, select the new RPT, then select the Properties link to open the properties dialog; alternately, double-click on the new RPT's name.
2. Select the Signature tab, then select Add.
3. In the resulting Open File dialog, select the Syncplicity token-signing certificate. If you have not received the certificate, contact Syncplicity support.
4. Select the Advanced tab then select SHA-256 as the Secure hash algorithm.
5. Click the Endpoints. Verify 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 the SAML Assertion Consumer Endpoints URL Index is 0 and Binding is POST. If not, select Edit and set these values appropriately.
7. Select OK to close the properties dialog.

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

Set 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 may 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

Configure the Syncplicity application

Enabling SSO with the Syncplicity application requires you to configure the SAML IDP (your identify provider, ADFS in this case) and your Syncplicity account (Business Edition or Enterprise Edition). Part of the configuration it to upload the Identity Provider Certificate; the certificate used to sign SAML assertions, 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 at the left of the window, and select 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, select the Details tab.
5. In the Details tab, select 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 .pem extension. Make sure the private key is not included.
7. Retrieve the file and use it as the Identity Provider Certificate when you configure 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 the problem. The steps above yield a reliable Remote Party Trust configuration; although, the RPT can be problematic when ADFS is set up 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 do not 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: for token signing, for token encryption (optional), and 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) will meet the requirements.
• For ADFS 2.0 or 2.1 only, by default only Internet Explorer authenticates properly. To 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 could have changed, this is a good place to check
• Another common point of failure is a typo in the RPT identifier; similar to the previous tip, check here if your subdomain could have changed.