SSO Single Sign-On Developer Documentation (Token-Based SSO)

In this article, we will step through implementation of token-based Single Sign-On.

For SAML-based Single Sign-On see the following resources: Okta, Auth 0, and Microsoft 365. 

What is Single Sign-On?

In basic terms, Single Sign-On (SSO) allows users of your web site to log into your Forumbee community automatically, without needing to sign up and create another account.

Implementation of SSO on your web site requires technical development skills. This article is intended to give the information needed for a developer to implement SSO to Forumbee from your web site.

SSO Settings for Your Community

To use the SSO API, please contact support or your account manager to enable it for your account. (Requires the Enterprise plan.)

Once SSO is enabled you will find it in Admin → Settings → SSO.

Secret key

You will use this secret key later when you construct your URL to generate a SHA-1 hex digest.

NOTE: You should keep your secret key private and never publish it.

Handling direct community login/logout

Remote login URL

When you implement SSO you manage the login process for users into the community from your remote application. However it is still possible for a user to access your community directly, such as through a bookmark or a link in an email notification.

When a non-logged in user accesses your community directly, they will be prompted to login.

To transfer control of the login to your remote application, specify a remote login URL. When prompted to login or sign up, the user will be redirected to the URL you specify. This should be a URL in your remote system that allows the user to login or sign up and then passes them back to your community via SSO.

If you have a private community and a non-logged-in user requests a page, the page URL is passed as a parameter on your remote login URL, for example:

https://company.com/login?url=https%3A%2F%2Fmycommunity.forumbee.com%2Fcategory%2Fdiscussions

When constructing your SSO link, you can pass this page URL into the SSO redirect parameter to send the user to their requested page.

Remote log out URL

When the user clicks log out in the community they will be sent to the URL you specify. Typically this would be a URL that also logs the user out of your remote system. The user key is passed (Base64 and URL encoded) on the Remote log out URL as a convenience for you to track the user.

Direct login option

Your remote login URL replaces the standard Forumbee login page. If you still need to login through the Forumbee login page after you set your remote login URL, use the direct login page. Access the direct login page by appending “/login/direct” to your community domain URL:

https://mysubdomain.forumbee.com/login/direct

SSO Implementation Instructions

From your remote application construct a unique URL login link for the user that includes a Base64-encoded JSON object containing user fields as shown below and a message digest ensuring the validity of the data. Use this URL to redirect the user to the community or to present a navigation link to the user.

SSO login URL structure: 

https://mysubdomain.forumbee.com/sso/1/login?digest={ }&data={ }

During your implementation, use the SSO Developer Tool described below for documentation and testing.

SSO Parameters

Custom Profile Fields

Custom profile fields are available as SSO parameters. The SSO parameter name is _fieldname where fieldname is the custom profile field name. Note that custom profile fields must be enabled for your community before they can be used in SSO. Contact your account manager or support@forumbee.com for more information.

Steps to create the login URL token

1. Construct a JSON object containing the following:

1. Your Forumbee sub-domain
2. URI (/sso/1/login)
3. Date in milliseconds since 1970 UTC
4. SSO parameters from above.

All parameters should be passed as quoted strings. Example:

{"domain":"mysubdomain","uri":"/sso/1/login","date":"1373854115780",
 "email":"hank@forumbee.org","name":"Hank Manning","role":"0","key":"100"}

2. Base64 encode the result of step 1.

3. Compute a SHA-1 hex digest by combining your SSO secret key and the Base64 result from step 2.

4. Convert the digest from step 3 and the Base64 data from step 2 into URL Encoded parameters.

5. Construct the final URL with the digest and data from step 4 as query parameters.

URL structure:

https://{mysubdomain.forumbee.com}/sso/1/login?digest={ }&data={ }

If you are using domain aliasing, replace {mysubdomain.forumbee.com} with your domain alias. Example: 

https://{your-domain-alias}/sso/1/login?digest={ }&data={ }

Using the SSO Developer Tool

During your implementation, use the SSO Developer Tool for documentation and testing.

Navigate to the Admin area → Settings → SSO, and click SSO Developer Tool.

 Create SSO URL

1. To create an actual working SSO URL, enter test data in the fields and click Create.
2. This returns the SSO login URL. Copy and paste this SSO link into a different browser to try it out. If you paste it in the current browser you are using, you will be logged out of your current session and logged in as the SSO user.
3. Click the Show Steps button to reveal the steps to create the URL. Each step in the process is documented and output is shown.

Validate SSO URL

To test whether your SSO URLs are constructed properly, use the Validator.

1. In the SSO Developer Tool, click Validate SSO URL.
      
2. Paste the SSO URL and click Validate.
   
3. The URL will be evaluated and a descriptive status will be returned. Source parameters will be deconstructed in JSON format.
      

User account creation and updates

When a user clicks through on your SSO link, Forumbee will look for the user in the community based on their SSO key or email. If no matching user is found, SSO will create a new user with the SSO parameters provided. If a matching user is found, by default SSO will not update existing values for name, user-uploaded avatar, or tagline. If avatar or tagline were previously blank, or if the avatar was previously set by SSO, they will be updated by SSO.

Example scenario 1:

Janet previously joined the community, uploaded her avatar and created her tagline. Later she logs in with SSO. Her existing name, avatar and tagline will not be updated by SSO by default. This ensures that the edits she made to her profile are not lost when she logs in again with SSO.

Example scenario 2:

Ross previously joined the community, but did not upload an avatar or set a tagline. Later he logs in with an SSO link that includes values for the avatar and tagline parameters. His profile is updated with the avatar and tagline passed by SSO.

Overwrite Parameter

If the SSO overwrite parameter is set to 1, it will update the user name, avatar and tagline with the values provided. It is a best practice to only use this parameter in cases where you need to reset a member.

• If no avatar is provided, it will revert the user avatar to the original setting. The original setting is Gravatar or the Forumbee avatar if the user originally established their account with an avatar prior to SSO login.
• If no tagline is provided, it will reset the user’s tagline to blank.

User roles

One of the following roles can be assigned to a user with the SSO role parameter.

Normal

This is the member role and is the default if no role is specified. Permissions:

• Access all unrestricted categories (forums.)
• Access restricted categories (forums) when granted access via SSO link.
• Add topics (if allowed in forum settings.)
• Post replies to topics.

Moderator

Permissions include all member capabilities plus:

• Monitor the community activity stream.
• Receive the community moderator report email.
• Edit/remove postings.
• Manage the community moderation queue.
• View and invite members.
• Suspend or block members.

Category Moderator

Category moderators are members with additional abilities for categories to which they are assigned as a moderator:

• Monitor category activity stream.
• Receive the moderator report email for that category.
• Edit/remove postings in that category.
• Manage the moderation queue for that category.

To assign a category moderator through SSO, set role to 1 and list the categories in the forums parameter. The user will be assigned as a category moderator to all listed categories.

SSO Code Example

Example SSO code example in C#:

https://github.com/Forumbee/forumbee-sso/blob/master/csharp.cs