Using Custom SAML for Single Sign On (SSO)

HappyFox Help Desk supports Security Assertion Markup Language (SAML) so you can set up single sign-on (SSO) with an identity provider of your choice, such as Azure Active Directory, OneLogin, Okta, SmartSignin, or any SAML-compatible app you host yourself. You can use SAML to authenticate both agents and contacts.

Available on Basic Team Pro Enterprise PRO

​ ​ Note ​ Only one SAML-based SSO integration can be active at a time on a HappyFox Help Desk account.

Before you start

• Get the SSO Target URL from your identity provider, the URL HappyFox redirects to when someone clicks Login with SAML.
• Get your identity provider's SAML certificate. X.509 certificates are supported and must be in PEM format.

Configure custom SAML SSO

1. Go to Apps > All Apps, then open Custom SAML method.
2. Click Manage.
3. Under SAML Configuration, set Choose SSO Provider to Custom SAML.
4. Paste your identity provider's URL into SSO Target URL.
5. Paste your identity provider's certificate into IdP Signature.
6. Turn on Authenticate helpdesk agent using SAML, Authenticate end users using SAML, or both, depending on who should log in with SAML.
7. Optionally, turn on Map Custom Field Values from SAML to sync contact custom fields from your identity provider.
8. Click Save.

​ ​ Note ​ Under Basic SAML Settings on the same page, you can turn on Disable standard login for agents and Disable standard login for contacts separately to turn off username/password login once SAML is working.

Enable encrypted SAML assertions

For added security, you can encrypt your SAML assertions under Advanced SAML Settings by turning on Enable encrypted SAML Assertions, then clicking Save.

What your SAML server needs

Configure your identity provider with the following:

• The Access Consumer Service (ACS) URL: https://<accountname>.happyfox.com/saml/callback/. To authenticate agents only, use https://<accountname>.happyfox.com/staff/saml/callback/.
• The Destination attribute of the SAML Response, and the Recipient attribute of Subject Confirmation Data: the same ACS URL above.
• The SPNameQualifier attribute of NameID (optional): https://<accountname>.happyfox.com/saml/client-metadata/, or https://<accountname>.happyfox.com/saml/metadata/ for agents only.
• The NameID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. HappyFox uses this email address to match or create the agent or contact record.

​ ​ Note ​ If you run more than one SAML integration on the same account, use https://<account-name>.happyfox.com/saml/custom-saml/callback/ (or the /staff/ variant for agents only) as the ACS URL for custom SAML instead. If you use a custom domain, add the ACS URL in both the custom domain format and the default HappyFox URL format.

Things to remember

• Contacts log in through the contact portal and agents log in through the agent portal, so share the correct URL with each group.
• An agent logging in with SAML for the first time needs to be approved by an administrator, from Manage > Agents > Pending, under Pending SSO Agents.
• If your account uses a custom domain, it needs to be SSL-enabled for SAML-based SSO to work.

Continue reading