DOCS || CORL-290 || Add Custom SSO Plugin Recipe (#2249)

* updated auth strategies

* added custom auth plugin recipe

* fixed format on TALK_SMTP_FROM_ADDRESS

* cleaned up formatting a bit

* added CDN to checklist

* Update docs/source/01-05-pre-launch-checklist.md

Co-Authored-By: immber <jessiekrushing@gmail.com>

* Update docs/source/integrating/authentication.md

Co-Authored-By: immber <jessiekrushing@gmail.com>

* added links to plugins

docs/source/01-05-pre-launch-checklist.md

@@ -13,6 +13,9 @@ permalink: /pre-launch-checklist/
 - [ ] Do you have a domain name for Talk?
   - **Recommended**: You should host Talk on a subdomain on your main site (e.g. if your site is mysitefornews.org, you should serve Talk from a subdomain like talk.mysitefornews.org) to avoid issues with third-party cookie sharing.
 
+
+- [ ] Do you have a Content Delivery Network (CDN) to improve performance and reduce load on your Talk servers?
+
   
 - [ ] Do you have a MongoDB instance?
   - A MongoDB [Docker instance](/talk/installation-from-docker/) hosted alongside Talk?
@@ -28,9 +31,11 @@ permalink: /pre-launch-checklist/
 - [ ] Do you want to provide single sign-on (SSO) by integrating with an external auth system?
   - See [Authenticating with Talk](/talk/integrating/authentication/)
 
+
 - [ ] Do you want to integrate Talk with your CMS to automate embedding Talk Comment Stream into your site?
   - See [CMS Integration](/talk/integrating/cms-integration/)
 
+
 - [ ] Do you want to use Social sign-on?
   - Facebook
     - Install [talk-plugin-facebook-auth](/talk/plugin/talk-plugin-facebook-auth/)

docs/source/02-02-advanced-configuration.md

@@ -416,13 +416,19 @@ cannot. You would use this option in the latter situation.
 
 ## TALK_SMTP_FROM_ADDRESS
 
-The email address to send emails from using the SMTP provider in the format:
+The email address to send emails from using the SMTP provider. You can include the name and email address or only provide the email. 
 
 ```plain
-TALK_SMTP_FROM_ADDRESS="The Coral Project" <support@coralproject.net>
+TALK_SMTP_FROM_ADDRESS="The Coral Project" support@coralproject.net
+
+```
+or 
+
+```plain
+TALK_SMTP_FROM_ADDRESS=support@coralproject.net
+
 ```
 
-Including the name and email address.
 
 ## TALK_SMTP_HOST
 

docs/source/04-05-plugin-recipes.md

@@ -47,3 +47,9 @@ Source: [talk-recipes/tree/master/plugins/author-name](https://github.com/coralp
 Enables the ability to hover over a commenter’s name and add plugin
 functionality there. The Member Since plugin that is provided in this recipe is
 an example of this.
+
+## recipe-custom-auth
+
+Source: [talk-recipes/tree/master/plugins/custom-auth](https://github.com/coralproject/talk-recipes/tree/master/plugins/custom-auth)
+
+Example code for creating, and updating Users in Talk from JWT data provided by your custom SSO authentication service. 

docs/source/integrating/authentication.md

@@ -3,25 +3,18 @@ title: Authenticating with Talk
 permalink: /integrating/authentication/
 ---
 
-Out of the box Talk supports account registration with username and password, as well as features like forgot password. 
+### Authentication Strategies 
 
-You can also integrate Talk with any external authentication service that will enable
-seamless single sign-on (SSO) for users within your organization. There are a few
-methods of doing so:
+Talk comes with built in user management features like account registration with username/email and password, as well as features like resetting a forgotten password. 
 
-1. Passport Middleware
-2. Custom Token Integration
+There are four strategies to choose from when it comes to user authentication:
 
-Both methods work, but there are product decisions that will affect the overall
-choice.
+#### Talk Email Authentication
+Best when you want Talk to manage all user registration, creation and authentication. Requires the least amount of setup and configuration. Users register by creating a Username (must be unique across users, no spaces or special chars), Email, and Password and are stored in Talk’s database. Optionally - you can require an email verification step at time of account creation. *Plugins required: [talk-plugin-local-auth](/talk/plugin/talk-plugin-local-auth), [talk-plugin-auth](/talk/plugin/talk-plugin-auth)*
 
-## Passport Middleware
+#### Social Sign-in (FaceBook or Google via Passport Middleware)
 
-You would choose the **Passport Middleware** route when you are OK using an auth
-that is triggered from inside Talk that is not connected to an external auth
-state (you don't use the auth anywhere else now). 
-
-Plugins are available for the following 3rd party authentication providers:
+Allows users to use existing social media account to sign in to Talk. Requires you to setup API keys with social sign on provider, and configure your API keys in Talk. Users register and login via a *“Sign in with ….”*, but are not required to set user details such as password or email address. *Plugins required: [talk-plugin-auth](/talk/plugin/talk-plugin-auth), plus at least one of the following:*
 
 * [Facebook](/talk/plugin/talk-plugin-facebook-auth/)
 * [Google](/talk/plugin/talk-plugin-google-auth/) 
@@ -29,15 +22,20 @@ Plugins are available for the following 3rd party authentication providers:
 _FAQ: Can I create a Twitter auth plugin?_ 
 This is currently not possible because Talk uses passport.js which does not support Twitter's oAuth2 requirements.
 
-## Custom Token Integration 
+#### Social Sign-in with Email Association 
+This strategy is actually a combination of the first two. Talk’s built in Email Authentication is augmented by also allowing registration with a social account. Users with social accounts are prompted to associate an email address with their social profile to enable notifications. *Plugins required: [talk-plugin-auth](/talk/plugin/talk-plugin-auth), [talk-plugin-local-auth](/talk/plugin/talk-plugin-local-auth), [talk-plugin-facebook-auth](/talk/plugin/talk-plugin-facebook-auth/), and or [talk-plugin-google-auth](/talk/plugin/talk-plugin-google-auth/)*
+
+#### Custom SSO Token Integration
+When you want users to authenticate via your existing identity system, and be automatically registered/logged into Talk. Users register, login, and manage their user details on your existing site, your user database maintains the source of truth for all user information. Users are created and updated in Talk via jwt tokens passed from your auth service to Talk. *Required Plugins: requires custom plugin development, as well as disabling talk-plugin-auth, and talk-plugin-local-auth*
+
+## Setting Up Custom SSO Token Integration
 
 You can integrate Talk with any authentication service to enable single sign-on
 for users. The steps to do that are:
 
 1. Create a service that generates [JWT tokens](https://jwt.io/introduction/).
-2. Push the token into the embed.
-3. Implement the [`tokenUserNotFound`](#implement-tokenusernotfound) hook to
-   process the token.
+2. Include the JWT token in your Talk embed script
+3. Create a custom plugin to generate and authenticate Talk users from the jwt token
 
 ### Create JWT Token
 
@@ -67,7 +65,7 @@ The generated JWT must contain the following claims:
 ### Generate a key to sign the JWT
 Optionally you can use https://github.com/coralproject/coralcert to generate a key with which to sign the JWTs and specify the secret as an environment variable. 
 
-### Push token into embed
+### Include token in embed
 
 We're assuming that your CMS is capable of authenticating a user account, or 
 at least having the user's details available to send off to the token creation
@@ -83,15 +81,17 @@ Coral.Talk.render(document.getElementById('coralStreamEmbed'), {
 });
 ```
 
-Which will pass down the token to Talk and will fire the next steps
+Which will pass down the token to Talk and will fire the 
 `tokenUserNotFound` hook to complete the auth flow.
 
-### Implement `tokenUserNotFound`
+### Create a Custom Plugin to Generate Talk Users 
 
 This is the only piece of code you'll have to write that lives inside Talk. 
 The role of this code is to live as a plugin and provide Talk with a way of
 taking the token that you gave it, and turning into a user.
 
+Your custom plugin will need to include a `tokenUserNotFound` function that will handle creating a user in Talk from the claims provided on the JWT, refer to [`tokenUserNotFound`](/talk/api/server/#tokenusernotfound) for reference.
+
 Using the example application we were working with in the JWT issuing step
 above, we'll need to ensure that the configuration is consistent in-between both
 Talk and the JWT issuer. Namely, the following environment variables from our
@@ -108,5 +108,4 @@ example issuer and Talk must match:
 reference, the basic takeaway is that the secret used to sign the tokens issued
 by the issuer must be able to be verified by Talk.
 
-For an example of implementing the plugin, refer to [`tokenUserNotFound`](/talk/api/server/#tokenusernotfound)
-reference.
+For an example of implementing the plugin, check out our [SSO Custom Auth Recipe](https://github.com/coralproject/talk-recipes/tree/master/plugins/custom-auth)