Skip to content

Commit 01db151

Browse files
LewisAtTinylhick2108kemister85Farzad Hayat
authored
DOC-2583 Add exportword, importword and exportpdf JWT authentication guides for (PHP). (#3519)
* Documentation for the JWT Authentication in relation to Document Exporters and Importers * DOC-2582 Removed Service URL for ExportPDF * DOC-2583 Removed Service URL for Export to Word * DOC-2583 Removed Service URL for Import Word * DOC-2583 Created New Folder for PHP JWT Authentication * Update modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-PHP.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/import-word-with-jwt-authentication-with-PHP.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/export-to-word-with-jwt-authentication-with-PHP.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/auth/document-converters/php/intro-and-prerequisites.adoc Co-authored-by: Farzad Hayat <[email protected]> * Update modules/ROOT/pages/import-word-with-jwt-authentication-with-PHP.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Rename export-to-word-with-jwt-authentication-with-PHP.adoc to export-to-word-with-jwt-authentication-with-php.adoc * DOC-2583 Rename export-to-pdf-with-jwt-authentication-with-PHP.adoc to export-to-pdf-with-jwt-authentication-with-php.adoc * DOC-2583 Rename import-word-with-jwt-authentication-with-PHP.adoc to import-word-with-jwt-authentication-with-php.adoc * DOC-2583 Update nav.adoc to match new page titles * Update modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/private-public-key-pairs-for-tiny-cloud-services.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> * Update modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc Co-authored-by: Farzad Hayat <[email protected]> * DOC-2583: Farzad/Lewis structural improvements * DOC-2583: Farzad/Lewis fix import/export docx nav structure * Update modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc Co-authored-by: Karl Kemister-Sheppard <[email protected]> --------- Co-authored-by: Lewis Hickson <[email protected]> Co-authored-by: Karl Kemister-Sheppard <[email protected]> Co-authored-by: Farzad Hayat <[email protected]>
1 parent eb7f593 commit 01db151

10 files changed

+427
-0
lines changed

‎modules/ROOT/nav.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -313,12 +313,18 @@
313313
*** xref:advtable.adoc[Enhanced Tables]
314314
*** xref:exportpdf.adoc[Export to PDF]
315315
**** xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API]
316+
**** JWT Authentication
317+
***** xref:export-to-pdf-with-jwt-authentication-with-php.adoc[Export to PDF with JWT authentication (PHP)]
316318
*** xref:exportword.adoc[Export to Word]
317319
**** xref:html-to-docx-converter-api.adoc[HTML to DOCX Converter API]
320+
**** JWT Authentication
321+
***** xref:export-to-word-with-jwt-authentication-with-php.adoc[Export to Word with JWT Authentication (PHP)]
318322
*** xref:footnotes.adoc[Footnotes]
319323
*** xref:formatpainter.adoc[Format Painter]
320324
*** xref:importword.adoc[Import from Word]
321325
**** xref:docx-to-html-converter-api.adoc[DOCX to HTML Converter API]
326+
**** JWT Authentication
327+
***** xref:import-word-with-jwt-authentication-with-php.adoc[Import From Word with JWT Authentication (PHP)]
322328
*** xref:editimage.adoc[Image Editing]
323329
*** xref:uploadcare.adoc[Image Optimizer Powered by Uploadcare]
324330
*** xref:inline-css.adoc[Inline CSS]

‎modules/ROOT/pages/export-to-pdf-with-jwt-authentication-with-php.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
= {pluginname} with JWT authentication (PHP) Guide
2+
:navtitle: JWT Authentication setup for Export to PDF
3+
:description: Guide on how to setup JWT Authentication for exporting PDF files with {productname}
4+
:keywords: jwt, authentication, exportpdf, pdf, php
5+
:pluginname: Export to PDF
6+
:plugincode: exportpdf
7+
8+
include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[]
9+
10+
include::partial$auth/document-converters/php/initial-project-setup.adoc[]
11+
12+
== Setup
13+
14+
=== Generate a Public/Private Key Pair
15+
16+
include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+2]
17+
18+
include::partial$auth/document-converters/php/server-setup-php.adoc[]
19+
20+
=== Web Page Setup (index.html)
21+
22+
Inside the `public` folder where you created the `index.html` file add the HTML setup code:
23+
24+
[source,html]
25+
----
26+
<!DOCTYPE html>
27+
<html>
28+
<head>
29+
<title>TinyMCE with PDF Export</title>
30+
<script
31+
src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
32+
referrerpolicy="origin">
33+
</script>
34+
<script>
35+
tinymce.init({
36+
selector: 'textarea',
37+
plugins: 'exportpdf',
38+
toolbar: 'exportpdf',
39+
exportpdf_converter_options: {
40+
'format': 'Letter',
41+
'margin_top': '1in',
42+
'margin_right': '1in',
43+
'margin_bottom': '1in',
44+
'margin_left': '1in'
45+
},
46+
// exportpdf_token_provider fetches a token from the `/jwt.php` endpoint.
47+
exportpdf_token_provider: () => {
48+
return fetch('http://localhost:3000/jwt.php', {
49+
method: 'POST',
50+
headers: { 'Content-Type': 'application/json' },
51+
}).then(response => response.json());
52+
},
53+
});
54+
</script>
55+
</head>
56+
<body>
57+
<h1>TinyMCE Export to PDF Demo</h1>
58+
<textarea>
59+
Welcome to TinyMCE! Try the Export to PDF feature.
60+
</textarea>
61+
</body>
62+
</html>
63+
----
64+
65+
include::partial$auth/document-converters/php/configuration-steps.adoc[]

