ADFS is a standard SSO service that can be used with Dispatch to provide SSO authentication for Dispatch Users. Single Sign On (SSO) authentication for Dispatch allows users to use their Active Directory accounts to login to Active Directory which greatly simplifies user administration. When SAML authentication for Dispatch is enabled, the dispatch login page will have a button that the user can use to perform SSO authentication.
This document explains how to configure Dispatch and ADFS to interoperate using SAML for authentication.
This document will use the Dispatch server of acme.leading2lean.com as the hostname for the Dispatch server we will setup, and adfs.acme.com as the hostname of the ADFS server. The examples use Windows Server 2016, but the instructions should work against older Windows Server instances.
You must have administrative access to both Dispatch and ADFS in order to complete these steps. ADFS should already be configured and setup, along with a working Active Directory instance, as we still setup ADFS to use Active Directory user attributes for SAML responses.
Step 1: Create the Dispatch SAML Config
Log in to acme.leading2lean.com, and navigate to Setup > IT Setup > SAML SSO Config at https://acme.leading2lean.com/setup/samlconfig/.
We will create a new SAML Config that defines the ADFS SAML trust. Click the Add New link.
In the Add New SAML Config page, we will enter the following information:
- Code: this must be a unique code among all SAML Config’s and gets used in the Dispatch SAML URL’s. For this example, we will use the code acme-sso.
- Display Name: This is user visible text on the Dispatch login page - we will use Dispatch ACME SSO for this example.
- IdP Entity Id: This is the identifying URL for the ADFS server. This can vary, but in most cases will be https://adfs.acme.com/adfs/services/trust/mex. You can find this in the ADFS Management Console on the Service / Edit Federation Service Properties dialog under Federation Service Identifier. The following images show where to find that information.
- IdP SSO URL: This is the url for the ADFS endpoint for processing SAML authentication. By default this will be https://adfs.acme.com/adfs/ls
- IdP User Naming Attribute: This can either be email or username. This is used to map the ADFS/Active Directory account that authenticates to a Dispatch user. This will usually be the email address if your Dispatch user accounts have their email address set to their corresponding Active Directory user account. If your Dispatch User accounts have their usernames set to the same username (usually the SAM Account Name attribute in Active Directory), pick that.
- IdP Certificate Information: This holds the public key information for the Certificate that signs SAML responses. You can get the certificate thumbprint for the Token-Signing certificate in the ADFS Management Console under Server/Certificates in the Certificate dialog under the Details tab and the Thumbprint field. Copy that value and note the Thumbprint algorithm value. Enter those values in the Certificate Thumbprint & Thumbprint Algorithm Tab. The following images show where you can find this certificate information:
- Force IdP Authentication Each Login: If this value is checked, then a user must authenticate against ADFS each time they login to Dispatch. This is probably not what you want as it eliminates the convenience of single sign on for your users, but it may be useful in some scenarios.
Now click save. On the SAML Config list view, click on the new SAML Config as we need to get some information from the new SAML Config that we will use to configure ADFS. The SP Initiate, SP SSO URL, and SP Entity ID URLs will all be used.
Step 2: Create the ADFS Configuration
In the ADFS Management console, we will now add a new Relying Party Trust. Click on the Relying Party Trusts folder, then click on the Add Relying Party Trust action. In the Add Relying Party Trust Wizard, do the following for each step:
- Step 1: Choose Claims Aware
- Step 2: Select Import data about the relying party published online or on a local network, and enter in the SP Entity ID url, which in this case is https://acme.leading2lean.com/saml/metadata/acme-sso/
- Step 3: Enter in a Display name – it’s a good idea to match the Dispatch SAML Config Display Name entered in already. In this case use Dispatch ACME SSO.
- Step 4: Here choose an access control policy. This can be as restrictive as you want. Note that only users that have a Dispatch account that has been enabled for SAML Config can login to Dispatch, so just turning on SAML support doesn’t allow everyone who can authenticate to ADFS to access Dispatch. In most cases you can just use Permit Everyone.
- Step 5: Finish
If Step 2 does not work and the Dispatch SAML metadata cannot be automatically loaded, you can manually specify the Relying Party endpoints. The SP SSO URL (in this case https://acme.leading2lean.com/saml/complete/acme-sso) must be specified as the SAML Assertion Consumer Endpoint.
The new Relying Party Trust has been created, and now we must add a Claim Issuance Policy. Click on the new Relying Party Trust and then select the Edit Claim Issuance Policy action. In this dialog, click the Add Rule… button. In the wizard that appears do the following:
- Step 1: Choose Send LDAP Attributes as Claims as the Claim rule template value
- Step 2: Enter Email Address as the Claim Rule Name, then in the Mapping of LDAP attributes to outgoing claim types box, choose E-Mail-Addresses under the LDAP Attribute column, and choose Name ID under the Outgoing Claim Type column. The following image shows how it should be configured:
- Click Finish
You now have a working SAML/ADFS configuration. Note, if you want to map Active Directory users to Dispatch users using the username field(See the section on creating a Dispatch SAML Config), you must pick a different LDAP Attribute (usually SAM-Account-Name) and map that to the Outgoing Claim Type. You must not have more than one claim rule that maps an attribute to Name ID.
We now must go and setup our Dispatch users to use SAML for authentication. Each Dispatch user can be configured to do local account authentication only, SAML authentication only, or allow both local and SAML authentication. This flexibility allows you to continue to let users without Active Directory accounts to use Dispatch, or enforce a single authentication source in Active Directory for auditing purposes, and still keep local accounts for administrators to support troubleshooting in the event of SAML authentication issues.
Each user detail page has a SAML Config option that defaults to Non SAML User. To allow this user to use SAML authentication, this option should be set to the SAML Config we created. In this case it would be Dispatch ACME SSO. The following image shows how this is done:
Note that the user’s email address must match the Active Directory account. After making these changes, click save for the user. This user now can authenticate via SAML and with their existing Dispatch password.
Users can initiate a SAML login for Dispatch from the Dispatch login page by visiting the Dispatch login page at https://acme.leading2lean.com/login/ and click on the Dispatch ACME SSO button. That will trigger a SAML authentication where their browser session is redirected to ADFS to sign on, and then gets redirected back to Dispatch. By default, ADFS also supports using a URL like https://adfs.acme.com/adfs/ls/IdpInitiatedSignOn.aspx to initiate SAML authentication to Dispatch, and this link is usually made available to users on the standard intranet pages.
Step 3: Migrate Dispatch Accounts to SAML Authentication
If you need to migrate most/all of your Dispatch accounts to use SAML authentication, there are Dispatch tools to make this easy. Each Dispatch SAML Config has a Migrate Accounts button that allows you to perform a bulk migration for users to use the SAML Config. Simply click the button and follow the instructions to enable your user accounts to authenticate using SAML.