OAuth2 is the recommended and more secure way of implementing SSO between your website and Tribe community. Tribe supports the most common implementations of OAuth2 including OpenID Connect.
To be able to use OAuth2 SSO method, your website or product should act as an OAuth2 identity provider. If you're using Okta or Auth0 as your user identity management system you can easily enable OAuth2 protocol since they support OAuth2 out of the box.
Most content management systems have plugins to support OAuth2 as well. For instance, you can use WP OAuth Server plugin to add OAuth2 support to your WordPress website.
To enable OAuth2 SSO on your Tribe, you can simply go to the Admin Panel and install OAuth2 SSO app. Before enabling the SSO, you should enter values for Client ID, Client Secret, Authorization URL, and Token URL. These fields are mandatory for enabling the OAuth2 SSO and are available in your identity management system control panel.
Bypass OAuth2 login
Use
<<community_url>>/login/direct
to skip OAuth2 workflow as an admin.
While setting OAuth2 settings you may enter some values incorrectly. Since OAuth2 takes over the login process, you may not be able to access your admin panel anymore to fix issues.
In this case, you can easily use <<community_url>>/login/direct
to access Tribe's regular login form.
OAuth2 Flow
When OAuth2 SSO app is enabled, Tribe will redirect user to your user identity system. If the user is not logged into your website, they will see your login screen. After logging in, Tribe will receive the access token generated by your user identity system and fetches the user's information.
Next, Tribe will create the user using the provided information and log them in if the user does not already exist. If the user exists, it will update the user's information and log them in.
Identifying User's Existence
Tribe will first try to find the user using the provided id
. It will check if any user has externalId
equal to provided id
. If the user is found, it will update their information including their email address.
If no user is found based on externalId == id
, it will try to find the user using the email
address provided and connects the user's externalId to the provided id
.
If a user with
externalId == id
check does not exist and the user matching with email already has anexternalId
, Tribe will through a conflict error.In this case, you may want to update existing users
externalId
or
OAuth2 App Settings
Now let's go through every single option available at Tribe OAuth2 SSO app.


