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.
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:
myClientID.apps.googleusercontent.com
N/A
Auth0
mySubdomain.region.auth0.com
mySubdomain.region
Okta
mySubdomain.okta.com
mySubdomain
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`
if your integration is older, you may not have a onBeforeRegistration
hook installed.

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
/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"
}
}]
Redirects can be performed by adding a redirect
query param to the URL. You can also pass things like id
's which will appear in the onBeforeRegistration
script in the $$BF_Query
variable.
//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.

Last updated
Was this helpful?