aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/plugins/guide.md
diff options
context:
space:
mode:
authorChocobozzz <me@florianbigard.com>2020-05-04 16:13:44 +0200
committerChocobozzz <chocobozzz@cpy.re>2020-05-04 16:21:39 +0200
commit5831dbcbc881a2b19fc0c14a328364700dbd7725 (patch)
tree31a9d8853f04f3a0a58fbadfd1f4e1b27de6cf3e /support/doc/plugins/guide.md
parent97b65ce58aaacbbfec2291f18fb95a9da9eb5263 (diff)
downloadPeerTube-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.md131
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
50A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks: 50A 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
71async function register ({ 71async 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
123Plugins can declare static directories that PeerTube will serve (images for example) 133Plugins can declare static directories that PeerTube will serve (images for example)
124from `/plugins/{plugin-name}/{plugin-version}/static/` 134from `/plugins/{plugin-name}/{plugin-version}/static/`
125or `/themes/{theme-name}/{theme-version}/static/` routes. 135or `/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
161const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ]) 171const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ])
162result['admin-name] 172result['admin-name]
173
174settingsManager.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
224If 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
227registerIdAndPassAuth({
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
262unregisterIdAndPassAuth('my-auth-method')
263```
264
265You 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
269const 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
287router.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
300unregisterExternalAuth('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.
349If you don't need static directories, use an empty `object`: 444If 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
372Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :) 467Now 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,
375and will be supported by web browsers. 470and will be supported by web browsers.
376If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/). 471If 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
407You'll need to have a local PeerTube instance: 502You'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
479If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field. 574If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.
480This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin. 575This 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
494You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins 589You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins