1

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

Parameter

Description

Required

Char length

email

User email (must be unique)

Yes

7-128

name

Display name for the user

Yes

2-128

domain

Your Forumbee subdomain or domain alias.

Yes

3-50

uri

The SSO login point: /sso/1/login

Yes

2-50

date

The current date/time in milliseconds since 1970 UTC. The system expects the date/time to be in the past but within 24 hours. (The link expires after 24 hours.)

Yes

13-20

key

Unique member key from your remote system.

It is good practice to use this if you need the ability to make updates to the user email at a later time.

No

1-128

avatar

URL to the avatar picture for the user

No

0-256

tagline

Job title or tagline for the user

No

0-128

role

Access role types:

0 normal (default)

1 moderator

Best practice: Do not to pass the role parameter unless you are assigning the moderator role or downgrading a moderator to a member.

See User Roles section below for more details on roles.

No

 

labelId

Assign a user label (badge) 1 through 10. This maps to the user labels defined in Admin Settings.

No

0-10

forums

Comma separated list of private categories and/or groups to grant access.

Specify categories using the category link. Use the final portion of the category URL, in this example discussions:

http://{your-domain}/category/discussions

Specify groups using the group ID. Go to Users → Groups and select the group. Use code at the end of the URL, in this example f8mkt:

https://{your-domain}/admin/group/settings/f8mkt

To revoke access to a category or group, prefix the category or group ID with the ! character. For example:

!private-discussions

No

0-256

redirect

Destination URL to send the user after successful login.  

When not specified the user is sent to the community home.

No

0-256

overwrite

By default, only blank fields will be updated. Pass a value of 1 to force an overwrite. (Applies to name, avatar and tagline.)

No

 

 

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

10 replies

null
    • Sr. Director of Marketing
    • Ajay_Parikh
    • 6 yrs ago
    • Reported - view

    We're going to have a private Forumbee community. Most of our users' accounts will be initially created via SSO when they click through our software to Forumbee.

    If a user decides to go to the community via a direct URL, they will be prompted to enter their username and password. Since they do not know their password, how can the user access the site?

    Also, if they attempt to create a new user account but use the same email address that is associated with their account created via SSO, will the system create a 2nd user account or merge the 2 accounts together based on the email address?

    (Trying to make sure we understand so that we can train our users appropriately from the start.)

    • Autumn_Spehar
    • 6 yrs ago
    • Reported - view

    I tried following the instruction to turn on SSO and do not see the option. Does SSO functionality need to be turned on by forumbee before I can see it in the settings area?

    Specifically, I am following the steps below and do not see "SSO" under settings in the Admin area.

    To enable SSO, navigate to the Admin area ⇒ Settings ⇒ SSO, check “Enable SSO” then click Save.

      • Forumbee
      • 6 yrs ago
      • Reported - view

      Hi Autumn , thanks for your question! SSO is now enabled for your account. Let us know if we can help with any other SSO questions. Thanks!

    • Ilan_Perez
    • 6 yrs ago
    • Reported - view

    SSO looks great however we require that an account is created in our instance when the user creates an account in our framework.

    Is there an api to do such a thing?

      • Forumbee
      • 6 yrs ago
      • Reported - view

      Hi Ilan, you should be able to make a server side call to the same SSO link to create the user at any time.

      • Ilan_Perez
      • 6 yrs ago
      • Reported - view

      Forumbee Support sorry I should have looked at the whole SSO document :)

      What I don't get is how I set the password for the user. We want to be the same password as the one created on our end.

      • Forumbee
      • 6 yrs ago
      • Reported - view

      Hi Ilan , we don't support sending passwords directly. Instead, the typical pattern for this is to provide the SSO link to the user at the time they access the community so that they do not have to log in again. You would use this in conjunction with the remote login link that points to your login handler. This means that if the user accesses the community directly and clicks 'Login' they will be routed to your login page. 

    • Mark_Ricard
    • 5 yrs ago
    • Reported - view

    Can you provide a link to documentation that works?   I found documentation, but the screens have changed and it does not work.   There are no SSO settings under Settings->Account that I can see.

      • Forumbee
      • 5 yrs ago
      • Reported - view

      Hi  Mark , thank you for your post! The SSO feature is now enabled for your account, and you will find it under Settings -> Account.