diff options
author | Chocobozzz <me@florianbigard.com> | 2020-05-04 16:13:44 +0200 |
---|---|---|
committer | Chocobozzz <chocobozzz@cpy.re> | 2020-05-04 16:21:39 +0200 |
commit | 5831dbcbc881a2b19fc0c14a328364700dbd7725 (patch) | |
tree | 31a9d8853f04f3a0a58fbadfd1f4e1b27de6cf3e /support/doc/plugins/guide.md | |
parent | 97b65ce58aaacbbfec2291f18fb95a9da9eb5263 (diff) | |
download | PeerTube-5831dbcbc881a2b19fc0c14a328364700dbd7725.tar.gz PeerTube-5831dbcbc881a2b19fc0c14a328364700dbd7725.tar.zst PeerTube-5831dbcbc881a2b19fc0c14a328364700dbd7725.zip |
Add auth plugins guide
Diffstat (limited to 'support/doc/plugins/guide.md')
-rw-r--r-- | support/doc/plugins/guide.md | 131 |
1 files changed, 113 insertions, 18 deletions
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index 81691c8c1..d95b7649b 100644 --- a/support/doc/plugins/guide.md +++ b/support/doc/plugins/guide.md | |||
@@ -48,7 +48,7 @@ Themes are exactly the same as plugins, except that: | |||
48 | ### Hooks | 48 | ### Hooks |
49 | 49 | ||
50 | A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks: | 50 | A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks: |
51 | * `filter`: used to filter functions parameters or return values. | 51 | * `filter`: used to filter functions parameters or return values. |
52 | For example to replace words in video comments, or change the videos list behaviour | 52 | For example to replace words in video comments, or change the videos list behaviour |
53 | * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published | 53 | * `action`: used to do something after a certain trigger. For example to send a hook every time a video is published |
54 | * `static`: same than `action` but PeerTube waits their execution | 54 | * `static`: same than `action` but PeerTube waits their execution |
@@ -70,14 +70,24 @@ Example: | |||
70 | ```js | 70 | ```js |
71 | async function register ({ | 71 | async function register ({ |
72 | registerHook, | 72 | registerHook, |
73 | |||
73 | registerSetting, | 74 | registerSetting, |
74 | settingsManager, | 75 | settingsManager, |
76 | |||
75 | storageManager, | 77 | storageManager, |
78 | |||
76 | videoCategoryManager, | 79 | videoCategoryManager, |
77 | videoLicenceManager, | 80 | videoLicenceManager, |
78 | videoLanguageManager, | 81 | videoLanguageManager, |
82 | |||
79 | peertubeHelpers, | 83 | peertubeHelpers, |
80 | getRouter | 84 | |
85 | getRouter, | ||
86 | |||
87 | registerExternalAuth, | ||
88 | unregisterExternalAuth, | ||
89 | registerIdAndPassAuth, | ||
90 | unregisterIdAndPassAuth | ||
81 | }) { | 91 | }) { |
82 | registerHook({ | 92 | registerHook({ |
83 | target: 'action:application.listening', | 93 | target: 'action:application.listening', |
@@ -120,8 +130,8 @@ function register ({ registerHook, peertubeHelpers }) { | |||
120 | 130 | ||
121 | ### Static files | 131 | ### Static files |
122 | 132 | ||
123 | Plugins can declare static directories that PeerTube will serve (images for example) | 133 | Plugins can declare static directories that PeerTube will serve (images for example) |
124 | from `/plugins/{plugin-name}/{plugin-version}/static/` | 134 | from `/plugins/{plugin-name}/{plugin-version}/static/` |
125 | or `/themes/{theme-name}/{theme-version}/static/` routes. | 135 | or `/themes/{theme-name}/{theme-version}/static/` routes. |
126 | 136 | ||
127 | ### CSS | 137 | ### CSS |
@@ -160,6 +170,10 @@ const adminName = await settingsManager.getSetting('admin-name') | |||
160 | 170 | ||
161 | const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) | 171 | const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) |
162 | result['admin-name] | 172 | result['admin-name] |
173 | |||
174 | settingsManager.onSettingsChange(settings => { | ||
175 | settings['admin-name]) | ||
176 | }) | ||
163 | ``` | 177 | ``` |
164 | 178 | ||
165 | #### Storage | 179 | #### Storage |
@@ -205,6 +219,87 @@ The `ping` route can be accessed using: | |||
205 | * Or `/plugins/:pluginName/router/ping` | 219 | * Or `/plugins/:pluginName/router/ping` |
206 | 220 | ||
207 | 221 | ||
222 | #### Add external auth methods | ||
223 | |||
224 | If you want to add a classic username/email and password auth method (like [LDAP](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-ldap) for example): | ||
225 | |||
226 | ```js | ||
227 | registerIdAndPassAuth({ | ||
228 | authName: 'my-auth-method', | ||
229 | |||
230 | // PeerTube will try all id and pass plugins in the weight DESC order | ||
231 | // Exposing this value in the plugin settings could be interesting | ||
232 | getWeight: () => 60, | ||
233 | |||
234 | // Optional function called by PeerTube when the user clicked on the logout button | ||
235 | onLogout: user => { | ||
236 | console.log('User %s logged out.', user.username') | ||
237 | }, | ||
238 | |||
239 | // Optional function called by PeerTube when the access token or refresh token are generated/refreshed | ||
240 | hookTokenValidity: ({ token, type }) => { | ||
241 | if (type === 'access') return { valid: true } | ||
242 | if (type === 'refresh') return { valid: false } | ||
243 | }, | ||
244 | |||
245 | // Used by PeerTube when the user tries to authenticate | ||
246 | login: ({ id, password }) => { | ||
247 | if (id === 'user' && password === 'super password') { | ||
248 | return { | ||
249 | username: 'user' | ||
250 | email: 'user@example.com' | ||
251 | role: 2 | ||
252 | displayName: 'User display name' | ||
253 | } | ||
254 | } | ||
255 | |||
256 | // Auth failed | ||
257 | return null | ||
258 | } | ||
259 | }) | ||
260 | |||
261 | // Unregister this auth method | ||
262 | unregisterIdAndPassAuth('my-auth-method') | ||
263 | ``` | ||
264 | |||
265 | You can also add an external auth method (like [OpenID](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-openid-connect), [SAML2](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-saml2) etc): | ||
266 | |||
267 | ```js | ||
268 | // result contains the userAuthenticated auth method you can call to authenticate a user | ||
269 | const result = registerExternalAuth({ | ||
270 | authName: 'my-auth-method', | ||
271 | |||
272 | // Will be displayed in a button next to the login form | ||
273 | authDisplayName: () => 'Auth method' | ||
274 | |||
275 | // If the user click on the auth button, PeerTube will forward the request in this function | ||
276 | onAuthRequest: (req, res) => { | ||
277 | res.redirect('https://external-auth.example.com/auth') | ||
278 | }, | ||
279 | |||
280 | // Same than registerIdAndPassAuth option | ||
281 | // onLogout: ... | ||
282 | |||
283 | // Same than registerIdAndPassAuth option | ||
284 | // hookTokenValidity: ... | ||
285 | }) | ||
286 | |||
287 | router.use('/external-auth-callback', (req, res) => { | ||
288 | // Forward the request to PeerTube | ||
289 | result.userAuthenticated({ | ||
290 | req, | ||
291 | res, | ||
292 | username: 'user' | ||
293 | email: 'user@example.com' | ||
294 | role: 2 | ||
295 | displayName: 'User display name' | ||
296 | }) | ||
297 | }) | ||
298 | |||
299 | // Unregister this external auth method | ||
300 | unregisterExternalAuth('my-auth-method) | ||
301 | ``` | ||
302 | |||
208 | ### Client helpers (themes & plugins) | 303 | ### Client helpers (themes & plugins) |
209 | 304 | ||
210 | #### Plugin static route | 305 | #### Plugin static route |
@@ -278,10 +373,10 @@ peertubeHelpers.getSettings() | |||
278 | console.error('Matomo settings are not set.') | 373 | console.error('Matomo settings are not set.') |
279 | return | 374 | return |
280 | } | 375 | } |
281 | 376 | ||
282 | // ... | 377 | // ... |
283 | }) | 378 | }) |
284 | ``` | 379 | ``` |
285 | 380 | ||
286 | 381 | ||
287 | ### Publishing | 382 | ### Publishing |
@@ -344,9 +439,9 @@ Update the `package.json` fields: | |||
344 | * `author` | 439 | * `author` |
345 | * `bugs` | 440 | * `bugs` |
346 | * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else) | 441 | * `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else) |
347 | 442 | ||
348 | **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin. | 443 | **Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin. |
349 | If you don't need static directories, use an empty `object`: | 444 | If you don't need static directories, use an empty `object`: |
350 | 445 | ||
351 | ```json | 446 | ```json |
352 | { | 447 | { |
@@ -371,7 +466,7 @@ And if you don't need CSS or client script files, use an empty `array`: | |||
371 | 466 | ||
372 | Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) | 467 | Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) |
373 | 468 | ||
374 | **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version, | 469 | **Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version, |
375 | and will be supported by web browsers. | 470 | and will be supported by web browsers. |
376 | If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). | 471 | If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). |
377 | 472 | ||
@@ -405,27 +500,27 @@ Translation files are just objects, with the english sentence as the key and the | |||
405 | ### Test your plugin/theme | 500 | ### Test your plugin/theme |
406 | 501 | ||
407 | You'll need to have a local PeerTube instance: | 502 | You'll need to have a local PeerTube instance: |
408 | * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites) | 503 | * Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites) |
409 | (to clone the repository, install dependencies and prepare the database) | 504 | (to clone the repository, install dependencies and prepare the database) |
410 | * Build PeerTube (`--light` to only build the english language): | 505 | * Build PeerTube (`--light` to only build the english language): |
411 | 506 | ||
412 | ``` | 507 | ``` |
413 | $ npm run build -- --light | 508 | $ npm run build -- --light |
414 | ``` | 509 | ``` |
415 | 510 | ||
416 | * Build the CLI: | 511 | * Build the CLI: |
417 | 512 | ||
418 | ``` | 513 | ``` |
419 | $ npm run setup:cli | 514 | $ npm run setup:cli |
420 | ``` | 515 | ``` |
421 | 516 | ||
422 | * Run PeerTube (you can access to your instance on http://localhost:9000): | 517 | * Run PeerTube (you can access to your instance on http://localhost:9000): |
423 | 518 | ||
424 | ``` | 519 | ``` |
425 | $ NODE_ENV=test npm start | 520 | $ NODE_ENV=test npm start |
426 | ``` | 521 | ``` |
427 | 522 | ||
428 | * Register the instance via the CLI: | 523 | * Register the instance via the CLI: |
429 | 524 | ||
430 | ``` | 525 | ``` |
431 | $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test' | 526 | $ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test' |
@@ -474,10 +569,10 @@ registerHook({ | |||
474 | }) | 569 | }) |
475 | ``` | 570 | ``` |
476 | * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific hook, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new) | 571 | * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific hook, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new) |
477 | * Don't use PeerTube dependencies. Use your own :) | 572 | * Don't use PeerTube dependencies. Use your own :) |
478 | 573 | ||
479 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. | 574 | If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. |
480 | This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. | 575 | This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. |
481 | 576 | ||
482 | ### Spam/moderation plugin | 577 | ### Spam/moderation plugin |
483 | 578 | ||
@@ -488,7 +583,7 @@ If you want to create an antispam/moderation plugin, you could use the following | |||
488 | * `filter:api.video-threads.list.result`: to change/hide the text of threads | 583 | * `filter:api.video-threads.list.result`: to change/hide the text of threads |
489 | * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies | 584 | * `filter:api.video-thread-comments.list.result`: to change/hide the text of replies |
490 | * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos | 585 | * `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos |
491 | 586 | ||
492 | ### Other plugin examples | 587 | ### Other plugin examples |
493 | 588 | ||
494 | You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins | 589 | You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins |