OpenCloud
/
PeerTube
mirror of https://github.com/Chocobozzz/PeerTube
1
0
Fork 0
Code Issues Releases Wiki Activity

Add auth plugins guide

pull/2737/head
Chocobozzz 2020-05-04 16:13:44 +02:00 committed by Chocobozzz
parent 97b65ce58a
commit 5831dbcbc8
1 changed files with 113 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
support/doc/plugins/guide.md
View File

@ -48,7 +48,7 @@ Themes are exactly the same as plugins, except that:
### Hooks
A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks:
* `filter`: used to filter functions parameters or return values.
* `filter`: used to filter functions parameters or return values.
For example to replace words in video comments, or change the videos list behaviour
* `action`: used to do something after a certain trigger. For example to send a hook every time a video is published
* `static`: same than `action` but PeerTube waits their execution
@ -70,14 +70,24 @@ Example:
```js
async function register ({
registerHook,
registerSetting,
settingsManager,
storageManager,
videoCategoryManager,
videoLicenceManager,
videoLanguageManager,
peertubeHelpers,
getRouter
getRouter,
registerExternalAuth,
unregisterExternalAuth,
registerIdAndPassAuth,
unregisterIdAndPassAuth
}) {
registerHook({
target: 'action:application.listening',
@ -120,8 +130,8 @@ function register ({ registerHook, peertubeHelpers }) {
### Static files
Plugins can declare static directories that PeerTube will serve (images for example)
from `/plugins/{plugin-name}/{plugin-version}/static/`
Plugins can declare static directories that PeerTube will serve (images for example)
from `/plugins/{plugin-name}/{plugin-version}/static/`
or `/themes/{theme-name}/{theme-version}/static/` routes.
### CSS
@ -160,6 +170,10 @@ const adminName = await settingsManager.getSetting('admin-name')
const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ])
result['admin-name]
settingsManager.onSettingsChange(settings => {
settings['admin-name])
})
```
#### Storage
@ -205,6 +219,87 @@ The `ping` route can be accessed using:
* Or `/plugins/:pluginName/router/ping`
#### Add external auth methods
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):
```js
registerIdAndPassAuth({
authName: 'my-auth-method',
// PeerTube will try all id and pass plugins in the weight DESC order
// Exposing this value in the plugin settings could be interesting
getWeight: () => 60,
// Optional function called by PeerTube when the user clicked on the logout button
onLogout: user => {
console.log('User %s logged out.', user.username')
},
// Optional function called by PeerTube when the access token or refresh token are generated/refreshed
hookTokenValidity: ({ token, type }) => {
if (type === 'access') return { valid: true }
if (type === 'refresh') return { valid: false }
},
// Used by PeerTube when the user tries to authenticate
login: ({ id, password }) => {
if (id === 'user' && password === 'super password') {
return {
username: 'user'
email: 'user@example.com'
role: 2
displayName: 'User display name'
}
}
// Auth failed
return null
}
})
// Unregister this auth method
unregisterIdAndPassAuth('my-auth-method')
```
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):
```js
// result contains the userAuthenticated auth method you can call to authenticate a user
const result = registerExternalAuth({
authName: 'my-auth-method',
// Will be displayed in a button next to the login form
authDisplayName: () => 'Auth method'
// If the user click on the auth button, PeerTube will forward the request in this function
onAuthRequest: (req, res) => {
res.redirect('https://external-auth.example.com/auth')
},
// Same than registerIdAndPassAuth option
// onLogout: ...
// Same than registerIdAndPassAuth option
// hookTokenValidity: ...
})
router.use('/external-auth-callback', (req, res) => {
// Forward the request to PeerTube
result.userAuthenticated({
req,
res,
username: 'user'
email: 'user@example.com'
role: 2
displayName: 'User display name'
})
})
// Unregister this external auth method
unregisterExternalAuth('my-auth-method)
```
### Client helpers (themes & plugins)
#### Plugin static route
@ -278,10 +373,10 @@ peertubeHelpers.getSettings()
console.error('Matomo settings are not set.')
return
}
// ...
})
```
```
### Publishing
@ -344,9 +439,9 @@ Update the `package.json` fields:
* `author`
* `bugs`
* `engine.peertube` (the PeerTube version compatibility, must be `>=x.y.z` and nothing else)
**Caution:** Don't update or remove other keys, or PeerTube will not be able to index/install your plugin.
If you don't need static directories, use an empty `object`:
If you don't need static directories, use an empty `object`:
```json
{
@ -371,7 +466,7 @@ And if you don't need CSS or client script files, use an empty `array`:
Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :)
**Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
**Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
and will be supported by web browsers.
If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
@ -405,27 +500,27 @@ Translation files are just objects, with the english sentence as the key and the
### Test your plugin/theme
You'll need to have a local PeerTube instance:
* Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
* Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
(to clone the repository, install dependencies and prepare the database)
* Build PeerTube (`--light` to only build the english language):
* Build PeerTube (`--light` to only build the english language):
```
$ npm run build -- --light
```
* Build the CLI:
```
$ npm run setup:cli
```
* Run PeerTube (you can access to your instance on http://localhost:9000):
* Run PeerTube (you can access to your instance on http://localhost:9000):
```
$ NODE_ENV=test npm start
```
* Register the instance via the CLI:
* Register the instance via the CLI:
```
$ node ./dist/server/tools/peertube.js auth add -u 'http://localhost:9000' -U 'root' --password 'test'
@ -474,10 +569,10 @@ registerHook({
})
```
* 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)
* Don't use PeerTube dependencies. Use your own :)
* Don't use PeerTube dependencies. Use your own :)
If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.
This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin.
This way, older PeerTube versions will still use your old plugin, and new PeerTube versions will use your updated plugin.
### Spam/moderation plugin
@ -488,7 +583,7 @@ If you want to create an antispam/moderation plugin, you could use the following
* `filter:api.video-threads.list.result`: to change/hide the text of threads
* `filter:api.video-thread-comments.list.result`: to change/hide the text of replies
* `filter:video.auto-blacklist.result`: to automatically blacklist local or remote videos
### Other plugin examples
You can take a look to "official" PeerTube plugins if you want to take inspiration from them: https://framagit.org/framasoft/peertube/official-plugins