Comment on page
OAuth
Documentation for the Form.io OAuth Integrations
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.
The very first step is to first choose 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 URLs 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 by your application configuration.
- Client Secret - This is the OIDC client secret provided by 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 emailthe value of the scope.
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.
If you wish to register any Form.io users using your OIDC provider, then this can be done through 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 them with the following fields.
- Hidden field - Email
- Hidden field - Name
- Button - "Register with OIDC", ensure it has OAuth selected, and 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.
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 mapped. 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 as 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
In order to log in a OIDC 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
Adding OIDC users to a Form.io Team closely mirrors the setup procedure for a standard Form.io configuration. OIDC users are added to a Form.io Team by utilizing the email address associated with the respective OIDC user. After adding the OIDC user emails to the Form.io Team, the Team Admin should check the SSO Team setting. This SSO Team setting will communicate to the API platform the team should be mapped with OIDC users.
If additional OIDC members need to be added to the Team, uncheck the "SSO Team" setting and input the additional OIDC User email addresses. Ensure the SSO Team setting is checked again after adding the additional users.
Like other SSO Teams, the OIDC user is automatically included in the Team and is not required to 'accept' the Team Invite.
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,
});
Form.io will use the authorization token to make a request to the OAuth endpoint, receive your user information, and create a new form.io token that is passed back to the form.io library and used on subsequent requests.
In order to perform a Token Swap, it is required to expose the /UserInfo endpoint
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 to 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 set up 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, you can feel free to delete the "Login with OIDC" and "Email" hidden fields since 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
In order to achieve SSO in 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 the User resource.
Create Application: Create an account in auth0 then in the management 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
Once you create the application we can get the client ID and Secret that we will need to add the provider to the 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
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
}
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.
Now we can add all the information from the endpoint and our application.Open ID Config
Go to your login form and drag&drop a Button Component change the action to OAuth and choose the OpenID provider Save settings.
Next, go to the Action tab and choose Oauth Action.
Next, setup the OAuth action by choosing the Provider, Action and map the button in your login form
Last modified 9d ago