diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 47b1c49a5a..20d1a64ea3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -313,12 +313,18 @@ *** xref:advtable.adoc[Enhanced Tables] *** xref:exportpdf.adoc[Export to PDF] **** xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API] +**** JWT Authentication +***** xref:export-to-pdf-with-jwt-authentication-with-php.adoc[Export to PDF with JWT authentication (PHP)] *** xref:exportword.adoc[Export to Word] **** xref:html-to-docx-converter-api.adoc[HTML to DOCX Converter API] +**** JWT Authentication +***** xref:export-to-word-with-jwt-authentication-with-php.adoc[Export to Word with JWT Authentication (PHP)] *** xref:footnotes.adoc[Footnotes] *** xref:formatpainter.adoc[Format Painter] *** xref:importword.adoc[Import from Word] **** xref:docx-to-html-converter-api.adoc[DOCX to HTML Converter API] +**** JWT Authentication +***** xref:import-word-with-jwt-authentication-with-php.adoc[Import From Word with JWT Authentication (PHP)] *** xref:editimage.adoc[Image Editing] *** xref:inline-css.adoc[Inline CSS] *** xref:linkchecker.adoc[Link Checker] diff --git a/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc b/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc new file mode 100644 index 0000000000..90d69cc4f5 --- /dev/null +++ b/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc @@ -0,0 +1,63 @@ += Export to PDF with JWT authentication (PHP) Guide +:navtitle: JWT Authentication setup for Export to PDF +:description: Guide on how to setup JWT Authentication for exporting PDF files with {productname} +:keywords: jwt, authentication, exportpdf, pdf, php +:pluginname: Export to PDF +:plugincode: exportpdf + +include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[] + +include::partial$auth/document-converters/php/initial-project-setup.adoc[] + +. Inside the `public` folder where you created the `index.html` file add the HTML setup code (refer to the *Setting up {productname} HTML* section). + +==== Web Page Setup (index.html) + +[source,html] +---- + + + + TinyMCE with PDF Export + + + + +

TinyMCE Export to PDF Demo

+ + + +---- + +. In the root directory, copy and paste the server setup code into the `jwt.php` file. + +include::partial$auth/document-converters/php/server-setup-php.adoc[] + +include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+1] + +include::partial$auth/document-converters/php/configuration-steps.adoc[] diff --git a/modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc b/modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc new file mode 100644 index 0000000000..506ff512f6 --- /dev/null +++ b/modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc @@ -0,0 +1,64 @@ += Export to Word with JWT authentication (PHP) Guide +:navtitle: JWT Authentication setup for Export to Word +:description: Guide on how to setup JWT Authentication for exporting Word files with {productname} +:keywords: jwt, authentication, exportword, word, php +:pluginname: Export to Word +:plugincode: exportword + +include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[] + +include::partial$auth/document-converters/php/initial-project-setup.adoc[] + + +. Inside the `public` folder where you created the `index.html` file add the HTML setup code (refer to the *Setting up {productname} HTML* section). + +==== Web Page Setup (index.html) + +[source,html] +---- + + + + TinyMCE with Word Export + + + + +

TinyMCE Export to Word Demo

+ + + +---- + +. In the root directory, copy and paste the server setup code into the `jwt.php` file. + +include::partial$auth/document-converters/php/server-setup-php.adoc[] + +include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+1] + +include::partial$auth/document-converters/php/configuration-steps.adoc[] diff --git a/modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc b/modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc new file mode 100644 index 0000000000..30b673f325 --- /dev/null +++ b/modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc @@ -0,0 +1,63 @@ += Import to Word with JWT authentication (PHP) Guide +:navtitle: JWT Authentication setup for Import Word to TinyMCE Edtior +:description: Guide on how to setup JWT Authentication for importing Word files with {productname} +:keywords: jwt, authentication, importword, word, php +:pluginname: Import from Word +:plugincode: importword + +include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[] + +include::partial$auth/document-converters/php/initial-project-setup.adoc[] + +. Inside the `public` folder where you created the `index.html` file add the HTML setup code (refer to the *Setting up {productname} HTML* section). + +==== Web Page Setup (index.html) + +[source,html] +---- + + + + TinyMCE with Word Import + + + + +

