Single Sign On
Single Sign On (SSO) is a way of connecting an existing website to your Plush forum, so users don't have to sign up or log in twice. This feature is available on our Medium plan or higher. It's a completely seamless implementation, with no extra steps for your end user.
To use SSO, you'll either need a developer or know how to code.
How it works
Basically, Plush 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, Plush validates this response and logs the user in to the forum, creating an account if necessary. If the user is not logged in to your site, they are sent to your login page.
Initial setup
Go to the Registration section of your dashboard and switch the registration mode to "Connect". We'll generate a "Secret Key" for you, which will be used to secure your SSO requests. Don't reveal this key to anyone. Note that the key will change if you disable and re-enable SSO.
You'll see three other boxes you need to fill in with details about your website. "Authentication URL" is an endpoint you or your developer will need to create, to respond to user authentication requests.
"Sign In URL" is the link to your site's login page and "Registration URL" should be your site's registration page. Plush will send users to these locations when necessary.
Authentication request
When a user attempts to sign in to Plush, we'll make a JSONP request (from the user's browser) to your Authentication URL, with three parameters:
• signature: an SHA256 hash of the user's IP address, the current UNIX timestamp and your Secret Key, concatenated in that order.
• timestamp: the current UNIX timestamp.
• callback: the name of the callback function you'll need when constructing your response.
Authentication response
First you need to verify the request, to make sure it came from Plush. Construct your own SHA256 hash of the requesting IP address, the provided timestamp and your Secret Key, concatenated in that order. If the hash matches the signature provided, the request is valid.
Now you'll need to use your site's session logic to fetch details about the logged-in user, then return them as a JSONP response. Here's an example:
callback({
"email":"[email protected]",
"name":"Phil Parkinson",
"photourl":"http:\/\/bwfc.co.uk\/avatars\/user4.jpg",
"roles":[
"Moderator",
"Wanderer"
],
"timestamp":"1525602444",
"uniqueid":4,
"signature":"a47b6aed44287cb7f5317d2d1c20892f264129f67358d6ecd199988115efe3b8",
"rolesync":true,
"meta":{
"Location":"Bolton",
"Website":"bwfc.co.uk",
"Job Title":"Manager"
}
});• callback: function name, as provided in the authentication request (required).
• email: a unique, validated email address (required).
• name: a unique username (required). If you send duplicate names, we'll create the account by appending numbers to the name.
• roles: an array of roles to assign (optional).
• photourl: link to the user's avatar image (optional).
• timestamp: as provided in the authentication request (required).
• uniqueid: unique user identifier from your system (required).
• signature: an SHA256 hash of the requesting IP address, user uniqueid, user email, the provided timestamp and your Secret Key, concatenated in that order (required).
• rolesync: boolean indicating whether you want roles to be synchronized at subsequent logins (optional).
• meta: an associative array of user information, with keys corresponding to member profile fields you've created in Plush (optional).
If the user is not logged in to your site, return an empty array. We'll then redirect the user to your login or registration page as appropriate. We'll include a "redirect_to" parameter, which is where you should send the user after they've logged in or signed up. This will ensure they're logged in to the forum automatically.
Account synchronization
The user's email address, avatar, metadata and (optionally) roles are synchronized at each forum login. If a user subsequently uploads a new avatar to the forum directly, this will not be overridden.
To keep user information up to date, make a POST request to "www.yourforum.com/entry/sso" (using your forum's domain, of course) with the same parameters as the JSONP example above. Use the originating server's IP address and current UNIX timestamp to generate the signature.
Division of labour
When deploying SSO, we're here to help if something breaks on our end. But the work required on your side is solely your responsibility. Changes or additions to your codebase are beyond our remit. SSO is a complex feature that requires considerable technical experience to implement. If you're unsure, just use the built-in Plush login system.
Troubleshooting
If you lose access to your Plush forum, you can log in with your password at "www.yourforum.com/entry/signin/password". If an SSO login fails with an "Error" message, you can check the Javascript console to see an error code:
• disabled: Connect registration mode is not enabled.
• missing: signature or timestamp is missing from your response.
• signature: signature could not be validated.
• time: the timestamp is stale.
• replay: this request has already been handled.
• banned: user has been banned or deleted from the forum.
• user: Plush error while creating new user.
Use these codes to troubleshoot your request handling. If the error is "user", contact us with the details and we'll investigate.
Security
This is important. Plush implicitly trusts email addresses you provide. Please make sure you validate email addresses on your side before using SSO.
We strongly recommend that when using SSO, both sites (Plush and yours) have SSL enabled. SSL for Plush can be enabled in the Security section of your dashboard.
That said, if you can't use SSL on your site for whatever reason, Plush's SSO implementation should still be secure. Each authentication response is tied to a particular IP, can only be used once and is only valid for 10 seconds. Just keep the Secret Key secret and you'll be OK. But if you can, use SSL.