OAuth
This section describes how to setup and configure Form.io with a OIDC Authentication Provider for Single-Sign-On authentication.
Last updated
This section describes how to setup and configure Form.io with a OIDC Authentication Provider for Single-Sign-On authentication.
Last updated
The most common OAuth method is leveraging the OpenID Connect framework to achieve user authentication into your application. OIDC proves to be a flexible and secure means of authenticating your user base, with a multitude of different providers available. Form.io seamlessly manages this integration, offering multiple strategies and methods to authenticate users through OIDC providers.
Choosing an OIDC provider is the first step in the integration process. An OIDC application will then be created and configured. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project. Form.io offers integration with many providers, including the following:
Microsoft Entra ID (Formerly Azure AD)
The configuration process will vary for each OAuth/OIDC provider, however each provider generally requires the same setup. Each Provider will require the application domain to be saved to the . This should be the domain the OIDC User is redirected to when they are authenticated from the OIDC Provider.
Once the application is configured, establish a user base within the authentication provider. OIDC Users can then be assigned to OIDC Groups, which allows role mapping between the OIDC Group and Form.io Role.
Each will produce comparable endpoints and credentials for integrating the provider into your Form.io project. Once the OIDC application has been configured, save the following information from your OIDC provider, which will be incorporated into the Authorization settings within your Project.
Access the application's well-known endpoint to retrieve the required endpoints for integration with the Form.io Project.
Navigate to the Form.io Project's Settings > Authentication > OAuth and apply your OIDC settings to the appropriate Form.io setting fields within the OpenID tab.
The Form.io User Login form will then be modified along with an OAuth action, to support the OneLogin OIDC Authentication workflow.
The OIDC Group associated with the OIDC user can be mapped to a Form.io role when the user authenticates. This is done by integrating the OIDC Provider group claim into the Form.io project and then mapping the OIDC Group name to a Form.io Role within the Oauth action saved to the Login Form.
While the OAuth provider configuration and settings fall outside of Form.io, here are some common troubleshooting tips if your OIDC authentication isn't functioning correctly.
The easiest way to identify the correct URI endpoints is to navigate to your OIDC URL and then append the 'well-known' endpoint.
/.well-known/openid-configuration
Example:
The response will provide all necessary URI endpoints specific to your OIDC provider as well as any scopes or claims you may want to include within your Form.io Authorization settings or OAuth Action.
Allow Origins - The application domain that will authenticate the OIDC User. Ensure the correct client (application) domains are set within your OIDC provider utilized for authentication of the OIDC provider that will be allowed
Callback URL - The URL to which Auth0 redirects users after they authenticate from the Allow Origin domain. Typically would be the same URL(s) as the Allow Orgin endpoints. In some cases, the authentication domain may be different than the domain the user is redirected to after authentication. Different Providers may refer to the Callback URL differently: Redirection URI, Redirection URL, Redirect URI, Redirect URL, or Callback URI
Connection - Connections determine how or where the OIDC user will authenticate. Many times, Username and Password credentials stored within the OIDC provider serve as the primary means of authenticating users. However, different providers offer integrations with other OAuth-enabled applications such as Google or Facebook for authentication. It's important to ensure that a connection method is enabled for your OIDC provider; some connections might be enabled by default, depending on the provider.
Scope - Check the supported Scope attributes (or claims) of your OIDC provider by searching 'scope' within the provider's 'well-known' endpoint. In every scenario, openid
and email
will always be included in the scope of any OIDC provider and must be configured within the OpenID settings of your project.
Authentication Method- In most cases, the Authentication Method should be set to POST
Application Type - Ensure the correct application type is configured for the OIDC application. In many cases, this will be a 'Web Page' or 'Single Page Application'.
This section covers the OneLogin Provider OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project.
From your OneLogin Admin dashboard, create a new application by clicking the Applications tab and then the Add App button.
Select the OpenId Connect (OIDC) application
Give the Application a name and click the Save button with the default configurations
Click the Configuration tab to set up the application details
Add the Redirect URIs - Live endpoint of the hosted application where the response to the SAML request should be sent, after the user signs in
https://app.yoursite.com
Add the Post Logout Redirect URIs - Live endpoint that redirects a user to a specified URL after the logout process is complete
https://app.yoursite.com
The configuration should look similar to the following:
Click the SSO tab and set the Authentication Method to POST
Adding a Group Parameter will enable the ability to include the user role (group) in the OIDC claim.
Click the Parameter tab
Click the existing Group parameter
Set the value to User Roles and the Transform to Semicolon Delimited input
Set the field name to Groups
With the application configured, create a user base within the OneLogin Admin dashboard. Users can then be assigned to a Role linked with the OIDC Application, allowing OIDC and Form.io role mapping.
Within the OneLogin Admin dashboard, hover over the User tab and click Users
Click the New User button
Input the Information for the User and then click Save User
If you would like to set a password, click the More Action tab and Change Password
Generate multiple users to assign them to different roles further in the walkthrough
With our Users in place, the next step is to create Roles the OIDC Users will be assigned to. This will allow us to establish mappings between OIDC roles and Form.io roles.
Within the OneLogin Admin dashboard, hover over the User tab and click Roles
Click the New Role button
Give the Role a name and select the OIDC Application the Role should be associated with
Click the Save role
Within the Roles tab, click the Role that was just created and click the Users Tab
Using the search bar, search and select all Users that should be added to the Role and click Check
Click the Add To Role button for each user
Click Save
With the Roles established, the next step is to assign the Role to the OIDC application
Hover over the Application tab and select Applications
Navigate to your OIDC Application
Click the Access tab
Select all of the Roles you wish to assign to the Application. Users assigned to the selected roles will be added to the Application.
Click Save
After the OIDC application is properly configured, information from the provider will be utilized to integrate with the Form.io project and establish remote authentication. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings.
Within your OIDC Application, click the SSO tab
Copy the Client ID
Click the Show client secret button and copy the secret
Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth
Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings
Click the SSO tab within the OIDC application
Click the Well-known Configuration button to access the OIDC application metadata
The well-known configuration will look something like this:
Search the well-known configuration JSON file and find the following endpoints, then map them to the corresponding fields in your Form.io settings.
Input the following values within the Scope setting openid | email
The openid
and email
scopes are required for all OIDC providers and must be configured in your project's OpenID settings to ensure successfully user authentication
Your settings should look something like this
Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.
Navigate to the Form.io project and edit the application Login form.
Add a Button component
Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID
Save the form
Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.
Navigate to the Login form within the Form.io Project
Click the Action tab and add the OAuth action
Click the OAuth Provider setting and select OpenID
Click the Action setting and select Remote Authentication
Click the Sign-in with OAuth Button setting and select the SSO button
If you are mapping roles, add the following setting to the Assign Roles setting fields
The Claim setting will be the claim name that supports roles within the OIDC scope.
The Value setting will be the identifier for the OIDC Group.
The Role setting is the Form.io role that should be assigned to users with the given OIDC Role.
In the example below OIDC users with the Member role will authenticate into the application with the Form.io Authenticated role. OIDC users with the Admin role will authenticate into the application with the Form.io Administrator role.
In many cases, you may want to map the OIDC Role associated with the OIDC User to a Form.io Role. This can be done by adding the OIDC group claim within the scope setting of the Form.io Project as well as the Oauth action.
Navigate to the Form.io Authorization setting Settings > Authentication > OAuth
Add the following values to the Scope setting field groups
Within the OneLogin OIDC Application, click the Access tab and take note of the Role Names assigned to the application.
Navigate to the Role settings and map the OIDC group (case sensitive) to the desired Form.io Role The example below maps OIDC users with the Member role to the Form.io Authenticated role and OIDC users with the Admin role to the Form.io Administrator role
Save the settings
Test the authentication workflow to ensure it functions correctly.
Navigate to your Applications authentication page and click the SSO with OIDC button.
Enter the OIDC credentials into the OneLogin authentication page
Once authenticated, the OIDC user should carry the OIDC Group Role (Member) as well as the mapped Form.io Role ID within the metadata of the user object.
This section covers the Okta OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project
From your Okta Developer dashboard, create a new application by clicking the Applications tab and then the Applications button.
Click the Create App Integration button
Select OIDC - OpenID Connect from the Sign-in method section
Select Web Application from the Application type section
Apply the following configurations to the General Settings of the Okta OIDC Application
Add the Sign-in Redirect URI - Domain of the hosted application where Okta sends the authentication response and ID token for the sign-in
https://app.yoursite.com/yourloginpage
Add the Sign-out redirect URIs - Live endpoint that redirects a user to a specified URL after the logout process is complete
https://app.yoursite.com
The configuration should look similar to the following:
Select a Controlled Access setting
Save the Settings to create the application
Once the application is configured, establish a user base in the Okta dashboard. Users can be assigned to Okta Groups, which can then be mapped to roles in Form.io.
Within your Okta Admin dashboard, click the Directory tab and select People
Click the Add person button
Enter person details for the SAML User
Click the Password dropdown to determine how Users password will be set
Click Save to add the User
With Users in place, create Groups the OIDC Users will be assigned to. This will allow us to establish mappings between OIDC roles and Form.io roles.
Within your Okta Admin dashboard, click the Directory tab and select Groups
Click the Add Group button
Give your Group a Name and click Save
With a Group created, the next step is to assign users to the Group.
From the Group tab, select the Group to add Users to
Click the Assign people button
Assign a User to a Group by clicking the + button next to their username.
After establishing the Groups, the next step is to assign them to the OIDC application
To assign the Group, open the Directory tab, select the Group, and click the Applications tab
Click the Assign applications button
Within the modal window, click the Assign button next to the OIDC application
After the OIDC application is properly configured, information from the provider will be utilized to integrate with the Form.io project and establish remote authentication. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings.
Within your Okta Application, click the General tab
Copy the Client ID and Client Secret
Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth
Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings
Append the well-known endpoint to the Okta application URL
https://dev-myapplication-admin.okta.com/
.well-known/openid-configuration
Open the URL within the browser.
The well-known configuration will look something like this:
Search the well-known configuration JSON file and find the following endpoints, then map them to the corresponding fields in your Form.io settings.
Input the following values within the Scope setting openid | email
The openid
and email
scopes are required for all OIDC providers and must be configured in your project's OpenID settings to ensure user authentication
Your settings should look something like this
Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.
Navigate to the Form.io project and edit the application Login form.
Add a Button component
Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID
Save the form
Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.
Navigate to the Login form within the Form.io Project
Click the Action tab and add the OAuth action
Click the OAuth Provider setting and select OpenID
Click the Action setting and select Remote Authentication
Click the Sign-in with OAuth Button setting and select the SSO button
If you are mapping roles, add the following setting to the Assign Roles setting fields
The Claim setting will be the claim name that supports roles within the OIDC scope.
The Value setting will be the identifier for the OIDC Group.
The Role setting is the Form.io role that should be assigned to users with the given OIDC Role.
In the example below OIDC users with the Member role will authenticate into the application with the Form.io Authenticated role. OIDC users with the Admin role will authenticate into the application with the Form.io Administrator role.
In many cases, you may want to map the OIDC Role associated with the OIDC User to a Form.io Role. This can be done by adding the OIDC group claim within the scope setting of the Form.io Project as well as the Oauth action.
Navigate to the Form.io Authorization setting Settings > Authentication > OAuth
Add the following values to the Scope setting field groups
Within the OneLogin OIDC Application, click the Access tab and take note of the Role Names assigned to the application.
Navigate to the Role settings and map the OIDC group (case sensitive) to the desired Form.io Role The example below maps OIDC users with the Member role to the Form.io Authenticated role and OIDC users with the Admin role to the Form.io Administrator role
Save the settings
Test the authentication workflow to ensure it functions correctly.
Navigate to your Applications authentication page and click the SSO with OIDC button.
Enter the OIDC credentials into the Okta authentication page
Once authenticated, the OIDC user should carry the OIDC Group Role (Member) as well as the mapped Form.io Role ID within the metadata of the user object.
This section covers the Microsoft Entra ID OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project
After setting up your Entra ID account, navigate to the Azure Portal, click the left navigation panel, and select Microsoft Entra ID.
Click the left-hand navigation bar and select App registrations
Click the +New registration button
Give the application a name
Under the Redirect URI section, select Web from the dropdown, and input the application URI
Click the Register button
The configuration should look similar to the following:
Once the application has been created, a Client secret will need to be generated that will be added to the Authentication OAuth integration settings within the Form.io Project.
Click the Certificates and secrets tab
Click the + New client secret button
Give the secret a Description
Click the Add button
Copy the Client Secret Value
This is the only opportunity to save the Client Secret Value
Once the application is configured, establish a user base within the Entra ID dashboard. Users can be assigned to Entra ID Groups, which can then be mapped to roles in Form.io.
Within the Entra ID application, click Home > Microsoft Entra ID > Users
Within the All Users tab click the +New user button then
Input the User information and click Review + create button
Ensure the User email address and name is set within the Properties tab of the user profile
Contact your Azure administrator to add the required properties to the user profile
Create several other users to test Group and Role mapping detailed in the next section.
With our Users in place, the next step is to create Groups the Entra ID Users will be assigned to. This will allow us to establish mappings between EntraID groups and Form.io roles.
Within the Azure dashboard, click the left-hand navigation bar, Groups, and All Groups tab
Click the New group button
Give the Group a Group Name and keep the remaining settings at their default values
Click the No Members Selected button to assign users
Search for the User created in the previous section
Select the User
Click the Select button
Click the Create button
Follow the same steps to create additional Groups
With the Groups established, the next step is to assign the Groups to the Entra ID application
Navigate back to your Entra ID OIDC application
Select the Users and groups tab then click the + Add user/group button
On the next screen, click the None Selected
Select the Groups created in the previous steps
Click the Select button at the bottom of the screen and then Assign on the following page
After assigning the Groups, you should see the Groups displayed within the User and Groups tab of the Entra ID application. Users assigned to the selected groups will be associated with the Entra ID Application.
Once the OIDC application is properly configured, information from the application will be used to integrate the application with the Form.io project. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings.
Navigate to the Entra ID dashboard, click App registrations, and select your application
Within your Entra ID Application, click the Overview tab
Copy the Application (client) ID value and Secret from the Client Secret Step
Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth
Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings
Within Entra ID, click the App registrations tab and select the OIDC Application
Within your Entra ID Application, click the Overview tab and then Endpoints
Copy the OpenID Connect metadata document ULR and open it in a browser
The Endpoints will look something like this:
Add the following endpoints from the Well-known configuration to the correlated field settings Authorize URI | Token URI | Logout URI | User Info (claims) URI
Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.
Navigate to the Form.io project and edit the application Login form.
Add a Button component
Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID
Save the form
This section covers the Auth0 Provider OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project
From your Auth0 Admin dashboard, create a new Auth0 application by clicking the Applications tab and then the +Create Application button
Select the OpenId Connect (OIDC) application
Provide a name for the Application and click the Create button
Click the Setting tab and the application endpoint to the Allowed Callback URLs
https://myapplication.com/dashboard
Once the application is configured, establish a user base in the Okta dashboard. Users can be assigned to Okta Groups, which can then be mapped to roles in Form.io.Auth0
Within the Auth0 admin dashboard, click the User Management tab and then Users
Click the +Create User button
Input user information and click Create
Create additional users to assign to the different Roles that will be established in the next step.
With our Users in place, the next step is to create Groups the OIDC Users will be assigned to. Auth0 groups are created and managed through extensions. This group extension will allow us to establish mappings between OIDC groups and Form.io for role mapping.
Within the left-hand navigation bar, click Extensions
Select Auth0 Authorization
Click Install within the Extension modal
Once installed, click the Extension and Authorize the extension for your application
Click the GO TO CONFIGURATION button
Click the Groups radio button
Click the Publish Rule button
Within the Extension, click the Groups tab then + Create Your First Group button
Give the Group a Name and Description
Click the +Add Member button
Search and select the user(s) to assign to the Group and Save
Once the OIDC application is properly configured, information from the application will be used to integrate the application with the Form.io project. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings.
Within your Auth0 Application, click the Settings tab
Copy the Client ID and Client Secret
Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth
Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings
Within your Auth0 Application, click the Settings tab
Scroll down the Settings page and expand the Advanced Settings
Click the Endpoints tab
The endpoint information will look something like this:
Add the following endpoints from the Well-known configuration then map them to the corresponding fields in your Form.io settings.
Input the following values within the Scope setting openid | email
The openid
and email
scopes are required for all OIDC providers and must be configured in your project's OpenID settings to ensure successfully user authentication
Your settings should look something like this
Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.
Navigate to the Form.io project and edit the application Login form.
Add a Button component
Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID
Save the form
Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.
Navigate to the Login form within the Form.io Project
Click the Action tab and add the OAuth action
Click the OAuth Provider setting and select OpenID
Click the Action setting and select Remote Authentication
Click the Sign-in with OAuth Button setting and select the SSO button
If you are mapping roles, add the following setting to the Assign Roles setting fields
The Claim setting will be the claim name that supports roles within the OIDC scope.
The Value setting will be the identifier for the OIDC Group.
The Role setting is the Form.io role that should be assigned to users with the given OIDC Role.
In the example below OIDC users with the Member role will authenticate into the application with the Form.io Authenticated role. OIDC users with the Admin role will authenticate into the application with the Form.io Administrator role.
In many cases, you may want to map the OIDC Role associated with the OIDC User to a Form.io Role. This can be done by adding the OIDC group claim within the scope setting of the Form.io Project as well as the Oauth action.
Navigate to the Form.io Authorization setting Settings > Authentication > OAuth
Add the following values to the Scope setting field groups
Within the OIDC Application, click the Extension tab, Installed Extensions, then the Auth0 Authorization extension. Click the Groups tab within the extension and take note of the Group Names assigned to the application.
Navigate to the Role settings and map the OIDC group (case sensitive) to the desired Form.io Role The example below maps OIDC users with the Member role to the Form.io Authenticated role and OIDC users with the Admin role to the Form.io Administrator role
Save the settings
Test the authentication workflow to ensure it functions correctly.
Navigate to your Applications authentication page and click the SSO with OIDC button.
Enter the OIDC credentials into the OneLogin authentication page
Once authenticated, the OIDC user should carry the OIDC Group Role (Member) as well as the mapped Form.io Role ID within the metadata of the user object.
One type of application design is where form.io forms are embedded in an existing application that already has OAuth authentication built into it. In this type of application, the OAuth token can be exchanged for a form.io token to enable all future interactions with form.io to be authenticated using the new form.io token.
To do this, you should have an existing Bearer (or other) authorization token from the OAuth provider. You also need to set up the OpenID and OpenID Connect settings in your project.
Then, instantiate the Formio library with your project URL and call the currentUser endpoint with your authorization header.
To perform a Token Swap, it is required to expose the /UserInfo endpoint
Form.io will use the authorization token to request the OAuth endpoint, receive the user information, and create a new form.io token that is passed back to the form.io library and used on subsequent requests.
To enable SSO in the Developer Portal, simply apply all the configurations detailed above, but apply the configurations to the Portal Base project. Utilizing the Remote Authentication method will set up authentication for the Developer Portal application, eliminating the necessity for resource-based authentication. Follow the link below for a detailed walkthrough:
The same concepts above can be applied to the Form Manager application. Since the Form Manager utilizes the Admin Login form for authentication, the only difference between this workflow and the previous SSO example is the form being modified is the Admin Login form instead of User Login.
1. Create an application within your OIDC provider (in this example auth0) and choose Single Page application type.
Gather the Client ID and secret as well as the necessary endpoints found within the well-known endpoint for your application.
Navigate to the Form.io Project the Form Manager application is connected to. Navigate to the Authorization > OAuth > OpenID settings.
Apply the information from the OIDC application and well-known endpoint.
Within your Project, navigate to the Admin Login form.
Add a Button Component
Select the OAuth action
Select the OpenID provider
Save settings.
Navigate to the Action tab and add the Oauth Action.
Configure the OAuth action
Select your OAuth provider
Select the Remote Authentication Action
Select the SSO button within the Admin login form
Since the Form Manager requires Administrative users, select the Administrator Role
Launch the Form Manager application
Click the Login with OIDC button
Enter your OIDC User credentials
You should authenticate into the Form Manager application
Form.io Setting | Well-known Configuration |
---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|
Form.io Setting | Well-known Configuration |
---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|
Form.io Setting | Well-known Configuration |
---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|
Claim (OIDC) | Value (OIDC) | Role (Form.io) |
---|---|---|