OAuth Authentication

OAuth allows you to authenticate with <form.io> using a 3rd party OAuth provider. This is very convenient because users may register new accounts and log in without having to manually enter a new username and password.

When configuring OAuth to work with form.io, there are two different methods to do so. One uses the Remote Authentication OAuth action and the other uses the Resource OAuth actions.

Remote Authentication

When using external authentication, user accounts only exist in the 3rd party service. An account is not created in Form.io. Users are still assigned a form.io role (or roles) and may have ownership over forms and submissions.

Resource Authentication

When using Resource authentication, when a user registers with OAuth a User Resource is created in form.io. Subsequent Logins are made using OAuth to that User Resource. Since the users exist in Form.io, they can be queried and viewed.

The OAuth actions associated with Resource Authentication are:

  • Login Existing Resource
  • Register New Resource
  • Link Current User

OAuth Provider Settings

Select one of the OAuth providers below and generate the Client ID and Client Secret as well as any other required information. Go to the OAuth settings section of your project and enter the information in the correct OAuth provider.

Save your Settings

Add OAuth Button to Form

If you are using Remote Authentication you do not need to modify the register form, you can just do this on the login form.

Edit your User Login Form and drag a new button component onto the form.

Be sure to select OAuth for the button action. You will not be able to assign the OAuth action later if it is not an OAuth action.

Ensure that Disable on Form Invalid is not checked.

Save and then Save the Form

Repeat this step for the User Register Form (But you may change the label to suit. For example: Register with Github).

Add OAuth Action to Form

Edit the Actions for the User Login Form

Add a new OAuth Action.

Remote Authentication

If you are using remote authentication then select that in the action and select your OAuth provider that you configured in the project settings. Make sure to also select which OAuth button to associate with the action.

Finally, assign roles based on the external user properties. You can map any OAuth claim value to a property. For example, if the data comes back as

{
  name: 'joe',
  group: 'admins'
}

You can map:

  • Claim: group
  • Value: ‘admins’
  • Role: Administrator

This will give administrator to anyone who has a claim of group: ‘admins’

Resource Authentication

To use Resource authentication, fill in the settings as shown below. For more information on what these settings do, see the OAuth Action in the User’s Guide.

Click Submit. Go to the Actions tab for the User Login Form. Add a new OAuth Action. Fill in the settings as shown below:

Click Submit.

Create a Link Form

At this point, your project is completely set up to use OAuth authentication! Once you embed the User Register and User Login forms in your application, users will be able to use the OAuth provider you configured to login. For information on how to embed forms into your application, see Application Embedding.

If you want to let users authenticate with both a traditional username-password pair or an OAuth provider, then one extra step is necessary to allow users who created an account with a username and password to link their existing account with an OAuth provider.

Create an OAuth Link form in your project. Edit the default Submit button to be an OAuth button with the settings below:

Click Create Form Click on the Actions tab and add a new OAuth Action with the settings below:

Click Submit Next embed this form somewhere in your application where only authenticated users can access it, like a user settings page. You will need some custom logic to hide the form for users who have already logged in. Specifically, you must 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
    }
});

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 Connnect settings in your project.

Then, instantiate the Formio library with your project url and call the currentUser endpoint with your authorization header.

var authorization = 'Bearer: ABC123XYZ789';

var formio = new Formio('https://myproject.form.io');
formio.currentUser({
  header: {
    authorization: authorization
  }
});

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.

OpenID

OpenID Connect is a single sign on (SSO) framework for OAuth 2. In order to use OpenID Connect you must have a auth provider that supports OpenID Connect and set up an APP within that provider. Then use the settings from your provider to configure the connection here. See OpenID Connect for detailed information.

