Important changes to Tiny Cloud pricing > Find out more

Tiny Drive JWT Authentication

Guide on how to setup JWT Authentication for Tiny Drive

Contribute to this page

Introduction

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

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.

Private/public key pair

TinyMCE cloud services tokens use public/private RSA key pairs. The TinyMCE cloud services only store the public key, allowing developers to have full control over the authentication.

The private/public key pair can be created on your Tiny - My Account page, however we only store the public key on the My Account page. The private key should be downloaded and stored in your backend.

Important: Keep the private key secure, do not commit files containing the key to public repositories or websites.

For information on generating an RSA key pair locally, see: Creating a private/public key pair for Tiny Drive.

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.

The following diagram explains the JWT call flow:

JSON Web Token Call Flow

JWT requirements

Algorithm

Our examples use, and we recommend RS256 algorithm. This is a list of supported ones: RS256, RS384, RS512, PS256, PS384, PS512

Claims

These are like options/data you can send with the JWT token.

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

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

JWT endpoint setup procedure

Follow these steps to set up your own JWT endpoint.

  1. Setup a JWT endpoint on your server, this could be a simple page using one of the examples below.
  2. Configure the tinydrive_token_provider to that endpoint.
  3. Make sure you copy the private key into the example code.
  4. You should be good to go now.

The JWT Endpoint should examine your systems sessions to verify your user has access to your system.

Need help?

We recommend reading up and trying to understand how JWT works; you need some necessary skills to implement Tiny Drive. This can be tricky if you need some help, check our help page and if that doesn’t work, contact our support.

PHP token provider endpoint example

This example uses the Firebase JWT library provided through the Composer dependency manager. The private key should be the private key that was generated through your Tiny Account.

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 with jwt.php Endpoint

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

Node 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.

/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', function (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 with /jwt endpoint

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

More configuration

If you managed to set this up, you should be good to go with checking out the various configuration options for Tiny Drive and how you can customize it. Don’t forget to change the JWT Claim’s (user id, user name) to get those from your system.

If you need some help, check our help page and if that doesn’t work, submit a support request.

Creating a private/public key pair for Tiny Drive

The procedure for creating a key pair depends on the operating system of the host machine.

Linux

To create a private/public key pair on a Linux operating system:

  1. Install OpenSSL.
  2. Create a private/public key pair.
  3. Retrieve the public key.

Installing OpenSSL on Linux

The procedure for installing OpenSSL on Linux distributions varies. The installation commands for common Linux distributions have been provided here.

Red Hat Enterprise Linux 7 or CentOS 7

On a command line, run the following commands to install OpenSSL on:

  • Red Hat Enterprise Linux 6 or 7.
  • CentOS 6 or 7.
sudo yum check-update
sudo yum install openssl
Red Hat Enterprise Linux 8+, Fedora, or CentOS 8+

On a command line, run the following commands to install OpenSSL on:

  • Red Hat Enterprise Linux 8 or later.
  • CentOS 8 or later.
  • Fedora 18 or later.
sudo dnf check-update
sudo dnf install openssl
Debian, Ubuntu, Linux Mint, or other Debian-based distributions

On a command line, run the following commands to install OpenSSL on Debian-based operating systems (such as: Debian, Ubuntu, and Linux Mint).

sudo apt update
sudo apt install openssl
SUSE Linux Enterprise Server or openSUSE

On a command line, run the following commands to install OpenSSL on openSUSE-based operating systems (such as: openSUSE and SUSE Linux Enterprise Server).

sudo zypper refresh
sudo zypper install openssl

Create a private/public key pair on Linux

To create a private/public key pair:

  1. On a command line, run:

     ssh-keygen -m PEM -t rsa -b 2048 -f <MY_TINY_DRIVE_KEY>
    

    Where <MY_TINY_DRIVE_KEY> should be replaced with a name for the key pair.

  2. Enter a passphrase for accessing the key.

Two files will be created in the current directory:

  • <MY_TINY_DRIVE_KEY> - The private key.
  • <MY_TINY_DRIVE_KEY>.pub - The public key.

Retrieve the public key on Linux

To retrieve the public key, on a command line, run:

openssl rsa -in <MY_TINY_DRIVE_KEY> -outform DER -pubout | base64 -w0

The public key for the <MY_TINY_DRIVE_KEY> key pair will be printed on the command line with base64 encoding.

Apple macOS

To create a private/public key pair on a macOS operating system:

  1. Create a private/public key pair.
  2. Retrieve the public key.

Create a private/public key pair on macOS

To create a private/public key pair:

  1. Using Finder, open a Terminal.
  2. On a terminal, run:

     ssh-keygen -m PEM -t rsa -b 2048 -f <MY_TINY_DRIVE_KEY>
    

    Where <MY_TINY_DRIVE_KEY> should be replaced with a name for the key pair.

  3. Enter a passphrase for accessing the key.

Two files will be created in the current directory:

  • <MY_TINY_DRIVE_KEY> - The private key.
  • <MY_TINY_DRIVE_KEY>.pub - The public key.

Retrieve the public key on macOS

To retrieve the public key, on a terminal, run:

openssl rsa -in <MY_TINY_DRIVE_KEY> -outform DER -pubout | base64 -

The public key for the <MY_TINY_DRIVE_KEY> key pair will be printed on the terminal with base64 encoding.

Microsoft Windows

To create a private/public key pair on a Microsoft Windows operating system:

  1. Install OpenSSL.
  2. Create a private/public key pair.
  3. Retrieve the public key.

Installing OpenSSL on Microsoft Windows

To install OpenSSL with Git for Windows:

  1. Download the Windows package from the Git Downloads page.
  2. Open the downloaded file Git-<VERSION>-<ARCH>-bit.exe, where <VERSION> is the latest version of Git for Windows and <ARCH> is the architecture, such as 32-bit or 64-bit.
  3. Click Next on the Information and Select Destination Location screens.
  4. Select Check daily for Git for Windows updates on the Select Components screen, then click Next.
  5. Click Next on the remaining screens to accept the default settings.
  6. Once the installation is complete, click Finish.

Create a private/public key pair on Windows

To create a private/public key pair:

  1. Open the Start menu (or Windows menu) and open Git Bash.
  2. On the Git bash command line, run:

     ssh-keygen -m PEM -t rsa -b 2048 -f <MY_TINY_DRIVE_KEY>
    

    Where <MY_TINY_DRIVE_KEY> should be replaced with a name for the key pair.

  3. Enter a passphrase for accessing the key.

Two files will be created in the current directory:

  • <MY_TINY_DRIVE_KEY> - The private key.
  • <MY_TINY_DRIVE_KEY>.pub - The public key.

Retrieve the public key on Windows

To retrieve the public key, on a Git bash command line, run:

openssl rsa -in <MY_TINY_DRIVE_KEY> -outform DER -pubout | base64 -w0

The public key for the <MY_TINY_DRIVE_KEY> key pair will be printed on the command line with base64 encoding.

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.