Add authorization docs (#3067)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: MUI bot <[email protected]>
Co-authored-by: Bharat Kashyap <[email protected]>

docs/data/pages.ts

@@ -78,6 +78,20 @@ const pages: MuiPage[] = [
       {
         pathname: '/toolpad/concepts/page-properties',
       },
+      {
+        pathname: '/toolpad/concepts/authorization',
+        title: 'Authorization',
+        children: [
+          {
+            pathname: '/toolpad/concepts/authentication',
+            title: 'Authentication',
+          },
+          {
+            pathname: '/toolpad/concepts/rbac',
+            title: 'Role-based access control',
+          },
+        ],
+      },
       { pathname: '/toolpad/concepts/custom-server' },
     ],
   },

docs/data/toolpad/concepts/authentication.md

@@ -0,0 +1,95 @@
+# Authentication
+
+<p class="description">Restrict a Toolpad application to authenticated users only, under certain authentication providers.</p>
+
+You can configure a Toolpad application so that users have to sign in with specific authentication providers in order to access it.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/sign-in-page.png", "alt": "Toolpad sign-in page", "caption": "Toolpad sign-in page", "indent": 1, "aspectRatio": 1 }}
+
+Authentication settings can be accessed through the **Authorization** option in the app editor header.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/authentication-settings.png", "alt": "Authentication settings", "caption": "Authentication settings", "indent": 1, "aspectRatio": 6 }}
+
+## Authentication secret
+
+To enable any authorization features, you must set a random string to be used as a secret in the `TOOLPAD_AUTH_SECRET` environment variable.
+
+This secret will be used to hash tokens, sign/encrypt cookies and generate cryptographic keys.
+
+You can quickly create a good value on the command line with this `openssl` command:
+
+```bash
+openssl rand -base64 32
+```
+
+:::warning
+Please make sure to keep this secret safe and do not share it with anyone!
+:::
+
+## Authentication providers
+
+In the authentication settings, you can set up one or more authentication providers for users to be able to sign in with, such as Github and Google.
+
+If any authentication providers are set, only authenticated users are able to access your Toolpad application.
+
+Each authentication provider has its own configuration options, to be set with certain environment variables.
+
+### Github
+
+| environment variable name &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | description                     |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
+| `TOOLPAD_GITHUB_CLIENT_ID`                                                                                                                               | Github OAuth app client ID.     |
+| `TOOLPAD_GITHUB_CLIENT_SECRET`                                                                                                                           | Github OAuth app client secret. |
+
+Take a look at the following official instructions to [create a Github OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
+
+In the Github OAuth app settings screen, in the **Authorization callback URL** option, use the production path of your application followed by `/api/auth/callback/github`, as in `http://mui.com/api/auth/callback/github`.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/github-callback-url.png", "alt": "Github callback URL configuration", "caption": "Github callback URL configuration", "zoom": false, "width": 460 }}
+
+### Google
+
+| environment variable name &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | description                 |
+| :------------------------------------------------------------------------------------------------------------------------- | :-------------------------- |
+| `TOOLPAD_GOOGLE_CLIENT_ID`                                                                                                 | Google OAuth client ID.     |
+| `TOOLPAD_GOOGLE_CLIENT_SECRET`                                                                                             | Google OAuth client secret. |
+
+Take a look at the following official instructions to [create a Google OAuth client ID](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id).
+
+In the Google OAuth client settings screen, under the **Authorized redirect URIs** option, make sure to include the production path of your application followed by `/api/auth/callback/google`, as in `http://mui.com/api/auth/callback/google`.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/google-redirect-url.png", "alt": "Google redirect URIs configuration", "caption": "Google redirect URIs configuration", "zoom": false, "width": 460 }}
+
+### Azure Active Directory (now Entra ID)
+
+:::warning
+The Azure AD authentication provider will be a paid feature of Toolpad very soon, so it's only available for free for a limited time.
+:::
+
+| environment variable name &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | description                                |
+| :------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- |
+| `TOOLPAD_AZURE_AD_CLIENT_ID`                                                                                               | Azure AD application (client) ID.          |
+| `TOOLPAD_AZURE_AD_CLIENT_SECRET`                                                                                           | Azure AD application client secret.        |
+| `TOOLPAD_AZURE_AD_TENANT_ID`                                                                                               | Azure AD application directory (tenant) ID |
+
+Follow these steps to configure your Azure AD client and get the necessary environment variables:
+
+1. Go to https://portal.azure.com, search for "Microsoft Entra ID" and go to it.
+
+2. In the left-side menu, go to **App registrations** and create a new app by choosing **New registration**.
+
+3. When registering your application, under the **Redirect URI** option, make sure to include the production path of your application followed by `/api/auth/callback/azure-ad`, as in `http://mui.com/api/auth/callback/azure-ad`.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/azure-ad-redirect-url.png", "alt": "Azure AD redirect URI configuration", "caption": "Azure AD redirect URI configuration", "aspectRatio": 6 }}
+
+4. Once your application has ben created, go to its page in **App registrations** where you can find the client and tenant IDs under the **Overview** option in the left-side menu.
+
+5. Go to **Certificates & secrets** and use the option **New client secret** to generate a client secret.
+
+With the Azure AD provider, only existing users of your Azure AD application will be able to sign in.
+
+## Restricted domains
+
+In the authentication settings, you can specify one or more domains (such as `mui.com`) to restrict user authentication based on the signed-in user's email address.
+
+If any restricted domains are set, the user must have at least one email address assigned to their current authentication provider that belongs to one of those domains, otherwise they will not be able to sign in.

docs/data/toolpad/concepts/rbac.md

@@ -0,0 +1,51 @@
+# Role-based access control
+
+<p class="description">Restrict pages in Toolpad application to users with certain roles only.</p>
+
+:::warning
+Role-based access control will be a paid feature of Toolpad very soon, so it's only available for free for a limited time.
+:::
+
+You can configure pages in a Toolpad application so that users must have certain roles within specific authentication providers in order to access them.
+
+Before using these features, make sure that you have [authentication](/toolpad/concepts/authentication/) enabled for the authenticated providers you are using.
+
+## Defining roles
+
+Role settings can be accessed through the **Authorization** option in the app editor header, under the **Roles** tab, where you can view, create, edit and delete roles for the whole application.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/roles-settings.png", "alt": "Roles settings", "caption": "Roles settings", "indent": 1, "aspectRatio": 6 }}
+
+## Restricting pages
+
+By default, all pages are viewable by users with any roles (or even no roles).
+
+You can change this for any individual page in the editor screen, under the **Page** settings in the right sidebar, where you can select/deselect **Allow access to all roles** and add one or multiple roles under the list of **Allowed roles** for the page.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/restricting-pages.png", "alt": "Page authorization settings", "caption": "Page authorization settings", "zoom": false, "width": 380 }}
+
+## Authorization providers
+
+In order for Toolpad users to have roles, you need to have those roles configured in the authentication provider they sign in with. Each authentication provider has its own configuration settings for roles.
+
+Not all available authentication providers in Toolpad support roles, so you must use one that does if you want to use this feature.
+
+### Azure Active Directory (now Entra ID)
+
+Follow these steps to assign roles to users in an Azure AD application:
+
+1. From the Azure AD home screen, go to **App registrations** in the left-side menu, then in your application go to **App roles** on the left, where you can create new roles with the **Create app role** option.
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/azure-ad-roles.png", "alt": "Azure AD app roles", "caption": "Azure AD app roles", "indent": 1, "aspectRatio": 6 }}
+
+2. To assign your created roles to a user, from the Azure AD home screen go to **Enterprise applications** in the left-side menu, then in your application go to **Users and groups** on the left, where you can assign/unassign roles to selected users with the **Edit assignment** option.
+
+## Role mapping
+
+By default, Toolpad will expect an exact match between the names of your Toolpad roles and the roles in the authentication provider being used.
+
+If you don't want these to match, you can assign each Toolpad role to one or more provider roles under the **Role mappings** tab in the Authorization options in the editor.
+
+To assign more than one provider role to a Toolpad role, you can separate the values with commas under the **Provider role** column (as in `viewer, editor, admin`).
+
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/authorization/role-mapping-settings.png", "alt": "Role mapping settings", "caption": "Role mapping settings", "indent": 1, "aspectRatio": 6 }}

docs/pages/toolpad/concepts/authentication.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from '../../../data/toolpad/concepts/authentication.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs disableAd {...pageProps} />;
+}

