Security Assertion Markup Language (SAML) is a set of specifications that establish a trusted relationship between two or more sites, allowing for secure single sign-on. This makes it possible to authenticate users and agents on your Helpy system using a centralized directory maintained by IT.

This article describes the general settings in Helpy that support the SAML standard. To see specific instructions on how to connect to a provider, see below:

How to integrate with Okta
How to integrate with OneLogin

How to configure SAML in Helpy Pro

Helpy Pro offers two options for configuring SAML Single sign-on. You can either add the SP and IdP configurations to a file stored on your self hosted instance(s), or add the settings to the admin panel in the settings section of Helpy. To use the file approach, view the instructions here:

https://support.helpy.io/en/knowledgebase/36/docs/157-configuring-saml-for-single-sign-on-sso

Configuring SAML using the system settings

1. Access SAML Configuration

Start by logging into the admin portal and visiting “Authentication” from the settings menu. Next, choose SAML from the options presented here:

The SAML configuration settings panel is broken up into 4 main sections, each detailed here:

2. General Settings:

>

Use these settings to enable SAML for your Helpdesk, and control how the login button is shown. You can also provide a label to be used on the login button.

SAML Enabled: This toggle determines whether or not SAML is turned on for your helpdesk. To authenticate with SAML, you also need to complete the rest of the configuration in Helpy and in your IdP.

Show a SAML button in the help center: This option Determines whether or not a “Sign in with SAML” button is present in the public-facing help center. It is possible to enable SAML without displaying the button publicly. Authentication would then be done using an IdP initiated login.

Provider Label: If a SAML button is displayed in the help center, the default button states “Sign in with SAML.” You may change this to reflect the Provider you are using- for example if your organization uses Okta, you should type in “Okta” here and the button will now show “Sign in with Okta”

3. Service Provider (SP) Settings

In the SAML relationship, your Helpy system is known as the Service Provider (SP). The information provided in the SP section is given to the Identity Provider (IdP). You will map each of these things to the appropriate configuration in the IdP’s interface.

SP Service Name: This setting is used to inform the IdP of the service provider. Generally, you will not need to give this to most IdPs. This is also known as the attribute service name.

SP SSO URL: You will provide this URL to the IdP. This is The URL at which the SAML assertion should be received. It is also known as the Assertion Consumer service URL or ACS Url.

SP Entity ID: This is required by most IdPs and is the URL where the SP Metadata is available.

4. Identity Provider IdP Settings

You will get values for each of the IdP settings from your Provider. Copy and paste the values into each field, including the IdP Cert (also known as the X.509).

IdP SSO Target URL: This is The URL to which the authentication request should be sent. It will be provided by the Provider and should be entered here.

IdP Entity ID: The IDP entity is provided by most Providers and should be entered here.

X.509 Certificate: The Providers certificate. This will be provided by the IdP.

Required IdP Attributes

You will also need to configure the Provider to pass attribute statements to Helpy in order for the integration to work. Helpy can only authenticate a user with a name and an email address. The minimum attributes required include:

“name” - this is the user's full name. Commonly known as the “displayName” in directories

“email” - this is the email address of the user being authenticated

Alternative attributes

Helpy also can accept custom attributes that you can use to control the role and team membership of users and agents.

“helpy_role” Pass an attribute of this name to set the role of the user being authenticated. Valid roles are ‘user’, ‘agent’, ‘editor’, and ‘admin’. If a helpy_role attribute is not sent, the user will be given the base ‘user’ role.

“helpy_team_list” Pass a comma delimited list of teams this agent should be given membership to.

5. Single Logoff (SLO)

SAML provides a facility for logging off a user from all applications associated with a user authenticated through the Provider.  Support for SLO varies by provider. Note: Helpy SAML does not currently support signed SLO Requests.

Enable SLO: To use the single logoff option, first enable it with this switch.

SLO Default Relay State: Describes where to redirect the user after logoff. Defaults to the Helpcenter homepage.

IDP SLO Target URL: The URL on the IdP to which the single logout request and response should be sent. This will be provided by your IdP provider and entered here.

SP Single Logout Service URL: For IdP initiated logout, log out requests from the IdP should go to this URL. You will provide this information to the IdP.