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 an externalId, Tribe will through a conflict error.

In this case, you may want to update existing users externalId or email using "Update a Specific User" API.

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.