Skip to main content

JWT SSO

Although OAuth2 is the most recommended way of authenticating your members to community, JWT SSO is the easiest way if your website does not support OAuth2. You should be able to implement it by adding a few lines of code to your website or product.

note

JWT SSO is usually the preferred method when you want to embed your community in your product, marketing website, or phone app using IFrame or WebView.

In this method, you'll sign a JSON Web Token (JWT) with User's information using a private key. Then the generated token should be passed as token in the query string to Tribe.

To generate the JWT token, first you need to get your Single Sign-On private key. Login to your community as an Admin. In the Administration page under Authentication, enable the "JWT SSO" and you should find the Single Sign-On private key there.

Next, you should first install a JWT library:

npm install --save jsonwebtoken

Then use the following source code and the SSO private key inside the Tribe "JWT SSO" section in Administration page, to generate the JWT token:

const jwt = require("jsonwebtoken");
const privateKey = "{Your Private Key}";
function createToken(user) {
const userData = {
sub: user.id, // user's ID in your product
email: user.email,
name: user.name,
tagline: user.tagline, // optional
iat: Math.round(new Date().getTime() / 1000), // token issue time
exp: Math.round(new Date().getTime() / 1000) + 60, // token expiration time
};
return jwt.sign(userData, privateKey, { algorithm: "HS256" });
}

Finally, you should pass the generated JWT token to Tribe as followed:

https://YOUR_COMMUNITY_DOMAIN/api/auth/sso?jwt=[Generated SSO Token]&redirect_uri=/

If the user does not already exist, Tribe will create the user using the provided information in the JWT and log them in. If the user exists, it will update user's information and log them in.

You can set an optional redirect_uri query string. If the redirect_uri is set, user will be redirected to that URL, otherwise, we'll invite the user to community home page.

note

To prevent open redirect attack, your redirect_uri can only be a relative path starting with / (e.g. /settings/account).

Identifying user's existence#

Tribe will first try to find the user using sub. If the user is found, it will update their information including their email address.

If no user is found based on sub, it will try to find the user using the email address provided.

Embedding Tribe pages#

One of the most common use-cases of JWT SSO is seamlessly embedding your community or part of it into your product, marketing website, or mobile app.

To do so, you will need to generate the JWT SSO url by following the above instruction and use it as the <iframe> or WebView source. Here is an example for embedding the General space using an <iframe> tag:

<iframe
src="https://YOUR_COMMUNITY_DOMAIN/api/auth/sso?jwt=[Generated SSO Token]&redirect_uri=/general"
frameBorder="0"
width="100%">
</iframe>
note

Embedding your community in an IFrame or Webview is only available on Enterpriste plan.

Supported JWT keys#

Tribe JWT SSO supports standard JWT fields. Here you can find all fields supported in the JWT:

  • sub (required): The ID of the user in your product or platform. This value will be stored as externalId on Tribe.
  • name (required): The name of the user.
  • email (required): The email of the user. This email address is considered as a verified address. You should make sure you've verified it on your side.
  • tagline: The short bio of the user in plain text format.
  • iat: The issue time of the JWT.
  • exp: The expiration time of the JWT. Although this value is not required, it's highly recommended to set it to 60 seconds from now. If it's not set, the token will be valid forever and can introduce security issues.

Supported Plans#

Authenticating your members using the JWT SSO method is available on the Premium and Enterprise plans. The ability to embed your Tribe community in an IFrame or Webview is only available on Enterpriste plan.