The following provides documentation on how to implement SAML 2.0 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.
SAML 2.0 (Redirect Authentication Provider)
SAML stands for Security Assertion Markup Language and we support 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).
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.
This setting is the ID of the IdP server and is used to target a specific IdP configuration on the external authentication system.
This setting is the SSO URL is the Single Sign-on endpoint for the IdP.
This setting is the x509 certificate used to sign and verify the requests from the IdP.
( .pem format rather than .cer format )
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.
Import the Metadata XML file via the direct URL or by uploading it. This will send the data into the IdP to simplify configuration.
This setting is the ID of the Formstack SP server.
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.
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.
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.