Skip to main content

OAuth 2.0 SSO

OAuth 2.0 is the recommended and more secure way of implementing SSO between your existing user directory and a Bettermode site. Bettermode supports the most common implementations of OAuth 2.0 including OpenID Connect.

To use OAuth 2.0, your website or product must act as an OAuth 2.0 identity provider. If you use Okta or Auth0, you can enable this easily since they support OAuth 2.0 out of the box.

Most content management systems have plugins to support OAuth 2.0 as well. For instance, you can use WP OAuth Server plugin to add OAuth 2.0 support to your WordPress website.

To enable OAuth 2.0 SSO on your Bettermode, go to Network Settings > Authentication and enable OAuth 2.0. Before enabling, pick your SSO Provider and fill out the mandatory fields. Bettermode supports Okta, Auth0, WordPress, Outseta, and Memberful out of the box. If your provider isn't listed, select "Custom Provider".

Client ID, Client Secret, and the Authorization Domain/URL are mandatory for all providers. For "Custom Provider" you will need to enter the Authorization URL and Token URL as well. You can find this information in your OAuth 2.0 identity provider panel.

note

If things go wrong while setting up the OAuth 2.0 connections, and you find yourself locked out of your site, use Bettermode dashboard to regain access.

OAuth 2.0 Authentication flow​

When a user selects the OAuth 2.0 login option, the following flow takes place:

  1. The user is redirected to the IdP authorization URL with the required parameters based on the adapter configuration and the user session.
  2. After authenticating with the IdP, user is redirected back to your Bettermode site with the tokens needed to complete the OAuth 2.0 flow.
  3. Bettermode calls the Token endpoint to validate the request and obtain an access token (and a refresh token, if scopes allow).
  4. If configured, the User Profile URL is called to fetch user information. Otherwise, claims from the ID token are used to construct the member properties.
  5. The member is created (or updated) with the acquired information and logged in.
note

If OAuth 2.0 is the only available authentication method, users will skip the default Bettermode authentication pages upon visiting and will be redirected to the authorization URL.

OAuth 2.0 Settings​

Client ID and Client Secret​

These credentials are provided and managed by the IdP. Consult your IdP documentation to locate these values.

Identity Provider URL / OAuth 2.0 Domain​

This URL is provided by the IdP. The value must match the ID token issuer claim.

Authorization URL and Token URL​

Provided by the IdP, these values are mandatory for the OAuth 2.0 workflow.

The Authorization URL is the user-facing endpoint that users are redirected to when they initiate authentication.

The Token URL is called server-side by Bettermode to validate the claims and the grants sent back via the callback URL during authentication.

warning

The ID token must have these claims or it will be deemed invalid and the authentication will be rejected: iss, sub, aud, exp, iat

User Profile URL​

If your OAuth 2.0 provider follows OpenID Connect standards, user information is included in the id_token JWT claims and no additional request is needed. Otherwise — if the id_token doesn't contain all required information (user ID, email, and name) — you'll need to provide a User Profile URL (a.ka. UserInfo endpoint) for Bettermode to fetch it.

Bettermode will send a GET request to this URL along with the access_token obtained from the token exchange step as the Bearer in the Authorization header. The response is expected to be in JSON format.

Authorization: Bearer {access_token}

Bettermode maps the JSON result to member properties as follows, in the respective order of the attributes. The attributes are case sensitive:

  • External ID:
    • id, sub, ID, nameid, nameID, externalId
    • Should be 50 characters or less
    • This property serves as the primary user identifier across systems and should be treated as immutable, even though changes may be processed in some cases.
  • Email:
    • email, user_email, emailAddress
    • Should be 200 characters or less.
  • Name:
    • name, display_name, full_name, fullName, displayName,
    • Compound fallbacks, {given_name} {family_name}, {first_name} {last_name}, {firstName} {lastName}
    • handle
    • If none matched, Username will be reused as the name. See below.
  • Username:
    • username, user_login, nickname
    • If none matched, then External ID will be reused.
  • Profile picture:
    • picture, icon_url, img_url, photo, photos[0].url or photos[0].value
  • Locale
    • locale, lang
  • Tagline
    • tagline

