Merge pull request marmelab#10357 from marmelab/doc-access-control-custom-routes

[Doc] Improve Access Control for Custom Pages

Author: djhi

docs/CanAccess.md

@@ -42,4 +42,59 @@ const UserEdit = () => (
 | `accessDenied` |          | `ReactNode`    | -                     | The element displayed when users are denied access to the resource |
 | `error`        |          | `ReactNode`    | -                     | The element displayed when an error occurs while calling `authProvider.canAccess` |
 
+## Securing Custom Routes
+
+By default, there is no authentication or authorization control on custom routes. If you need to restrict access to a custom route, wrap the content with `<CanAccess>`. Remember to check the authentication status before with `<Authenticated>`:
+
+```tsx
+import { Authenticated, CanAccess, AccessDenied } from 'react-admin';
+
+export const LogsPage = () => (
+    <Authenticated>
+        <CanAccess resource="logs" action="read" accessDenied={<AccessDenied />}>
+            ...
+        </CanAccess>
+    </Authenticated>
+);
+```
+
+Use the [`<CustomRoutes>`](./CustomRoutes.md) component to add custom routes to your admin. 
+
+```tsx
+import { Admin, CustomRoutes, Authenticated, CanAccess, AccessDenied, Layout } from 'react-admin';
+import { Route } from 'react-router-dom';
+
+import { LogsPage } from './LogsPage';
+import { MyMenu } from './MyMenu';
+
+const MyLayout = (props) => <Layout {...props} menu={MyMenu} />;
+
+const App = () => (
+    <Admin authProvider={authProvider} layout={MyLayout}>
+        <CustomRoutes>
+            <Route path="/logs" element={<LogsPage />} />
+        </CustomRoutes>
+    </Admin>
+);
+```
+
+Remember to also wrap your [custom menu items](./Menu.md) with `<CanAccess>` to hide the menu items if the user doesn't have access to the resource.
+
+```tsx
+import { Menu, CanAccess } from "react-admin";
+import SsidChartIcon from "@mui/icons-material/SsidChart";
+
+export const MyMenu = () => (
+    <Menu>
+        <Menu.ResourceItems />
+        <CanAccess resource="logs" action="read">
+            <Menu.Item primaryText="Logs" to="/logs" leftIcon={<SsidChartIcon />} />
+        </CanAccess>
+    </Menu>
+);
+```
+
+**Note**: You don't need to use `<CanAccess>` on the core react-admin page components (`<List>`, `<Create>`, `<Edit>`, `<Show>`) because they already have built-in access control.
+
+**Note**: You don't need to use `<Authenticated>` on custom pages if your admin uses [`requireAuth`](./Admin.md#requireauth).
 

docs/Permissions.md

@@ -253,30 +253,59 @@ const CommentsToolbar = ({ record }) => (
 
 ### Custom Routes
 
-By default, there is no authentication or authorization control on the custom routes. If you need to restrict access to a custom route, you can use the `<CanAccess>` component. Remember to check the authentication status before with `<Authenticated>`:
+By default, there is no authentication or authorization control on custom routes. If you need to restrict access to a custom route, you can use the `<CanAccess>` component. Remember to check the authentication status before with `<Authenticated>`:
 
 ```tsx
-import { Admin, CustomRoutes, Authenticated, CanAccess } from 'react-admin';
+import { Authenticated, CanAccess, AccessDenied } from 'react-admin';
+
+export const LogsPage = () => (
+    <Authenticated>
+        <CanAccess resource="logs" action="read" accessDenied={<AccessDenied />}>
+            ...
+        </CanAccess>
+    </Authenticated>
+);
+```
+
+Use the [`<CustomRoutes>`](./CustomRoutes.md) component to add custom routes to your admin. 
+
+```tsx
+import { Admin, CustomRoutes, Authenticated, CanAccess, AccessDenied, Layout } from 'react-admin';
 import { Route } from 'react-router-dom';
 
+import { LogsPage } from './LogsPage';
+import { MyMenu } from './MyMenu';
+
+const MyLayout = (props) => <Layout {...props} menu={MyMenu} />;
+
 const App = () => (
-    <Admin authProvider={authProvider}>
+    <Admin authProvider={authProvider} layout={MyLayout}>
         <CustomRoutes>
-            <Route path="/restricted" element={
-                <Authenticated>
-                    <CanAccess action="read" resource="restricted">
-                        <RestrictedPage />
-                    </CanAccess>
-                </Authenticated>
-            } />
+            <Route path="/logs" element={<LogsPage />} />
         </CustomRoutes>
     </Admin>
 );
 ```
 
+Remember to also wrap your [custom menu items](./Menu.md) with `<CanAccess>` to hide the menu items if the user doesn't have access to the resource.
+
+```tsx
+import { Menu, CanAccess } from "react-admin";
+import SsidChartIcon from "@mui/icons-material/SsidChart";
+
+export const MyMenu = () => (
+    <Menu>
+        <Menu.ResourceItems />
+        <CanAccess resource="logs" action="read">
+            <Menu.Item primaryText="Logs" to="/logs" leftIcon={<SsidChartIcon />} />
+        </CanAccess>
+    </Menu>
+);
+```
+
 **Note**: You don't need to use `<CanAccess>` on the core react-admin page components (`<List>`, `<Create>`, `<Edit>`, `<Show>`) because they already have built-in access control.
 
-**Note**: You don't need to use `<CanAccess>` on custom pages if your admin uses [`requireAuth`](./Admin.md#requireauth).
+**Note**: You don't need to use `<Authenticated>` on custom pages if your admin uses [`requireAuth`](./Admin.md#requireauth).
 
 ## Permissions