Add auth plugins guide

support/doc/plugins/guide.md

@@ -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',
@@ -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