Single Sign-On Authentication
Single Sign On integrations with Helpjuice
Written by Emir Vatric
Updated at October 6th, 2022
Overview
Helpjuice supports a Single Sign-On authentication process. This page aims to clarify a bit about SSO and teach you how to properly configure SSO in your account.
Single sign-on (SSO) is an authentication method that enables users to securely authenticate with multiple applications and websites by using just one set of credentials.
The SSO process enables you to use your own ID provider to authenticate the users that should have access to your Knowledge Base. This is especially useful when you have tons of users and you don't want to create a Helpjuice user for each one of them.
How it works
In order to enable SSO in your account visit SSO(SAML) page in your Helpjuice settings.
If the fields in the Single Sign-On tab are disabled, it means that your current plan does not support it. If that is the case, contact our team and we will be happy to upgrade your account.
Helpjuice SSO is compatible with many different Identity Providers like Okta, Azure AD, OneLogin, ADFS, and custom IDPs.
Single Sign-On feature is established with two broad standard protocols adopted by Service providers that Helpjuice supports SAML and OpenId. Almost all implementations share the same configuration in Helpjuice settings, and we will take a quick look at the fields.
Helpjuice also supports Identity provided initiated Authentication.
SSO fields in Helpjuice settings page
In order to enable the SSO, we require you to fill in some fields on the settings page, not all fields are required in order to get SSO working.
| SSO Domain | The domain your users' emails are under, Helpjuice uses this to auto-create new users. |
| SSO Company | The name of your company within your Identity Provider. Helpjuice uses this to identify your account for users that do not have an email matching your SSO Domain. This field should match the company attribute in the response. |
| Identity Provider URL | The URL Helpjuice will send your users to authenticate. Once this field is populated the SSO is considered active! |
| Logout URL | Optional. The URL Helpjuice will send your users to log out. |
| Fingerprint | The SHA1 fingerprint of the SAML certificate. Obtain this from your SAML identity provider. |
| IDP Metadata | We require XML Metadata from your IDP when using Okta. |
| SSO Email Field | The field Helpjuice should use from the SAML response to get the user's first name. Defaults to first_name. |
| SSO Last Name Field | The field Helpjuice should use from the SAML response to get the user's last name. Defaults to last_name. |
| SSO Group Name Field | The field Helpjuice should use from the SAML response to get the user's groups. Defaults to group_names. Groups have to be created before sending group names inside this attribute. Multiple attribute values are accepted. |
| Issuer | The issuer to be sent with the request. Used by Active Directory Federation Services. |
| Authn Context | Keep this unchanged unless you are sure you need to change it. Select "None" for Active Directory Federation Services |
How users will log in
Now, all you need to do is ask your users to go to our regular Sign In page and choose the option that fits your case:
SAML Identity Provider
If you use a custom Identity Provider or Okta, you must click on Custom Single Sign-On. On the next page, you must provide your account's subdomain. It will be yoursubdomain.helpjuice.com.
OpenId
Helpjuice will redirect the user to your ID ProviderURL and, once the user is authenticated, he/she will be signed in. If a user record for that e-mail does not exist, it will be created automatically ( if the Auto Provision Users option is active ).
SSO Users vs Helpjuice Users
Users from your Identity Provider and users you add via Helpjuice Dashboard are independent. You can have people signing in via SSO and/or regular email/password at the same time without a problem.
When you set up an SSO provider, existing users can also start using SSO to authenticate, as long as their emails match.
When a user authenticates via SSO, Helpjuice will try to match the signing-in user to an existing one by email. If it exists and is already a member of your KB, he is authenticated and signed in, password and other user details are left untouched. If it exists but isn't a member of your KB yet, an email invitation will be sent. The user must accept it before he is allowed to access the KB. If no user matches, a new one is created with the Viewer role and an auto-generated password is forwarded to their email. This user can then sign in either via SSO or regular email/password authentication without a problem. We need to provide a password to SSO users so they can update their profile details in Helpjuice dashboard and therefore this email cannot be deactivated.
Troubleshoot SSO Issues
Setting up SSO is not always an easy and straightforward process, in this section, we will go through some useful tools for debugging as well as through some common issues that you might face.
Debugging Tools
Over the years of supporting our customers with implementing Single Sign-on, we default to one useful tool for tracking SAML messages between Helpjuice and Identity Provider.
- Install this add-on on Chrome.
- Restart the browser
- Initiate SSO login again
- Observe the SAML response via the add-on
Common Error Messages
Here we are going to run through some common error messages that you could face during the setup process and how to resolve them.
Important
We have to note that it is not possible to update the user via SSO, or if you delete the user via the dashboard and recreate it. If you want to see changes reflected you need to sign in as a fresh user.
Helpjuice doesn't redirect the user to IDP for authentication
This issue indicates that Identity Provider URL is not set, or is incorrect, please visit Helpjuce settings page and populate that field.
Current time is earlier than NotBefore condition'. Please login as admin and verify your IdP fingerprint is correct and your certificates have not expired on your IdP
It looks like there's a time difference between your identity provider and Helpjuice servers. Since you are the only customer with this problem, it means that Helpjuice servers have the correct time. Can you please check the time in your server and make sure it's not delayed or anything?
Could not find an Email in the field
When this error occurs it means that the email attribute name specified in the email field in helpjuice settings was not found in the SAML response. You can find your SAML response with the tool above.
Users are not created with first and last name
When this error occurs it means that the first name or last name attribute name specified in the first name or last name field in helpjuice settings was not found in the SAML response. You can find your SAML response with the tool above.
If you are using Azure AD it is important to remove the namespace before the attribute name.
How to assign groups via SSO
Let us consider the example from OKTA:
<saml2p:Response
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
......
......
<saml2p:Status
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
<saml2p:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</saml2p:Status>
<saml2:Assertion
......
......
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
<saml2:AttributeStatement
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute
Name="groups"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">admins_group_1
</saml2:AttributeValue>
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">it_admins
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
</saml2:Assertion>
</saml2p:Response>In order to assign the user to id_admins and admin_group_1 we need to specify in helpjuice settings groups attribute groups since that is the name that carries the values for groups.
Warning
This feature is currently being tested. Contact support so we can enable it for you.
Check https://help.helpjuice.com/en_US/authentication/sso-with-okta on how to configure the group assignments via SSO.