Single Sign-On overview
Single sign-on (SSO) is how to let your users sign on to a third-party system (like a Vanilla Forum) without needing a separate username and password.
In broad terms, an SSO solution defines how two systems securely communicate the identity of a user that is switching between them. In the context of Vanilla, that means the forum securely talking to your site or identity provider to see if a user is signed in, and then automatically using that identity.
Solutions we offer
Vanilla offers three flavors of single sign-on:
- SAML (cloud-only)
- OAuth 2
- jsConnect (our in-house solution)
We also offer:
- Social SSO (Twitter, Facebook, and more).
- Third-party service integration (e.g. Auth0; cloud-only).
- Custom SSO integrations (cloud-only).
All flavors and types of SSO follow general rules in Vanilla, many of which are outlined below.
General principles
Regardless of your type of SSO, the following principles/recommendations apply to how it is handled by Vanilla:
- Since you are the provider, make sure that the information you pass through SSO is already validated. Email addresses, for example, should be already confirmed on your side before a user is allowed to connect through SSO.
- It is strongly recommended you do not create users over the API. The fault-tolerant way to map users to your forum is to always let them be asynchronously created as they login.
Account connection
When a user logs in through SSO for the first time, a connection is made using the SSO UniqueID and Vanilla UserID. The connection between the two IDs is permanent for that connection. If the user changes their email address after the first connection it won’t causes any problem.
Generally, two things can happen when that connection is being made:
- All the required information is correctly passed through SSO and no matching Vanilla user is found.
- This will result in a brand new user created on the forum.
- Some required information is missing or some information matches an existing user account on the forum.
- The user will be redirected to a page where he will have to either:
- Fill out the missing information.
- Manually connect to an existing forum account by specifying the password of that account. This ensures the user owns the forum’s account.
- Create a new account with a username/email that does not conflict with an existing forum account.
Omitting one required field, for example username (often ‘name’), will prompt the user to fill in the information.
AutoConnect
AutoConnect is a feature that uses email addresses to automatically connect an account in the Account connection process. When this feature is enabled, and the email passed through SSO matches the email of a user account on the forum, the connection between the SSO UniqueID and Vanilla UserID is made right away without the user having to go through confirming ownership over an existing account.
For security reasons it must be opted into. Email addresses must be validated on your side when using this feature..
Vanilla only connects existing accounts by matching email address. No exceptions.
Redirection
Most SSO solutions honor this behavior.
When tightening your SSO configurations to redirect users automatically after the sign-in process, you can use {target} in the redirect URL. Vanilla will replace {target} with the page the user is currently on when generating the URL.
Example (using jsConnect): https://sso.example.com/jsconnect/signin?redirect={target} would become something like https://sso.example.com/jsconnect/signin?redirect=/discussions
Logging users out
Log out initiated from the community
We recommend using the default logout approach, which is generally accomplished by
- Setting a default connection ( having your SSO connection as the only method for connecting users to the community), and
- Including in its config your site’s signout URL.
After a user clicks “Sign Out” on Vanilla, we will log them out of the community and then redirect them to your logout page.
Log out initiated from your site
You may want to ensure that when someone logs out from your site that the be logged out of the community automatically. There are several ways to make this happen, but they require having a shared domain (or subdomain) and modifying your Cookie Domain.
By shared domain we mean that if your site is thisismysite.com then you would set your community Custom Domain as community.thisismysite.com . Because they share the same domain you can now set the Cookie Domain on the community as *.thisismysite.com . (Modifying the Cookie Domain requires the assistance of the Vanilla Support Team.) Now when the user is on thisismysite.com you can read and/or delete cookies that were set on community.thisismysite.com .
Now you have two ways of logging users out from your site.
- When the user clicks on your Sign Out you can sign them out and then redirect them to the community Sign Out with the TransientKey which is stored in their cookies and the Target which is the url encoded final destination where you would like the user to end up after being logged out, for example: https://community.thisismysite.com/entry/signout?TransientKey=59WaY3nFTSHLiDWN%3A33%3A1585763045%3Abfb7f6e3cd8dda34095a441dcba52f1f&Target=https%3A%2F%2Fthisismysite.com%2Fthank-you-come-again . The Target URL must be put in the Trusted Domains section of the Security page in your Dashboard.
- When the user clicks on your Sign Out, as part of your session ending routine you can delete all the cookies vanilla generated cookies.
To know more about Vanilla's cookies, how they are named and what they do, please see this article.