Single Sign-On (SSO) Developer Documentation

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.

TIP:

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

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.

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

 

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:

http://{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

10replies Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
  • 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.)

    Reply Like
  • 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.

    Reply Like
    • 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!

      Reply Like
  • 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?

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

      Reply Like
      • Ilan Perez
      • Ilan_Perez
      • 8 mths 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.

      Reply Like
    • 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. 

      Reply Like
  • 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.

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

      Reply Like
Like1 Follow
  • 1 Likes
  • 2 mths agoLast active
  • 10Replies
  • 2378Views
  • 5 Following