SAML Authentication Setup 

Overview

SAML (Security Assertion Markup Language) can be used to secure access to your FormAssembly account and forms. There are two methods for using SAML with FormAssembly:

Single Sign-On: this will allow users to sign into their FormAssembly account using their SAML credentials.  

Form by Form Authentication: by enabling this feature, you will be able to restrict access to your forms by only allowing users who can be authenticated by your SAML server to access a form. 

Requirements

• FormAssembly Team plan or above
• SAML Metadata from your IdP
• Your FormAssembly username must match your SAML username

Single Sign-On (SSO) Setup

1. Navigate to the Admin Dashboard.
2. Click Settings and then Application from the left side menu.
3. Scroll to the SAML section at the bottom.
4. Click Configure SAML.
   • If you're not currently logged in, you'll receive a popup that says You're not currently authenticated with your SAML Server.  Click OK on the popup and log into your SAML Domain.
5. Under Update Method, choose your metadata option.
   • Metadata URL Endpoint
     • This is provided by the Identity Provider.  
     • Enter your URL Endpoint.
     • Select Update Domain.
   • Metadata File
     • This is provided by the Identity Provider.  
     • Upload your Metadata File.
     • Select Update Domain.
   • Manual (Advanced)
     • Add SAML data manually.  
     • After entering your data manually, click Apply.
     • Select Update Domain.
6. After changes have been saved, your domain is set up and more options are shown for updating.
7. Click Retrieve Attributes.
   • If you're not currently logged in, you'll receive a popup that says You're not currently authenticated with your SAML Server.  Click OK on the popup and log into your SAML Domain.
8. Your IDP attributes will be shown in the User Authentication Table.  
9. These attributes will be disabled by default so you can enable the attributes that you'd like to use.
10. Select Unique SAML attribute in your dropdown.
    • If you do not select a unique SAML attribute dropdown, you'll receive a red error that your changes were not saved.
    • Your unique SAML attribute must be enabled to be used.
11. Select Authentication formula if needed.
12. Click Apply to save your changes.
13. Access your All Users list.  Edit Users that need to use SSO and select SSO under the Authentication Type dropdown.
14. Users will use the unique attribute to log in.

Form by Form Authentication Initial Setup

• From the Forms list, hover over Configure and select Processing.
• Choose Allow Responses from SAML Authenticated Users.

• Click Apply.

• Click Configure under Allow Responses from SAML Authenticated Users dropdown box.

• Under Update Method, choose your metadata option.
  • Metadata URL Endpoint.
    • This is provided by the Identity Provider.  
    • Enter your URL Endpoint.
    • Select Update Domain.
  • Metadata File.
    • This is provided by the Identity Provider.  
    • Upload your Metadata File.
    • Select Update Domain.
  • Copy from Form.
    • This is used to copy the SAML settings and setup from another form already using SAML Authentication in your instance.
    • Enter the ID of a form that already has SAML Authentication setup.
    • Select Update Domain.
  • Manual (Advanced).
    • Add SAML data manually.  
    • After entering your data manually, click Apply.
    • Select Update Domain.
• After changes have been saved, your domain is set up and more options are shown for updating.
• Click Retrieve Attributes.
  • If you're not currently logged in, you'll receive a popup that says You're not currently authenticated with your SAML Server.  Click OK on the popup and log into your SAML Domain.
• Choose Attributes
• Your IDP attributes will be shown in the User Authentication Table.  
• These attributes will be disabled by default so you can enable the attributes that you'd like to use.
• Select Unique SAML attribute in your dropdown.
  • If you do not select a unique SAML attribute dropdown, you'll receive a red error that your changes were not saved.
  • Your unique SAML attribute must be enabled to be used.
• Select Authentication formula if needed.
• Click Apply to save your changes.
• You can test your settings by viewing the form which will now require a login.

Advanced Configuration of Metadata Fields

The following metadata fields may require additional consideration or special formatting:

NameIdFormat 

The default value for this field is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. If this field is left blank, the default value will be used.

The following formats are supported:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
• urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
• urn:oasis:names:tc:SAML:2.0:nameid-format:entity
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient
• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted

RequestedAuthNContext 

The default value for this field is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport. If this field is left blank, the default value will be used.

The following formats are supported (Multiple values may be entered separated by a comma ","):

• urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
• urn:oasis:names:tc:SAML:2.0:ac:classes:Password
• urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
• urn:oasis:names:tc:SAML:2.0:ac:classes:X509
• urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard
• urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
• urn:federation:authentication:windows
• urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient

SAML Prefill Connector Setup

• Ensure SAML Authentication is setup on the Processing page of your form.  Follow the steps above to enable.
• To enable the SAML prefill connector, click Connectors on the form you'd like to set up
• Next, drag in the SAML Prefill Connector into the view section of the timeline and click Configure.

• Then map the fields in your form to the SAML session attributes that you would like to fill those fields.
• When you're finished, click Apply

• You're now ready to begin testing your SAML authentication and connector!

Updating Your SAML SSL Certificate

If you need to update your SAML SSL certificate you will use the self-serve configuration steps above to do so.  

• If you already have a SAML configuration set up in your FormAssembly account you would update that configuration with your new metadata file with the new certificate, which you will import as part of the configuration.
• If you do not have a SAML configuration set up in your FormAssembly account, and your SAML configuration was originally set up by FormAssembly you will need to follow the process in this document to set up a SAML configuration in your FormAssembly account to update your SAML SSL certificate.