OAuth

This section describes how to setup and configure Form.io with a OIDC Authentication Provider for Single-Sign-On authentication.

OAuth Application Setup Overview

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.

Setting up an OIDC provider

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:

• OneLogin

• Okta

• Microsoft Entra ID (Formerly Azure AD)

• Auth0

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.

Creating / Assigning Users and Groups

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.

Form.io Integration

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.

	The endpoint where the OIDC user is asked to authenticate, granting access to the client application Example URL: https://yourcompany.oidcprovider.com/auth
	The endpoint utilized to retrieve the OAuth token from the provider after authorization has been granted. Example URL: https://yourcompany.oidcprovider.com/token
	Examlpe URL The endpoint holding the scope of the authorizing user (or user attributes) such as email and ID stored within the OIDC provider Examlpe URL: https://yourcompany.oidcprovider.com/me
Client ID	Character string representing the client ID generated by the OAuth provider Example ID: abc123def456
Client Secret	Character string representing the client ID generated by the OAuth provider Example Secret: abc123def456
Scope	Communicates to the OIDC provider what information should be returned from the user to utilize for authentication. This data is compromised of various attributes and information about the User. Ensure the required scopes openID and email are set within the Form.io project authentication.

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.

Configure Login Form

The Form.io User Login form will then be modified along with an OAuth action, to support the OneLogin OIDC Authentication workflow.

Role Mapping

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.

General Troubleshooting

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.

• How Do I Find The URI Endpoints?

  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:

  https://yourcompany.oidcprovider.com/.well-known/openid-configuration

  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'.

One Login

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.

Create and Configure Application

1. From your OneLogin Admin dashboard, create a new application by clicking the Applications tab and then the Add App button.

1. Select the OpenId Connect (OIDC) application

1. Give the Application a name and click the Save button with the default configurations

1. 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:

1. 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.

1. Click the Parameter tab

2. Click the existing Group parameter

3. Set the value to User Roles and the Transform to Semicolon Delimited input

4. Set the field name to Groups

Create User

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.

1. Within the OneLogin Admin dashboard, hover over the User tab and click Users

2. Click the New User button

1. Input the Information for the User and then click Save User

2. If you would like to set a password, click the More Action tab and Change Password

3. Generate multiple users to assign them to different roles further in the walkthrough

Create and Assign Groups

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.

1. Within the OneLogin Admin dashboard, hover over the User tab and click Roles

2. Click the New Role button

1. Give the Role a name and select the OIDC Application the Role should be associated with

2. Click the Save role

1. Within the Roles tab, click the Role that was just created and click the Users Tab

2. Using the search bar, search and select all Users that should be added to the Role and click Check

1. Click the Add To Role button for each user

2. Click Save

Assign Role To OneLogin Application

With the Roles established, the next step is to assign the Role to the OIDC application

1. Hover over the Application tab and select Applications

2. Navigate to your OIDC Application

3. Click the Access tab

4. Select all of the Roles you wish to assign to the Application. Users assigned to the selected roles will be added to the Application.

5. Click Save

Form.io Integration

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.

Client ID and Secret Key

1. Within your OIDC Application, click the SSO tab

2. Copy the Client ID

3. Click the Show client secret button and copy the secret

1. Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth

1. Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings

Well-Known Configuration

1. Click the SSO tab within the OIDC application

2. Click the Well-known Configuration button to access the OIDC application metadata

The well-known configuration will look something like this:

1. Search the well-known configuration JSON file and find the following endpoints, then map them to the corresponding fields in your Form.io settings.

Form.io Setting	Well-known Configuration
Authorize URI	authorization_endpoint
Token URI	token_endpoint
Logout URI	end_session_endpoint
User Info (claims) URI	userinfo_endpoint

1. 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 Login Form

Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.

1. Navigate to the Form.io project and edit the application Login form.

2. Add a Button component

3. Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID

4. Save the form

Oauth Action

Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.

1. Navigate to the Login form within the Form.io Project

2. Click the Action tab and add the OAuth action

3. Click the OAuth Provider setting and select OpenID

4. Click the Action setting and select Remote Authentication

5. Click the Sign-in with OAuth Button setting and select the SSO button

6. 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.

Claim (OIDC)	Value (OIDC)	Role (Form.io)
groups	Member	Authenticated
groups	Admin	Administrator

Role Mapping

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.