Fill in the application details. The Authorization (or login redirect) callback URL MUST be set to the domain name of your application (ex: https://mydomain.com).

Popular OpenID Connect services include Auth0 and Okta.

OpenID must use Authorization code flow.

Github

Login to GitHub and visit your Developer applications settings page.

Click Register new application.

Fill in the Application name, Homepage URL, and Application description with appropriate details about your application. This information is displayed to potential users of your application when they asked to grant permissions to your app.

Fill in the Authorization callback URL with your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using localhost for running your app locally is acceptable, but make sure the right port is provided.

Click Register application.

Take note of the Client ID and Client Secret. Enter them in the Project Settings for GitHub Oauth.

Github OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

Facebook

Login to Facebook and visit the Developer page.

Click on My Apps > Add a New App.

Click on Website.

Enter a name for your app and click Create New Facebook App ID.

Select a category for your app and click Create App ID.

Scroll down and fill in the Site URL with your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using localhost for running your app locally is acceptable, but make sure the right port is provided.

Click Next.

Scroll to the top and click Skip Quick Start.

Take note of the App ID and App Secret (in this guide we will refer to them as Client ID and Client Secret). Enter them in the Project Settings for Facebook Oauth.

Note that your Facebook app is now in development mode and can only be logged into by you. When you are ready to open up OAuth logins to the public, go to the Status & Review page and click the toggle button to make your app public.

Facebook OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

Dropbox

Login in to Dropbox and visit the Create Application page

Fill out the appropriate settings for your app. Using “Dropbox API” and “App Folder” should work for most applications.

You should Enable additional users for your app so that others can use it as well. When ready, you can apply for production as well.

Grab the App Key and App Secret. These should be put in your project settings under Dropbox OAuth under Client ID and Client Secret.

Fill in the Redirect URIs with your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using localhost for running your app locally is acceptable, but make sure the right port is provided.

Dropbox OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

Twitter

Login to Twitter and visit the Developer page.

Click on Create New App.

Fill in the Application Name, Website, and Application description with appropriate details about your application. This information is displayed to potential users of your application when they are asked to grant permissions to your app.

Fill in the callback URL with your application’s hostname. OAuth will not work unless you enter the same host name as the one your application is served from. Using 127.0.0.1 for running your app locally is acceptable, but make sure the right port is provided.

Click Keys and Access Tokens.

Take note of the App ID and App Secret (in this guide we will refer to them as Client ID and Client Secret). Enter them in the Project Settings for Twitter Oauth.

Twitter OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

Google

Login to Google and visit the Developer page.

Click on Create a project.

Enter a Project name for your app and click Create.

Click on Enable and manage APIs.

Click on Credentials > OAuth consent screen. Scroll down and fill in the Product name shown to users with your application’s Homepage URL.

Click on left menu Credentials > Credentials tab.

Scroll down and click on New credentials then Select oauth client ID.

Scroll down to Select Application type Web application and fill in the Authorized redirect URIs with your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using 127.0.0.1 for running your app locally is acceptable, but make sure the right port is provided.

Click on Create

Take note of the Client ID and Client Secret. Enter them in the Project Settings for Google Oauth.

Google OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

LinkedIn

Login in to LinkedIn and Click On the Create Application

Fill in the Company Name, Name, Application Logo, Application Use, Business Email, Business Phone, Website URL and Description with appropriate details about your application. This information is displayed to potential users of your application when they asked to grant permissions to your app.

You should checked ‘r_basicprofile’ for Default Application Permissions.

Grab the Client ID and Client Secret. These should be put in your project settings under LinkedIn OAuth under Client ID and Client Secret.

Fill in the Authorized Redirect URLs with your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using localhost for running your app locally is acceptable, but make sure the right port is provided.

Click On the Update LinkedIn OAuth should now be set up. Continue with adding Login, Register and Link buttons to your forms.

Microsoft Office 365

Create your Office 365 Business Account Associate your Office 365 account with Azure Sign into the Azure Management Portal using your Office 365 Developer Site credentials.

Click Active Directory on the left menu, then click on the directory for your Office 365 developer site.

Create a new Active Directory “Directory”.

Fill out your application information.

Click on “Applications”, then click on “Add” to create a new application.

Click on the link that says “Add application my organization is developing”.

Give your application a name.

Provide an application URL. It can be localhost if you are just using it for <form.io> integration

Click on Configure within your application

Add a new key for 2 years

Set the Reply URL as your application’s hostname. OAuth will not work unless you enter the same hostname as the one your application is served from. Using localhost for running your app locally is acceptable, but make sure the right port is provided.

Then click on the Add application button.

Click on Office 365 Exchange Online and Office 365 unified API permissions and then click the Save icon.

Enable the appropriate application permissions, and then press Save.

Press Save.

Take note of the Client ID and the key you added. These are the Client ID and Client Secret, respectively, that should be entered in your Project Settings for Microsoft Office 365 Oauth.