docs/pages/toolpad/concepts/rbac.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from '../../../data/toolpad/concepts/rbac.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs disableAd {...pageProps} />;
+}

packages/toolpad-app/src/constants.ts

@@ -20,5 +20,3 @@ export const VERSION_CHECK_INTERVAL = 1000 * 60 * 10;
 
 // TODO: Remove once global functions UI is ready
 export const FEATURE_FLAG_GLOBAL_FUNCTIONS = false;
-
-export const FEATURE_FLAG_AUTHORIZATION = false;

packages/toolpad-app/src/toolpad/AppEditor/PageEditor/PageOptionsPanel.tsx

@@ -20,7 +20,6 @@ import UrlQueryEditor from './UrlQueryEditor';
 import NodeNameEditor from '../NodeNameEditor';
 import PageTitleEditor from '../PageTitleEditor';
 import PageDisplayNameEditor from '../PageDisplayNameEditor';
-import { FEATURE_FLAG_AUTHORIZATION } from '../../../constants';
 
 const PAGE_DISPLAY_OPTIONS: { value: appDom.PageDisplayMode; label: string }[] = [
   { value: 'shell', label: 'App shell' },
@@ -119,27 +118,25 @@ export default function PageOptionsPanel() {
           </ToggleButtonGroup>
         </Tooltip>
       </div>
-      {FEATURE_FLAG_AUTHORIZATION ? (
-        <div>
-          <Typography variant="body2">Authorization:</Typography>
-          <FormControlLabel
-            control={<Checkbox checked={allowAll} onChange={handleAllowAllChange} />}
-            label="Allow access to all roles"
-          />
-          <Autocomplete
-            multiple
-            options={Array.from(availableRoles.keys())}
-            value={allowAll ? [] : allowedRoles}
-            onChange={handleAllowedRolesChange}
-            disabled={allowAll}
-            fullWidth
-            noOptionsText="No roles defined"
-            renderInput={(params) => (
-              <TextField {...params} label="Allowed roles" placeholder="Roles" />
-            )}
-          />
-        </div>
-      ) : null}
+      <div>
+        <Typography variant="body2">Authorization:</Typography>
+        <FormControlLabel
+          control={<Checkbox checked={allowAll} onChange={handleAllowAllChange} />}
+          label="Allow access to all roles"
+        />
+        <Autocomplete
+          multiple
+          options={Array.from(availableRoles.keys())}
+          value={allowAll ? [] : allowedRoles}
+          onChange={handleAllowedRolesChange}
+          disabled={allowAll}
+          fullWidth
+          noOptionsText="No roles defined"
+          renderInput={(params) => (
+            <TextField {...params} label="Allowed roles" placeholder="Roles" />
+          )}
+        />
+      </div>
       {appDom.isCodePage(page) ? null : (
         <div>
           <Divider variant="middle" sx={{ alignSelf: 'stretch' }} />

packages/toolpad-app/src/toolpad/Toolpad.tsx

@@ -15,7 +15,7 @@ import { APP_FUNCTIONS_ROUTE } from '../routes';
 import ToolpadShell from './ToolpadShell';
 import { getViewFromPathname } from '../utils/domView';
 import AppProvider, { AppState, useAppStateContext } from './AppState';
-import { FEATURE_FLAG_AUTHORIZATION, FEATURE_FLAG_GLOBAL_FUNCTIONS } from '../constants';
+import { FEATURE_FLAG_GLOBAL_FUNCTIONS } from '../constants';
 import { ProjectProvider } from '../project';
 import AppAuthorizationDialog from './AppEditor/AppAuthorizationEditor';
 
@@ -104,11 +104,9 @@ function EditorShell({ children }: EditorShellProps) {
   return (
     <ToolpadShell
       navigation={
-        FEATURE_FLAG_AUTHORIZATION ? (
-          <Stack sx={{ ml: 3 }}>
-            <Button onClick={handleAuthorizationDialogOpen}>Authorization</Button>
-          </Stack>
-        ) : null
+        <Stack sx={{ ml: 3 }}>
+          <Button onClick={handleAuthorizationDialogOpen}>Authorization</Button>
+        </Stack>
       }
       actions={
         previewPath ? (