Single Sign On - Token Based Authentication

We also support Single Sign On using SAML, OAuth2, LDAP, SQL, and OpenID.

You can use the Single Sign On (SSO) API to automatically log your visitors into your forum. This can be helpful if you have a separate log in area on your website and you don't want to make your visitors log in twice.

The SSO API allows you to make an API request to get a log in token for a user and then include it in the forum address to log the user in.

Please follow the directions below to integrate the SSO API into your website:

1. Get your API key

2. Make a request for a log in token

   In the log in script for your website, make an HTTP Request to the SSO API log in URL:
   https://FORUM_DOMAIN/register/setauthtoken?type=json&apikey=APIKEY&user=USER
   Replace APIKEY with the API Key you retrieved in step 1.

   Replace USER with the username of the forum user you would like to log in. If your website doesn't use usernames, you can use an email address as the username.

   You can optionally include an &email=EMAIL parameter if you would like to have the forum account automatically created in cases where the specified forum account doesn't already exist. We recommend including the email parameter. (Replace EMAIL with the user's email address.)

   You can also optionally specify other account information, such as the user's full name ("name" parameter), avatar ("avatar" parameter), and more. Additional parameters must be URL encoded.

   If you are using PHP, we highly recommend using our PHP SSO Library. It contains one file with all of the library code you'll need and other files with example usage.

3. Get the token from the response

   Parse the JSON returned by the HTTP Request to get the authentication token and user ID and then store it in a cookie or your database. The authentication token expires in 6 months or immediately after it has been used to ensure a high level of security. The JSON response will look similar to this:

   {
     "authtoken": "88SngRVArwrsZ053lfrqL",
     "userid": 424764
   }
   

   If an error occurs, JSON similar to the JSON below will appear rather than the normal JSON response:

   {
      "message": "The error message will be here."
   }
   

4. Log the user in with the token

   Pass the authentication token in your forum's link on your website. For example:
   <a href="https://FORUM_DOMAIN/?authtoken=AUTHTOKEN&remember=REMEMBER">Forum</a>

   Replace AUTHTOKEN with the authentication token retrieved in the previous steps. Replace REMEMBER with 1 if you'd like to keep the user logged in even after the browser is closed or exclude it if you'd like the user to be logged out at the end of the browser session.

   If you're using the embed code, you can pass the authentication token to the page in which the forum is embedded or within the src attribute of the embed code. For example:

   <!--Begin Website Toolbox Forum Embed Code-->
   <div id="wtEmbedCode"><script type="text/javascript" id="embedded_forum" src="https://FORUM_DOMAIN/js/mb/embed.js?authtoken=AUTHTOKEN&remember=REMEMBER"></script> <noscript><a href="https://FORUM_DOMAIN">Forum</a></noscript></div>
   <!--End Website Toolbox Forum Embed Code-->

   Alternatively, if you don't want to pass the authentication token in the forum address, you can add the following HTML IMG tag to your "log in successful" landing page:

   <img src="//FORUM_DOMAIN/register/dologin?authtoken=AUTHTOKEN&remember=REMEMBER" border="0" width="1" height="1" alt="">

   Due to third-party cookies being blocked in the Safari browser, the IMG tag approach will not work in Safari unless your forum has been set up to use a subdomain.

5. Log the user out with the token

   After a user logs out of your website, redirect them to the following address to also log them out of the forum:

   https://FORUM_DOMAIN/register/logout?authtoken=AUTHTOKEN&redirect=REDIRECT_URL

   Replace REDIRECT_URL with the URL encoded website address where you'd like to send the user after they have been logged out of the forum. Replace AUTHTOKEN with the authentication token retrieved in the previous steps. When used for the purpose of logging out, a token is valid for 6 months even if it has already been used to log a user in. Once it is used to log a user out, the token expires immediately.

   Alternatively, if you would not like to redirect the user, you can add the following HTML IMG tag to the "log out successful" landing page on your website:

   <img src="//FORUM_DOMAIN/register/logout?authtoken=AUTHTOKEN" border="0" width="1" height="1" alt="">

   Due to third-party cookies being blocked in the Safari browser, the IMG tag approach will not work in Safari unless your forum has been set up to use a subdomain.

6. Make your forum use your website's log in page

   In the Settings -> Single Sign On section of your Website Toolbox account, specify the address of your website's Log in page to ensure that all forum log ins occur using your website's log in form.

   When we direct a user to your login page, we'll add a requestURI parameter to the URL. This parameter will carry the page path (e.g., /categories) from where the user originated. This way, after they log in, you can send them back to the same page.

7. Make your forum use your website's log out page

   Optionally, in the Settings -> Single Sign On section of your Website Toolbox account, specify the address of your website's Log out page to ensure that users are shown your website's log out page once they have been logged out of the forum.

Use a custom domain and our embed code, API and webhooks to set up even deeper integration.

If you still need help, please contact us.