TinyMCE Import Word Demo

+ + + +---- + +. In the root directory, copy and paste the server setup code into the `jwt.php` file. + +include::partial$auth/document-converters/php/server-setup-php.adoc[] + +include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+1] + +include::partial$auth/document-converters/php/configuration-steps.adoc[] diff --git a/modules/ROOT/partials/auth/document-converters/jwt-setup-document-converters.adoc b/modules/ROOT/partials/auth/document-converters/jwt-setup-document-converters.adoc new file mode 100644 index 0000000000..24810aa8c9 --- /dev/null +++ b/modules/ROOT/partials/auth/document-converters/jwt-setup-document-converters.adoc @@ -0,0 +1,55 @@ +[[setting-up-jwt-authentication]] +== Setting up JWT authentication + +To set up JSON Web Token (JWT) authentication for {productname} {pluginname}: + +. Add a public key to you {accountpage}, link:https://www.tiny.cloud/auth/login/[login]. +. Set up a JSON Web Token (JWT) Provider endpoint via link:{accountjwturl}[{accountpage} - JWT Keys] +. Configure your {productname} to use the JWT endpoint. + +include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] + +[[set-up-a-json-web-token-jwt-endpoint]] +== Set up a JSON Web Token (JWT) endpoint + +include::partial$auth/how-jwts-are-used.adoc[] + +=== JWT endpoint requirements + +A JSON Web Token (JWT) endpoint for {pluginname} 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 {pluginname}. +* The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys]. +* The endpoint or server produces a JSON response with the token. {pluginname} will submit the token with requests to the {pluginname} Server. + +=== Required JWT claims for {pluginname} + +JSON Web Tokens produced by the JWT endpoint must include the following claims: + +`+aud+` _(required)_:: +*Type:* `+String+` ++ +The `aud` is case-sensitive string that must match a valid API key that has the {pluginname} plugin enabled. + +`+iat+` _(required)_:: +*Type:* `+Number+` ++ +The `iat` represents the issue timestamp, specified as the number of seconds. For example, to set the issue time to the current timestamp, calculate the issue time as the current timestamp divided by 1000. + +.Example +[source,json] +---- +iat: Math.floor(Date.now() / 1000), // Issue timestamp +---- + +`+exp+` _(required)_:: +*Type:* `+Number+` ++ +The `exp` represents the expiration timestamp, specified as the number of seconds. For example, to set a validity period of 10 minutes, calculate the expiration time as the current timestamp plus 600 seconds. + +.Example +[source,json] +---- +exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes) +---- \ No newline at end of file diff --git a/modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc b/modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc new file mode 100644 index 0000000000..cb588ca3a5 --- /dev/null +++ b/modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc @@ -0,0 +1,26 @@ +=== Configuration Steps + +==== 1. Add Your API Key + +* Replace `YOUR-API-KEY` in both files with your actual {productname} API key +* The API key should be the same in both the HTML script source and the JWT payload + +==== 2. Add Your Private Key + +* Replace the private key placeholder in `jwt.php` with your actual private key +* Make sure it's in `PKCS8` format +* Keep this key secure and never share it publicly + +=== Running Your Project + +. Start the server: ++ +[source,bash] +---- +php -S localhost:3000 +---- + +. Open your browser to: `http://localhost:3000` +. You should see: +* The {productname} editor +* An "{pluginname}" button in the toolbar \ No newline at end of file diff --git a/modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc b/modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc new file mode 100644 index 0000000000..ded74afd2a --- /dev/null +++ b/modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc @@ -0,0 +1,49 @@ +== Update PHP php.ini Files + +Update files inside the downloaded php package: + +* php.ini +* php.ini-development +* php.ini-production + +Ensure the following lines are uncommented: + +[source, bash] +---- +extension=openssl +extension_dir={Depends on your development environment} +---- + +== Quick Start Guide + +=== Project Setup (5 minutes) + +[source,bash] +---- +# Create and enter project directory +mkdir tinymce-app +cd tinymce-app +# Initialize Composer +composer require firebase/php-jwt +---- + +=== Create Project Structure + +[source,bash] +---- +# Create the public folder for your web files +touch index.html +touch jwt.php +---- + +Your project should look like this: + +[source] +---- +/tinymce-app + index.html (TinyMCE webpage) + jwt.php (Server code) + composer + composer.lock + vendor +---- diff --git a/modules/ROOT/partials/auth/document-converters/php/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/document-converters/php/intro-and-prerequisites.adoc new file mode 100644 index 0000000000..e5b34d05c5 --- /dev/null +++ b/modules/ROOT/partials/auth/document-converters/php/intro-and-prerequisites.adoc @@ -0,0 +1,33 @@ +== Introduction + +{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over file security. A JWT endpoint generates and provides authorization tokens that verify submitted content is sent by authorized users, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. + +This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a PHP server for JWT token generation. It covers project setup, server configuration, and {productname} customization. + +== What You'll Build + +Before diving into the technical details, here's what you'll achieve with this guide: + +* A working {productname} editor running {pluginname} plugin. +* A secure authentication system using JWT tokens +* A simple PHP server to handle the authentication + +[TIP] +==== +This guide is designed for developers new to JWT authentication and {productname} integration. +==== + +=== Prerequisites + +Before starting, ensure you have: + +* PHP installed on your computer +* OpenSSL installed on your computer +* Composer installed on your computer +* A {productname} API key (get one from link:https://www.tiny.cloud/signup[TinyMCE's website]) +* Basic familiarity with the command line + +[IMPORTANT] +==== +Make sure you have your API key ready before starting. You'll need it for both the server and client configuration. +==== \ No newline at end of file diff --git a/modules/ROOT/partials/auth/document-converters/php/server-setup-php.adoc b/modules/ROOT/partials/auth/document-converters/php/server-setup-php.adoc new file mode 100644 index 0000000000..1b5cca8df1 --- /dev/null +++ b/modules/ROOT/partials/auth/document-converters/php/server-setup-php.adoc @@ -0,0 +1,47 @@ +==== Server Setup (jwt.php) + +[source,php] +---- + "JWT auth failed: " . $message))); +} + +// Check for OpenSSL extension +if (!extension_loaded('openssl')) { + fatalError('You need to enable the openssl extension in your php.ini.'); +} + +// Enable CORS +header("Access-Control-Allow-Origin: *"); +header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept"); + +// JWT payload +$payload = array( + "aud" => "YOUR-API-KEY-HERE", + "iat" => time(), // Issue timestamp + "exp" => time() + 60 * 10 // Expiration time (10 minutes) +); + +try { + // Tokens are signed with the RS256 algorithm your private key + $privateKey = << $token)); +} catch (Exception $e) { + fatalError($e->getMessage()); +} +?> +---- \ No newline at end of file diff --git a/modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc b/modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc new file mode 100644 index 0000000000..4c54ef7ebe --- /dev/null +++ b/modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc @@ -0,0 +1,14 @@ +The {pluginname} 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 {pluginname} Server are used to ensure that content is sent by authorized users. +The **{pluginname}** 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 {pluginname} 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: + +@@ -7,7 +7,7 @@ There are two methods for generating and adding a public key to your API key: + +== Generate a key pair using the {accountpage} JWT Keys page + +The link:{accountjwturl}[{accountpage} - 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. {companyname} does not store the _private_ key and the key pair cannot be retrieved later. +The link:{accountjwturl}[{accountpage} - 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. {companyname} does **not store** the _private_ key and the key pair **cannot** be retrieved later. + +[[generate-a-key-pair-locally]] +== Generate a key pair locally \ No newline at end of file