OAuth

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. To get your project working with OAuth, please walk through the following steps. These steps will be using a new project from the Default template, but you may use any project you wish.

Register with OAuth Provider

In order to use OAuth with a provider, you must first register your application with that provider and obtain a Client ID and Client Secret. See the Oauth providers below for instructions on how to signup for each.

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.

Save in Project Settings

Login to <form.io> and go to the project you wish to use OAuth in. Click on the Settings tab.

Click on the OAuth tab.

Click on the OAuth provider you registered with and fill in the Client ID and Client Secret you received in the previous step.

Click Save Settings.

Add Oauth Button to Form

Go back to your Project page and click the Edit button for User Register.

Drag a new Button component to your form.

Set the Action to OAuth and uncheck the Disable on Form Invalid checkbox. Use an appropriate label like Sign-Up with GitHub.

In this example we set the Left Icon classes to fa fa-github to show the Font Awesome icon. If you would like to use these icons, you must add Font Awesome to your application. You are free to use any icon library, however.

Click Save and then click Save Form Repeat this step for the User Login Form (But you may change the label to suit. For example: Sign-In with Github).

Add Oauth Action to Form

Click on the Actions tab for the User Register Form. Add a new OAuth Action.

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