Enable Auth0 Single Sign-On for your HappyFox Account

This article describes how the Single Sign-On (SSO) integration with Auth0 can be set up.

Using this integration, it's possible to have HappyFox agents and/or end users sign into the respective portals using the same email ID as configured in auth0. 

Enabling Auth0 Login SSO for your HappyFox account Involves:

• Creating an Application in Auth0 and configuring it with Callback URIs.
• Creating a SAML2 Web app add-on for your Auth0 application.
• Installing the Custom SAML app inside HappyFox with the SSO target URL and IDP signature.

Creating an Application in Auth0 and configuring it with Callback URIs.

• Log in to Auth0 admin portal.
• Click "Applications" on the left navigation pane.Arial
• Click "Create Application" to begin the process of creating an application.
• Give your application a name and set the application type as "Regular Web App".
• Click "Create".  Go to the Settings Tab, and Under Allowed Callback URLs specify the URLs:
  1. https://<your account name>.happyfox.com/saml/callback/
  2. https://<your account name>.happyfox.com/staff/saml/callback/
  3. https://<your account name>.happyfox.com/saml/custom-saml/callback/

• Click on Show Advanced Settings at the bottom of the page.
• Under the Certificates tab, copy the contents of the certificate from the Signing Certificate text area. This needs to be pasted in HappyFox later as IdP signature.
• Under the Endpoints tab, SAML section copy "SAML Protocol URL".This needs to be pasted in HappyFox as SSO target URL. 
• Click on Save Changes.

Creating a SAML2 Web app add-on for the Auth0 application.

• Go to your Auth0 admin portal.
• Go to Application >> <Created Application>.
• Click on the "Add-ons" tab.
• Enable "SAML2 Web app".
• Ensure that the application callback URL is https://<your account name>.happyfox.com/saml/callback/ This should be picked automatically in auth0.
• Under Settings, enable(uncomment) these two parameters and set the values as:
  • nameIdentifierFormat
    • "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  • nameIdentifierProbes 
    • ["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]  
• Click Save. 

• Go to "Usage Tab" to cross-verify the various parameters:

Installing the Custom SAML app inside HappyFox with the SSO target URL and IDP signature.

• Log in to your HappyFox Agent portal.

• Go to Apps >> Single Sign-On >> Custom SAML method.
• Choose "Custom SAML method" under "Choose SSO provider".

• The SSO target URL should be the URL copied from "SAML Protocol URL" inside Auth0 application advanced settings.
• The IDP signature should be the certificate content copied from "Signing Certificate" inside Auth0 applications advanced settings.
• If you want agents to log in to HappyFox using Auth0:
  • Enable Authenticate helpdesk agent using SAML  drop-down.
• If you want contacts to log in to HappyFox using Auth0:
  • Enable Authenticate end users using SAML drop-down.
• Click "Save Settings" to complete the SSO configuration.

Enabling Encrypted SAML assertions:

You can also encrypt your SAML assertions for added security. This configuration is optional. To know more about this configuration inside HappyFox, click here. You'd also have to do some configurations inside Auth0. Here are the steps:

• Keep your SAML app client ID, Certificate and Encryption key handy.
• Inside Auth0, navigate to Dashboard > Auth Pipeline > Rules and click Create.
  • If you're new to Auth0 rules, click here to learn more.
• Pick an "Empty" rule template and specify a rule name.
• Under the "Script" section, paste the following code and replace the placeholders.

function (user, context, callback) {
  // this rule sets a specific public key to encrypt the SAML assertion generated from Auth0 
  if (context.clientID === 'THE_CLIENT_ID_OF_THE_APP_WITH_THE_SAML_APP_ADDON') {
	  context.samlConfiguration = (context.samlConfiguration || {});
    context.samlConfiguration.encryptionPublicKey = "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END PUBLIC KEY-----\n";
    context.samlConfiguration.encryptionCert = "-----BEGIN CERTIFICATE-----\nnnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n";
	}
  callback(null, user, context);
}

• Click "Save Changes". You're all set!

Usage

Once the configuration is done, Contacts can click on the Custom SAML button in the Support center login page to initiate the workflow. If Configured, Agents can also click on the Custom SAML button in their agent login page to do the same.