Skip to main content
Contact Support

Troubleshooting Single Sign-On with Formstack

Ryan J.
Updated

Setting up single sign-on can have unique challenges for each account since setup needs will vary for each organization. Review below for go-to troubleshooting steps. 

 

Initial troubleshooting steps 

  1. Check with your IT Department for any changes to your Identity Provider or SSO application
  2. Check your authentication provider settings in the Formstack Admin Panel for any changes. You can see who last changed the authentication provider and when. 
  3. Run the SAML Tracer add-on to diagnose issues with your SAML connection.

 

SAML Tracer

If you run into issues with your SAML Single Sign-on setup with Formstack, SAML Tracer is recommended to diagnose.

SAML Tracer is a free add-on available for Firefox and Chrome browsers. When enabled, It captures the SAML request and response when you start an IdP- or SP-initiated flow. For step-by-step instructions on how to use SAML Tracer, refer to this documentation.

Note: Most errors found with this add-on should be able to be addressed by your IT department.


 

Common errors and recommended troubleshooting

Error: 404 Error Not Found

Solution: If you receive a 404 error when attempting to log in to Formstack from your Identity Provider (like Okta or OneLogin), there’s a good chance that there is an error in your Formstack authentication provider configuration. Check for these issues:

  1. The authentication provider is enabled in the Formstack Admin Panel Single Sign-on page

  2. The ACS URL you’re using in your SSO application in your identity provider matches the one listed in your authentication provider metadata located in the SSO Settings within your Admin Panel. Your application may have been configured using the Formstack Forms feature that allows you to set up SSO to gate access to published forms called ‘Form Authentication’. This is not the same as SSO to gate user login to the Formstack Platform. Follow these directions to set up Single Sign-on for logging in.


Error: 405 Method Not Allowed

Solution: This error typically occurs when, in your Okta Identity Provider SSO Application settings, the Entity ID is used for the SSO URL rather than the ACS URL. To confirm, look at the end of the URL. If you see /samlEntityId, you’re using the wrong URL. Use the ACS URL in the authentication provider metadata in your Formstack Single Sign-on auth provider settings that end with /process.


Error: Application with identifier ‘https://admin.formstack.com/orgidp/xxxx/samlEntityID’ was not found in the directory ‘your_directory_name’. This can happen if the application has not been installed by the administrator of the tenant or is consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.

Solution: This error may occur if the metadata is out of sync between the application and Formstack’s authentication provider. Try re-importing the Formstack (service provider) metadata into your identity provider application to re-sync things between the systems.


Error: Oops! Unable to process saml response: Unable to authenticate: invalid_response. Invalid audience for this Response (expected https://admin.formstack.com/orgidp/xxxx/samlEntityID’, got ‘https://yourdomain.formstack.com’)

Solution: In this case, the new authentication provider was set up to use the IdP application that controls Forms Form Authentication functionality. A new application needs to be created within the Identity Provider and configured with the service provider metadata found in the authentication provider setup settings in the Admin Panel.


Error: Oops! Unable to process saml response: Unable to authenticate: invalid_response, The status code of the Response was not Success, was Requester -> urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy

Solution This error typically occurs when the naming policy set by the IdP application does not match what Formstack is expecting. There are several ways to resolve this issue and choosing the best option is highly dependent on the identity provider used.

To understand the issue better, we recommend starting by running SAML Tracer to find the exact nameid the SAML request includes. Then, adjust the naming policy to match Formstack’s specs.

 

Error: Oops! Unable to process saml response: Unable to authenticate: invalid_response, The status code of the Response was not Success, was Responder -> Unable to encrypt assertion. 

Solution This error occurs when the SAML2 SSO Assertion is set to always or conditionally be encrypted. In the IdP application settings, set ‘Encrypt SAML2 SSO Assertion’ to Never.


Error: "SAML Response not found, Only supported HTTP_POST Binding”

Solution: This error is generally not related to the SAML response attributes, but rather, to how the SAML response is returned to Formstack. The library we use only supports the identity provider sending the SAML response in a POST request back to the Formstack ACS URL. If you look at the SP metadata XML file that Formstack provides, in our SPSSODescriptor element, we have the AssertionConsumerService element which specifies the binding attribute as "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" which indicates that we expect the response as a POST variable.

  

Error: “Username already exists for this authentication provider”

Solution: This usually means an existing account has another authentication method enabled. If so, the user should sign in using that method (such as email and password).

This error message can also be received if the Username Attribute of their SAML credentials doesn’t match the username of their account. If so, the user can update the attribute at their identity provider (for instance, back to the old value if it had been previously updated).  


Error: "Error: Failure decrypting data”

Solution: This typically means the XML response sent back to Formstack is invalid. Additionally, this may also indicate that the x509 certificate is not up-to-date or accurate. 


Error: "urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy"

Solution: This usually means that on the Auth Provider side, an email address is missing or not coming through in the response. If you are on AD/ADFS then you may need to add a claim with an E-Mail Address (for example). 

If you have an alternative provider that is going through SAML, you will need to make sure the response contains the email address. This needs to come across as the “Name ID” in the SAML response.


Error: "ERROR: Unable to authenticate: invalid_response, The status code of the Response was not Success, was Requester"

Solution: This is a generic error that occurs when we are unable to parse the response that we receive back and usually means that there was some kind of error or bad data that has been sent back.

Errors like this generally occur with SAML and in these cases, the XML sent back is not like a regular response, rather it may have been configured to hit a webpage instead of sending back the correct XML SAML response.


Error: "Reference Validation Failed"

Solution: Formstack may be receiving a response from a server or domain that was not expected. There is likely a misconfiguration in the settings, however, it may also be a response from Auth Provider not expecting a request from Formstack. We recommend checking your settings to ensure the host/domain is correct.
 


If you’re experiencing other error messages or the troubleshooting tips you see above don’t fix the issue please reach out to our support team for further assistance. Please have the following information available:

  • Your account’s Org ID

  • The name of your Identity Provider (OneLogin, Okta, ADFS, Shiboleth, etc) 

  • The type of provider (SAML, OIDC)

  • The SAML Trace file

  • A screenshot of the error message you’re seeing

Related articles