Single Sign-On

Single Sign-On (SSO) is a way of connecting an existing website to your forum, so users don't have to sign up or log in twice. This feature is available on our Standard plan or higher.

To use SSO, you'll either need a developer or know how to code.

How it works

Instaforum sends a secure request to your site. Your site validates this request and, if the user is logged in, responds with a set of credentials. In turn, Instaforum validates this response and logs the user in to the forum, creating an account if necessary.

Initial setup

Go to the "Access" section of your dashboard and check the "Enable SSO" box. Then click the "refresh" icon to generate a "Secret", which will be used to secure your SSO requests. Don't reveal this to anyone.

You'll see one more box called "Endpoint". This is a URL you or your developer create, to respond to authentication requests. Once you know the URL, enter it and hit "Save".

Authentication request

When a user attempts to sign in to Instaforum, we'll redirect them to your Endpoint, with two query parameters added:

token: a single-use secure token, valid for 15 minutes.

sig: HMAC-SHA256 hash of the token using your Secret as the key.

You need to verify this request, to make sure it came from Instaforum. Construct your own HMAC-SHA256 hash of the token using your Secret as the key. If the hash matches the signature ("sig") provided, the request is valid.

Authentication response

Now you'll need to use your site's session logic to fetch details about the logged-in user.

If the user is not logged in, first redirect them to your login page, then to https://yourforum.com/sso once they're logged in. This will initiate a new SSO request.

Otherwise, generate a JSON string with the following keys and values:

token: token from the original request. (string, required)

user_id: unique user identifier from your system. (integer/string, required)

email: user's unique, validated email address. (string, required)

name: unique name of the user. (string, required)

image: HTTPS URL of user's avatar. (string, optional)

bio: user's bio. (string, optional)

roles: array of roles to assign. (array of strings, optional)

banned: revoke forum access during sync. (boolean, optional, see below)

Building your response

Now you need to generate a URL that includes an encoded version of this data, plus a signature for verification. The final URL should take the form:

https://yourforum.com/sso?data={data}&sig={sig}

Where {data} is your JSON string, Base64-encoded, then URL-encoded.

And {sig} is the HMAC-SHA256 hash of {data} using your Secret as the key.

Finally, redirect the user to the URL you've generated. Instaforum will validate the request and log the user in, creating an account if necessary.

Account synchronization

To keep user information up to date, make a POST request to https://yourforum.com/sso/sync with the same query parameters and encoding described above. The only difference is there is no token to include in the JSON string. Besides the user_id, you only need to include the fields you wish to update.

Revoking forum access

You may wish to revoke forum access to a user, if they unsubscribe from your service or leave your organisation, for example. Simply follow the sync procedure described above, but include the banned field set to true.

Troubleshooting

If you lose access to your forum, you can always log in with your email address at https://yourforum.com/login. If the SSO handshake fails at any stage, a relevant error message should indicate where the problem lies.