1. Navigate to the Form.io Authorization setting Settings > Authentication > OAuth

2. Add the following values to the Scope setting field groups

1. Within the OneLogin OIDC Application, click the Access tab and take note of the Role Names assigned to the application.

1. 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

Claim (OIDC)	Value (OIDC)	Role (Form.io)
groups	Member	Authenticated
groups	Admin	Administrator

1. Save the settings

Testing Authentication

Test the authentication workflow to ensure it functions correctly.

1. Navigate to your Applications authentication page and click the SSO with OIDC button.

2. Enter the OIDC credentials into the OneLogin authentication page

1. 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.

Okta

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

Create and Configure Application

1. From your Okta Developer dashboard, create a new application by clicking the Applications tab and then the Applications button.

2. Click the Create App Integration button

1. Select OIDC - OpenID Connect from the Sign-in method section

2. Select Web Application from the Application type section

1. 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:

1. Select a Controlled Access setting

2. Save the Settings to create the application

Create User

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.

1. Within your Okta Admin dashboard, click the Directory tab and select People

2. Click the Add person button

1. Enter person details for the SAML User

2. Click the Password dropdown to determine how Users password will be set

3. Click Save to add the User

Create and Assign Groups

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.

1. Within your Okta Admin dashboard, click the Directory tab and select Groups

2. Click the Add Group button

1. Give your Group a Name and click Save

With a Group created, the next step is to assign users to the Group.

1. From the Group tab, select the Group to add Users to

2. Click the Assign people button

1. Assign a User to a Group by clicking the + button next to their username.

Assign Groups To Okta Application

After establishing the Groups, the next step is to assign them to the OIDC application

1. To assign the Group, open the Directory tab, select the Group, and click the Applications tab

2. Click the Assign applications button

1. Within the modal window, click the Assign button next to the OIDC application

Form.io Integration

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.

Client ID and Secret Key

1. Within your Okta Application, click the General tab

2. Copy the Client ID and Client Secret

1. Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth

1. Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings

Well-Known Configuration

1. Append the well-known endpoint to the Okta application URL

https://dev-myapplication-admin.okta.com/.well-known/openid-configuration

1. Open the URL within the browser.

The well-known configuration will look something like this:

1. Search the well-known configuration JSON file and find the following endpoints, then map them to the corresponding fields in your Form.io settings.

   Form.io Setting	Well-known Configuration
   Authorize URI	authorization_endpoint
   Token URI	token_endpoint
   Logout URI	end_session_endpoint
   User Info (claims) URI	userinfo_endpoint

   1. 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 Login Form

Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.

1. Navigate to the Form.io project and edit the application Login form.

2. Add a Button component

3. Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID

4. Save the form

Oauth Action

Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.

1. Navigate to the Login form within the Form.io Project

2. Click the Action tab and add the OAuth action

3. Click the OAuth Provider setting and select OpenID

4. Click the Action setting and select Remote Authentication

5. Click the Sign-in with OAuth Button setting and select the SSO button

6. 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.

Claim (OIDC)	Value (OIDC)	Role (Form.io)
groups	Member	Authenticated
groups	Admin	Administrator

Role Mapping

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.

1. Navigate to the Form.io Authorization setting Settings > Authentication > OAuth

2. Add the following values to the Scope setting field groups

1. Within the OneLogin OIDC Application, click the Access tab and take note of the Role Names assigned to the application.

1. Navigate to Sign On and click Edit on the OpenID Connect ID Token pane. Set the groups claim type to filter and the group claim filter to groups matches regex .* and hit save

   
2. 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

Claim (OIDC)	Value (OIDC)	Role (Form.io)
groups	Member	Authenticated
groups	Admin	Administrator

1. Save the settings

Testing Authentication

Test the authentication workflow to ensure it functions correctly.

1. Navigate to your Applications authentication page and click the SSO with OIDC button.

2. Enter the OIDC credentials into the Okta authentication page

1. 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.

Microsoft Entra ID

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

Create and Configure Application

1. After setting up your Entra ID account, navigate to the Azure Portal, click the left navigation panel, and select Microsoft Entra ID.

1. Click the left-hand navigation bar and select App registrations

2. Click the +New registration button

1. Give the application a name

2. Under the Redirect URI section, select Web from the dropdown, and input the application URI

3. Click the Register button

The configuration should look similar to the following:

Creating Client Secret

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.

