Single Sign-On (SSO)

TABLE OF CONTENTS

• How to Claim Your Domain
• Troubleshooting Single Sign-On with Formstack
• Quiet User Creation
• Configure Auto-Redirect for SSO Login
• OneLogin SAML SSO Setup Guide
• OpenID Connect SSO Setup Guide
• SSO Autofill vs Field Prefill
• Getting Started with ADFS through SAML 2.0
• Formstack Single Sign-On Overview
• SAML SSO Overview
• Microsoft Entra ID SSO Setup Guide (Formerly Azure AD)

How to Claim Your Domain

If you’re using single sign-on for login and user management, claim your domain to prevent users that don’t belong to your organization from logging in to your account.

You can have more than one claimed domain; however, a domain can only be claimed once, and can only be applied to one Formstack account. If your domain has already been claimed, you must either join that Formstack account to use that domain for SSO or use a different domain for SSO.

Claiming your domain is quick and easy and verifying your domain can be done automatically in the app.

Step 1: On the Single Sign-On tab in the Formstack administration panel, select “Claim domain.”
 

You have two ways to verify your domain: DNS or HTTPS.

DNS

With this option, simply publish a txt record you can take the text value and make a record in your DNS host and add the copied text value to the record and publish.

Note: There may be a delay for the changes to post within your DNS host.

HTTPS

Your second option is HTTPS. This can be verified by having a valid SSL certificate from your web host. Simply download the HTML file from the Formstack claimed domain model and upload it to your root directory and publish it.

Step 2: Select Verify now to capture your claimed domain and confirm verification.

Once you’ve verified your domain, the following modal will appear and your claimed domain will appear in the “verified” state.

What if my domain has already been claimed? 

If someone has already claimed the domain, an error message will pop up letting you know that the domain has already been claimed. 

Do I have to verify my domain right away?

You also have the option to save and verify later. If you choose to save and verify later, your domain will appear as pending verification.

What if I cannot verify my domain?

If you are able to claim your domain but are not able to verify, the following modal will appear. Check for errors and contact your IT administrator for assistance to complete the verification process.
 

Troubleshooting Single Sign-On with Formstack

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

Quiet User Creation

Automatically accept new users, like onboarding new employees, into your Formstack organization and bypass the user invitation emails with quiet user creation. Here’s how!

From the Admin Panel, Admin Users can toggle this feature on from Single Sign-On > User Creation:
 

Configure Auto-Redirect for SSO Login

Formstack offers Auto-Redirect to make the transition from identity provider login to Formstack seamless for end users. Admin Users can toggle this on from the Admin Panel > Single Sign-On > User Login:

OneLogin SAML SSO Setup Guide

Utilize this guide to set up SAML SSO as your Formstack authentication provider. Here's how!

Step 1: Log in to OneLogin and confirm you are in the admin section of OneLogin (URL should be something like account-subdomain.onelogin.com/admin). 

Step 2: Navigate to Applications > Applications (URL should be something like account-subdomain.onelogin.com/apps) and click Add App. 

Step 3: In the search box, type "Formstack" to populate options. Choose the one with the "SAML2.0" description. 

Step 5: Navigate to the SSO tab and copy the "Issuer URL."

Step 7: Give this a unique name and confirm the Auth Provider type is SAML 2.0.


Step 8: You will have the option to import your identity provider information via URL, file, or manually:

Step 9: On this page, copy the ACS URL and head back to OneLogin. In OneLogin, navigate to the "Configuration" tab and then enter the subdomain for your Formstack account and the  "ACS URL" you just copied (note that your subdomain is currently in your ACS URL, and it should look something like:  https://subdomain.formstack.com/admin/session/auth_provider_hook/123/process

Step 10: In OneLogin, you can now add users to your app or select a custom field to pass from OneLogin to Formstack. 

If your SSO has been set up correctly, you will see the following model and be prompted to enable your SSO login.

If you’ve completed your SSO set up, but your domain has not been verified, you will see the following modal. Your SSO set up in this case was successful, but you’ll need to verify your domain before SSO can be enabled.
 

 

If there has been an error in your SSO setup, the following modal will appear. Check out the Troubleshooting SSO FAQ article to troubleshoot any issues that may arise during your setup.
 

For additional questions on OneLogin, visit the OneLogin knowledge base to get additional tips on OneLogin setup.

OpenID Connect SSO Setup Guide

The following provides documentation on how to implement OpenID Connect Authentication in conjunction with Single Sign-On (SSO) Authentication (only available on Enterprise plans). For directions on how to turn on Single Sign-On Authentication start here.

OpenID Connect (Redirect Authentication Provider)

OpenID Connect is a newer protocol that builds on the well know OAuth2 protocol. Formstack uses OAuth2 in the majority of our integrations to access restricted resources on external services as an authenticated user. OpenID Connect builds on top of this authentication mechanism to provide a standardized way to discover OAuth2 configuration settings and retrieve user information for the authenticated user.

Formstack will use the discovery URL to get an authentication endpoint and will then redirect the authenticating user to that endpoint to continue authentication. Once the user is authenticated and authorizes Formstack to access their information, the user is returned to Formstack. Formstack will then use the user information endpoint returned from the discovery URL to get the email and other user information for the authenticating user.

Once Formstack has an email address, we search for the Formstack user and authenticate as that user. If a user is not found, the user information is used to create a new user under that account. When users are created this way, they have no account permissions and will need to be granted permission to Formstack resources.

Just like any OAuth2 configuration, OpenID Connect will require a client on the target external authentication system. Once the account owner has created an OAuth2 client, they will use the client settings and a discovery URL to configure the authentication provider. Other than having to register a client with the external authentication system, OpenID Connect's use of a discovery URL makes it very easy to set up.

Client ID: This setting is the client ID for the client that the account owner created on the external authentication system.

Client Secret: This setting is the client secret for the client that the account owner created on the external authentication system.

Discovery URL: This setting is the discovery URL for the external authentication system. During authentication, Formstack will use this discovery URL to get the OpenID Connect settings required for authentication.

If your SSO has been set up correctly, you will see the following model and be prompted to enable your SSO login.

 

If you’ve completed your SSO setup, but your domain has not been verified, you will see the following modal. Your SSO setup in this case was successful, but you’ll need to verify your domain before SSO can be enabled.  

Check out the Troubleshooting SSO FAQ article to troubleshoot any issues that may arise during your setup.

SSO Autofill vs Field Prefill

If your organization is leveraging single sign-on technology to streamline how you log in across platforms, manage data, and increase security, you might be interested in learning that Formstack also works with your single sign-on provider. There are two ways you can leverage single sign-on with Formstack: to streamline account logins and to prepopulate forms with the data housed in your directories and data banks. 

We offer two ways to prefill your forms: SSO Autofill and Field Prefill. In this support article, we’ll help you identify which form prefill method works best for your organization. 

SSO Autofill vs. Field Prefill 

While SSO Autofill and Field Prefill function similarly, Field Prefill offers more functionality. Below, you’ll find a chart that outlines what features and functionality you can expect from Field Prefill and SSO Autofill. 

Learn More: Check out this support article to learn how you can get started with Field Prefill today. 

With SSO Autofill, users must map the fields from their SSO provider to fields on their form each time a new form is created. With Field Prefill, Prefill Mappings can be sent to to any form in your account. This is especially useful for organizations with sub accounts. Field Prefill makes it easy to add users to prefill mappings, suggest or require form encryption, and grant or deny form access. 

The bottom line is that Field Prefill offers your organization more scalability and makes form building easier. If you’re looking for a simpler tool and don’t need additional functionality, SSO Autofill may meet your use case. But if you’re working to increase form security, simplify login, and prefill forms with data on standard or custom fields in your SSO, Field Prefill is the solution for you! 

Customers on Pro and Enterprise accounts can start a 30-day free trial of Field Prefill by visiting the Form Authentication page under their profile or by talking to their account manager. Contact sales to learn more! 

Getting Started with ADFS through SAML 2.0

To prepare for a successful Active Directory Federation Services (ADFS) using SAML 2.0 configuration on your Formstack Account, we have prepared a brief introduction and overview of our configuration. Active Directory Federation Services using SAML 2.0 may be used in conjunction with Single Sign-On (SSO) Authentication (only available on Enterprise plans)

Once you have gathered these details, you may proceed with your ADFS setup in your Formstack account following this guide. 

Be sure to thoroughly test your settings before confirming them. It’s also a good idea to provide an alternative login option until you have confirmed that these settings work as intended or as a back-up method.

Step 1: In Formstack

• Create a SAML 2.0 Auth Provider in Formstack
• Logged in as the Admin User on your Account, navigate to your Account Profile page > Authentication.
  

Please note: the Import from URL or Import from File options are for filling in your information for Entity ID, SSO URL and x509 Certification. It is not required to do this. 

Specify the Identity Provider Metadata for your ADFS server:

Entity ID

• Example: http://ad.example.com/adfs/services/trust
• SSO URL
• Example: https://ad.example.com/adfs/ls
• x509 Certificate
• Use the token-signing certificate from your ADFS server. The certificate needs to be in DER binary format or PEM format.

Click Save Changes to Save the Auth Provider

Step 2: On the ADFS Server

Add a Relying Party Trust for Formstack

• Specify the URL for the Formstack Metadata XML for the Federation metadata address
• Example: https://subdomain.formstack.com/admin/session/auth_provider_hook/12345/metadata
• Add a Claim Issuance Policy to send LDAP Attributes as Claims
• The LDAP Attribute should be E-Mail-Addresses
• The Outgoing Claim Type should be E-Mail Address
• Add a Claim Issuance Policy to Transform an Incoming Claim
• The Incoming Claim type should be E-Mail Address
• The Outgoing Claim type should be Name ID
• The Outgoing name ID format should be Email

Formstack Single Sign-On Overview

Setting up Single Sign-On in the Formstack Administration Panel

The following is a guide for Organization Admin Users looking to configure single sign-on for their Formstack account to manage users.

Please note: Admin and Standard users can be setup with SSO configuration abilities (Check out this article for more information on editing users)

Full Walkthrough Video 

Here is a video that walks through the whole process. Below the video is a step by step walk through for a more granular approach.

Step by Step Setup Instructions 

• Once you’re logged in as the Admin User on your Account, navigate to the “Single Sign-On’ tab within the Admin panel of your account. Here you will see the main options for setup including; Claiming a Domain, Adding an Authentication Provider, and using Built in Providers (Google/Apple).

Claim a Domain 

• You will first want to claim a domain. We have a detailed breakdown of how to do this in this article

Add an Authentication Provider 

Note - The next few steps will be unique depending on your identity provider. Check out the following reference articles to continue with the setup. 

• Start by clicking, "Add Provider". You will be presented with the next screen that will have you select if you are using SAML, or OpenID Connect. 

• You will then be presented with the authentication provider configuration.
• Enter the name the provider. This is what will be displayed on the main SSO administration page once created.
• You will notice that your claimed domains are visible in this setup screen.
• You then want to import your Identity Provider metadata. (This can be done via URL, metadata file, or manual entry)
• You can also see our Service Provider metadata on right side of this page.
• Make sure to click "Save Provider" once you have successfully added a display name and imported your metadata.

• Your authentication provider will now be visible on the main SSO configuration page.
• Make sure to toggle on the "Show on Login" button that appears on the right side of your newly added provider. A "Ready to Activate" notice will show until you toggle the button to on. 

• This toggle activates the setup and allows it to be displayed when your users access the main login page for Formstack. Once they enter their email, they will be presented with an option to "Login With (Your Provider Name You Created)". 

 Built in Providers (Google and Apple)

• This option is displayed on the main SSO admin page and will allow your users to login to your Formstack org using their Google, or Apple logins. Please refer to this article for a deeper dive into how the authentication process looks like when using this option. 
• If you would like to remove these options on the main Formstack login screen, you can easily toggle off the "Show on Login" button under the built in provider section on the main SSO admin page.

Optional / Additional Settings 

Require Login via SSO

• This optional setting requires any users in your organization with an email matching your claimed domain(s) to log in to Formstack using your SSO authentication provider and won’t see a password field when logging in. Admins will still be able to access the Formstack platform using their Formstack credentials as well as via their SSO credentials.

Auto-redirect to Identity Provider

• This option will auto-redirect non-admin users to your identity provider on login after they input their email address. This streamlines the login experience and reduces the amount of clicks on the login page a user will make.

Note: Enabling the "Require Login via SSO" setting will no longer cause users on other organizations with email addresses matching your claimed domains to be blocked from logging in. 

Enable User Creation via SSO

• When the ‘Enable user creation via SSO’ feature is enabled, any member of your org who tries to log in to your org using your authentication provider will become a user on your account based on the roles specified in the settings.
  • Note - You can not create users if you are using the built in provider option (Apple and Google) User creation is only available via a provider your org owns. 

Enable Quiet User Creation

• This option will allow you to auto-accept a new Formstack user within your account and skip user invite or password reset emails.

SAML SSO Overview

To prepare for a successful SAML (Security Assertion Markup Language) configuration on your Formstack Account, please review the overview of our SAML configuration including basic terminology and uses to prepare the following authentication assets from your SAML Service Provider. The integration configuration guide can be accessed here. SAML may be used in conjunction with Single Sign-On (SSO) Authentication (only available on Enterprise plans).
 

Once you have gathered these details, proceed with your SAML setup in your Formstack account following this guide.
 

Note: Be sure to thoroughly test your settings before confirming them. It’s also a good idea to provide an alternative login option until you have confirmed that these settings work as intended or as a backup method.
 

Depending on your identity provider, check out these specific articles to support your setup:

SAML 2.0 (Redirect Authentication Provider)

Formstack supports the SAML 2.0 version. The SAML 2.0 protocol is a well-established authentication protocol and is widely supported by third-party authentication systems. The SAML 2.0 authentication provider will provide a button on the Formstack login page that will prompt the Formstack user to "Login with AuthProviderName". Once the user clicks that button, they're redirected to the SAML 2.0 provider where they authenticate.

Once the user has authenticated, they are redirected back to Formstack along with an email address and other user information. Once Formstack has an email address, we search for the Formstack user and authenticate as that user. If a user is not found, the user information is used to create a new user under that account. When users are created this way, they have no account permissions and will need to be granted permission to Formstack resources.

SAML 2.0 can be a complicated authentication provider to configure because it requires configuration on the external authentication system. Formstack servers as what's called a Service Provider (SP). Formstack will connect as an SP to an external authentication system serving as an Identity Provider (IdP).

If your SSO has been set up correctly, you will see the following model and be prompted to enable your SSO login:



If you’ve completed your SSO set up, but your domain has not been verified, you will see the following modal. Your SSO set up in this case was successful, but you’ll need to verify your domain before SSO can be enabled.

If there has been an error in your SSO setup, the following modal will appear. 

SSO terminology 

1. Identity Provider (IdP) settings: When a SAML 2.0 authentication provider is added to Formstack, the account owner is prompted to enter information about their IdP. These IdP settings can be imported from a provided XML endpoint or entered manually.

2. Entity ID: This setting is the ID of the IdP server and is used to target a specific IdP configuration on the external authentication system. 

3. SSO URL: This setting is the SSO URL is the Single Sign-on endpoint for the IdP.  

4. x509 Certificate: This setting is the x509 certificate used to sign and verify the requests from the IdP. Use .pem format rather than .cer format.

5. Service Provider (SP) settings: Once the SAML 2.0 authentication provider has been saved, we provide the SP settings that are required to add Formstack as a valid service provider to the external authentication system.  

6. Metadata XML: Import the Metadata XML file via the direct URL or by uploading it. This will send the data into the IdP to simplify configuration.

7. Entity ID: This setting is the ID of the Formstack SP server. 

8. ACS URL: This setting is the Assertion Consumer Service URL and is used to tell the external authentication system the URL to redirect authentication results to once the user has authenticated. 

9. ACS Binding: This setting is the Assertion Consumer Service Binding value and is used to tell the external authentication system the mechanism to use when returning the authentication result to Formstack. 

10. Name ID Format: This setting is the format of the authentication result that the external authentication system should use when returning the authentication result to Formstack. Name ID Format should be email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) and nameId value should be the email.

Microsoft Entra ID SSO Setup Guide (Formerly Azure AD)

Add new application for Single Sign-On (SSO) in Microsoft Entra ID (Formerly Azure AD)

Add SSO users to app and set up SSO

Once the application you added loads, you are ready to go through the following Getting Started steps:

• You will need to add all users you want to be able to login to Formstack via SSO.

• Choose SAML
• Copy App Federation Metadata Url
  • This will look something like this: https://login.microsoftonline.com/1242n12314123/federationmetadata/2007-06/federationmetadata.xml?appid=45dcfasrt-45sxcfgr45qefcve34-1234dadfa3-asdfadfvef

Create New Auth Provider in Formstack

Navigate to the Authentication section of your Formstack and Add New Auth Provider. 

Complete SSO configuration in Microsoft Entra ID

Copy and paste the following newly created URLs back into Entra ID “Basic SAML Configuration” box

• Entity ID -> Identifier
• ACS URL -> Reply URL
• Use this as the Sign-on URL: https://www.formstack.com/admin/dashboard. Click save.
• Navigate to User Attributes & Claims. Update the Unique User Identifier to be the user’s email address. 
• This is where you can add custom attributes you want to use within Formstack for things such as form prefilling.