‎modules/ROOT/pages/export-to-word-with-jwt-authentication-with-php.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
= {pluginname} with JWT authentication (PHP) Guide
2+
:navtitle: JWT Authentication setup for Export to Word
3+
:description: Guide on how to setup JWT Authentication for exporting Word files with {productname}
4+
:keywords: jwt, authentication, exportword, word, php
5+
:pluginname: Export to Word
6+
:plugincode: exportword
7+
8+
include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[]
9+
10+
include::partial$auth/document-converters/php/initial-project-setup.adoc[]
11+
12+
== Setup
13+
14+
=== Generate a Public/Private Key Pair
15+
16+
include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+2]
17+
18+
include::partial$auth/document-converters/php/server-setup-php.adoc[]
19+
20+
=== Web Page Setup (index.html)
21+
22+
Inside the `public` folder where you created the `index.html` file add the HTML setup code:
23+
24+
[source,html]
25+
----
26+
<!DOCTYPE html>
27+
<html>
28+
<head>
29+
<title>TinyMCE with Word Export</title>
30+
<script
31+
src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
32+
referrerpolicy="origin">
33+
</script>
34+
<script>
35+
tinymce.init({
36+
selector: 'textarea',
37+
plugins: 'exportword',
38+
toolbar: 'exportword',
39+
exportword_converter_options: {
40+
'format': 'Letter',
41+
'margin_top': '1in',
42+
'margin_right': '1in',
43+
'margin_bottom': '1in',
44+
'margin_left': '1in'
45+
},
46+
// exportword_token_provider fetches a token from the `/jwt.php` endpoint.
47+
exportword_token_provider: () => {
48+
return fetch('http://localhost:3000/jwt.php', {
49+
method: 'POST',
50+
headers: { 'Content-Type': 'application/json' },
51+
}).then(response => response.json());
52+
},
53+
});
54+
</script>
55+
</head>
56+
<body>
57+
<h1>TinyMCE Export to Word Demo</h1>
58+
<textarea>
59+
Welcome to TinyMCE! Try the Export to Word feature.
60+
</textarea>
61+
</body>
62+
</html>
63+
----
64+
65+
include::partial$auth/document-converters/php/configuration-steps.adoc[]

‎modules/ROOT/pages/import-word-with-jwt-authentication-with-php.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
= {pluginname} with JWT authentication (PHP) Guide
2+
:navtitle: JWT Authentication setup for Import from Word
3+
:description: Guide on how to setup JWT Authentication for importing Word files with {productname}
4+
:keywords: jwt, authentication, importword, word, php
5+
:pluginname: Import from Word
6+
:plugincode: importword
7+
8+
include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[]
9+
10+
include::partial$auth/document-converters/php/initial-project-setup.adoc[]
11+
12+
== Setup
13+
14+
=== Generate a Public/Private Key Pair
15+
16+
include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+2]
17+
18+
include::partial$auth/document-converters/php/server-setup-php.adoc[]
19+
20+
=== Web Page Setup (index.html)
21+
22+
Inside the `public` folder where you created the `index.html` file add the HTML setup code:
23+
24+
[source,html]
25+
----
26+
<!DOCTYPE html>
27+
<html>
28+
<head>
29+
<title>TinyMCE with Word Import</title>
30+
<script
31+
src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
32+
referrerpolicy="origin">
33+
</script>
34+
<script>
35+
tinymce.init({
36+
selector: 'textarea',
37+
plugins: 'importword',
38+
toolbar: 'importword',
39+
importword_converter_options: {
40+
'format': 'Letter',
41+
'margin_top': '1in',
42+
'margin_right': '1in',
43+
'margin_bottom': '1in',
44+
'margin_left': '1in'
45+
},
46+
// importword_token_provider fetches a token from the `/jwt.php` endpoint.
47+
importword_token_provider: () => {
48+
return fetch('http://localhost:3000/jwt.php', {
49+
method: 'POST',
50+
headers: { 'Content-Type': 'application/json' },
51+
}).then(response => response.json());
52+
},
53+
});
54+
</script>
55+
</head>
56+
<body>
57+
<h1>TinyMCE Import Word Demo</h1>
58+
<textarea>
59+
Welcome to TinyMCE! Try the Import from Word feature.
60+
</textarea>
61+
</body>
62+
</html>
63+
----
64+
65+
include::partial$auth/document-converters/php/configuration-steps.adoc[]