1. Click the Certificates and secrets tab

2. Click the + New client secret button

3. Give the secret a Description

4. Click the Add button

1. Copy the Client Secret Value

This is the only opportunity to save the Client Secret Value

Adding group claim

1. Click on Token Configuration

2. Click Add groups claim

3. Select the Groups assinged to the application select box

4. Click Save

Create User

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.

1. Within the Entra ID application, click Home > Microsoft Entra ID > Users

2. Within the All Users tab click the +New user button then

1. 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

1. Create several other users to test Group and Role mapping detailed in the next section.

Create and Assign Groups

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.

1. Within the Azure dashboard, click the left-hand navigation bar, Groups, and All Groups tab

2. Click the New group button

1. Give the Group a Group Name and keep the remaining settings at their default values

1. 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

1. Click the Create button

2. Follow the same steps to create additional Groups

Assigning Groups to Application

With the Groups established, the next step is to assign the Groups to the Entra ID application

1. Navigate back to your Entra ID OIDC application

2. Select the Users and groups tab then click the + Add user/group button

3. On the next screen, click the None Selected

1. Select the Groups created in the previous steps

2. 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.

Form.io Integration

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.

Client ID and Secret Key

1. Navigate to the Entra ID dashboard, click App registrations, and select your application

1. Within your Entra ID Application, click the Overview tab

2. Copy the Application (client) ID value and Secret from the Client Secret Step

1. Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth

1. Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings

Well-Known Configuration

1. Within Entra ID, click the App registrations tab and select the OIDC Application

2. Within your Entra ID Application, click the Overview tab and then Endpoints

3. Copy the OpenID Connect metadata document ULR and open it in a browser

The Endpoints will look something like this:

1. Add the following endpoints from the Well-known configuration to the correlated field settings Authorize URI | Token URI | Logout URI | User Info (claims) URI

1. Add openid and email to the scope field

Configure Login Form

Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.

1. Navigate to the Form.io project and edit the application Login form.

2. Add a Button component

3. Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID

4. Save the form

1. Click on Actions

2. Select the OAuth (premium) action and click Add an action

3. In the Action Settings set the Oauth Provider to OpenID

4. Set Action to Remote Authentication

5. Set Sign-in with OAuth Button to your OIDC login button

6. Under Assign Roles add groups to Claim, group id to value, and Role type to Role

1. Set the Oauth Callback URL to the url of your login form

2. Click Save Action

Testing Authentication

Test the authentication workflow to ensure it functions correctly.

1. Navigate to your Applications authentication page and click the SSO with OIDC button.

2. Enter the OIDC credentials into the Microsoft authentication page

1. Once authenticated, the OIDC user should carry the OIDC Group Role (group id) as well as the mapped Form.io Role ID within the metadata of the user object.

Auth0

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

Create and Configure Application

1. From your Auth0 Admin dashboard, create a new Auth0 application by clicking the Applications tab and then the +Create Application button

1. Select the OpenId Connect (OIDC) application

2. Provide a name for the Application and click the Create button

1. Click the Setting tab and the application endpoint to the Allowed Callback URLs https://myapplication.com/dashboard

Create User

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

1. Within the Auth0 admin dashboard, click the User Management tab and then Users

1. Click the +Create User button

1. Input user information and click Create

1. Create additional users to assign to the different Roles that will be established in the next step.

Create and Assign Groups

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 Roles. Roles will allow us to establish mappings between OIDC groups and Form.io for role mapping.

1. Within the left-hand navigation bar, click Roles

2. Click Create Role

1. Add a Name and Description to the Role and click Create

1. Click on one of the role(s) you just created

2. Click on the Users tab

3. Click Add Users

1. Select your user you would like to add to this group and click Assign

2. Click on Actions > Library > Create Action > Build from scratch

1. Give the action a Name

2. Set the Trigger to Login / Post Login

3. Set Runtime to Node 18 and click Create

4. In the onExecutePostLogin function add the following code

exports.onExecutePostLogin = async (event, api) => {
  if(event.authorization){
    api.idToken.setCustomClaim('formioRoles', event.authorization.roles);
  }
};

Note: you cannot .setCustomClaim('groups', ...) or .setCustomClaim('roles', ...)

1. Click the Deploy button

2. Click on Triggers

3. Click post-login

4. Click Custom

5. Drag your action in between Start and Complete

