Add VanillaConnect documentation

content/help/sso/vanillaconnect/index.md

@@ -0,0 +1,117 @@
+---
+title: VanillaConnect
+tags:
+- Features
+- Single Sign-On
+- VanillaConnect
+category: help
+menu:
+  help:
+    parent: sso
+    identifier: sso-vanillaconnect
+aliases:
+- /features/sso/vanillaconnect
+---
+
+## Why VanillaConnect?
+
+Much simple than, for example, SAML or OAuth VanillaConnect is perfect for small-to-medium business owners.
+
+However, even if simpler, VanillaConnect still requires a developer on your team. 
+Setting it up usually require between 2 to 6 hours using our [technical documentation](/help/sso/vanillaconnect/technical).
+
+## VanillaConnect Concepts Overview
+
+Our SSO solution has a few basic assumptions:
+
+* Your user is signed into a **website** AKA **provider**.
+* **You** control this website and can add files & pages to it.
+* Your user have a **unique identifier**. This can be a number or a randomly generated string.
+What is important is that no users can have the same **unique identifier** and that identifier will never change.
+
+The integration will be a lot easier and tighter if:
+
+* You have unique, validated **usernames** for users.
+* You have confirmed, unique **email addresses** for users.
+
+## Creating & mapping users
+
+Data that can currently be passed over SSO with VanillaConnect:
+
+* id: The **unique identifier** of the user on your system (*required*)
+* email: The email address of the user (*required*)
+* name: The name of the user (*recommended*)
+* photourl: The URL of the photo/avatar of the user.
+* roles: A comma separated list of Vanilla's roles name.
+
+When receiving an SSO response, Vanilla will do a lookup by **email address** against the forum database.
+If it finds a match and the user connects, a **permanent mapping** is made against the unique ID your provided.
+This means future email changes on your side do not affect the login process.
+
+If no email match is found, a new forum account will be created instantly using the provided data.
+If no username is provided, the user will be prompted to create one.
+
+Data is synced at every new login. 
+For instance, providing a different email address on the user's fifth login will still log them into the same account,
+but will update their Vanilla email address.
+
+The Photo URL is accepted only if the user has not uploaded their own avatar in the forum yet, and it is a valid URL.
+Imported avatars (if you migrated to Vanilla from another platform) count as the user having uploaded their own avatar.
+
+**We recommend against creating new users via the API.** 
+Our SSO solution lazy-creates new users for maximum robustness and reliability.
+Creating users manually may potentially cause problems with out auto mapping process.
+Once a new user is created, you can optionally sync additional data about the user over API as needed.
+
+## Unified user experience
+
+In Vanilla, these optional configuration changes are possible:
+
+* Auto-connect to existing forum user accounts without prompting for a password (i.e. your SSO source is 100% trusted).
+* Disable all email sending in Vanilla.
+* Disable profile editing.
+* Redirect user profile links to another system.
+
+Cloud users can contact support to make these changes.
+
+## How it connects
+
+Clicking the "Sign In" button in Vanilla redirects the user to the **provider** which 
+will validate the authentication request and redirect back to vanilla with an authentication response.
+From there, the user will be either:
+
+- Signed In.
+- Asked to provide missing information to complete the Sign In process.
+- Displayed an error message if something went wrong. (*This should not be happening under normal circumstances*)
+
+More information on our [technical documentation](/help/sso/vanillaconnect/technical).
+
+## Two Flavors of SSO
+
+There are two implementations of SSO that VanillaConnect supports. 
+You can implement either of the methods or both as they serve different purposes.
+
+### Method 1: Site-Wide SSO
+
+You implement site-wide SSO when Vanilla is as a full site.
+With this method you need to use our VanillaConnect library to process the Authentication Request JWT and
+reply with an Authentication Response JWT.
+
+### Method 2: Embedded SSO
+
+Vanilla also has the ability to be embedded in a page either as an entire site or just as embedded comments. 
+With this scenario you need to create a special SSO string that can be passed to the embedded Vanilla 
+and provide login information.
+
+This effectively skip the authentication request and do an authentication response directly.
+By doing so you Push 
+
+Again, refer to the [technical documentation](/help/sso/vanillaconnect/technical) for more details.
+
+## Make it seamless
+
+When setting up a jsConnect connection in full-site mode, you have the option to specify it as your "default" connection.
+Doing this attaches it to the special `/sso` endpoint in Vanilla. 
+When a user clicks "Forum" in your website's navigation, instead of linking to the forum homepage, 
+instead link them to the `/sso` page. This will auto-fire the SignIn process rather than waiting for the user to click "sign in", 
+then drops them on the homepage as normal.

content/help/sso/vanillaconnect/technical.md

