Merge pull request #1654 from coralproject/docs

Enhanced documentation on JWT's

docs/source/02-01-required-configuration.md

@@ -81,4 +81,4 @@ TALK_JWT_SECRET=jX9y8G2ApcVLwyL{$6s3
 
 Be default, we sign our tokens with HMAC using a SHA-256 hash algorithm. If you
 want to change the signing algorithm, or use multiple signing/verifying keys,
-refer to our [Advanced Configuration](/talk/advanced-configuration/) documentation.
+refer to our [Advanced Configuration](/talk/advanced-configuration/#talk-jwt-secret) documentation.

docs/source/integrating/authentication.md

@@ -25,9 +25,10 @@ state (you don't use the auth anywhere else now). A great example of this is our
 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).
+1. Create a service that generates [JWT tokens](https://jwt.io/introduction/).
 2. Push the token into the embed.
-3. Implement the `tokenUserNotFound` hook to process the token.
+3. Implement the [`tokenUserNotFound`](#implement-tokenusernotfound) hook to
+   process the token.
 
 ### Create JWT Token
 
@@ -39,7 +40,20 @@ Using that demo application, you'll see how you can:
 
 1. Create a node application that can issue JWT's that are compatible with Talk.
 2. Provide a validation endpoint that can be used by Talk to validate the token
-   and get the user via the `tokenUserNotFound` hook.
+   and get the user via the [`tokenUserNotFound`](#implement-tokenusernotfound)
+   hook.
+
+It's also important to note a few requirements for proper integration with Talk.
+The generated JWT must contain the following claims:
+
+- [`jti`](https://tools.ietf.org/html/rfc7519#section-4.1.7): a unique identifier for the token (like a uuid/v4)
+- [`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4): the expiry date of the token as a unix timestamp
+- [`sub`](https://tools.ietf.org/html/rfc7519#section-4.1.2): the user identifier that can be used to lookup the user in the mongo
+  database
+  - The user may not yet exist in the database, but that's the responsibility
+    of the [`tokenUserNotFound`](#implement-tokenusernotfound) hook.
+- [`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1): the issuer for the token must match the value of `TALK_JWT_ISSUER`
+- [`aud`](https://tools.ietf.org/html/rfc7519#section-4.1.3): the audience for the token must match the value of `TALK_JWT_AUDIENCE`
 
 ### Push token into embed
 
@@ -47,7 +61,8 @@ 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
 service we created/used in the previous step.
 
-Using the token that was created for the user, you simply have to ammend the template where Talk is rendering to read as the following:
+Using the token that was created for the user, you simply have to amend the
+template where Talk is rendering to read as the following:
 
 ```js
 Coral.Talk.render(document.getElementById('coralStreamEmbed'), {
@@ -72,12 +87,12 @@ example issuer and Talk must match:
 
 | Talk | Token Issuer Example |
 |------|----------------------|
-|`JWT_ISSUER`|`JWT_ISSUER`|
-|`JWT_AUDIENCE`|`JWT_AUDIENCE`|
-|`SECRET`|`JWT_SECRET`*|
+|[`TALK_JWT_ISSUER`](/talk/advanced-configuration/#talk-jwt-issuer)|`JWT_ISSUER`|
+|[`TALK_JWT_AUDIENCE`](/talk/advanced-configuration/#talk-jwt-audience)|`JWT_AUDIENCE`|
+|[`TALK_JWT_SECRET`](/talk/advanced-configuration/#talk-jwt-secret)|`JWT_SECRET`*|
 
 \* Note that secrets is a pretty complex topic, refer to the
-[TALK-JWT-SECRET](/talk/advanced-configuration/#TALK-JWT-SECRET) configuration
+[TALK_JWT_SECRET](/talk/advanced-configuration/#talk-jwt-secret) configuration
 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.
 

docs/themes/coral/source/css/talk.scss

@@ -291,11 +291,10 @@ pre {
 
 .content {
   article {
-    p a:not(.plain-link) {
-      @extend .coral-link;
-    }
+    p a:not(.plain-link),
     ul:not(.toc__menu) li a,
     ol li a,
+    td a,
     dd > a {
       @extend .coral-link;
     }