Help > Forum > Website Integration > Single Sign On - Token Based Authentication

Single Sign On - Token Based Authentication

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 send an HTTP request from within your application to log a user into or out of your forum. A token is returned by the API, which is then used in a small IMG tag on the next page to store the necessary browser cookies.

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

  1. 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.

    If you are using WordPress, we have a WordPress plugin that automatically integrates your log in and registration process.

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

    If all of this is too technical for you, our developers can setup Single Sign On integration on your website for just $149. Contact Us

  2. Get your API Key.
  3. In the log in script for your website, make an HTTP Request to the SSO API log in URL:

    https://USERNAME.websitetoolbox.com/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 login.

    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. You can also optionally include a &pw=PASSWORD parameter to set the account's password. (Replace EMAIL and PASSWORD with the email address and unencrypted/unhashed password of the user.) In cases where an account is created without a password, the user would not be able to log in directly to the forum unless they first reset their password on the log in page. SSO log in would work smoothly even without the user's account having a password.

  4. Parse the JSON returned by the HTTP Request to get the authentication token. The JSON response will look similar to this:

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

  5. On your website, add the following HTML IMG tag to your "log in successful" landing page:

    <img src="//USERNAME.websitetoolbox.com/register/dologin?authtoken=AUTHTOKEN" border="0" width="1" height="1" alt="">

    Replace AUTHTOKEN with the authentication token retrieved in step 3.

    The browser window that loads the IMG tag will be logged into the forum as the user with the username provided in step 2.

  6. On your website, add the following HTML IMG tag to your "log out successful" landing page:

    <img src="//USERNAME.websitetoolbox.com/register/logout?authtoken=AUTHTOKEN" border="0" width="1" height="1" alt="">

    Replace AUTHTOKEN with the authentication token retrieved in step 3.

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

  8. 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.

  9. Setup a subdomain for your forum. For example, https://forums.yourwebsite.com. This step is optional. However, the Safari browser ships with a conservative cookie policy which limits cookie writes to only the pages chosen ("navigated to") by the user. This prevents the forum's log in cookie from being set on the "log in successful" landing page. Therefore, the only way to make Single Sign On work on the Safari browser is to use a subdomain for your forum or also pass the authentication token in your forum's link on your website. For example:

    <a href="https://USERNAME.websitetoolbox.com/?authtoken=AUTHTOKEN">Forum</a>

Important Notes:

  • Need Help? Our developers can setup Single Sign On integration on your website for just $149. Contact Us
  • If you have purchased a managed domain name or you are using a custom domain name for your forum, use that domain name instead of "USERNAME.websitetoolbox.com".
  • USERNAME should be replaced by your Website Toolbox username.
  • A &userid=USERID parameter can be passed instead of the &user=USER parameter.
  • 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."
    }
    

  • If you need to log a user out and you do not have the authentication token that was returned during the HTTP request in step 2, you can retreive the authentication token by making an HTTP request to:

    https://USERNAME.websitetoolbox.com/register/getauthtoken?type=json&apikey=APIKEY&user=USER

  • You can also integrate your website's registration process. More information...
  • The authentication token retrieved in step 3 expires in 1 month, when a new authentication token is generated, or immediately after it has been used to ensure a high level of security.
  • Normally the user will be logged out at the end of the browser session. To keep the user logged in even after the browser is closed, add &remember=1 to the end of the URL in step 5 and 9.
  • The query string must be URL-encoded.


If you still need help, please contact us.