Configuring single sign-on (SSO) with ADFS

For partners subscribed to Enterprise plans.

This article explains how to configure the SSO integration of a self-hosted Active Directory Federation Services (ADFS) server and IT Glue.

ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials. Installing ADFS is beyond the scope of this topic, but is detailed in a Microsoft KB article. For further help, refer to the main SAML topic. Also, for ADFS-based SSO, it's recommended to always check the ADFS logs in the Windows Event Viewer to locate error details.

Prerequisites

  • Administrator level access to IT Glue.
  • An Active Directory instance where all of your users under your account in IT Glue have an account, with exactly the same email address. We don’t create user accounts under SSO.
  • A server running Microsoft Server 2012 or 2008. 
  • An SSL certificate to sign your ADFS login page and the fingerprint for that certificate.
  • Before you begin, log in to your IT Glue account twice - once in a regular browser window and once in a incognito/private window. This is to ensure that you are still logged in to your account just in case you get locked out of your account in the other window.

Instructions

Adding a new relying party trust

The connection between ADFS and IT Glue is defined using a relying party trust.

  1. Log in to the server where ADFS is installed.
  2. Launch the AD FS Management application (click Start, Administrative Tools, AD FS Management) and select the Trust Relationships > Relying Party Trusts node.
  3. Click Add Relying Party Trust from the Actions sidebar.

  4. Click Start on the Add Relying Party Trust wizard.

  5. On the Select Data Source screen, click Enter data about the relying party manually and click Next.



  6. Provide information for each screen in the Add Relying Party Trust wizard.
    • On the Specify Display Name screen, enter a Display name of your choosing and any notes (e.g. IT Glue SSO), select AD FS profile, and then click Next.
    • Skip the Configure Certificate screen by clicking Next.
    • On the Configure URL, select the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The URL will be https://subdomain.itglue.com/saml/consume, replacing subdomain with your IT Glue subdomain. Note that there's no trailing slash at the end of the URL.
    • On the Configure Identifiers screen, enter the Relying party trust identifier. This is the URL of your IT Glue subdomain. The URL will be https://subdomain.itglue.com, click Next.
    • Skip the Configure Multi-factor Authentication screen (unless you want to configure this) by clicking Next.
    • Skip the Choose Issuance Authorization Rules screen by clicking Next.
  7. On the Ready to Add Trust screen, review your settings and then click Next.
  8. On the final screen, make sure the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes checkbox is selected and click Finish. This opens the claim rule editor.

Creating claim rules

After you create the relying party trust, you can create the claim rules and make minor changes that aren't set by the wizard.

  1. If the claim rules editor appears, click Add Rule. Otherwise, in the Relying Party Trusts list, right-click the relying party object that you created, click Edit Claims Rules, and then click Add Rule.

  2. In the Claim rule template list, select the Send LDAP Attributes as Claims template, and then click Next.
  3. Create the following rule:
    • LDAP Attribute: E-Mail-Addresses 
    • Outgoing Claim Type: E-Mail Address
    1. Enter a descriptive rule name 
    2. Attribute Store: Active Directory
    3. Add the following mapping
  4. Click OK.
  5. Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.
  6. On the next screen, create the following rule:
    1. Enter a descriptive rule name
    2. Incoming Claim Type: E-Mail Address
    3. Outgoing Claim Type: Name ID
    4. Outgoing Name ID Format: Email
    5. Pass through all claim values (the default)
  7. Finally, click OK to create the claim rule, and then OK again to finish creating rules.

Adjusting the settings

You still need to adjust a few settings on your relying party trust.

  1. In the Relying Party Trusts list, double-click the relying party object that you created (or select Actions > Properties while you have the Relying Party Trust selected).
  2. On the Advanced tab, change the Secure hash algorithm to SHA-1.
  3. On the Endpoints tab, click on add SAML to add a new endpoint.
    • For the Endpoint type, select SAML Logout.
    • For the Binding, choose POST.
    • For the Trusted URL, create a URL using:
      1. The URL of your ADFS server
      2.The value for the 'SAML 2.0/W-Federation' URL from the ADFS Service > Endpoints node
      3. The string ?wa=wsignout1.0
      The URL will look something like:
      https://sso.domain.tld/adfs/ls/?wa=wsignout1.0

  4. Click OK twice. You should now have a working relying party trust for IT Glue.

Configuring IT Glue

After setting up ADFS, you need to configure your IT Glue account to authenticate using SAML. You will need a few pieces of information from ADFS to complete this step.

Important. It's highly recommended that before you begin the below set of instructions, log into your IT Glue account twice - once in a regular browser and once in an incognito/private window. Alternatively, you can also log in to two separate browsers. This is to ensure that you are still logged in to your account in case you are locked out in the other window.
  1. Log in to IT Glue and click Account from the top navigation bar.
  2. Click Settings in the sidebar.

    Account_Settings___IT_Glue_copy.png
  3. Click the Authentication tab and then turn the Enable SAML SSO toggle switch to ON. Once this is turned on, a form will appear. You will need to collect information from ADFS and enter it into this form.


    Untitled-2_copy.png

    • Issuer URL: 
      • In the AD FS Management application, select the Service node.
      • Click Actions > Edit Federation Service Properties.
      • The ADFS federation service identifier is shown on the General tab.
    • SAML Login Endpoint URL:
      • In the AD FS Management application, select the Service > Endpoints node.
      • Scroll down to the endpoint that has SAML 2.0/WS-Federation as the type and note the URL path. This is typically your ADFS public URL with /adfs/ls after the FQDN.
    • SAML Logout Endpoint URL:
      • Enter the logout URL you constructed in previous steps. It should be the same as the login endpoint URL, but with /adfs/ls/?wa=wsignout1.0 after your FQDN.
    • Fingerprint: 
      • Open PowerShell on the ADFS server.
      • Run Get-ADFSCertificate -CertificateType Token-Signing
      • The thumbprint looks something like:a909502dd82ae41433e6f83886b00d4277a32a7b
    • Certificate:
      • Export the token-signing certificate with the ADFS Microsoft Management Console.
      • When using the certificate exporting wizard, ensure you select Base-64 encoded X.509 (.CER) for the encoding format.
      • Open the exported file in a text editor to get the certificate value.

        base64.png
      Important. Ensure there are no extra spaces trailing at the end of the Certificate string (i.e. after -----END CERTIFICATE-----).
  4. Click Save.
    Warning. Click Save only when all information has been entered. If you turn on SSO prematurely, it will break the login experience for all users on your account.

You should now have a working ADFS SSO implementation for IT Glue, which you can test by going to your subdomain (mycompany.itglue.com) in a new browser session.

Troubleshooting

Users cannot log in

In order for ADFS to pass a login through for authentication, a user's email address must be present in the "E-mail" field of the General tab in their AD profile.

image.png

Common Questions

When the SSO server is unavailable, how do we access our accounts?

If your SSO provider's service is unavailable, you can still login using your IT Glue username and password at app.itglue.com.

If your SSO is not working, confirm your provider's service is available. Send us an email for assistance.

How do we disable SSO for a user?

To disable a user account, an Administrator or a Manager will need to navigate to the Account > Users page in IT Glue. We don’t currently support disabling user accounts through the SSO server.

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Contact us