Merge pull request #20 from tinymce/TINY-1903

Tiny 1903

configure/jwt-authentication.md

@@ -1,6 +1,7 @@
 ---
 layout: default
-title: JWT Authentication
+title: JWT authentication setup
+title_nav: JWT authentication setup
 description_short: JWT Authentication
 description: JWT is a common authorization solution for web services.
 ---
@@ -11,17 +12,17 @@ This section is intended to be used by developers with prior knowledge of JSON W
 
 ## Introduction
 
-Some cloud services for TinyMCE require you to setup JWT authentication. This allows us to verify that you and your end user are allowed to access a particular feature. JWT is a common authorization solution for web services and is documented in more detail at the https://jwt.io/ website. The guide aims to show how to setup JWT authentication for the cloud services provided for TinyMCE.
+Some cloud services for TinyMCE require configuring JWT authentication to verify that the end users are allowed to access a particular feature. JWT is a common authorization solution for web services and is documented in more detail at the https://jwt.io/ website. This section aims to show how to setup JWT authentication for the cloud services provided for TinyMCE.
 
 
-## Private/Public Key Pair
+## Private/public key pair
 
-Tokens used by the TinyMCE cloud services make use of a public/private RSA key-pair. This allows you as an integrator to have full control over the authentication as we don't store the private key. Only you have access to the private key, and only you can produce valid tokens. We can only verify that they are valid and extract user information from that token.
+Tokens used by the TinyMCE cloud services make use of a public/private RSA key-pair. This allows the integrating developer to have full control over the authentication as Tiny does not store the private key. Only the user has access to the private key and can produce valid tokens. Tiny only verifies that they are valid and extracts user information from that token.
 
