OAuth

OpenID Connect (OIDC)
The most common form of OAuth authentication is to use the OpenID Connect framework to achieve OAuth 2 authentication into the Form.io Platform. There are four different kinds of authentication methods that are supported within the OIDC integration. These are as follows.
Remote Authentication - This allows for you to use the users from the remote authentication source as the authenticated entity for all interactions within Form.io. This method will not create a user record within any user resource within your project, but rather use the remote user entity for all interactions.
OIDC User Registration - This allows for you to create a new user entity within the Form.io platform using the user information provided by your external authentication system.
OIDC User Login - This will use the remote OIDC authentication to locate a Form.io user record within a resource, and then establish an authenticated link to that submission resource.
OIDC 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. In order to achieve this within Form.io, we must first configure our project so that it is OIDC ready.
Setting up an OIDC provider
The very first step is to first chose an OIDC provider. There are many different providers out there, but some of the more common ones are as follows.
Azure AD
Okta
OneLogin
Auth0
Each configuration for each of these platforms is different, but all of them provide the following credentials that will be used within the configurations for our project. You will need to save the following from your OIDC provider which will be used to configure your project. The easiest way to determine these URL's is to navigate to your OIDC URL and then append /.well-known/openid-configuration to the end of that URL. For example:
The following URL
https://dev-abcdefghij.us.auth0.com/.well-known/openid-configuration
This provides the following response.
{
    "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
}
Authorize URI (authorization_endpoint) - This is the authorization url. An example would be https://yourcompany.onelogin.com/oidc/2/auth
Token URI (token_endpoint) - This is the url that will be used to fetch the OAuth token from the provider once you have been authorized. An example looks like https://yourcompany.onelogin.com/oidc/2/token
User Info URI (userinfo_endpoint) - This is the url that will be used to fetch the OAuth user profile object so that we can retrieve fields such as "email" and "name". An example looks like https://yourcompany.onelogin.com/oidc/2/me
Client ID - This is the OIDC client ID provided from your application configuration.
Client Secret - This is the OIDC client secret provided from your application configuration.
Scope - This tells the OIDC provider which information it should return about the user who is authenticated. The Form.io platform requires that it at least return the ID of the user as well as the email. This is usually done by saying openid email as the value of the scope.
Configure the Form.io Project
Once you have all of these fields from your OIDC provider, you will now go to the Project Settings of your project and then click on the Authentication section and then OAuth and then expand the OpenID panel. First you will input all the fields captured above as follows.
Next, we will need to set the following properties within the OpenID Connect panel.
Scope: openid email
Claim: For now we will just leave the "Claim" field empty, but ensure we select the Role of "Authenticated"
We can now press the Save button to save our Project Settings. Our project is now configured with OIDC. Next we will need to configure our User Login and User Register forms to enable the different OIDC flows described at the top of this page.
User Registration with OIDC
If you wish to register any Form.io users using your OIDC provider, then this can be done within a User Register form. Most default projects do come with a default User Register form, so we will just use this one and make modifications so that it will work with OIDC instead. After we have a new project, our User Register form will look like the following.
We will first delete all of the fields from this form, and then replace it with the following fields.
Hidden field - Email
Hidden field - Name
Button - "Register with OIDC", ensure it has OAuth selected, select OpenID. Here is an example of what was configured for the button component.
Also, you will need to ensure that Disable on Form Invalid is unchecked
Press Save to save both the button and the form.
Your form should look like the following.
We are now ready to configure the OAuth actions.
OIDC User Registration Actions
In order to establish a Form.io submission, the first action that will be important is the Save Submission action. This action should already be added to the default User Register form, but we will need to ensure that the fields that we added are properly mapping. To do this, we will need to edit the Save Submission action by clicking on the Actions section and then clicking on the Save Submission action.
This will then open up the Save Submission action where you will ensure that the Email and Name fields that you added to the form are configured correctly like the following illustrates.
We will now Save the action.
Next we will need to remove the existing Login action since we will be authenticating with the OAuth Login action instead. We will just need to press the Delete button next to this action to remove it.
After the Login action has been removed from this form, we will now need to add an OAuth action by selecting it in the Action dropdown and then clicking on the Add Action button.
On the next page, we will then just need to configure the following.
Now Save this action.
This form is now configured to Register new users associated with your OIDC provider!
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
User Login with OIDC
In order to login a user, we will first need to ensure that we have our project configured so that Users within our user resource have been either "Linked" or "Registered" using the OIDC methods described above. Once this criteria has been met, then we can now establish a Login form that will authenticate with the OIDC provider and then login to an existing user resource submission associated with that OIDC authentication. The first thing we will need to do is make some changes to the default User Login form, which can be found in any project.
Now that we are editing this form, we will need to do exactly what we did with the user login form above so that our form looks like the following.
And then we will add the OAuth action to this form.
Next, we will configure this action as follows.
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
Remote Authentication (SSO)
Remote authentication is used if you would not like to associate the OIDC user entity with any underlying Form.io user resources. This is commonly referred as SSO (Single Sign On). Because of this, we will only need to associate this form of authentication with a Login form so that it will remotely authenticate a user into the Form.io platform. We can do this using the existing User Login form that we have setup in the User Login with OIDC section. Navigating to this form, we will just need to add an additional OAuth login button like so.
Also note that if you would ONLY like to use Remote Authentication within this form, that you can feel free to delete the "Login with OIDC" and "Email" hidden fields since the Remote Authentication does not need these fields to properly authenticate. Once we have made these changes, we can now navigate to our Actions section where we will add an OAuth action.
Within this OAuth action, we will configure it as follows.
Next we will click Save to ensure that we save the new action.
We now have our login form work with OIDC Remote Authentication!
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
OIDC for Developer Portal
In order to achieve SSO into the Developer portal, you will simply need to make all of the configurations provided above but to the Portal Base project. In most cases, simply using the Remote Authentication method since it will establish authentication into the Developer Portal application without requiring any user resources saved to a the User resource.
OIDC for Form Manager Application 
auth0 Provider
Create Application: Create an account in auth0 then in the manage dashboard page click on Create Application button. Choose the application type that you are working on. In this case we choose SPA (Single Page Application)Create ApplicationApplication Type
Could not load image
Could not load image
Open ID config from Application.
Once you create the application we can get the client ID and Secret that we will need to add the provider into our Form.io Project. Next you will need to gather the OPEN ID configuration from the .well-known endpoint which is a standard url.Settings information
Could not load image
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
}
OPEN ID Form.io Project Config
Once you have all the information you need we proceed to add all the information in the OAuth settings of your project. Go to your project settings into Authorization settings then choose OAuth and finally open OpenID Connect to add all the information.
Could not load image
Now we can add all the information from the endpoint and our application.Open ID Config
Could not load image
Setting Up Open ID Login Button
Go to your login form and drag&drop a Button Component change the action to OAuth and choose the OpenID provider Save settings.
Could not load image
Next go to actions and choose Oauth Action.
Could not load image
Next, setup the OAuth action choosing the Provider, Action and map the button in your login form
Could not load image
Finally, you can now embed your form with the Open ID Button Action.
​
Could not load image
Could not load image
Developer Guide - Previous
SAML
Next - Developer Guide
LDAP
Last modified 3mo ago
Copy link
Outline
OpenID Connect (OIDC)
Setting up an OIDC provider
Configure the Form.io Project
User Registration with OIDC
User Login with OIDC
Remote Authentication (SSO)
OIDC for Developer Portal
OIDC for Form Manager Application