No results

AD FS SAML 2.0 Setup Guide

Created Mar 22, 2023 by Diederik, last modified Mar 23, 2023.Last modified Mar 23, 2023 by Diederik.
 
Table of contents
You can connect Papyrs to Active Directory Federation Services (AD FS) via SAML 2.0 for the purpose of single sign-on. Your AD FS server will be the identity provider (ID) and Papyrs will be the Service Provider (SP).

This page has step-by-step instructions to link Papyrs with AD FS via SAML. The screenshots are for Windows Server 2022, but the steps for other versions of Windows Server are very similar. If you have any questions, please don't hesitate to reach out to us at team@papyrs.com

1. Set up a Relying Party Trust

Open the AD FS Management tool and select "Add Relying Party Trust..." from the action bar.


You'll get a wizard like shown below. You need a Claims Aware trust.

The second page of the wizard asks for a Federation Meta XML file.

The metadata XML address is https://[yoursite].papyrs.com/accounts/saml/sp.xml. The URL should point to an XML file that looks like this:


This file contains all the configuration parameters, so you can click through the remaining steps of the wizard.

2. Upload your AD SF configuration to Papyrs

Your AD FS server should provide you with a login page that looks somewhat like this:


This server should also provide metadata available for download. The default URL is:

https://[YOUR ADFS server]/federationmetadata/2007-06/federationmetadata.xml

Download the metadata XML file from your AD FS server.

Upload the XML file to Papyrs at https://[yoursite].papyrs.com/settings/saml/ (Papyrs site admin login required):


Click Save SAML connection.

3. Configure Claim Issuance Policy

At this point your integration almost works. Your AD FS server knows what Papyrs expects, and Papyrs knows what your AD FS server expects. Now you have to decide which AD properties to send to Papyrs at sign on.

Open the AD FS Management tool select and Edit Claim Issuance Policy for your Papyrs 3rd party trust connector.


Two claims rules are needed, the third one is optional. Click on Add Rule...


In the first step of the wizard choose "Send LDAP Attributes as Claims" and click Next. Configure the claim rule to map LDAP Attribute E-Mail-Addresses to outgoing Claim Type E-Mail Address. See screenshot: 


The purpose of this rule is to share the AD user's email address with Papyrs during login. Papyrs identifies users by email address.

Then create a second Claim Issuance Policy. This time choose Transform an Incoming Claim in the first page of the wizard. Here we want to map the incoming claim type E-Mail Address (unspecified) to Name ID (Transient Identifier). The other defaults are fine, see screenshot:


The purpose of this rule is to let AD FS know that the users are identified by their email address. The order of the claims matters.

(optional) If you want to share additional AD properties with Papyrs at sign on you can do that by creating a 3rd rule.


Optional LDAP attributes to sync with Papyrs profiles during login:
  • website
  • twitter
  • tel_home, tel_work, tel_mobile
  • position
  • street
  • city
  • street
  • state
  • zipcode
  • country
  • bio
  • birthday
If you have custom attributes in your Papyrs people directory we can sync those as well. Please contact us at team@papyrs.com and we'll set sync rules up for you.

4. Done

At this point you should be able to log in to Papyrs with your AD FS credentials.  Your Papyrs login page should now have a button SAML Login. This button will take users to your AD SF sign on page. Alternatively, users can navigate directly to your AD SF sign on page and select Papyrs from the list of supported 3rd party applications (idpinitiatedsignon)


(optional) If you're satisfied single sign-on works correctly we can disable the password based login option on request.

(optional) AD users that have not yet used Papyrs won't be able to login yet. They'll get a message that they need to be invited by an administrator first. You can configure Papyrs to allow users from a trusted email domain (e.g. @yourcompany.com) to join your Papyrs site without invitation. This allows for rapid onboarding of many users. You can choose which subsites new users should get access to, and you can configure an automatic welcome note users will get the first time they log in. You can configure this on Settings > Site > Joining without Invitation:


If you have any questions please contact us at team@papyrs.com