‎modules/ROOT/partials/auth/document-converters/jwt-setup-document-converters.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
[[setting-up-jwt-authentication]]
2+
== Setting up JWT authentication
3+
4+
To set up JSON Web Token (JWT) authentication for {productname} {pluginname}:
5+
6+
. Add a public key to you {accountpage}, link:https://www.tiny.cloud/auth/login/[login].
7+
. Set up a JSON Web Token (JWT) Provider endpoint via link:{accountjwturl}[{accountpage} - JWT Keys]
8+
. Configure your {productname} to use the JWT endpoint.
9+
10+
include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[]
11+
12+
[[set-up-a-json-web-token-jwt-endpoint]]
13+
== Set up a JSON Web Token (JWT) endpoint
14+
15+
include::partial$auth/how-jwts-are-used.adoc[]
16+
17+
=== JWT endpoint requirements
18+
19+
A JSON Web Token (JWT) endpoint for {pluginname} requires:
20+
21+
* The endpoint or server accepts a JSON HTTP POST request.
22+
* User authentication - A method of verifying the user, and that they should have access to the {pluginname}.
23+
* The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys].
24+
* The endpoint or server produces a JSON response with the token. {pluginname} will submit the token with requests to the {pluginname} Server.
25+
26+
=== Required JWT claims for {pluginname}
27+
28+
JSON Web Tokens produced by the JWT endpoint must include the following claims:
29+
30+
`+aud+` _(required)_::
31+
*Type:* `+String+`
32+
+
33+
The `aud` is case-sensitive string that must match a valid API key that has the {pluginname} plugin enabled.
34+
35+
`+iat+` _(required)_::
36+
*Type:* `+Number+`
37+
+
38+
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.
39+
40+
.Example
41+
[source,json]
42+
----
43+
iat: Math.floor(Date.now() / 1000), // Issue timestamp
44+
----
45+
46+
`+exp+` _(required)_::
47+
*Type:* `+Number+`
48+
+
49+
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.
50+
51+
.Example
52+
[source,json]
53+
----
54+
exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes)
55+
----

‎modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
=== Configuration Steps
2+
3+
==== 1. Add Your API Key
4+
5+
* Replace `YOUR-API-KEY` in both files with your actual {productname} API key
6+
* The API key should be the same in both the HTML script source and the JWT payload
7+
8+
==== 2. Add Your Private Key
9+
10+
* Replace the private key placeholder in `jwt.php` with your actual private key
11+
* Make sure it's in `PKCS8` format
12+
* Keep this key secure and never share it publicly
13+
14+
=== Running Your Project
15+
16+
. Start the server:
17+
+
18+
[source,bash]
19+
----
20+
php -S localhost:3000
21+
----
22+
23+
. Open your browser to: `http://localhost:3000`
24+
. You should see:
25+
* The {productname} editor
26+
* An "{pluginname}" button in the toolbar

‎modules/ROOT/partials/auth/document-converters/php/initial-project-setup.adoc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
== Update PHP Configuration File
2+
3+
Use the following command to locate the PHP configuration file:
4+
5+
[source,bash]
6+
----
7+
php --ini
8+
----
9+
10+
Open the configuration file in a text editor and ensure the following settings are enabled:
11+
12+
[source,ini]
13+
----
14+
extension=openssl
15+
extension_dir='ext'
16+
----
17+
18+
[TIP]
19+
The path to the extension directory may vary depending on your system.
20+
21+
== Quick Start Guide
22+
23+
=== Project Setup
24+
25+
[source,bash]
26+
----
27+
# Create and enter project directory
28+
mkdir tinymce-app
29+
cd tinymce-app
30+
# Initialize Composer
31+
composer require firebase/php-jwt
32+
----
33+
34+
=== Create Project Structure
35+
36+
[source,bash]
37+
----
38+
# Create the public folder for your web files
39+
touch index.html
40+
touch jwt.php
41+
----
42+
43+
Your project should look like this:
44+
45+
[source]
46+
----
47+
/tinymce-app
48+
index.html (TinyMCE webpage)
49+
jwt.php (Server code)
50+
composer.json
51+
composer.lock
52+
vendor
53+
----

‎modules/ROOT/partials/auth/document-converters/php/intro-and-prerequisites.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
== Introduction
2+
3+
{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/].
4+
5+
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.
6+
7+
== What You'll Build
8+
9+
Before diving into the technical details, here's what you'll achieve with this guide:
10+
11+
* A working {productname} editor running {pluginname} plugin.
12+
* A secure authentication system using JWT tokens
13+
* A simple PHP server to handle the authentication
14+
15+
[TIP]
16+
====
17+
This guide is designed for developers new to JWT authentication and {productname} integration.
18+
====
19+
20+
=== Prerequisites
21+
22+
Before starting, ensure you have:
23+
24+
* PHP installed on your computer (to check, run `php -v` in your terminal)
25+
* OpenSSL installed on your computer (to check, run `openssl version` in your terminal)
26+
* Composer installed on your computer (to check, run `composer -v` in your terminal)
27+
* A {productname} API key (get one from link:https://www.tiny.cloud/signup[TinyMCE's website])
28+
* Basic familiarity with the command line
29+
30+
[IMPORTANT]
31+
====
32+
Make sure you have your API key ready before starting. You'll need it for both the server and client configuration.
33+
====

0 commit comments

Comments
 (0)