@@ -0,0 +1,65 @@
+---
+title: Technical Overview
+tags:
+- Features
+- Single Sign-On
+- VanillaConnect
+category: help
+menu:
+  help:
+    parent: sso-vanillaconnect
+    identifier: vanillaconnect-technical
+    weight: 100
+aliases:
+- /features/sso/vanillaconnect/technical
+---
+
+## VanillaConnect technical documentation
+
+To integrate VanillaConnect to your website you will need the [Library](https://github.com/vanilla/vanilla-connect-php).
+The in-depth details required to successfully implement VanillaConnect are located on the library repository.
+
+### Configuration of the addon
+
+The configuration interface is pretty neat and self explanatory but here are a few things you might want to know:
+
+- If you put `{target}` in an URL that will be replaced by the page from where the user tried to Sign In.
+So for example if the user clicks "Sign In" from a discussion he will be redirect to that discussion after being Signed In. 
+- If you set your connection as "trusted" it will also enable the auto-connect feature even if it is not enable globally.
+
+### Workflow
+
+#### Site-Wide SSO
+
+![VanillaConnect workflow](/img/help/features/sso/vanillaconnect-workflow.svg)
+
+1. Vanilla -> Provider: Redirect With Authentication Request JWT. 
+
+    This step occur when a user click the Sign In button.
+    (Or when someone go on https://yourforum.example.com/sso if the connection is set as the default connection)
+
+    - A. Provider -> Provider: Sign In User.
+
+        This step is only necessary if the user is not already Signed In on your website.
+        When that's the case you need to 
+        - Preserve the JSON Web Token (JWT) that was sent during step 1
+        - Allow the user to Sign In on your website
+        - Process the JWT token
+        - Continue with step 2.
+
+2. Provider -> Vanilla: Redirect With Authentication Request JWT
+
+    In this step you have constructed, with the user information, the redirect URL that contains the
+    Authentication Response JWT. All you need to do is to do a redirect to that URL.
+
+#### Embed SSO
+
+![VanillaConnect embed workflow](/img/help/features/sso/vanillaconnect-embed-workflow.svg)
+
+1. Provider -> Vanilla: Push SSO JWT.
+
+    Using the [Library](https://github.com/vanilla/vanilla-connect-php) to create a PushSSOJWT you then pass it
+    in the embed parameters like so: `vc_sso={JWT}`
+
+2. Vanilla will check the validity of the JWT and process it. It will then redirect on itself with the user 
+signed in if everything went right.

static/img/help/features/sso/vanillaconnect-embed-workflow.xml

@@ -0,0 +1 @@
+<mxfile userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.89 Safari/537.36" version="7.7.1" editor="www.draw.io"><diagram id="9d00dd8e-621e-7664-87b1-c47271120b53" name="Page-1">5VnbctowEP0aP4axJNvAY0ySXmY6ZYZO0z4qtjBqjMUIc8vXV8KSL5JdCCElbfAM2LvSStpzdrUyDhrNtx84Xsy+sJikDnTjrYNuHAiBO/DEj5TsCknfB4Ug4TRWjSrBhD4R3VNJVzQmy0bDnLE0p4umMGJZRqK8IcOcs02z2ZSlzVEXOCGWYBLh1Jbe0zifFdKB71byj4QmMz0ycJXmAUePCWerTI3nQDTdfwr1HGtbqv1yhmO2qYnQrYNGnLG8uJtvRySVvtVuK/rddWjLeXOS5cd0gEWHNU5XaunfcUbTFKvp5Tvtkv2iiOwGHBRuZjQnkwWOpHYjSCBks3yeKvVUmBixlPF9X+TCIbgJhXyZc/ZItCZjmegeJileSrxc2UD7Qz5EbE4jdT9lWV6zeLf/yM4cx5RUOmVTLYvwnGw7XQNKhwsiEzYnOd+JJqoD0hgpDnvqcVMRAugmsxoZAiXDioNJabnCQdwoKNph8SxYHBikYoAwpmtxm8jbMWdrESZcq4TRmva8ALqjURC8CoBnQGpwOaD8FqAMv5MsvpYpqfJX3c8dXin8rHMPshGZ+vKyEBGa61BeQiO8x3c/pPt7vn78qcb9tZovJmqOjZAhsZUZDRjE4tiKR6pVoLIz5gnJa+S1warB4begoWWcpDin6+Yk2iBSI4wZFdMruQA8gwwDA+Vi8qpXPTOahozwLw1rQ8WSLUN7xpTLPopEwWESPSt4GzFYD856PLZGclfYd2TZV4xpgAz3Qzuq24LaROmUoO6/x6CuR3DwliLYgvToCDYMlUXa+SMYgH+UMqclfTi0OQMvyRlklADw1KxvGirTzvk588zaIZJ5XGbvRqbvBL1JHGhTzLuRV50eV27PbRDE7YE+0oIx4VSsjnC1f5yWWQrmXCy1+Aa6aHgiTYIDhs5IE7s6AD3xPF4tZ+JnMvkqvj/ff7O4I/bevMkWTpb0CT/sG0gIF3J6+wn7oeNLLuCUJpkkm8BQIh3KPZyKc/G1UsxpHMv+YYofSBqWp916RirOu92E66wO1GlezdAp9/c6p4qo6SwbJIf7gdcA5wqehzxNyK+A17TAptMleTHaw8NJ4UK1oD7D//1aEPVPqwUBOEMxiOxXJP/b1v52ErS1j59a+1n7+OvVfqjtZc0F9vFoxddlVjgW/IsBPTTwMV/GHA20YQgeCbSAA+9qzdRe2Dlhz3wdELh/nJdnnl8HB9rD9nVUvCxmfDJL7WoTyjJiIvd16H7K3kn9gDreTlX1A9CHOb3Ro/Mw3m9YRS8vHsRj9UdB0bz6Nwbd/gY=</diagram></mxfile>