Configuring SAML 2.0 in ADFS 2016

Jitbit supports authenticating via SAML 2.0. One of the more popular SAML providers is Active Directory Federation Services (ADFS) - a Microsoft service that gives you an ability to authenticate with third-party services using existing Active Directory credentials.


All the instructions and screenshots in this manual are taken in Windows Server 2016, but you should be able to follow it without problems on Server 2012 as well.

Prerequisites

• You need to have AD and ADFS configured and working. Initial set up is outside of the scope of this article. There plenty of manuals by Microsoft - just find the one for your OS. Obviously, you will need to know your AD FS URL so note that down somewhere during the set up.
  
• All users in AD that are going to authenticate with Jitbit must have an email address in their profiles. Email address is a primary identification in Jitbit and it must be unique.
  
• You need to either have a hosted Jitbit instance (trial will work too) or a working on-premises installation (trial version won't work in this case). If you have an on-premises instance it has to be working over HTTPS - it's a SAML requirement. The certificate can be self-signed, although it's not recommended.

Adding a Relying Party Trust
1. Open Server Manager - Tools - AD FS Management
2. Expand Service - Endpoints and check that you have SAML 2.0/WS-Federation endpoint enabled. You will need to enter this path along with your AD FS URL later in Jitbit. The default is "/adfs/ls". We will refer to it as "Login URL" later in the manual.



3. Now click on Relying Party Trusts in the left tree and then click on Add Relying Party Trust... in the Actions pane on the right.
4. Choose Claims aware and click Start.


5. On the next screen choose Enter data about the relying party manually



6. Specify any name to remember what it's for.


7. Don't do anything on the next screen, just click next.


8. Select the second checkbox and enter your Jitbit URL with "/Saml/Consume" at the end. Do not forget to replace it with your Jitbit URL. HTTPS is required here.




9. Enter your URL again without HTTPS and path and click Add. In our case it would be "hd.jitbit.com". Note what you've entered here - you will need that later. We will refer to it as "Entity ID" later in the manual.



10. The next screen lets you set up permissions. The default is Permit everyone. We recommend you to leave it that way at least until you get it working properly.


11. Click Next twice on the next two screens.

Claim rules

1. With your new relying trust selected click Edit Claim Issuance Policy... in the right Actions pane.
2. Click Add rule. We will need to add two rules.
3. Select "Send LDAP Attributes as Claims" as your claim rule template.


4. Enter any name, select Active Directory as your attribute store, select E-Mail-Addresses in the left column and E-Mail Address in the right. Click Finish.



5. Now we need to add the second rule. Choose Transform and Incoming Claim as a rule template.


6. Enter any name. Incoming claim type: E-Mail Address; Outgoing claim type: Name ID; Outgoing ID format: Email. Click Finish.





Obtaining Token-signing certificate

1. This part is a bit tricky. You need your AD FS token-signing certificate in a plain text form. If you know how to get it you can skip this part. We will describe the default AD FS configuration with auto-rolling certificates.
2. In AD FS manager expand Service and click on Certificates.
3. Double click the token-signing one:


4. Click Install Certificate. Select Current User.


5. Select Personal store so that it will be easier to find and finish the installation.


6. Launch mmc.exe. File - Add/Remove Snap-in. Add Certificates snap-in for My user account. Click Okay. Expand Personal and click Certificates. It should look like this in the end:


7. Right-click the ADFS certificate - Tasks - Export. Choose Base-64 encoded as an export format. Save the certificate to your Desktop.



8. We will need this certificate in a second. We'll refer to it as x509 certificate.

Configuring Jitbit
1. Go to Administration - General Settings in Jitbit. Scroll at the very bottom of the page.
2. Click Enable SAML 2.0 single sign on.
3. Enter your Login URL (the one that ends with "/adfs/ls" by default).
4. Open your certificate in Notepad and copy everything to the x509 certificate field.
5. Enter the same Entity ID as you did when configuring the relying party trust.
6. In the end it should look something like this:


7. Do not enable "Hide regular login controls" setting just yet - if SAML doesn't work you may be locked out of your help desk. You can turn it on later. Click Save.

Testing

1. Log out from Jitbit. You should now see SSO Login button on the login page. Click on it.


2. If everything is correct you should see the AD FS login screen. Sign in.



3. If everything is still correct you will be logged in to Jitbit with your AD credentials. That's it!

Troubleshooting

If you see an error on one of the Microsoft pages (on the login page for example) open Event Viewer (eventvwr.exe). Expand Applications and Services Logs - AD FS - Admin. Look for errors there.


If you see a Jitbit error one of the settings you've entered is incorrect - entity ID, x509 certificate or login URL. If everything else fails contact our support.