SSO Setup for Shelf with AD FS



This document describes the required steps to enable SSO for Shelf via AD FS.

There are four configuration steps to enable Shelf SSO:
  1. Adding a Relying Party Trust
  2. Editing Claim Rules for the Relying Party Trust
  3. Enable SSO for AD FS on the Shelf Admin Panel
  4. Limiting access to Shelf to a subset of ADFS users

These four steps are described in detail below. In case you require assistance, please don’t hesitate to contact us at support@shelf.io or via the Live Chat on our Website or inside of the Shelf App.


Step 1: Adding a Relying Party Trust

  1. Open the AD FS Management Tool
  2. Expand the Trust Relationships in the left pane
  3. Select Relying Party Trusts and click Add Relying Party Trust on the right pane.
  4. The Add Relying Party Trust Wizard will be opened.
  5. Click the Start button on Welcome step.
  6. Select Enter data about the relying party manually
  7. Specify a display name (e.g. Shelf) and click Next.
  8. Choose AD FS Profile on the Choose Profile step and click Next.
  9. Keep the default values on the Configure Certificate step. Click Next.
  10. Select Enable Support for the WS-Federation Passive Protocol. Then enter https://shelfio.auth0.com/login/callback?connection=YOUR-SHELF-ACCOUNT-ID and click Next.
    You can get that URL from Shelf Admin Panel here:

  11. Enter urn:auth0:shelfio in the Relying party identifier input and click Add, then click Next.
  12. Select I do not want to configure multi-factor authentication settings for this relying party trust at this time. Then click Next.
  13. Check Permit all users to access this relying party and click Next.
  14. Review your settings on the Ready to Add Trust step and click Next.


Step 2: Editing Claim Rules for the Relying Party Trust

  1. Right-click on the relying party trust that you have recently added and click Edit Claim Rules...
  2. Click Add Rule.
  3. Keep the default Send LDAP Attributes as Claims.
  4. Give the rule a name that describes what it does (e.g. ShelfClaimRule).
  5. Select the following mappings under Mapping of LDAP attributes to outgoing claim types and click Finish.

  6. Click Add Rule again
  7. Select Transform an Incoming Claim and click Next.
  8. This action is relevant if you used Name ID instead of userPrincipalName in .5 of this step. Or your setup is not planned to be used when user principal name and email address will be different
    Set the Claim rule name, e.g. Email as NameID. Select E-Mail Address as Incoming claim type, Name ID as Outgoing claim type, and Email as Outgoing name ID format from the drop-down lists. Make sure that Pass through all claim values is selected. Click Finish.
  9. Click Apply and then OK.


Step 3: Enabling AD FS SSO on the Shelf Admin Panel

1. Log into your Shelf Account and go to the SSO Settings page on the Admin Panel.

2. Enable SSO and select Microsoft AD FS as the Identity Provider.

3. Provide AD FS URL which has the following format:

https://YOUR-ADFS-DOMAIN-EXAMPLE.XXX/FederationMetadata/2007-06/FederationMetadata.xml

Replace YOUR-ADFS-DOMAIN-EXAMPLE.XXX in the URL above with your real domain.

4. With enabled SSO, your users will be forced to log in via SSO. Apart from the Admin setting up SSO on Shelf, all users will be logged out as soon as SSO is enabled (after clicking on Save).

5. The setup is complete! All your users will be authenticated via AD FS. Navigate to your account URL, i.e. {{yourdomain}}.shelf.io. to log in via AD FS. You may be asked to enter your email as a first step before the Sign in with ADFS button is displayed.


Step 4: Limiting access to Shelf to a subset of ADFS users

Following the setup in steps 1 & 2, we allowed all ADFS users access to Shelf. With Just-in-time user provisioning enabled, this may become a problem. Every ADFS user can become a view-only Shelf user.

One way to combat this is limiting access to Shelf based on ADFS group membership. In this tutorial, we will create a group called “Shelf Users” and permit logging in to Shelf only its members.

1. Open “Active Directory Users And Computers” window
2. Create a new user group

3. Enter “Shelf Users” as a name for the group


4. Edit user’s group membership



5. Add a new group. Start typing “Shelf”



6. Then click “Check Names” and the rest of the group name will be autocompleted



7. Edit Claims of the previously created Relying Party Trust



8. Navigate to the second tab “Issuance Authorization Rules”



9. Click “Add Rule” and select “Permit or Deny based on an Incoming Claim” in the first step of the wizard


10. Name Rule as “Permit to “Shelf Users” group members” and select “Group SID” as the incoming claim type


11. Click “Browse” and select “Shelf Users” group 



12. After completing the wizard you can finally remove the old rule which permitted authorizing into Shelf to all ADFS users. 



From now on only members of the “Shelf Users” group will be allowed to authorize into Shelf.