Space membership management through profile attributes​

In addition to member attributes, you can pass instructions with the user profile to manage user membership in spaces and groups.

  • spaceIds: An array of Bettermode space IDs the user should be added to as a regular member.
  • spaces: An array of objects with spaceId, role and action properties. See below.
  • spacesOperation: Can only be set to REPLACE. If provided, user will be removed from any space which isn’t listed in either spaces or spaceIds.

Example

{
  // ...other properties

  "spaceIds": ["space-id-1", "space-id-2"],

  // ...or if you want more control
  "spaces": [
    {
      "spaceId": "space-id-1",
      "role": "MEMBER", // Can be "ADMIN", or "MEMBER"
      "action": "JOIN", // Can be "JOIN" or "LEAVE"
    },
    {
      "spaceId": "space-id-2",
      "role": "ADMIN", // Can be "ADMIN", or "MEMBER"
      "action": "JOIN", // Can be "JOIN" or "LEAVE"
    },
  ]
}
warning

Avoid using both spaces and spaceIds in the same response.

Custom Fields​

Any other field that is included in the profile data will be processed as a potential custom field, matched against the externalKeys of the custom profile fields, configurable via the following path:

Administration > Profile Fields > {Your custom field} > Advanced Options > External Keys

The matching value in the profile data with a non-empty value will be used to populate the custom field.

Scopes​

Depending on the IdP you should set appropriate scopes, so that Bettermode can fetch the required information (such as email, name, picture, etc.) from the IdP. A typical value for the scopes would be "email,openid". These scopes will be passed along with the authorization request when redirecting user to the IdP.

Settings URL (a.k.a Account Settings URL)​

By default, your members can always change the email on their Bettermode account, regardless of their type of authentication. However, if your site has an external centralized user base, it is likely that they already have access to a different account management system. This will cause confusion for your members since they can update their information in two different places which aren’t actively synchronized.

You can prevent email updates through Bettermode account settings by setting the Settings URL value. If this value is provided, the user will be redirected to this URL when they attempt to edit their email. You can then choose to synchronize their Bettermode account through a custom backend via our APIs, use an automation platform like Zapier, or trigger a re-sync by invalidating their session in the IdP.

warning

If the external ID changes when the email is touched, a new user will be created instead of updating the existing user's email. As mentioned earlier, external ID should be treated as an immutable reference to the IdP user.

Logout URL​

If you want users to also be logged out of your identity provider when they log out of Bettermode, provide a Logout URL. After logout, Bettermode will redirect the user to this URL so you can end their IdP session.

Login Button Text​

This allows the OAuth 2.0 login button label to be customized. If left empty, the option will be hidden from the authentication forms.

Member matching and identification​

Bettermode matches users by External ID first, then by email. If the external ID matches an existing user, their email will be synchronized with ID profile, and vice-versa. As mentioned, we highly recommend treating external ID as the stable reference to avoid possible data inconsistencies.

Auto-redirect to and from the IdP​

As mentioned earlier, if OAuth 2.0 is the only available authentication option, users will be redirected to the authorization URL when they land on any authentication page. However, if your Bettermode site is public and you still want to trigger authentication in specific scenarios (like in embedded iframes), you can add ?auth=true to any link of your Bettermode website.

This will cause two consecutive redirects:

  1. From any page to Bettermode authentication page
  2. From Bettermode authentication page to the IdP authorization URL, since there’s only one authentication method

By default if users are already authenticated in the IdP, they’ll be redirected back to the original landing page that triggered the authentication flow (via two more transparent redirects), resuming their browsing session as intended.

However, if you want to make sure the IdP login screen is always shown, you can add a prompt parameter to the Authorization URL as described by the OpenID Connect specification. For example http://{AUTHORIZATION_URL}?prompt=login should force a re-authentication, and http://{AUTHORIZATION_URL}?prompt=select_account should allow users to choose between multiple active IdP sessions. Consult your IdP documentation for a full list of authorization options.