Group SSO test troubleshooting

This page is for administrators of Overleaf Group Professional plans who are testing their SSO configuration. Make sure you review the group SSO configuration and testing page for information about how to set up Overleaf group SSO. The Managing Group SSO page has information about troubleshooting SSO issues reported by group members.

Four phases of testing

Testing the Overleaf Group SSO consists of four different phases, and it is possible for problems to occur at any stage. The chart below summarizes what is happening at each stage of the testing flow, and identifies some issues which may occur.

	Test flow phase	Details	Causes of problems
1	An Authentication Request is sent from Overleaf to your IdP.	Overleaf sends a SAML request to your IdP’s single sign-on redirect URL (provided to Overleaf in setup Step 2) signed with Overleaf’s certificate (provided to your IdP in setup Step 1). A problem here looks like: An immediate problem after pressing the Test button may be caused by an issue at this phase. If you don’t see your IdP login screen, you have a problem in phase 1.	The wrong Redirect Endpoint URL was set in Overleaf (from your IdP). A mistake was made providing Overleaf’s certificate to your IdP.
2	Login at your IdP.	Your IdP presents you with a log on screen. You log in using an account that is authorized to access Overleaf (configured in setup Step 1). A problem here looks like: An error shown by your IdP indicates a problem at this phase. If you don’t get back to Overleaf after logging in, you have a problem in phase 2.	Overleaf is not registered as a service or app in your IdP. Your user is not authorized to access Overleaf.
3	Your IdP sends an Authentication Response to Overleaf.	Your IdP sends a SAML response to Overleaf’s Assertion Consumer Service endpoint (provided to your IdP in Step 1) using your IdP’s certificate (provided to Overleaf in setup Step 2). A problem here looks like: An unexpected error in Overleaf after logging in.	There is a mistake in the Overleaf ACS endpoint that was configured in your IdP. A mistake was made in providing your IdP’s certificate to Overleaf.
4	Overleaf processes the response from your IdP.	Overleaf will check the SAML attributes released by your IdP (set up in Step 1) and compare these with the attributes Overleaf is expecting (set up in setup Step 2). A problem here looks like: Overleaf received the authentication response from your IdP, but something is missing or different than expected.	The Unique Identifier was not released to Overleaf in your IdP. The Unique Identifier has a different name than what was expected.

If there is a misconfiguration either in your IdP or in Overleaf, one or more of these steps might fail. Fixing the problem may require going back and adjusting the configuration either in your IdP or in Overleaf.

Examples of errors

Test flow phase 1 problem

Clicking on the Test configuration button does not take you to a login screen.

• Verify that the Redirect URL provided to Overleaf in Step 2 is the Single Sign On HTTP-Redirect URL from your IdP metadata.

• Verify that Overleaf has been configured as a service provider in your IdP, that this configuration is enabled, and that it includes the signing certificate provided in Overleaf’s SAML metadata (https://www.overleaf.com/saml/group-sso/meta).

Test flow phase 2 problem

An access denied or similar error is shown by your IdP after you log in.

• Verify that the test user that you are logging in with has been authorized to access Overleaf in your IdP. This may require creating a security group in your IdP and adding the user to the security group.

Test flow phase 3 problem

A server error is shown from Overleaf after you log in.

• Verify that the Overleaf configuration is using the valid signing certificate provided by your IdP.

• Verify that the Assertion Consumer Service endpoint provided to your IdP is the Assertion Consumer Service endpoint found in Overleaf’s SAML metadata (https://www.overleaf.com/saml/group-sso/meta).

Another exception or error is raised.

• If you see a problem that is not identified on this page, please contact our support team. Be sure to let us know the email address associated with your Overleaf subscription administrator’s account, and describe the problem you're seeing. Including a screen capture of any error message or problem will help.

Test flow phase 4 problem

A validation warning is shown on the test results page.

• Verify that the name you provided for the unique identifier matches the attribute name that was released in your IdP for Overleaf and that this matches the name of the attribute that was sent to Overleaf.

Below are some error codes that you might see in a phase 3 or phase 4 problem, along with some details about the problem and some possible remedies.

Error code	Problem	Remedy
SAMLInvalidSignatureError or SAMLMissingSignatureError	This could be due to a certificate problem with the certificates that you have provided to Overleaf in setup Step 2. It could also be due to not setting the correct signing option for the responses sent to Overleaf in Step 1.	Check the metadata from your IdP and ensure that you are providing a valid X509 signing certificate. Your metadata may include several certificates, some could be out of date. You can add each available X509 signing certificate in Overleaf. We recommend that you remove outdated certificates from the configuration. Also, verify that the responses and assertions returned by your IdP are signed. In Azure, for example, you can choose various signing options as described here. Please ensure that you have chosen to sign both the SAML response and the assertion.
MISSING_EXTERNAL_USER_ID or INVALID_EXTERNAL_USER_ID	Overleaf did not find the Unique Identifier in the SAML that was sent in the Authentication Response.	Look at the SAML data shown to see if the Unique Identifier was sent under a different name. It can happen that IdPs will send this data under a different label. Change the configuration in Overleaf to match the name of the attribute that was sent. If there is no attribute that includes the Unique Identifier, it may not have been released by your IdP. Back in the settings for the Overleaf service in your IdP, make sure that this attribute or claim has been released.
MISSING_FIRSTNAME_ATTRIBUTE MISSING_LASTNAME_ATTRIBUTE	Overleaf did not find the first name attribute or the last name attribute that was specified in the group SSO setup.	Look at the SAML data shown to see if the missing attribute was sent under a different name. It can happen that IdPs will send this data under a different label. Change the configuration in Overleaf to match the name of the attribute that was sent. If there is no attribute that includes the missing information it may not have been released by your IdP. Back in the settings for the Overleaf service in your IdP, make sure that this attribute or claim has been released

Related documentation

• Overleaf group single sign-on—an overview of Overleaf group SSO.

• Setting up group single sign-on—detailed steps to help you configure single sign-on in Overleaf and in your Identity Provider.

• Linking users to group SSO—outlines steps required to get your subscription and your users ready to use single sign-on.

• Logging in with group single sign-on—instructions for group members to link their Overleaf accounts to their SSO identities and log in to their accounts. This documentation is intended for group members.

• Managing Overleaf group SSO—information for administrators on how they can maintain and make changes to their SSO configuration in Overleaf.

• User management in Overleaf—an overview of our Managed Users features.

• Managing a group subscription—an overview of adding and removing users and managers from an Overleaf group subscription.