ADFS Integration Guidelines

Transcription

1 ADFS Integration Guidelines Version 1.6 updated March 13 th 2014

2 Table of contents About This Guide 3 Requirements 3 Part 1 Configure Marcombox in the ADFS Environment 4 Part 2 Add Relying Party in ADFS 5 Part 3 Assign Signature Verification Certificate 14 Part 4 Configure ADFS in Marcombox 16 Part 5 Certificate Export Process 20 Part 6 Test ADFS Connection 23 Appendix A 26 Appendix B 26 Appendix C 27 2

3 About This Guide This is a step-by-step guide that will help you set up Marcombox to authenticate with your Active Directory. With this setup your Marcombox users will upon login be validated against your AD to ensure that the user has a valid account. To integrate Marcombox and your AD an ADFS (A Microsoft Web frontend for an Active Directory) is required. This guide will help you set up the required trust relationship between your AD/ADFS and your Marcombox. Please note that installation and maintenance of an ADFS server is beyond the scope of this document. We provide only a very basic example of how to set up an ADFS for testing purposes (see Appendix A). For any further details we refer to Microsoft s documentation. ( com/library/adfs2%28ws.10%29.aspx) Prerequisites An Active Directory with an ADFS server accessible by all the relevant Marcombox users A Marcombox 3

4 Part 1 Configure Marcombox in the ADFS Environment Note: You will need to log in to Marcombox as Administrator in order to make the following configurations. 1.1 Log in to Marcombox 1.2 Go to Manage > Settings 1.3 Click the Configure button in the section Active Directory Federation Service (ADFS) -> You will get the following pop-up Note: Please consider the right side information (Identifier, Endpoint Url, Certificate File, Required claims) for the following setup. 4

5 Part 2 Add Relying Party in ADFS In the ADFS terminology, the service provider is a relying party (e.g. Marcombox). Using the ADFS management console, add a relying party trust for the service provider. Note that strings in ADFS, including URLs, are case sensitive. 2.1 Open the ADFS management console -> Click on Add Relying Party Trust from the Action Menu or expand Trust Relationships and right click on the Relying Party Trusts folder in the left side navigation panel -> select Add Relying Party Trust 2.2 Click the Start button to start the process 5

6 2.3 Select the option Enter data about the relying party manually -> Click Next 2.4 Specify a user friendly display name. The display name does not have to match with any other configuration. -> Click Next 6

7 2.5 Choose the ADFS profile between the following options -> Click Next 2.6 Go to Marcombox -> Download the Marcombox Certificate File 7

8 2.7 Go to the ADFS management console -> Browse to specify the Certificate File as the token encryption certificate. Ignore any warnings about the key length. -> Click Next Note: The token encryption certificate is used to encrypt the SAML assertion. The service provider decrypts the SAML assertion using the associated private key. 2.8 Go to Marcombox -> Copy the appropriate Endpoint Url 8

9 2.9 Go to the ADFS management console -> Select Enable support for the SAML 2.0 WebSSO protocol option and paste the copied URL to the immediate following textbox Note: Enable support for SAML v2.0 and specify the service provider s assertion consumer service URL. ADFS sends the SAML response to this URL Go to Marcombox -> Copy the appropriate Identifier 9

10 2.11 Go to the ADFS management console -> Paste the copied Identifier into the textbox -> Click Add -> Click Next Note: Specify the relying party trust identifier. This identifier must match the issuer field in the authentication request sent by the service provider Select the option Permit all users to access this relying party -> Click Next 10

11 2.13 Review the configuration by visiting the different tabs -> Click Next 2.14 Click Close to finish 11

12 2.15 A new wizard called Edit Claim Rules will appear after closing the Add Relying Party Trust wizard -> Click Add Rule button 2.16 Select Send LDAP Attributes as Claims from the dropdown. -> Click Next 12

13 2.17 Specify a user friendly name in Claim rule name field. -> Select the Active Directory option from the Attribute store dropdown -> Map the following compulsory attributes LDAP Attribute User-Principle-Name Outgoing Claim Type Name ID -> Click Finish to end the setup 2.18 Click OK to close the wizard 13

14 Part 3 Assign Signature Verification Certificate Note: Make sure that you have downloaded the certificate from Marcombox. See 2.6 (page 6). 3.1 Go to the ADFS management console -> Click thr Properties link in the right pane 3.2 Go to the Signature Tab -> Add the same service provider s certificate which we had downloaded from Marcombox previously Note: The authenticated request sent by the service provider is signed. Specify the certificate to use to verify the signature. 14

