Skip to main content
Eptura Knowledge Center

Set up ADFS SSO with Hippo

  1. Last updated
  2. Save as PDF

Introduction

This tech note discusses how to set up Active Directory FS Single Sign On (SSO) with Hippo V6.

What is Single Sign On (SSO)

mceclip0.png

Single Sign On (SSO) is a new feature utilized by Hippo that simplifies the login procedure.

Single Sign On (SSO) is an authentication process that allows the user to access multiple applications with a single set of login credentials (username and password). One of these applications can be Hippo CMMS.

How does It work?

mceclip1.png

In Hippo, SSO is managed by an identity provider. The role of an identity provider is to allow for reliable integration for SSO to all your applications, including Hippo. Examples of identity providers include Active Directory Federated Services (AD FS), Active Directory Azure, and Okta.

I have Active Directory FS. How do I set it up to work with Hippo?

Hippo supports single sign-on (SSO) authentication through SAML 2.0. A SAML 2.0 identity provider (IdP) can take many forms, one of which is a self-hosted Active Directory Federation Services (AD FS) server. AD FS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials

Requirements:

To use AD FS to log into Hippo, you will need the following components:

  1. An Active Directory instance where all users have a uniquely specified username attribute.
  2. An Active Directory instance where all users have an email address attribute.
  3. A server running Microsoft Server 2012 or 2008. This guide uses screenshots from Server 2012R2 but similar steps should be possible on other versions.
  4. A SSL certificate to sign your AD FS login page and the Signing Certificate for that certificate.
  5. An installed certificate for hosted SSL.

After meeting these basic requirements, you must have AD FS installed on your server. Instructions for configuring and installing AD FS can be found here. (Instructions can also be found here.)

In your AD FS installation, please note the value for the ‘SAML 2.0/W-Federation’ URL in the AD FS Endpoints section. If you chose the defaults for the installation, this will be ‘/adfs/ls/’.

Step 1 – Adding a Relying Party Trust

At this point, you should be ready to set up the AD FS connection with Hippo. The connection between AD FS and Hippo is defined using a Relying Party Trust (RPT).

Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.

In the Select Data Source screen, select the last option, Enter Data About the Party Manually.

mceclip0-1.png

On the next screen, enter a Display Name that you'll recognize in the future, and any notes you want to make.

mceclip1-1.png

On the next screen, select the AD FS profile radio button.

mceclip2.png

On the next screen, leave the certificate settings at their defaults unless you would like to choose a certificate in which case you'll have to provide your public key later.

mceclip3.png

On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol.

The service URL will be:

https://auth.hippocmms.com/sso/provi...nt_id=clientID 

or 

https://auth.hippocmms.ca/sso/provid...nt_id=clientID

(If your login URL ends with .CA)

replacing clientID with your Hippo’s clientID.

Note: that there's no trailing slash at the end of the URL. Enter the service URL in the space highlighted in red.

mceclip4.png

On the next screen, add a Relying party trust identifier of https://auth.hippocmms.com

 or 

https://auth.hippocmms.ca (If your login URL ends with .CA)

Note: that there's no trailing slash at the end of the URL

mceclip5.png

On the next screen, you may configure multi-factor authentication, but this is beyond the scope of this guide.

mceclip6.png

On the next screen, select the Permit all users to access this relying party radio button.

mceclip7.png

On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.

mceclip8.png

Step 2 - Creating claim rules

Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default, the claim rule editor opens once you created the trust.

  1. To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims
  2. On the next screen, using Active Directory as your attribute store, do the following:
    1. From the LDAP Attribute column, select E-Mail Addresses.
    2. From the Outgoing Claim Type, select E-Mail Address

mceclip9.png

  1. Click on OK to save the new rule.

Hippo CMMS uses Email of the user as a login ID. In order for this to work, you need to set up the Email as the NameID on the SAML login request. This can be achieved by setting up a Transform Rule.

  1. Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.

mceclip10.png

  1. On the next screen:
    1. Select E-mail Address as the Incoming Claim Type.
    2. For Outgoing Claim Type, select Name ID.
    3. For Outgoing Name ID Format, select Email.

Leave the rule to the default of Pass through all claim values.

mceclip11.png

  1. Finally, click OK to create the claim rule, and then OK again to finish creating rules.

Step 3 - Adjusting the trust settings

You still need to adjust a few settings on your relying party trust. To access these settings, select Properties from the Actions sidebar while you have the RPT selected.

  1. In the Endpoints tab, click on add SAML to add a new endpoint.
  2. For the Endpoint type, select SAML Logout.
  3. For the Binding, choose POST.
  4. For the Trusted URL, create a URL using:

https://sso.yourdomain.tld/ADFS/ls/

example: https://sso.yourdomain.com/ADFS/ls/

  1. The Response URL should look something like this:

https://yourdomain.tld/ADFS/ls/?wa=wsignout1.0

Confirm OK twice. You should now have a working relying party trust for Hippo.

Step 4 - Export the certificate

  1. On the AD FS Management Window, choose Services -> Certificates and double click on Token Signing Certificate, which will give you an option "copy to file". By doing this, you will be able to export the X509 certificate from the raw file.
    4zEJoZFLhiUP6F59SH2ZsUhCKfeH-J_wcg_1494446336.png
    q_7UXpHqP7SBEtplGr9C8u93NRbf8XFbHQ_1494446321.png
  2. Choose a location to save the certificate file, click Next and click Finish, OK, and OK again.
  3. Open the certificate file you exported in Notepad(or another plain text editor) and copy the contents.

*Note: You must include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers when copying the certificate file contents. You should use Notepad or another plain text editor to open the certificate file; WordPad, Word, etc. are not plain text editors and may prevent you from copying the certificate correctly.

AD-FS-Cert-in-Notepad.png

Configuring Hippo to authenticate SAML

Please provide Hippo Support with the following (via xml or text):

For example: 

 '-----BEGIN CERTIFICATE-----MIIDdDCCAlygAwIBAgIGAV9KjgbeMA0GCSqGSIb3DQEBCwUAMHsxFDASBgNVBAoTC0dvb2dsZSBJ 
 ……………………………………………………………………………………………………………………………………………………………………………………… 
 r9W286fnOiD9lmIik1pv1XS7VirqoPqRZdJ4jP9+5wdC7qSRWZWNt9KCneZQSxTJ8AGR4X8OH8bx kbDloKgAvQM/g0l79NCAYNjqYhSYlaVhUNCqNf8v+2KqeCbFoH12h9l/UzCHYAJuf+oQyLALOmwb /vefuMKDwOmA4FEhfbMqnnlALN/wetev4io4a5yQJfrCvw2wHQkkFaKZAXEdRmYHhFvwEb71Vqp5 
 T7ooh74Yqj9UwWJKBHMruUcpPvqlllUWDOopTOxhn7Nm-----END CERTIFICATE-----