To prepare for a successful SAML (Security Assertion Markup Language) configuration on your Formstack Account, we have prepared a brief introduction and overview of our SAML configuration including basic terminology and uses. SAML 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 SAML setup in your Formstack account following this guide. Before enabling SAML on your Formstack Account, please familiarize and prepare the following authentication assets from your SAML Service Provider. The integration configuration guide can be accessed here.
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.
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).
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.
( .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.
On successful authentication, you must return an XML response to our server. In order for us to find the correct email address, you must send along an Attribute with the property of "mail". An example response is below:
Custom SSO User Fields
Within your CAS configuration, you will also be presented with a Single Sign-On (SSO) Autofill plugin that allows your users to populate fields on your forms with information from a selected SSO Provider and populate in your CAS Authentication settings page in Formstack:
Custom Field Key: Locate the custom field is your CAS account and retrieve the field unique identifier or field key ID. Copy this from CAS and paste to your Formstack account.
Custom Field Label: Copy the field label from the CAS account and paste to your Formstack account.
To complete the SSO Auto-fill mappings, please follow the setup steps outlined here.