Microsoft AD FS

Overview

Active Directory Federation Services (AD FS) is a Windows Server component that allow us manage single sign-on (SSO) access with external applications via Relying Party Trusts (RPT) object. The following procedure will create a RPT object in your AD FS in order to trustily connect Desko app for single sign-on authentication. These instructions also apply to Windows Server 2019, 2016, 2012 R2 and 2008 R2 versions with ADFS v2 and v3, but be aware that there are slight differences in the configuration flow.

Before start, it is necessary to get the Desko’s URLs that is going to be inserted into the proper fields during the RPT object creation, then please follow the steps below:

Go to your Desko panel heading over to https://<YourCompanyName>.painel.desko.com.br

Note: You have to log in using a Master or Admin account.

2. Expand Integrations and click on Authentication

3. Turn on SSO SAML 2.0 authentication

4. Go to the bottom of the page at SAML Basic setup section and keep it open, you will need these 3 URLs Identifier (Entity ID), ACS response URL and Logout URL in the next steps

Note: The image below is for illustrative purposes only, please check on your Desko Panel the URLs matching your account. Each account has its own unique URLs.

Creating Relying Party Trusts (RPT) object

5. Open your AD FS Management snap-in, right click on Relying Party Trusts e choose Add Relying Party Trust

6. Keep Claims aware option and click on Start

7. Select Enter data about the relying party manually option and click on Next

8. Insert a name for the Display name field and click on Next

9. Click on Next to skip the token certificate option which is optional

10. Choose Enable support for the SAML 2.0 WebSSO protocol option, insert the ACS response URL from Desko panel opened in item 4 as shown below and click on Next

11. In the Configure Identifiers step, insert the Identifier Entity ID URL from Desko panel as shown below, click on Add and then on Next

12. Keep the default Policy as Permit Everyone and click on Next

13. Review your settings and click on Next to add your Relying Party Trust to the AD FS database

14. Keep the selected check-box Configure claims issuance policy for this application in order to open and configure Claims policies for Desko RPT and click on Close

Note: Once a user is authenticated by SSO, it is mandatory to have claim rules to specify data attributes and its formats such as Name and email. These data attributes will be sent to _Desko** in response to SAML 2.0. As **Desko_** requires a name identification element that contains the user's email address, in the next section we will create 2 configuration rules.**

Creating Claim Rules Policies

15. In the Issuance Transform Rules tab, click on Add Rule to start a new rule

16. For the first rule, select Send LDAP Attributes as Claims option and click on Next

17. Enter a name for your first rule and select Active Directory attribute store. In the table Mapping of LDAP attributes to outgoing claim types, select:

Display-Name** ** to ** _Name**_

E-Mail-Addresses** ** to ** _E-Mail Address**_

Just like shown below and click on Finish

18. Click on Add rule to add and start the second rule

19. For the second rule, select Transform an Income Claim option and click on Next

20. Enter a name for your second rule and select:

E-Mail** ** for ** _Incoming claim type**_

Name ID** ** for ** _Outgoing claim type**_

Persistent Identifier** ** for ** _Outgoing name ID format**_

Just like shown below and click on Finish

21. Click on Apply in order to commit the new rules

22. After commit and close the Claim dialog, go to your Relying Party Trusts list, right-click on the object you just created and click on Properties

23. Go to Endpoints tab and click on Add SAML

24. Select SAML Logout for Endpoint type option and Redirect for Binding option. Insert the Logout URL from Desko panel into the Trusted URL field just like shown below and click on OK

25. Go to Advanced tab and make sure that Secure hash algorithm is set to SHA-256. Click on Ok to close the object properties

Getting the Token Signing Certificate

26. In your AD FS Management, expand Service, go to Certificates, right-click on your Token-signing certificate and choose View Certificate

27. Go to Details tab and click on Copy to File

28. Choose Base-64 encoded X.509 (.CER) option and click on Next

29. Specify a name and a location to export the CER file and click on Next. You will need to upload the CER file on Desko panel later on

Getting the AD FS Federation Metadata

30. In this step, it is necessary to get the AD FS Federation Metadata in order to obtain the URLs from your AD FS to insert on Desko panel. For that, open a web-browser, head over to https://adfshelp.microsoft.com/MetadataExplorer/GetFederationMetadata insert your federation service name and click on Get federation metadata as shown below

31. Once you get your federation metadata, it’s time configure your Desko panel. First of all give a name to your connection, then insert the Entity ID URL from federation metadata into Identity ID field on Desko panel and Federation Passive Endpoint URL into Login URL, just like shown below (The Logout URL is optional)

32. Upload the certificate file you exported and converted in the item 29. Click on Update Certificate, select the CER file and click on Open

33. Scroll down to the bottom of the page, click on Save button and it’s done!

34. To access your Desko app, just head over to https://<YourCompanyName>.desko.com.br and click on the button you named for your login method.