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

Single Sign On - Token Based Authentication

If you are using WordPress, use our WordPress plugin.

We can do it for you - Go to the Single Sign On settings and select your website builder to have our development team integrate SSO for you, starting at just $199.

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

  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.

    You can also use an email address as the username.

  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 Log in 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>

    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.

Important Notes:

  • 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 the URL below or you can generate a new authentication token.

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

  • You can also integrate your website's sign up process. More information...
  • The authentication token retrieved in step 3, when used for log in, expires in 30 days, when a new authentication token is generated, or immediately after it has been used to ensure a high level of security. The authentication token, when used for log out, only expires after a new authentication token has been generated.
  • 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.
  • Use our API to do all kinds of other integrations.


If you still need help, please contact us.