15 3.3 Double click on the certificate file to open it -> Go to the Details tab -> See the value of the Thumbnail algorithm field 3.4 Go to the Advanced tab of the Properties window -> Select that appropriate algorithm from the dropdown. -> Click OK to save and close the window ADFS should now be ready to communicate with Marcombox. To review the metadata published by ADFS browse to: HOST NAME]/FederationMetadata/ /FederationMetadata.xml 15

16 Part 4 Configure ADFS in Marcombox 4.1 Log in in to Marcombox as Administrator 4.2 Go to Manage > Settings 4.3 Click the Configure button in the section Active Directory Federation Service (ADFS) -> You will get the following pop-up Note: Please consider the left side information (Provider Name, Identifier, Endpoint Url, Certificate File) for the following setup. 16

17 4.4 Add a user friendly name in the Provider Name textbox. The name will be displayed as a log in option for new users in the Marcombox Log in page 4.5 Go to the ADFS Properties window by clicking the Edit Federation Service Properties link in the right pane 17

18 4.6 Copy the value of the Federation Service identifier field and paste it into the Marcombox Identifier field 18

19 4.7 Go to the ADFS management console -> expand the Service folder -> select the Endpoints folder -> confirm that the /adfs/ls endpoint for SAML v2.0 exists. 4.8 /adfs/ls is actually a relative URL. Make a complete Url by adding in prefix. e.g. if [Host Name] = adfs.marcombox.adfs then the complete URL will be adfs.marcombox.adfs/adfs/ls/ Insert the complete URL in the Endpoint URL in Marcombox 19

20 Part 5 Certificate Export Process 5.1 Go to the ADFS window -> Click the Certificates folder. Export the public key of Tokensigning certificate from certificates folder of ADFS by following these steps. 5.2 Double click on the certificate file to open it 5.3 Go to the Details Tab > open the Copy Export Wizard by clicking the Copy to File button -> Click Next 20

21 Select the Base-64 encoded X.509 (.CER) -> click Next 5.4 Browse the location where you want to save the file with a proper name -> click Next 21

22 5.5 Click Finish to complete the export process. 5.6 Go to Marcombox -> upload the exported certificate file 5.7 Click save to complete the configuration of ADFS in Marcombox. 22

23 Part 6 Test ADFS Connection 6.1 Click the button Test ADFS connection in the Settings page -> a pop-up will appear 6.2 Click the button Test log in using ADFS 23

24 6.3 Insert AD log in credentials in the Authentication Required pop-up -> Click OK to test connection Note: For test purposes you can use any and password combination from your Active Directory. The user does not have to be added to your Marcombox. 6.4 If the connection is established successfully you will see the message below Click the button Test log in using ADFS 24

25 6.5 If the connection has not been established you will see an error message -> Go back to check the settings in your AD and Marcombox 25

26 Appendix A: ADFS Installation This installation should ideally be carried out on a server that is web facing with an installed (not self-signed) SSL certificate and which has access to Active Directory. A1. Run AdfsSetup.exe A2. Click Next A3. Click I accept the terms in the License Agreement and then click Next A4. Click Federation server and then click Next (you may wish to setup a proxy and a farm but this is outside of the scope of this article) A5. Click Next A6. Once the installation is complete click Finish (the Start the AD FS 2.0 Management snap-in when this wizard closes checkbox is automatically checked) Reference: Appendix B: SAML Configuration B1. Click AD FS 2.0 Federation Server Configuration Wizard B2. Click Next ( Create a new Federation Service should be automatically selected note that setting up a Federation server farm is out of scope of this article) B3. Click Stand-alone federation server and then click Next B4. Select your SSL certificate and the default Federation Service name and click Next (note that this SSL certificate should ideally be signed by a provider e.g. Thawte or Verisign and should be public facing or else you may experience issues further along) B5. Click Next B6. Click Close 26

27 Appendix C: Additional Setup To support Google Chrome browser to access the ADFS site. Note: without this configuration Google Chrome user will not be able to login using ADFS provider C1. Go to the IIS Manager window of the ADFS server -> Select ls site under adfs -> Double click Authentication the thumbnail C2. Select Windows Authentication in the list -> Click on Advanced Settings link from right pane 27

28 C3. An advance settings pop-up will appear -> Select the Off option in the Extended Protection dropdown -> Click OK to save the settings 28