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.