Enable Azure Active Directory SSO for your HappyFox account

With Microsoft Azure AD Single Sign-on, you can allow your agents and customers log in to the respective HappyFox panels (Agent Panel and Self-Service Panel) with their Azure credentials. 

Available in all pricing plans.

Note:

  • The Administrator in Azure needs to set up this integration (needs access to Active Directory / Application settings)

  • Customers are expected to login into customer portal and agent members are expected to login into agent portal. The right URL should be shared with concerned parties.

  • The custom domain in HappyFox (if present) needs to be SSL enabled in order to work with Azure integration.

  •  Integration can be achieved for all azure active directory plans(including trial account) 

Enabling Azure AD SSO involves:

  • Configuring HappyFox enterprise app inside your Microsoft Azure account.
  • Installing the Azure AD SSO app inside HappyFox with the target URL and Certificate.

Configuring HappyFox enterprise app inside your Microsoft Azure:

1.  Login to Azure. Choose "Azure Active Directory" and click on "Enterprise applications".

2. Click on "New Application"

3. Navigate to "CRM" category and search for "HappyFox".

4. Select  “Add" to confirm adding HappyFox. You can customize the name and icon if required.

5. After adding HappyFox, navigate back into "Enterprise applications" and click on the HappyFox logo (or an alternate logo uploaded by you).

6. Now, navigate to the "Single Sign-On" tab. For Single Sign-on Mode, choose "SAML-based Sign-on" and enter appropriate values for the fields below:

Sign On URL : https://<account-name>.happyfox.com/

Identifier : https://<account-name>.happyfox.com/saml/metadata/

Examples:

Sign On URL : https://xyz.happyfox.com/

Identifier : https://xyz.happyfox.com/saml/metadata/

7. Click on Download Certificate and copy the “SAML SSO URL” to your clipboard that needs to be pasted on the HappyFox setup. Also, fill the confirm checkbox.

 

8. Enter the email address that needs to be notified of the setup.

9. Scroll to the bottom and click on "Configure HappyFox". In the next screen, go to "Quick Reference" section and copy the value for "Azure AD Single Sign-On Service URL".

10. Now, from the Application (Happyfox in this example)->Users and Groups->All Users->check the tick mark->Select the User and assign access.

Installing the Azure AD SSO app inside HappyFox with the target URL and Certificate:

  1. Log in to HappyFox. Go to Apps >> Single Sign On >> Azure AD.
  2. Click "Install".
  3. Ensure SAML integration is active. Under "SAML Configuration", Choose "Azure AD".
  4. SSO Target URL is the Single Sign-on Service URL that was copied previously (in step #9) into the clipboard. Open the saved certificate(.cer file) in a text editor, copy its content and paste it in IdP Signature. Choose the settings shown below and save settings.

LOGIN SCENARIOS

Scenario 1: Agent Login:

From the HappyFox’s agent login page, when the agent clicks choose Azure SSO as the login method, he/she gets directed to the login screen shown below.

  1. When an existing agent member enters his credentials, he will be directed to the agent portal.

  2. When a new agent member enters his credentials, he will be added as a pending agent member.

Scenario 2: Customer Login

From HappyFox customer login page, when the customer chooses Azure SSO as the login method, he/she gets directed to Azure login screen.

  1. If an existing customer enters his credentials, he/she  will be directed to the self-service portal

  2. If a new customer enters his credentials, a new customer account will be created and he/she will be directed to the self-service portal

SETTING UP CUSTOM ATTRIBUTES

This feature allows us you to set attributes from Azure Active Directory to populate HappyFox Contact Custom Fields when a contact signs into HappyFox through Single Sign-on.

This feature requires Azure's Active Directory Premium plan.

In the Azure Active Directory application's (HappyFox) configuration page, go to the Single Sign-on tab and click on "View and edit all other attributes". Now click on "Add Attribute" and specify the name and the value that needs to be passed through. The mapping between the properties in Azure Active Directory with HappyFox Contact Custom fields happens automatically through the Name field. Enter the custom field name as-is in this configuration and it will be mapped. This currently supports text, number, dropdown and multiple choice fields (comma separated values).

 

Note that the custom field name in HappyFox should match that in Azure exactly.(Case-Sensitive)

Example: The string "City"  should be the same on Azure and HappyFox.

Example: The custom field value shown above gets populated in the HappyFox system when the user logs in.

To enable this in HappyFox, set the "Map Custom Field Values from SAML" setting to Yes in the same Apps -> Single Sign On -> Azure AD page from earlier in your HappyFox account.

Once this is set up, these fields will be updated every time the user logs in.

TROUBLESHOOTING:

In case you face the following error: ' Error AADSTS50003: No signing key configured. ' follow the steps given below.
This error is probably caused when the HappyFox object is corrupted and Azure Active Directory does not recognize the certificate configured for HappyFox.
Resolution:

To delete and create a new certificate, follow the steps below:

  1. Open the Azure Portal and sign in as a Global Administrator or Co-admin.

  2. Open the Azure Active Directory Extension by clicking More services at the bottom of the main left-hand navigation menu.

  3. Type in “Azure Active Directory” in the filter search box and select the Azure Active Directory item.

  4. click Enterprise Applications from the Azure Active Directory left-hand navigation menu.

  5. click All Applications to view a list of all your applications.

    • If you do not see the application you want to show up here, use the Filter control at the top of the All Applications List and set the Show option to All Applications.
  1. From the list of applications, select HappyFox. 

  2. Once the HappyFox application loads, click the Single sign-on from it’s left-hand navigation menu.

  3. click Create new certificate under the SAML signing Certificate section.

  4. Select Expiration date. Then, click Save.

  5. Check Make new certificate active to override the active certificate. Then, click Save at the top of the blade and accept to activate the rollover certificate.

  6. Under the SAML Signing Certificate section, click remove to remove the Unused certificate.

This error has been documented by Microsoft Azure AD here.
 

  • 556
  • 03-Oct-2018
  • 7376 Views