Single Sign On (SSO) - Auth0 Configuration

Prerequisites

• An Auth0 account is needed before EngageIP can be configured for Single Sign On.  You can create your account by visiting Sign Up - Auth0

• You will need two SSL certificates. One for the SAML request signing, this can either be a self signed certificate or from a public CA (e.g. GoDaddy). The other will come from Auth0 (see step 13 below)

• To configure the Single Sign On option in EngageIP, the logged in user needs to be a member of a role that has the "OwnerSingleSignOnConfiguration" options enabled. To check this go to Setup / Roles / select the proper role / find the "OwnerSingleSignOnConfiguration" under "ROLE PERMISSIONS"

Adding EngageIP  to Auth0

1. Login to your Auth0 dashboard

2. Navigate to the Applications page in your Auth0 dashboard

   Open

   

    

3. Click +Create Application

   Open

   

    

4. Provide a name for your application

5. Select Regular Web Applications for the application type

6. Click Create

7. Click the Settings tab (bypassing the Quick Start)

8. Populate the Allowed Callback URLs with the following (replacing YOUR_EIP_URL with the actual hostname for your EngageIP instance)

    

9. Scroll down and click Save Changes

10. Click on the Addons tab

11. Click the SAML2 Web App button

     

12. This will bring up the settings page. Scroll down and Click Enable

13. Click on the Usage tab and Copy the data shown in Identity Provider Login URL and Issuer, and then download the certificate by clicking the Download Auth0 Certificate link for use a bit later

14. Close the popup window

15. SAML2 should now indicate that it's enabled

Configuring Auth0 in EngageIP

1. Log into the web server that is running your EIP instance

2. Browse to the C:\Program Files (x86)\EngageIP\AdminPortal folder

3. Create a folder called "Certificates" and place your SAML signing certificate and the certificate you downloaded in step 13 above into the new folder

4. Go back into the AdminPortal folder and find the web.config file. Make a backup of the config file

5. Open the original web.config file in a text editor

6. Add the below line in the <configSections> area

   <section name="samlConfiguration" type="Logisense.Boss.Presentation.SamlConfigurationSection" />

7. Add another line below to the bottom of the web.config just above the </configuration> line
   Note: this step is using your SAML Signing Certificate, not the one you downloaded from Auth0

   <samlConfiguration name="EngageIP" description="Engage Default" assertionConsumerServiceUrl="~/login/saml.rails" localCertificatePassword="YOUR_SAML_CERT_PSWD" localCertificatePfxFile="Certificates\YOUR_SAML_CERT.pfx" />

   Important: You must save the changes you made to the web.config file. Saving the changes will cause the application pool to recycle which will terminate any active sessions and will require your users to log back into the EngageIP system

8. Login as an administrator into EngageIP

9. For the desired owner, click on Setup then scroll down to Accounts and Roles. In the Permissions area you will see the option for Single Sign On, click it to navigate to the SSO setup

    

10. Configure the SSO Settings:

     

    1. Check the Enable Single Sign On checkbox

    2. Populate the Authentication URL in EngageIP using the Identity Provider Login URL from Auth0 (from step 13 of previous configuration steps above)

    3. Populate the "Issuer" in EngageIP using the "Issuer" from Auth0 (from step 13 of previous configuration steps above)

    4. Click Choose file next to Replacement Identity Provider Certificate in EngageIP and browse to the Certificates folder you created in step 3 above.  Select the certificate you downloaded from Auth0 (from step 13 of previous configuration steps above)

    5. Enter a Session Time Out (e.g. '1h')

    6. the Logout URL can be any site to send user to after logout, but what makes the most sense is to use the user's Auth0 home.  This is the same hostname as what you entered into the Authentication URL

    7. Click Save

Adding Users to Auth0

1. Access your Auth0 admin dashboard

2. Click Users & Roles in the menu on the left, then Users

3. Click the + Create User button

4. Add the user information and leave the connection set as Username-Password-Authentication

5. Click Create

Configuring User Mapping in EngageIP

1. Login to Auth0

2. Navigate to the Users page (using left-hand link)

3. Click on the user who you wish to add to EngageIP

4. Scroll down to Identity Provider Attributes and copy the data shown in the “user_id” field

5. Login to EngageIP

6. Navigate to the Overview page for the owner you wish to configure SSO for using Auth0

7. Under Components click Add and then Single Sign On

Note: if the Single Sign On link does not appear, ensure that you've properly configured Single Sign On for this owner. See the 'Configuring Auth0 in EngageIP' steps above

8. Enter the SAML Federation ID.  This is the user_id that is populated by Auth0

9. Ensure that the Single Sign On Enable checkbox is checked

10. Click Save

Logging Into EngageIP From Auth0

1. Navigate to the Auth0 app login. This will be the same as the 'Identity Provider Login URL' you entered in the 'Configuring Auth0 in EngageIP' section above

2. You should now see the Auth0 log in specific to your app

    

3. Enter your Auth0 credentials and click Log in

4. You should now be signed into EngageIP. There may be a slight delay (of white screen) while EngageIP completes the login process

See Also

• Single Sign On (SSO) – Overview

• Single Sign On (SSO) – Okta Configuration