OAuth

Oauth authentication is the protocol that allow users to login to your application using external provider credentials, such as Google, Auth0 or Okta.

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.

Here are the links for each provider documentation: Google, Auth0 and Okta.

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).

Whenever an information from above is changed, the Client Secret always need to be reinserted.

Subdomain values vary from provider to provider:

Provider
Domain
Subdomain

Google

myClientID.apps.googleusercontent.com

N/A

Auth0

mySubdomain.region.auth0.com

mySubdomain.region

Okta

mySubdomain.okta.com

mySubdomain

No subdomain value is needed for Google, and Auth0 domain doesn't always have a region in it.

Helper File

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

Remember to add the ouahtId field to the layout.

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.

If onBeforeRegistration hook script is not created and/or createUser not set to true, users will not be allowed to register via OAuth.

Updating your Common hooks to support `onBeforeRegistration`

Update the BF Common Dispatch Script

add an onBefore Registration script as shown

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.

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.

Note for early OAuth users: the OAuth action used to be oauthLoginHook , and as shown above, it changed to authLoginOauth. However, both actions will be supported at the moment.

Login Page

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

Provider
Provider

Google

/oauth/google

Auth0

/oauth/auth0

Okta

/oauth/okta

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.

"OAuth Provider Settings"

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

"OAuth Credentials"

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.

"OAuth Redirect URI"

Last updated

Was this helpful?