Set up Tiny Drive JWT Authentication

Introduction

Tiny Drive requires you to setup JSON Web Token (JWT) authentication. This is to ensure that the security of your files remains in your control.

A JSON Web Token (JWT) endpoint is a service for generating and providing authorization tokens to users. These tokens can then be used to verify that submitted content was sent by an authorized user and to prevent unauthorized access.

JWT is a standard 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 Tiny Drive.

If you haven’t tried any of the Starter projects yet, we urge you to try them before trying to implement your solution. The source is also available on Github to study.

Overview

Setting up JWT authentication for Tiny Drive
Add a public key to the Tiny Cloud API key
Set up a JSON Web Token (JWT) endpoint
JWT endpoint examples

Setting up JWT authentication for Tiny Drive

To set up JSON Web Token (JWT) authentication for TinyMCE Tiny Drive:

Add a public key to your Tiny Account.
Set up a JSON Web Token (JWT) Provider endpoint.
Configure TinyMCE to use the JWT endpoint.

The Tiny Drive Server requires a public key generated from the same private key that will be used on your JSON Web Token (JWT) provider endpoint. The public key(s) stored on the Tiny Drive Server are used to ensure that content is sent by authorized users.

There are two methods for generating and adding a public key to your API key:

The secure key pair generator at Tiny Account - JWT Keys (recommended).
Generate a key pair locally and add the public key to Tiny Account - JWT Keys.

Generate a key pair using the Tiny Account JWT Keys page

The Tiny Account - JWT Keys page provides a private/public key generator, providing a quick and secure way of generating the required keys. This generator will store a copy of the public key, and provide a downloadable file for both the public and private keys. Tiny does not store the private key and the key pair cannot be retrieved later.

Generate a key pair locally

When generating a key pair locally, use one of the supported algorithms. Tiny Drive does not support symmetrical encryption algorithms, such as HS256. Tiny recommends using the RS256 algorithm. The following algorithms are supported:

RS256
RS384
RS512
PS256
PS384
PS512

For details on each of these algorithms, visit: RFC 7518, JSON Web Algorithms (JWA) Section 3 - Cryptographic Algorithms for Digital Signatures and MACs.

For instructions on generating a key pair locally, see: Creating a private/public key pair for Tiny Cloud.

Add a public key to the Tiny Cloud API key

Once a public key has been generated, add the public key to the Tiny Cloud API key at: Tiny Account - JWT Keys.

Set up a JSON Web Token (JWT) endpoint

The following diagram shows how JWTs are used:

Figure 1. JSON Web Token Call Flow

When a user opens Tiny Drive:

Tiny Drive requests a signed JWT on behalf of the user.
If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to Tiny Drive, certifying the user.
When the user makes a request (such as adding or deleting a file), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the public key stored on the Tiny Cloud Server.
The Tiny Cloud Server sends a response, indicating that content submission was successful (or unauthorized if necessary).

JWT endpoint requirements

A JSON Web Token (JWT) endpoint for Tiny Drive requires:

The endpoint or server accepts a JSON HTTP POST request.
User authentication - A method of verifying the user, and that they should have access to the Tiny Drive.
The JWTs are generated (signed) using the private key that pairs with the public key provided to Tiny Account - JWT Keys.
The endpoint or server produces a JSON response with the token. Tiny Drive will submit the token with requests to the Tiny Drive Server.

Required JWT claims for Tiny Drive

JSON Web Tokens produced by the JWT endpoint must include the following claims:

sub (required): Type: String or URI

Unique string or URI to identify the user. This can be a database ID, hashed email address, or similar identifier.
name (required): Type: String

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.
https://claims.tiny.cloud/drive/root (optional): Type: String

Full path to a Tiny Drive specific root for example "/johndoe". The user won’t be able to see or manage files outside this configured root path.

The “sub” claim is a case-sensitive string containing a String or URI value. The sub claim cannot have a : unless it is a valid URI or else the callback will fail.

JWT endpoint examples

The following examples show a minimal JWT endpoint and how to configure TinyMCE to use them.

PHP token provider endpoint example
Node.js token provider endpoint example

PHP token provider endpoint example

This example uses the Firebase JWT library provided through the Composer dependency manager.

$privateKey should be the private key that pairs with the public key generated at (or provided to) Tiny Account - JWT Keys.

jwt.php

<?php
require 'vendor/autoload.php';
use \Firebase\JWT\JWT;

header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept");

$privateKey = <<<EOD
-----BEGIN PRIVATE KEY-----
....
-----END PRIVATE KEY-----
EOD;

// NOTE: Before you proceed with the TOKEN, verify your users session or access.

$payload = array(
  "sub" => "123", // unique user id string
  "name" => "John Doe", // full name of user

  // Optional custom user root path
  // "https://claims.tiny.cloud/drive/root" => "/johndoe",

  "exp" => time() + 60 * 10 // 10 minute expiration
);

try {
  $token = JWT::encode($payload, $privateKey, 'RS256');
  http_response_code(200);
  header('Content-Type: application/json');
  echo json_encode(array("token" => $token));
} catch (Exception $e) {
  http_response_code(500);
  header('Content-Type: application/json');
  echo $e->getMessage();
}
?>

TinyMCE example using the jwt.php endpoint

tinymce.init({
  selector: 'textarea',
  plugins: 'image media link tinydrive code editimage',
  tinydrive_token_provider: 'jwt.php',
  toolbar: 'insertfile image link | code'
});

Node.js token provider endpoint 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. For instructions on setting up a basic Node.js Express server and adding TinyMCE, see: Integrating TinyMCE into an Express JS App.

privateKey should be the private key that pairs with the public key generated at (or provided to) Tiny Account - JWT Keys.

/jwt

const express = require('express');
const jwt = require('jsonwebtoken');
const cors = require('cors');

const app = express();
app.use(cors());

const privateKey = `
-----BEGIN PRIVATE KEY-----
....
-----END PRIVATE KEY-----
`;

app.post('/jwt', (req, res) => {
  // NOTE: Before you proceed with the TOKEN, verify your users' session or access.
  const payload = {
    sub: '123', // Unique user id string
    name: 'John Doe', // Full name of user

    // Optional custom user root path
    // 'https://claims.tiny.cloud/drive/root': '/johndoe',

    exp: Math.floor(Date.now() / 1000) + (60 * 10) // 10 minutes expiration
  };

  try {
    const token = jwt.sign(payload, privateKey, { algorithm: 'RS256'});
    res.set('content-type', 'application/json');
    res.status(200);
    res.send(JSON.stringify({
      token: token
    }));
  } catch (e) {
    res.status(500);
    res.send(e.message);
  }
});

app.listen(3000);

TinyMCE example using the /jwt endpoint

tinymce.init({
  selector: 'textarea',
  plugins: 'image media link tinydrive code editimage',
  tinydrive_token_provider: '/jwt',
  toolbar: 'insertfile image link | code'
});