Merge pull request #2107 from strapi/sec/up

docusaurus/docs/dev-docs/plugins/users-permissions.md

@@ -839,7 +839,7 @@ The use of `ngrok` is not needed.
 Patreon does not accept `localhost` urls. <br/>
 Use `ngrok` to serve the backend app.
 
-```
+```bash
 ngrok http 1337
 ```
 
@@ -853,9 +853,9 @@ Don't forget to update the server url in the Strapi config file `./config/server
 - Click on "Create Client"
 - Enter the details of your organization and website.
 - There is a drop-down for "App Category" but no explanation of what the different categories mean.
-"Community" seems to work fine. 
+"Community" seems to work fine.
 - You can choose either version 1 or version 2 of the API - neither are actively developed.
-Version 2 is probably the best choice. See their 
+Version 2 is probably the best choice. See their
 [developer docs](https://docs.patreon.com/#introduction) for more detail.
 - Under "Redirect URI's" enter `https://your-site.com/api/connect/patreon/callback`
 - Save the client details and you will then see the Client ID and Client Secret.
@@ -1231,7 +1231,7 @@ You can update these templates under **Plugins** > **Roles & Permissions** > **E
 
 ## Security configuration
 
-JWTs can be verified and trusted because the information is digitally signed. To sign a token a _secret_ is required. By default Strapi generates and stores it in `./extensions/users-permissions/config/jwt.js`. 
+JWTs can be verified and trusted because the information is digitally signed. To sign a token a _secret_ is required. By default Strapi generates and stores it in `./extensions/users-permissions/config/jwt.js`.
 
 This is useful during development but for security reasons it is recommended to set a custom token via an environment variable `JWT_SECRET` when deploying to production.
 
@@ -1266,3 +1266,45 @@ export default {
 :::tip
 You can learn more about configuration [here](/dev-docs/configurations).
 :::
+
+### Creating a custom callback validator
+
+By default, Strapi SSO only redirects to the redirect URL that is exactly equal to the url in the configuration:
+
+<ThemedImage
+  alt="Users & Permissions configuration"
+  sources={{
+      light: '/img/assets/users-permissions/sso-config-custom-validator.png',
+      dark: '/img/assets/users-permissions/sso-config-custom-validator_DARK.png'
+    }}
+/>
+
+If you need to configure a custom handler to accept other URLs, you can create a callback `validate` function in your plugins.js for the `users-permissions` plugin.
+
+```tsx title="/config/plugins.js|ts"
+  // ... other plugins configuration ...
+  // Users & Permissions configuration
+  'users-permissions': {
+    enabled: true,
+    config: {
+      callback: {
+        validate: (cbUrl, options) => {
+          // cbUrl is where Strapi is being asked to redirect the auth info
+          // that was received from the provider to
+
+          // in this case, we will only validate that the 
+          // if using a base url, you should always include the trailing slash
+          // although in real-world usage you should also include the full paths
+          if (cbUrl.startsWith('https://myproxy.mysite.com/') || 
+              cbUrl.startsWith('https://mysite.com/')) {
+            return;
+          }
+
+          // Note that you MUST throw an error to fail validation
+          // return values are not checked
+          throw new Error('Invalid callback url');
+        },
+      },
+    },
+  },
+```