-The private/public key pair is created in your [Tiny account page](https://apps.tiny.cloud/my-account/jwt-key-manager/), but we only store the public key on our side. The private key is for you to store in your backend.
+The private/public key pair is created in the user's [Tiny account page](https://apps.tiny.cloud/my-account/jwt-key-manager/), but only the public key is stored on Tiny web server. The user needs to store the private key in their backend.
 
 
-## JWT Provider URL
+## JWT provider URL
 
 The easiest way to setup JWT authentication against TinyMCE cloud services is to create a JWT provider endpoint. This endpoint takes a JSON HTTP POST request and produces a JSON result with the token that the service will then use for all the HTTP requests.
 
@@ -47,11 +48,11 @@ All of these algorithms use the private RSA key to sign the JWT, but vary in how
 ### Claims:
 
 * **sub** - _(required)_ Unique string to identify the user. This can be a database ID, hashed email address, or similar identifier.
-* **name** - _(required)_ Full name of the user that will be used for presentation inside Tiny Drive. When the user uploads a file, this name is presented as the creator of that file.
+* **name** - _(required)_ Full name of the user that will be used for presentation inside Tiny [Drive]({{site.baseurl}}/plugins/drive/). When the user uploads a file, this name is presented as the creator of that file.
 
-## PHP Token Provider Example
+## PHP token provider example
 
-This example uses the [Firebase JWT library](https://github.com/firebase/php-jwt) provided through the Composer dependency manager. The private key should be the private key that was generated through your Tiny Account. Each service requires different claims to be provided. The following example shows the sub and name claims needed for Tiny Drive.
+This example uses the [Firebase JWT library](https://github.com/firebase/php-jwt) provided through the Composer dependency manager. The private key should be the private key that was generated through the user's Tiny Account. Each service requires different claims to be provided. The following example shows the sub and name claims needed for Tiny Drive.
 
 ```php
 <?php
@@ -68,9 +69,17 @@ $privateKey = <<<EOD
 EOD;
 
 $payload = array(
-  "sub" => "123",           // Unique user id string
-  "name" => "John Doe",     // Full name of user
-  "exp" => time() + 60 * 10 // 10 minutes expiration
+  // Unique user id string
+  "sub" => "123",
+
+  // Full name of user
+  "name" => "John Doe",
+
+  // Optional custom user root path
+  // "https://claims.tiny.cloud/drive/root" => "/johndoe",
+
+  // 10 minutes expiration
+  "exp" => time() + 60 * 10
 );
 
 try {
@@ -86,9 +95,9 @@ try {
 ?>
 ```
 
-## Node Token Provider Example
+## Node token provider example
 
-This example shows you how to set up a Node.js express handler that produces the tokens. It requires you to install the Express web framework and the `jsonwebtoken` Node modules. Each service requires different claims to be provided. The following example shows the sub and name claims needed for Tiny Drive.
+This example shows how to set up a Node.js express handler that produces the tokens. It requires installing the Express web framework and the `jsonwebtoken` Node modules. Each service requires different claims to be provided. The following example shows the sub and name claims needed for Tiny Drive.
 
 ```js
 const express = require('express');
@@ -106,9 +115,17 @@ const privateKey = `
 
 app.post('/jwt', function (req, res) {
   const payload = {
-    sub: '123',         // Unique user id string
-    name: 'John Doe',   // Full name of user
-    exp: Math.floor(Date.now() / 1000) + (60 * 10) // 10 minutes expiration
+    // Unique user id string
+    sub: '123',
+
+    // Full name of user
+    name: 'John Doe',
+
+    // Optional custom user root path
+    // 'https://claims.tiny.cloud/drive/root': '/johndoe',
+
+    // 10 minutes expiration
+    exp: Math.floor(Date.now() / 1000) + (60 * 10)
   };
 
   try {
@@ -127,9 +144,10 @@ app.post('/jwt', function (req, res) {
 app.listen(3000);
 ```
 
-## Tiny Drive Specific JWT Claims:
+## Tiny Drive specific JWT claims:
 
 **sub** - (required) Unique string to identify the user. This can be a database id, hashed email address, or similar identifier.
 
 **name** - (required) Full name of the user that will be used for presentation inside Tiny Drive. When a user uploads a file, the username is presented as the creator of that file.
 
+**https://claims.tiny.cloud/drive/root** - (optional) Full path to a tiny drive specific root for example "/johndoe".

plugins/drive.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Drive
+title: Drive plugin
 title_nav: Drive
 description: Cloud-based file and image management for TinyMCE.
 keywords: tinydrive storage media tiny drive
@@ -80,6 +80,22 @@ tinymce.init({
 });
 ```
 
+### `tinydrive_max_image_dimension`
+
+This setting enables you to constrain the width/height of uploaded images. When this is enabled any images with a higher width or height than the specified amount would be proportionally resized down to the specified max dimension.
+
+**Type:** `Number`
+
+#### Example
+
+```js
+tinymce.init({
+  selector: "textarea",  // change this value according to your HTML
+  plugins: "tinydrive",
+  tinydrive_max_image_dimension: 1024
+});
+```
+
 ## Insert File toolbar button
 
 Drive will automatically integrate into the Image, Link, and Media dialogs as a file picker. You can also configure it to insert files directly into your content using the `insertfile` button. To enable this button, add it to your toolbar editor setting.
@@ -136,3 +152,6 @@ All files are uploaded to a central storage with a CDN endpoint that means that
 The URL format for each file is `https://drive.tiny.cloud/1/{your-api-key}/{uuid}` and gets generated when a file is uploaded.
 If you move or rename a file, it will still have the same unique URL, so the restructuring of your files using Drive won't affect where they are being used. However, deleting a file will mark the URL as being unused, and the URL will not continue to work.
 
+## User specific root
+
+It's common that you want to be able to have user specific paths so that each user within your system gets it's own directory. This can be done by setting the `https://claims.tiny.cloud/drive/root` custom jwt claim to a path within your tiny drive account. This path will automatically be constructured when the user is accessing drive using a jwt key with that claim. The user only be able to see and manage files within that root.