This article will help you troubleshoot issues with your Single Sign On setup.

The admin user login page is centralised and not specific to your company account. Users have to enter their email address at the start of a SAML SSO login so we can find their company account.

Email entry is not required on the End User Portal as those login pages are specific to your company account. This means our SAML SSO solution can look up your configuration directly in order to connect with your identity provider.

The platform generates a pre-authentication token as part of the SAML SSO authentication process. This will not be present when an identity provider’s SAML test utility is used so the platform will show an error screen. This is because the platform cannot verify the company account for the SAML SSO authentication attempt.

You will have to test the SAML SSO integration by logging into the platform.

The Assertion Consumer Service (ACS) URL is the URL the SAML SSO identity provider will use to send a response to our platform. SAML SSO authentication responses will not reach the platform If the ACS URL configured in your identity provider is incorrect. Users will not be redirected back to the platform after the identity provider part of the process when this is the case.

Please confirm that the ACS URL in the platform’s SSO settings and your identity provider’s SAML SSO configuration match. The ACS URL will change if your Preferred Domain setting in the platform is updated.

The Entity ID identifies the platform as a SAML service provider. It is included in the SAML request URLs that redirect users from the platform’s login page to your identity provider. If it is incorrect, your identity provider will reject the request as the service provider (i.e. the platform) is not recognised.

Please confirm that the Entity ID in the platform’s SSO settings and your identity provider’s SAML SSO configuration match. The Entity ID will change if your Preferred Domain setting in the platform is updated.

The SAML Entry Point (or Identity Provider SSO URL) is used to construct the SAML request URLs that redirect users from the platform’s login page to your identity provider. If it is incorrect, users will not be redirected to your identity provider and SAML SSO will not be possible.

Please confirm that the SAML Entry Point in the platform’s SSO settings matches the one in your identity provider’s SAML SSO configuration.

The SAML Signing Certificate (or Public x509 Certificate) is used to sign the SAML request URLs that redirect users from the platform’s login page to your identity provider. If the signature cannot be verified then your identity provider will reject the request.

If in doubt you should go into the platform’s SSO Settings and replace the certificate with the current one from your identity provider’s SAML SSO configuration. You can also see the fingerprint of the current certificate which you can use to verify if the certificate present matches the one in your identity provider. Not all providers make this fingerprint visible which is why we advise to replace the certificate in the platform instead.

These certificates do have an expiry date so you may find that SAML SSO stops working because the certificate in place has expired. It is best practice to monitor the expiry date of your SAML certificates and replace them ahead of time. Otherwise you could be locked out of the system if you only allow SSO authentication for admin users on the platform.

Any user who wishes to log in to the platform using SAML SSO will need to be assigned to the integration on the identity provider side.

Most identity providers will include a user assignment option either during setup or as an administrative feature. Setting up a SAML SSO integration will include a user assignment step. That should allow you to specify the user who can authenticate on the corresponding service provider i.e. this platform. Your assigned users should match the platform’s user base as closely as possible. For example, if you use one of sync integration to import end users then your SAML SSO user assignments should pull in the same groups.

The SAML SSO authentication process matches identity provider and platform user accounts by email address. This feature does not support user provisioning of any kind so user accounts will not be created in response to successful SAML authentication. Users who need to authenticate using SAML SSO will require admin and/or end user accounts on the platform to access the admin console and/or end user portal respectively.

Some configurations of Microsoft Entra require the RequestedAuthnContext attribute be removed from the SAML request. You can achieve this by updating your SSO settings in usecure platform:

This error code is caused by an invalid signing certificate, and is often resolved by re-uploading for signing certificate. This can be done by navigating to Settings > SSO in your usecure portal and clicking the Replace Certificate button.

This error code means that no admin user account could be found for the email address returned in the SAML SSO profile data returned by the identity provider (IdP) when a login attempt has been made.

If the login attempt was to access the admin portal then it means that there is either no admin user for that email address or there is an email mismatch between the usecure account and IdP account. You would need to check that the User Principal Name on the account used to sign in matches the email address in usecure.

If the login attempt was for the end user portal then this is expected behaviour as the end user portal has a separate URL. You can find this URL under Settings > End User Portal.

This error code means that the SSO login reached the point where we get user profile data back from Azure AD but no end user account could be found for the email address returned.

The first step for diagnosing the cause of this issue is confirming whether or not a user account exists in the platform for the person attempting to login.

Out of the box, Azure AD returns the user’s User Principal Name (UPN) in the SAML response for their SSO login. If there’s a mismatch between a user’s usecure email address and their UPN then login will fail because the system can’t find a corresponding account.

There are 2 approaches to fixing this:

This error occurs when the system can't find an admin user account for the email address used to log in.

If end users are seeing this error when trying to access the system via SSO, make sure they are using the end user portal login page.

You can find the end user portal page for any customer by going into that account via the Admin Button in uService and navigating to Settings > End User Portal.

This typically means that you may have misconfigured the SAML setup on your identity provider outside of the option documented in our setup guides. For example, our solution relies on the Relay State returned by your identity provider. If you’ve set any options that disrupt the Relay State, the pre-authentication token we send as part of the SAML SSO authentication process may be lost or modified which will break our verification process.

You may find that users cannot login despite a successful login on their identity provider account. The pre-authentication tokens we issue during an SAML SSO login expire after a short period of time. If a user does not complete the full SAML SSO login process in that time they will need to try again. Subsequent attempts should be quicker as the user is logged into their identity provider already at this point.

When reporting SAML SSO issues to support please provide the following information:

If you use Google Workspace as an identity provider, your users may see a Google error screen if SAML SSO authentication fails. This typically indicates an issue with the custom SAML app you created in Google Workspace for this integration. You can find a full list of Google SAML app error messages here along with possible solutions for the underlying issues.