Integrating Marq with ADFS enables your users to authenticate using SAML single sign-on through ADFS. The following tutorial walks through the process of integrating ADFS with Marq.
Get started by downloading the federation metadata and importing it into Marq.
- Download the federation metadata. The federation metadata can be accessed on the ADFS server at the following URL, replacing [myserver.domain] to reflect your ADFS server URL:
https://[myserver.domain].com/FederationMetadata/2007-06/FederationMetadata.xml - Navigate to the Marq Admin Panel.
- Select the "SAML" option, enter your organization domain, and click save.
- Upload the XML metadata to Marq using the file picker. (Note: if you have this in text format please save it as an XML file then upload it to Marq.)
Configure the Marq Relying Party Trust in ADFS.
Next we will create and configure a Relying Party Trust using the Marq metadata.
- From the Marq SAML page, select “Download Metadata” to download the Marq metadata. Save the metadata in a location accessible to the ADFS server.
- Open ADFS and right click on “Relying Party Trust.” Select “Add Relying Party Trust” from the menu to open the Add Relying Party Trust Wizard.
- Click through the Welcome screen. On the Select Data Source screen, select “Import data about the relying party from a file.” Choose “Browse” and locate the Marq metadata file. Complete the remaining settings based on your organization's preferences.
- Open the Endpoints configuration for your Marq relying party trust. You will need to add another endpoint to accommodate for ADFS storing the incoming sign-on URL against the supplied ACS/reply URL. The settings should be:
-
- Type = SAML Consumer Assertion
- Binding = POST (if you use REDIRECT only please contact support)
- Index = 1
-
Trusted URL = https://app.marq.com/saml/sso/[Your_Domain]
- Once finished the configuration will look like this:
-
- Right-click on the Marq Relying Party Trust and select “Edit Claim Rules.” Add a claim rule using LDAP and configure the claim rule to match the attributes and claim types shown below. Then click “Finish.”
Now you have completed the ADFS SAML integration in Marq, and your Marq account will support SAML single sign-on authentication through ADFS.
While we hope your integration setup is a painless experience, here’s a look at how to resolve errors you may encounter.
Troubleshooting
Invalid SAML Response
This error corresponds with an incorrect SAML response from the IDP. It usually means that the hash algorithm needs to be switched from “SHA-1” to “SHA-256” in ADFS. Navigate to the Marq Relying Party Trust, right click, and select “Properties.” Click the Advanced tab and switch the hash algorithm from “SHA-1” to “SHA-256.”
SAML is not configured for your team. Request an invite from a SAML enabled team.
This error appears when a user attempting to log in through SAML is not associated with the SAML enabled team. The admin will need to send an invite to the user to be accepted to the team. From the Marq Admin Panel, select “Users.” Click “+User” in the top right corner and enter the user’s email.
Invalid Identity Attribute
This error indicates that an invalid identity attribute was received in the SAML response. Configure a claim attribute for the Marq Relying Party Trust where “Email-Addresses” corresponds to “Name ID” in ADFS.
Could Not Parse XML
This error indicates an incorrect syntax in the identity provider XML metadata. This can happen when downloading metadata from an Internet Explorer window. Internet Explorer will add dashes to XML tags for expanding and collapsing. You can fix this issue by either opening the XML data in a text editor or deleting all of the dashes in the copied XML text.
username_12345@example.com Users Being Created
The Marq SAML integration accepts 3 attributes: First Name, Last Name, and Email Address. When an invalid email address is passed from the SAML identity provider, a valid email will be generated to create the user: “passed value” + “SAML ID” + “@example.com.” This often occurs when a username or given name is passed to the Email Address attribute instead of the valid email. You can resolve this issue by configuring your claim rule to send a valid email address in the Email Address attribute.
ADFS does not return a response to Marq
Check the Endpoints to make sure you followed the steps listed in the ADFS set up steps. If you just have a single endpoint or have your www. endpoint indexed before your app. endpoint, the response will not make it back to Marq.