OAuth

Documentation for the Form.io OAuth Integrations

OpenID Connect (OIDC)

The most common OAuth approach is leveraging the OpenID Connect framework to achieve user authentication into your application or the Form.io portal. With numerous providers available OIDC proves to be a flexible and secure means of authenticating your user base. Form.io seamlessly manages this integration, offering multiple strategies and methods to authenticate users through your OIDC provider.

Setting up an OIDC provider

The first decision to make is choosing an OIDC provider. There are many different providers out there, the following being the most common:

Okta
Auth0
OneLogin
Microsoft Entra ID (Formerly known as 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.

In addition, 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. Each provider will produce comparable endpoints and credentials for integrating the provider into your 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 openID and email is set within your scope settings.

The Form.io platform requires the UserID and Email within the Scope to be returned for authentication. Addopenid and email to the scope value within the Project's authorization settings.

How Do I Find My 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.

{
    "issuer": "https://yourcompany.oidcprovider.com",
    "authorization_endpoint": "https://yourcompany.oidcprovider.com/authorize",
    "token_endpoint": "https://yourcompany.oidcprovider.com/oauth/token",
    "device_authorization_endpoint": "https://yourcompany.oidcprovider.com/oauth/device/code",
    "userinfo_endpoint": "https://yourcompany.oidcprovider.com/userinfo",
    "mfa_challenge_endpoint": "https://yourcompany.oidcprovider.com/mfa/challenge",
    "jwks_uri": "https://yourcompany.oidcprovider.com/.well-known/jwks.json",
    "registration_endpoint": "https://yourcompany.oidcprovider.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
}

OAuth Provider 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.

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

Configuring the Form.io Project

Once you have the necessary information from your OIDC provider, 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.

OpenID Configuration Settings

The Client ID and Client Secret are typically found within the OIDC application settings. The URI and Scope settings can be found within your OIDC 'well-known' endpoint displayed in the example below:

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

Authorization URI (Required*): OIDC Provider endpoint where the user is asked to authenticate to grant access to the client application. This endpoint is found within your OIDC provider's 'well-known' endpoint

Token URI (Required*): The token endpoint that allows the client application to exchange the code received from the authorization URI in exchange for the access token. This endpoint is found within your OIDC provider's 'well-known' endpoint

Logout URI: Redirects the user to the logout endpoint of the OIDC provider, allowing the user to log out and clear the OIDC authentication session.

Client ID (Required*): The identifier of the client generated within the OIDC provider.

Client Secret (Required*): The secret of the Client generated within the OIDC provider.

Authorization Method: Determines if the OIDC authorization request will be contained within the Body (most common) or the request Header.

User Info URI (Required*): Endpoint containing the authorizing User's scope (or user attributes) saved within the OIDC provider.

Scope (Required*): The entire grouping of attributes (or claims) used to authorize a user. Form.io requires openid and email saved to the scope. Scope attributes (or claims) are separated by white space within the Scope setting field.

The Form.io platform requires the UserID and Email within the Scope to be returned for authentication. The scope is set by adding openid and email to the scope value within your Project's authorization settings.

Roles: Configures OIDC provider claims saved to an OIDC User and associates the claim with a Form.io role, enabling granular permissions between OIDC Group claim (roles ) and Form.io roles. The following UI facilitates the mapping between the Claims and a Form.io role.

In the following example, the OIDC provider has a claim called groups found saved within the scope. That groups claim references OIDC Roles that is configured within the OIDC Provider. The example below is mapping OIDC Users that carry the Member role with the Form.io Authenticated role and OIDC Users that carry the Admin role with the Form.io Administrator role.

Check your OIDC provider's 'well-known' endpoint to determine what role/group based claims are available within the 'supported_scope'.

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

Claim (OIDC)

Value (OIDC)

Role (Form.io)

groups

Member

Authenticated

groups

Admin

Administrator

OIDC Authentication Methods

After configuring the OIDC settings within the Form.io Project, the Login/Registration forms can be modified to support OIDC authentication. Four different kinds of authentication methods are supported for OIDC which will be dictated by the OAuth Action saved to the Authentication form:

Remote Authentication - Authentication strictly utilizing the OIDC User credentials connected to the OAuth provider. This approach will not create a User in any resource within your project; instead, it utilizes the remote user entity stored within the OIDC provider for all authentication purposes in your application. Beneficial if you wish to decouple the OIDC user information from the Form.io project.
User Registration - Creates a new user record within Form.io by utilizing the user credentials from the OAuth provider.
User Login - Utilizes the remote OIDC User authentication to locate a Form.io user record within a resource to establish authentication.
User Link - This will "link" an external OIDC user entity with an existing Form.io user record.

Each of these methods can be used to establish a variety of authentication strategies within the Form.io platform. To achieve this within Form.io, an OIDC provider must be established first. Once OIDC has been set up, credentials generated from the provider will be integrated into the Form.io project. Modifications of your Form.io authentication forms will be necessary to establish the final connection between your forms and the OIDC provider.

Preconditions for the authentication method examples:

Ensure the Project is configured to support your OIDC Provider
The following default forms that are created with a Form.io project are being utilized: User Login Form User Registration Form
The Registration and Login Forms are being mapped to the default User Resource

Remote Authentication (SSO)

Remote authentication, commonly referred to as SSO (Single Sign-On) authenticates the user by using credentials saved to the OIDC provider, without requiring or referencing underlying Form.io data. This decouples the OIDC user information from the Form.io project.

The following example will showcase how to configure the Form.io User Login form to support Remote OIDC Authentication within our application.

Ensure OIDC Settings have been properly configured within your Project Settings.

Navigate to the Form.io project and edit the User Login form.
Add a Button component called SSO with OIDC
Within the Button settings, set the Action to OAuth and OAuth Provider to OpenID

Click the Actions tab and add the OAuth action
Within the OAuth action, configure the following settings
- Set OAuth Provider to OpenID
- Set Action to Remote Authentication
- Set Sign-In With OAuth Button to the SSO Button - SSO with OIDC
- If you are not delegating OIDC Roles, leave the Claim and Value setting blank and select a Form.io role you want to assign the user. The following configuration will delegate every OIDC user logging in to carry the Form.io Authenticated role.

Your Login form should look something like this

Navigate to your Applications authentication page and click the SSO with OIDC button. You should be prompted to enter your OIDC credentials

When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed url to allow for the OAuth action to trigger properly

Mapping OIDC Roles To Form.io Roles

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 setting the Claim and related Value within the OAuth action of the Login form. The Claim and Value will be specific to the OIDC Provider and can be found within the well-known endpoint.

Building off the Remote Authentication (SSO) workflow example, the OAuth action added to the User Login form can be extended to support OIDC Role mapping.

OIDC Application Configuration

In some cases, you may need to configure your OIDC Application to enable the Group claim and Role mapping. Refer to your OIDC Provider documentation for details.

Form.io Setting Configuration

To enable the Group claim within your Form.io Project, simply add 'groups' to the scope within your OpenID settings.

OAuth Action Modification

This step is assuming you have your Login form already configured to support Remote Authentication. Click Here for more information on

Scroll down to the Assign Roles setting within the OAuth action:

The setting will be the claim name that supports roles within the OIDC scope. The OIDC provider in this example utilizes 'groups' as the claim mapping.
The Value setting will be the identifier for the OIDC Role. The OIDC provider is in this example utilizes the Role name for the value.
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.

OIDC provider claims and values may differ between providers. Ensure you check your OIDC provider's 'well-known' endpoint to see a list of supported claims.

Test the workflow out by authenticating into your application and reviewing your Dev Console. Within the Local Storage, The authenticated OIDC user should carry the OIDC Group Role (Member) as well as the correct Form.io Role ID (Authenticated 65de..) within the metadata of the user object.

User Registration with OIDC

The OIDC User Registration method allows OIDC Users to register their accounts using Form.io, saving their OIDC User record within a Form.io Resource. Most Form.io Projects come with a User Register form by default which will be modified in this example to support OIDC registration.

In this example, the User Registration form is embedded within my application to enable SSO registration that will save to the User Resource within my project.

It's important to note that this workflow does not register a user with an OIDC provider, but rather registers an OIDC user within the Form.io Project. This registration can be applied to the Portal Base Project within your deployed environment or for a connected application.

Registration Form Modifications

To get started, navigate to your Project and edit the User Registration Form.
Add a Hidden field called Email and a Hidden field called Name
Add a Button called Register with OIDC and modify the following settings
- Set a Label for the button like Register with OIDC
- Set the Action to OAuth
- Set the OAuth Provider to OpenID

OAuth Action

This action will integrate the OIDC Provider and map the provider claims to the User Resource within the Form.io Project.

Add an OAuth Action to the Registration form and modify the following settings
- Set OAuth Provider to OpenID
- Set Action to Register New Resource
- Set Resource to User
- Set Sign-in with OAuth Button to Register With OIDC

Set the OAuth Callback URL to your application Domain

Map Claims

These settings will dictate what information from the OIDC User scope should be saved with the Registration record. Since the data input will be done on the OIDC authentication page, no physical fields on the form are needed. The hidden email and name field will be used to map the email and name from the OIDC User scope to the submission object.

Set the Claim to email and select the Email field
Set the Claim to name and select the Name field
Save the Action

Save Submission Action

Now that the OAuth settings have been mapped to the User Resource, a Save Submission action will be added to ensure the data submitted against the Registration form is stored within the User Resource.

Add a Save Submission Action and configure the following settings
- Set the Save Submission To field to the User Resource
- Map the Name and Email field on the form to the corresponding fields on the User Resource

After saving the Action, our Registration form should look like this

Registration Workflow Testing

With the Registration form modified, we are now ready to test the workflow.

Navigate to your application's registration page
Click the Register with OIDC button and enter the OIDC User credentials

Navigate to the User Resource Data tab within the Project and ensure a User record was generated based on OIDC User registration.

When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed url to allow for the OAuth action to trigger properly

This Authentication method will utilize OIDC User credentials to log in a User that has been saved within the User Resource of the Form.io Project. The OIDC User and Form.io User record must be 'Registered' or 'Linked' using the OIDC methods detailed within this documentation to establish a proper connection.

Once these conditions have been met, the User Login form can be configured to authenticate the OIDC User against the User Resource within the project.

Edit the User Login form within your Project
Add a Button component called Login with OIDC and configure the following settings
- Set a Label for the button like Login with OIDC
- Set the Action to OAuth
- Set the OAuth Provider to OpenID

Add an OAuth Action to the Registration form and modify the following settings
- Set OAuth Provider to OpenID
- Set Action to Register New Resource
- Set Resource to User
- Set Sign-in with OAuth Button to Register With OIDC

Now click Save and our form is now configured for Login using OIDC!

When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed url to allow for the OAuth action to trigger properly

Workflow Testing

With the Registration form modified, we are now ready to test the workflow.

Navigate to your application's login page
Click the Login with OIDC button and enter the OIDC User credentials

The same user created using the OIDC User Registration method is now authenticated into the application.

This example can be followed for your client application or for SSO into the Form.io Developer Portal.

User Link with OIDC

This authentication method will "link" an external OIDC user entity with an existing Form.io user record. This method requires custom code within your application to properly link the user records with the OIDC user.

Create a Form called Link User
Edit the Submit Button and modify the following settings:
1. Set the Action to OAuth and the Provider to OIDC
Embed the form somewhere in your application where only authenticated users can access it, like a user settings page.
Add custom logic within the Application to hide the form for users who have already logged in. Specifically, check if the user has an externalIds entry for your provider. Here is some sample code that will check if the user has been linked with GitHub using the formio.js library:

var isLinkedToGithub = false;

Formio.currentUser().then(function(user) {

    if(!user) {
        return;
    }

    user.externalIds.forEach(function(id) {
        if(id.type === 'github') {
            isLinkedToGithub = true;
        }
    });

    if(isLinkedToGithub) {
        // Hide form here
    }
});

OIDC Teams

Adding OIDC Users to a Form.io Team mirrors the setup procedure for a standard Form.io Team configuration. If the OIDC users were created using the OIDC User Registration method, simply add them to a Form.io Team with the email address associated with their respective OIDC account.

The OIDC User will log in into the Portal and accept the Team Invitation, just like any other user joining a Team.

SSO Team

To create SSO Teams, the correct environment variable must first be configured within your deployment. Add the following API Server Environment Variable and redeploy the Portal application.

SSO_TEAMS=true

When creating a new team, an SSO Team configuration checkbox will display beneath the Team name. To add SSO Users, uncheck the SSO team checkbox and add the email address of the OIDC User to the Team. After all users have been added, check the SSO Team checkbox to save the Team.

If additional OIDC members need to be added to the Team, uncheck the "SSO Team" setting and input the additional OIDC User using their OIDC email address. Ensure the SSO Team setting is checked again after adding the additional users.

SSO Team Role Mapping (COMING SOON FOR OIDC)

Another SSO Team option is to avoid manually adding individual SSO users to the Team. Instead, during the SSO authentication process, roles associated with OIDC users are automatically linked to a Team if the Team's name matches the user role.

Dynamic SSO Team Mapping is coming soon for OIDC and is currently available for SAML

Depending on the OIDC Provider, it may be necessary to configure the Group 'Claim' parameter within the provider's configuration. This will ensure the OIDC Role associated with the authenticating OIDC user is returned to Form.io so it can be mapped to a Form.io role.

Typically, the roles of the OIDC provider are tied to the 'groups' claim. This could vary depending on the provider.

Within your project's OpenID settings, ensure the 'groups' parameter is included within the Scope setting of your Project OpenID settings

To finalize this process, create a new Team and ensure the Team name matches the OIDC Role your authenticated users are associated with. In this example, the OIDC Role my SSO user is associated with is 'Member'.

Workflow Example

Ensure the authenticating OIDC user is associated with a Group Role

Ensure the OIDC provider application has the Group parameter configured

3. Ensure the deployed environment has the correct Environment Variable set to enable SSO Teams SSO_TEAMS: true

Portal Base Project configuration
- Ensure your Portal Base Project is configured for OIDC Authentication
- Ensure your Portal Base Project login form is configured for SSO Authentication
Create a new Form.io Team
- Give the Team a name that matches the OIDC User Role
- Check the SSO configuration setting

Create or modify an existing Project the SSO Team will be added to
- Ensure this Project is configured for OIDC Authentication
Add the SSO Team to the OIDC-configured Project

Authenticate into the Portal using the OIDC User

You should have access and permissions to the Project the SSO Team has been added to.

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');

var formio = new Formio('https://myproject.form.io');
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 with the Form.io 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:

SSO Authentication Into Developer Portal Using OIDC

OIDC for 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.

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

Workflow Testing

Launch the Form Manager application
Click the Login with OIDC button
Enter your OIDC User credentials

You should authenticate into the Form Manager application

PreviousSAML NextLDAP

Last updated 2 months ago

OpenID Connect (OIDC)

Setting up an OIDC provider

How Do I Find My URI Endpoints?

OAuth Provider General Troubleshooting

Configuring the Form.io Project

OpenID Configuration Settings

OIDC Authentication Methods

Remote Authentication (SSO)

Mapping OIDC Roles To Form.io Roles

OIDC Application Configuration

Form.io Setting Configuration

OAuth Action Modification

User Registration with OIDC

Registration Form Modifications

OAuth Action

Map Claims

Save Submission Action

Registration Workflow Testing

User Login with OIDC

User Login Modification

Workflow Testing

User Link with OIDC

OIDC Teams

SSO Team

SSO Team Role Mapping (COMING SOON FOR OIDC)

Workflow Example

Token Swap

OIDC with the Form.io Developer Portal

OIDC for Form Manager Application

OIDC Provider Application

Open ID Application Configuration

Form.io Project Configuration

Setting Up OpenID Login Button

Workflow Testing