Enabled
You can easily enable/disable OAuth2 authentication without deleting the app by checking/unchecking this checkbox.
Client ID and Client Secret
Both of these values are generated by your identity management system. They are the credentials that give Tribe access to act as an authentication client.
In Okta or Auth0 you can get these credentials by adding a new App. The Client ID and Secret will be available under the app settings.
Please make sure to set the callback URL as instructed at the bottom of OAuth2 app under your identity management system's Callback URL or Callback URI section.
Authorization URL and Token URL
OAuth2 protocol requires two URLs to work properly. These URLs are also provided by your identity management system.
For Okta, these URLs look like this:
Authorization URL: https://{YourOktaURL}/oauth2/v1/authorize
Token URL: https://YourOktaURL}/oauth2/v1/token
For Auth0, it should look like:
Authorization URL: https://{YourAuth0URL}/authorize
Token URL: https://{YourAuth0URL}/oauth/token
For other identity management systems, you should be able to find it in the app or account settings.
Sign Up URL
The Sign Up URL is where users are being redirected by clicking on the Sign Up button in the community.
After enabling SSO, when a user wants to sign up you don't want them to see Tribe's sign up page. Instead, the user should be redirected to your identity management system's sign up page.
Account Settings URL
Your community members can change their name and email inside Tribe by default. Most likely there is a section on your identity management system where users can change their name and email as well. This will cause confusion for your members since they can update their information in two different places and they're not synced by default.
For instance, "John Smith" can update their name in the community to "J Smith", unless you're using our Webhooks, API, and/or Zapier the name of this user on your identity management system is still "John Smith". In some cases, this might be the right behavior and you want to let members have a different name in the community since it's public-facing. But in many cases, you want the names to be synced and in this case, the best solution is to let them change their information only inside your identity management system.
To do so, you can just enter a link to your website's account setting URL. If this link is provided we won't let members change their name and email inside the community and instead they will see a link to your website's account setting. After they change their information you can use our API or Zapier to update their name right away in the community. Otherwise, their information will be updated the next time they login to Tribe.
Scope
Scope defines the user fields and the permission that Tribe should have access to. If you're not sure what it is, you can skip entering any value for it.
If your OAuth2 provider follows OpenID Connect standards, you can enter "email openid". This will let Tribe have access to user's email as well as their basic information.
Extra Query String
In some cases, you may want to add some query string parameters such as a fixed state when we redirect the user to the authorization or sign up URL. Most likely, you don't need to fill this field.
User Info URL
If your OAuth2 provider follows OpenID Connect standards, user's information will be included inside id_token
JWT and there will not be a need for Tribe to send another request to get user's information.
User object mapping for
id_token
JWT is explained under JWT Key section of this page.
However, if all the information needed (User's id, email, name) are not provided inside the id_token
or the OAuth2 provider does not follow OpenID Connect, you'll need to provide another URL for Tribe to fetch needed user's information. You can enter this URL in User Info URL textbox.
Tribe will send a GET request to this URL and expects the user's information in JSON format. The request includes the access token in the header according to bearer authentication:
Authorization: Bearer {AccessToken}
Tribe maps the JSON result to Tribe user's object as followed considering the order mentioned for each field:
- externalId: id, ID, userId
- email: email, user_email
- name: name, display_name, displayName, full_name, pseudo
- username: username, user_login, nickname
- gender: gender
- picture: picture, icon_url
- fields: fields (This is only available for enterprise clients with custom user fields)
If externalId is not available in the root JSON object, Tribe will also look for data
key for all keys mentioned above (e.g. data.id
, data.name
, etc.)
The above mapping covers most of the standard user info endpoints including WP OAuth Server. Custom mapping implementation is available for Enterprise clients.
Pass access token as query string
You may need to check this option if you're using WP OAuth Server for WordPress or serving PHP through php-fpm using the default configurations.
In some cases, you may not support Bearer Authentication on User Info URL. A good example is when you're using WP OAuth Server plugin for WordPress and you're serving PHP pages using php-fpm
(FastCGI Process Manager). In this case, the default configurations do not pass Authorization
headers to your PHP script (more on this here). The more secure solution is to change your .htaccess
or web server settings to pass the Authorization
header. If it's not possible, you can check the "Pass access token as query string" checkbox and we'll pass ?access_token={AccessToken}
as a query string while requesting the user's information.
Logout URL
When the user logs out of the community, most likely, you want them to be logged out of your identity management system as well. Otherwise, next time they click on the login button, after being redirected to your identity management system authorization URL, the user will be logged in to the community right away without asking for username and password because they're not logged out of the identity management system yet.
To fix this, you can provide a Logout URL. After the user is logged out of Tribe we're sending them to the URL provided and you can log them out of the identity management system as well.
Tribe also provides a logout URL. Redirecting user to
<<community_url>>/api/v1/logout?redirect={URLToRedirectAfterLogout}
will logout the user from the community and redirect them to the URL provided after?redirect=
.
JWT Key
If your OAuth2 provider supports OpenID Connect standard, the user's information should be passed as a JWT under id_token
key. In some cases, your authentication provider may return the JWT under another key name. You can provide the key name here.
Tribe maps the content of JWT to Tribe user's object as followed considering the order mentioned for each field:
- externalId: sub, email
- email: email, emailAddress (if not set, we will use
{sub}@{communityUrl}
) - name: name, displayName,
given_name + ' ' + family_name
,first_name + ' ' + last_name
,firstName + ' ' + lastName
, username, sub, email - username: username, nickname
- gender: gender
- picture: icon_url, picture
- updatedAt: updated_at
The above mapping covers most of the standard JWT values. Custom mapping implementation is available for Enterprise clients.
Verify State
Some OAuth2 providers send a random string as the state
and require both parties to verify this random string to prevent some security risks. You can check this checkbox if you want Tribe to verify the state.
Enable OAuth2 alongside Tribe authentication
You may want to use OAuth2 alongside Tribe's social login or Tribe's regular login (not recommended). By checking this checkbox, we will show a button pointing to your Single Sign-On provider, Social Login buttons, and Tribe's regular login next to each other. You can set the name of the SSO button under the SSO Button textbox.
An example is to provide LinkedIn and Twitter login alongside your SSO. You can achieve this by installing Social Login app, checking "Disable login with Email" under the Social Login app, and enabling this checkbox under OAuth2 app.
Updated 9 months ago