Microsoft AD FS
Last updated
Last updated
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.
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.**
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
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
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.
Version
Author
Date
v1.0
Eduardo de Oliveira
01/13/2022
