US English (US)
FR French
DE German
SA Arabic
BS Bosnian

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Book a Demo
  • Product Updates
  • Contact Us
English (US)
US English (US)
FR French
DE German
SA Arabic
BS Bosnian
  • Home
  • Authentication

Single Sign-On Authentication

Single Sign On integrations with Helpjuice

Written by Emir Vatric

Updated at October 6th, 2022

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Integrations
  • Getting Started
    Users Accessibility New to Helpjuice? Start Here Content Management Multiple Languages/Translations & Localization Multilingual Knowledge Bases Analytics Video Tutorials
  • Customization
    Customization Guides
  • API V2
  • API V3
  • Article Editor
  • Swifty (In-App Widget)
  • Billing / Subscription
  • Authentication
+ More

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.

  1. Install this add-on on Chrome.
  2. Restart the browser
  3. Initiate SSO login again
  4. 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.

Your browser does not support HTML5 video.

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.

Delete

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.

 


Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Single Sign On with Okta
  • Single Sign On with Azure AD
  • Single Sign On with ActiveDirectory Federation Services (ADFS)
  • Single Sign On with JSON Web Token

Copyright © 2023 - Helpjuice

Helpjuice, Inc. is a registered US Corporation, EIN # 45-2275731

Download W9
  • Help
  • Features
  • Pricing
  • About
  • Careers
  • Customers
  • Blog
  • Case Studies
  • Resources
  • Knowledge Base Examples
  • Privacy Policy
  • Terms of Service

Why is the knowledge base important?

With a knowledge base, you can allow your customers to self-help themselves, thus reducing your customer support by up to 60%. Furthermore, you can also have your team get instant answers to the questions they need without having to email themselves all using knowledge base software.

What is the purpose of a knowledge base?

The purpose of knowledge base software is to allow you to host your knowledge base/corporate wiki in one centralized 'hub'. Both your customers, and employees can now access information within seconds!

Made with from Miami, Bosnia, Morocco & Brasil

+1 (833) 387 3877 success@helpjuice.com
Expand