6. Click Apply

Form.io Integration

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.

Client ID and Secret Key

1. Within your Auth0 Application, click the Settings tab

1. Copy the Client ID and Client Secret

1. Navigate to the OAuth settings within your Form.io project Settings > Authentication > OAuth

1. Paste the OIDC Client ID and Client Secret to the correlated Form.io field settings

Well-Known Configuration

1. Within your Auth0 Application, click the Settings tab

2. Scroll down the Settings page and expand the Advanced Settings

3. Click the Endpoints tab

   

The endpoint information will look something like this:

1. Add the following endpoints from the Well-known configuration then map them to the corresponding fields in your Form.io settings.

Form.io Setting	Well-known Configuration
Authorize URI	authorization_endpoint
Token URI	token_endpoint
Logout URI	end_session_endpoint
User Info (claims) URI	userinfo_endpoint

1. 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 Login Form

Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application.

1. Navigate to the Form.io project and edit the application Login form.

2. Add a Button component

3. Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID

4. Save the form

Oauth Action

Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process.

1. Navigate to the Login form within the Form.io Project

2. Click the Action tab and add the OAuth action

3. Click the OAuth Provider setting and select OpenID

4. Click the Action setting and select Remote Authentication

5. Click the Sign-in with OAuth Button setting and select the SSO button

6. 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.

Claim (OIDC)	Value (OIDC)	Role (Form.io)
formioGroups	admin role	Administrator
formioGroups	user role	Authenticated

Testing Authentication

Test the authentication workflow to ensure it functions correctly.

1. Navigate to your Applications authentication page and click the SSO with OIDC button.

2. Enter the OIDC credentials into the OneLogin authentication page

1. 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.

Token Swap

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.

var header = new Formio.Headers();
header.set('Authorization', 'Bearer 2e762950-9498-4079-a699-xxxxxxxxxxxx');

Formio.setBaseUrl('https://yourdomain.com');
Formio.setProjectUrl('https://yourdomain.com/yourproject');
var formio = new Formio('https://yourdomain.com/yourproject');
formio.currentUser({
  external: true,
  header: 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.

OIDC - Developer Portal

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:

OIDC - Form Manager Application

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.

OIDC Provider Application

1. Create an application within your OIDC provider (in this example auth0) and choose Single Page application type.

Open ID Application Configuration

Gather the Client ID and secret as well as the necessary endpoints found within the well-known endpoint for your application.

https://dev-abcdefghij.us.auth0.com/.well-known/openid-configuration

{
    "issuer": "https://dev-abcdefghij.us.auth0.com/",
    "authorization_endpoint": "https://dev-abcdefghij.us.auth0.com/authorize",
    "token_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/token",
    "device_authorization_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/device/code",
    "userinfo_endpoint": "https://dev-abcdefghij.us.auth0.com/userinfo",
    "mfa_challenge_endpoint": "https://dev-abcdefghij.us.auth0.com/mfa/challenge",
    "jwks_uri": "https://dev-abcdefghij.us.auth0.com/.well-known/jwks.json",
    "registration_endpoint": "https://dev-abcdefghij.us.auth0.com/oidc/register",
    "revocation_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/revoke",
    "scopes_supported": ["openid", "profile", "offline_access", "name", "given_name", "family_name", "nickname", "email", "email_verified", "picture", "created_at", "identities", "phone", "address"],
    "response_types_supported": ["code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token"],
    "code_challenge_methods_supported": ["S256", "plain"],
    "response_modes_supported": ["query", "fragment", "form_post"],
    "subject_types_supported": ["public"],
    "id_token_signing_alg_values_supported": ["HS256", "RS256"],
    "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
    "claims_supported": ["aud", "auth_time", "created_at", "email", "email_verified", "exp", "family_name", "given_name", "iat", "identities", "iss", "name", "nickname", "phone_number", "picture", "sub"],
    "request_uri_parameter_supported": false
}

Form.io Project Configuration

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.

Setting Up OpenID Login Button

1. Within your Project, navigate to the Admin Login form.

2. Add a Button Component

   • Select the OAuth action

   • Select the OpenID provider

   • Save settings.

1. Navigate to the Action tab and add the Oauth Action.

1. 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

Workflow Testing

1. Launch the Form Manager application

2. Click the Login with OIDC button

3. Enter your OIDC User credentials

You should authenticate into the Form Manager application