OAuth

Pre-requisites

In order to use OAuth make sure you have the following information from the external provider that will be used.

• Client ID;

• Secret Key;

• Subdomain.

In addition, apps need to be running version BetterForms 2.0.12+ (bf-staging, as of May 2023).

Setting up

Add domain to allowed callback URLs

Go to provider's admin console and add your domain as an Allowed Callback URLs, as following.

https://your.domain.com/oauth/providerName/callback
//Where providerName can be set as: google, auth0 or okta

Save Credentials

Select the app where OAuth will be added, click on the ellipsis besides the App name and select App Settings.

Under Authentication, toggle the button Enable 3rd Party Authentication.

Select one of the 3 providers from the dropdown menu, enter Client ID, Client Secret and Subdomain (Scope still not implemented).

Subdomain values vary from provider to provider:

Helper File

A new field oauthId needs to be created in the Users table.

Before Registration Hook - Business File

A before registration hook script can be used to the business file if you want to control whether a user is allowed to register or not.

The script needs to be called onBeforeRegistration, and by setting createUser to true on $$BF_Model will allow users to register to your app via OAuth.

Updating your Common hooks to support `onBeforeRegistration`

Update the BF Common Dispatch Script

Users registered via OAuth workflow are automatically verified, so there's no need to send verification emails.

New Callback Landing Page

This page is a new page that needs to be added to the app. Once the user is authenticated with the external user, the request will be redirected to this page, where the JWT token will be generated by calling the action presented below.

Navigation slug

The callback lading page must use auth/oauth as its navigation slug.

Add action to onFormLoad

In your new callback landing page, add the following actions to your onFormLoad:

"onFormLoad": [{
            "action": "authLoginOauth"
        }]

If the external provider or internal code returns an error, the error will return as a query parameter errorMessage , be added to default model.authMessage key, as well as a console log message.

Login Page

Button or Link

Add a button or link that redirects to one the following paths

For example, if we were to add Google to our app:

//Button in Page Schema
{
  "actions": [{
       "action": "namedAction",
       "name": "loginGoogle"
  }],
  "buttonClasses": "btn btn-info",
  "styleClasses": "col-md-2",
  "text": "Sign in with Google",
  "type": "button"
}

//Named Action in Page Info
"loginGoogle": [{
            "action": "path",
            "options": {
                "sameWindow": true,
                "url": "/oauth/google"
            }
        }]

//This is just an example, multiple params can be passed as needed
//Named Action in Page Info
"loginGoogle": [{
            "action": "path",
            "options": {
                "sameWindow": true,
                "url": "/oauth/google?redirect=%2Fdashboard&token=123-123-123-123"
            }
        }]

For Auth0, this can be found under the settings for your application.

Now in BetterForms, navigate to the User connectors page and create a new OAuth2 connector.

Copy the settings from your Auth0 application into the fields in BetterForms. The scope can be left as openid profile email for Auth0.

Redirect URI

The redirect URI is a security measure to ensure that the authentication provider only sends users to a trusted location. You must copy the redirect URI from BetterForms and paste it into your authentication provider's settings.