ADFS Integration Guidelines

Version 1.6 – updated March 13

th 2014

2

Table of contentsAbout 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

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 docu-ment. We provide only a very basic example of how to set up an ADFS for testing purposes (see Ap-pendix A). For any further details we refer to Microsoft’s documentation. (http://technet.microsoft.com/library/adfs2%28WS.10%29.aspx)

Prerequisites• An Active Directory with an ADFS server accessible by all the relevant Marcombox users• A Marcombox

4

Part 1

Configure Marcombox in the ADFS EnvironmentNote: 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.

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

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”

7

2.5 Choose the ADFS profile between the following options -> Click “Next”

2.6 Go to Marcombox -> Download the Marcombox Certificate File

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”

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.

2.10 Go to Marcombox -> Copy the appropriate “Identifier”

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.

2.12 Select the option “Permit all users to access this relying party” -> Click “Next”

11

2.13 Review the configuration by visiting the different tabs -> Click “Next”

2.14 Click “Close” to finish

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”

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 Outgoing Claim TypeUser-Principle-Name Name ID

-> Click “Finish” to end the setup

2.18 Click “OK” to close the wizard

14

Part 3

Assign Signature Verification CertificateNote: 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.

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: https://[ADFS HOST NAME]/FederationMetadata/2007-06/FederationMetadata.xml

16

Part 4

Configure ADFS in Marcombox4.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.

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

18

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

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 https://[ADFSHostName] in prefix. e.g. if [Host Name] = adfs.marcombox.adfs then the complete URL will be https://adfs.marcombox.adfs/adfs/ls/

Insert the complete URL in the “Endpoint URL” in Marcombox

20

Part 5

Certificate Export Process5.1 Go to the ADFS window -> Click the “Certificates” folder. Export the public key of Token-

signing 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”

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”

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.

23

Part 6

Test ADFS Connection6.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”

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 e-mail 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”

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

26

Appendix A: ADFS InstallationThis 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: http://technet.microsoft.com/library/dd727938(WS.10).aspx

Appendix B: SAML ConfigurationB1. 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

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

28

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