Single Sign-On Authentication

Single Sign On integrations with Helpjuice

Updated at May 14th, 2024, by Amanda Stançani

+ More

SSO Overview SSO Users vs Helpjuice Users Login Screen SSO Users Will See Helpjuice SSO (SAML) Page Configuration Troubleshooting

SSO Overview

In this article, we'll explore the concept of SSO and walk you through the process of setting it up seamlessly within your Helpjuice account.

Single Sign-On (SSO) is a modern authentication method designed to simplify user access to multiple applications and websites. With SSO, users can securely authenticate themselves using a single set of credentials across various platforms, eliminating the need for multiple login credentials.

Becoming Familiar with SSO Key Components

The majority of our users use SSO with SAML and to understand it, it's important to be familiar with its key components:

Identity Provider (IdP): The IdP is responsible for authenticating users and issuing SAML assertions, which contain information about the user's identity and attributes. The IdP acts as a trusted authority that validates user credentials and generates the necessary tokens for authentication.
Service Provider (SP): The SP relies on the IdP for user authentication and receives SAML assertions. It leverages these assertions to determine the user's identity and grant or deny access to the requested resources or services.
SAML Assertion: A SAML assertion is an XML document that contains information about a user's identity, attributes, and authentication status. It is digitally signed by the IdP to ensure its integrity and authenticity.

Becoming Familiar with How SSO (SAML) Works

The SSO process with SAML involves the following steps:

User initiates login: The user attempts to access a protected resource or application and is redirected to the SP's login page.
SP requests authentication: The SP generates a SAML request and redirects the user to the IdP's login page, passing along the SAML request as a parameter.
User authenticates with IdP: The user enters their credentials on the IdP's login page. The IdP verifies the credentials and generates a SAML assertion containing the user's identity information.
IdP sends SAML assertion: The IdP sends the SAML assertion back to the user's browser as a response to the initial SAML request.
User presents SAML assertion to SP: The user's browser submits the SAML assertion to the SP.
The SP verifies the integrity and authenticity of the SAML assertion. Upon successful validation, the SP grants access to the requested resource or application.

SSO Users vs Helpjuice Users

When you set up SSO, existing users can also start using SSO to authenticate as long as their emails match.

During SSO authentication, Helpjuice automatically attempts to match the signing-in user with an existing account based on their email.

If a match is found and the user is already a member of your Knowledge Base (KB), authentication occurs smoothly, preserving passwords and user details.
If the matching account exists but is not yet a KB member, Helpjuice sends an email invitation. The user must accept this invitation before accessing the KB.
In cases where no matching account is found, a new user is created with the User Role specified in the SSO Role ID field.

This new user can then sign in either via SSO or via regular Helpjuice email/password authentication.

Please note that SSO users will always have Helpjuice Credentials to login using our Regular Sign In and this cannot be removed.

Helpjuice SSO (SAML) Page Configuration

Here you will find a list of all fields available on your Helpjuice SSO (SAML) section and how to fill them out.

Specification of All Fields on the Settings Page

SSO Domain	The domain your users' emails are under (like in amanda@helpjuice.com). Helpjuice uses this to auto-create new users.
SSO Company	If you want users with multiple email domains to login via SSO, add your subdomain to the SSO Company field, create a 'company’ attribute on your IdP and set it's value to your subdomain.
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	The field Helpjuice should use from the SAML response to get the user's email. Defaults to nameid.
SSO First Name	The field Helpjuice should use from the SAML response to get the user's first name. Defaults to first_name.
SSO Last Name	The field Helpjuice should use from the SAML response to get the user's last name. Defaults to last_name.
SSO Group Name	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.
SSO Role ID	The field Helpjuice should use to assign a role to a new users.
Signing & Encrypting	In beta and not required
Auto-Create Users	Automatically create a user account for new users signing in via SSO
Auto-Accept Invite Settings	Configure the domains that should have invites auto-accepted for easier user onboarding.
Issuer	The issuer to be sent with the request. Used by Active Directory Federation Services and can be set to helpjuice.com
Authn Context	Keep this unchanged unless you are sure you need to change it. Select "None" for Active Directory Federation Services
Send Welcome E-mails to New SSO Users	Choose whether new SSO users should receive a Helpjuice Inviation email or not.

Assigning Groups via SSO

Let us consider the following example (it's from OKTA, but the same rules apply)

<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>

Considering the example above, if youwant to assign users to groups admins_group_1 and it_admins, the SSO Group Name Field on Helpjuice should be set to groups, since that is the name that carries the values for groups.

(Beta) Groups Syncing

This option allows you to sync groups every time the user signs in with the groups provided on the SAML response.

If you want to manage the users' groups from your IDP, please contact support@helpjuice.com to enable this option.

Please note that users will be removed from groups that are not present on the SAML response.

Troubleshooting

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

Provide this response to the Helpjuice Support Team to facilitate the troubleshooting.

Helpjuice Doesn't Redirect the User to IDP for Authentication

This issue indicates that Identity Provider URL is not set or is incorrect. Please go to your Helpjuice Settings Page and populate that field.

Users Are Not Automatically Created

Check the Helpjuice Settings Page to confirm that Auto-Create Users option is enabled

Users Are Not Able to Login via SSO

The first thing you need to do is check if the email domain of the user who is experiencing issues is the email domain added in the SSO Domain field, on the Helpjuice settings page. This is the problem in the majority of the cases and happens because only one email domain is allowed in the SSO Domain field. However, there is a workaround:

If you need SSO with multiple email domains, you can use the SSO Company field and two modifications will be required

Helpjuice Settings page: The SSO Company field should contain your subdomain. For example: if the knowledge base is help.helpjuice.com, the subdomain is help
Identity Provider side: You need to create a new attribute named company and the value should match what is in the SSO Company field

Users Are Not Mapped Correctly

Make sure the Attributes section on the Helpjuice Settings Page matches the Values of the Attributes created on your IdP.

Users Are Not Created with First and Last Name

When this happens, 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.

“You were not correctly authenticated, SAML response is invalid. (Invalid Signature on SAML Response)”

The Fingerprint added in the Helpjuice SSO page is probably not correct. Please double-check this information on your end and update the Helpjuice Settings Page accordingly.

“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 likely the only customer with this problem, it means that Helpjuice servers have the correct time.

Please check the time in your server and make sure it's not delayed.

"Could Not Find an Email in the Field"

When this error happens, it means that the email attribute name specified in the SSO Email field in Helpjuice settings was not found in the SAML response. You can find your SAML response with the tool mentioned above.

"AADSTS700016: Application with identifier 'helpjuice' not found in the directory…"

You need to update two things:

Helpjuice Settings page: Set the Issuer field to helpjuice.com - no HTTPS
Identity Provider side: Set EntitityID to helpjuice.com - no HTTPS

"AADSTS75011 Authentication method by which the user authenticated with the service doesn't match requested authentication method, 'Password, ProtectedTransport'. Contact the Helpjuice application owner"

The issue is due to the Authn Context configuration on the Helpjuice Settings Page

In this case, we can recommend two approaches:

You can ask your users to log in using Password Protected method
Or you can set the Authn Context field to blank on the Helpjuice Settings Page and this is the recommended approach for Azure AD SSO in our Help Articles.

Azure Users - This Will Likely Fix 99% of the Issues

Most issues are related to the Namespace, which is the following part added to attributes
"http://schemas.xmlsoap.org/ws/2005,..."

If this is present on your attributes, please remove it as explained in the following video.

auth sign-on

Contact Us