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. Check out the Troubleshooting SSO FAQ article to troubleshoot any issues that may arise during your setup.
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.