Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/master' into auth-example
Browse files Browse the repository at this point in the history
  • Loading branch information
apedroferreira committed Feb 8, 2024
2 parents 4c1c3f9 + 5c4e926 commit 73e1f17
Show file tree
Hide file tree
Showing 93 changed files with 2,099 additions and 1,172 deletions.
2 changes: 1 addition & 1 deletion .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ jobs:
resource_class: 'large'
parallelism: 2
docker:
- image: mcr.microsoft.com/playwright:v1.41.1-focal
- image: mcr.microsoft.com/playwright:v1.41.2-focal
environment:
NODE_ENV: test
TOOLPAD_TEST_RETRIES: 1
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ jobs:
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@b7bf0a3ed3ecfa44160715d7c442788f65f0f923 # v3.23.2
uses: github/codeql-action/init@e8893c57a1f3a2b659b6b55564fdfdbbd2982911 # v3.24.0
with:
languages: typescript
# If you wish to specify custom queries, you can do so here or in a config file.
Expand All @@ -29,4 +29,4 @@ jobs:
# Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
# queries: security-extended,security-and-quality
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@b7bf0a3ed3ecfa44160715d7c442788f65f0f923 # v3.23.2
uses: github/codeql-action/analyze@e8893c57a1f3a2b659b6b55564fdfdbbd2982911 # v3.24.0
2 changes: 1 addition & 1 deletion .github/workflows/scorecards.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@ jobs:

# Upload the results to GitHub's code scanning dashboard.
- name: Upload to code-scanning
uses: github/codeql-action/upload-sarif@b7bf0a3ed3ecfa44160715d7c442788f65f0f923 # v3.23.2
uses: github/codeql-action/upload-sarif@e8893c57a1f3a2b659b6b55564fdfdbbd2982911 # v3.24.0
with:
sarif_file: results.sarif
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,46 @@
# Changelog

## v0.1.49

<!-- generated comparing v0.1.48..master -->

_Feb 8, 2024_

A big thanks to the 5 contributors who made this release possible. Here are some highlights ✨:

- Adds **authentication and authorization** support with Google, GitHub, and Azure AD (_paid_), along with detailed documentation on how to get up and running.

- Miscellaneous bug fixes and maintenance work.

- &#8203;<!-- 26 -->Authentication fixes/improvements (#3174) @apedroferreira
- &#8203;<!-- 25 -->chore(deps): bump mui core (#3175) @renovate[bot]
- &#8203;<!-- 24 -->Add isCanvas into app host context (#3170) @Janpot
- &#8203;<!-- 23 -->Fix a few react-resizable-panels warnings (#3173) @Janpot
- &#8203;<!-- 22 -->Improve package layout (#3148) @Janpot
- &#8203;<!-- 21 -->Add authorization docs (#3067) @apedroferreira
- &#8203;<!-- 20 -->Authentication/authorization tests (#3056) @apedroferreira
- &#8203;<!-- 19 -->Update renovate.json @Janpot
- &#8203;<!-- 18 -->chore(deps): bump dependencies (#3163) @renovate[bot]
- &#8203;<!-- 17 -->chore(deps): bump dependencies (major) (#3166) @renovate[bot]
- &#8203;<!-- 16 -->chore(deps): bump devdependencies (#3160) @renovate[bot]
- &#8203;<!-- 15 -->chore(deps): bump github/codeql-action action to v3.24.0 (#3164) @renovate[bot]
- &#8203;<!-- 14 -->chore(deps): bump pnpm to 8.15.1 (#3162) @renovate[bot]
- &#8203;<!-- 13 -->chore(deps): bump playwright (#3161) @renovate[bot]
- &#8203;<!-- 12 -->chore(deps): bump @mui/monorepo digest to 3c445c6 (#3159) @renovate[bot]
- &#8203;<!-- 11 -->fix: "Unexpected token ';'" in expressions with trailing ';' (#3147) @bharatkashyap
- &#8203;<!-- 10 -->Lock file maintenance (#3150) @renovate[bot]
- &#8203;<!-- 09 -->Add stronger warning to the auto generated files to avoid hand-editing (#3146) @Janpot
- &#8203;<!-- 08 -->Add RBAC with Azure AD authentication provider (#3077) @apedroferreira
- &#8203;<!-- 07 -->Run prettier (#3144) @Janpot
- &#8203;<!-- 06 -->Update monorepo (#3134) @apedroferreira
- &#8203;<!-- 05 -->[code-infra] Avoid aliasing to the monorepo dependencies (#3137) @Janpot
- &#8203;<!-- 04 -->[core] [docs] Add warnings, docs and gating for paid features (#3156) @bharatkashyap
- &#8203;<!-- 03 -->[core] Use non breaking spaces (#3145) @oliviertassinari
- &#8203;<!-- 02 -->[core] Sync with main repo @oliviertassinari
- &#8203;<!-- 01 -->[docs] Fix 301 link @oliviertassinari

All contributors of this release in alphabetical order: @apedroferreira, @bharatkashyap, @Janpot, @oliviertassinari, @renovate[bot]

## 0.1.48

<!-- generated comparing v0.1.47..master -->
Expand Down
16 changes: 0 additions & 16 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,12 @@ const { version: transformRuntimeVersion } = fse.readJSONSync(
require.resolve('@babel/runtime-corejs2/package.json'),
);

const errorCodesPath = require.resolve('@mui/monorepo/docs/public/static/error-codes.json');
const missingError = process.env.MUI_EXTRACT_ERROR_CODES === 'true' ? 'write' : 'annotate';

const muiErrorMacro = require.resolve('@mui/monorepo/packages/mui-babel-macros/MuiError.macro');

module.exports = {
presets: [
// backport of https://github.com/zeit/next.js/pull/9511
['next/babel', { 'transform-runtime': { corejs: 2, version: transformRuntimeVersion } }],
],
plugins: [
[
'babel-plugin-macros',
{
muiError: {
errorCodesPath,
missingError,
},
// TODO: Figure out dependency resolution for macros so this hack isn't needed.
resolvePath: () => muiErrorMacro,
},
],
'babel-plugin-optimize-clsx',
// for IE 11 support
'@babel/plugin-transform-object-assign',
Expand Down
15 changes: 15 additions & 0 deletions docs/data/pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import componentsManifest from './toolpad/reference/components/manifest.json';
const pages: MuiPage[] = [
{
pathname: '/toolpad/getting-started-group',
title: 'Getting Started',
children: [
{ pathname: '/toolpad/getting-started', title: 'Overview' },
{ pathname: '/toolpad/getting-started/installation' },
Expand Down Expand Up @@ -78,6 +79,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' },
],
},
Expand Down
95 changes: 95 additions & 0 deletions docs/data/toolpad/concepts/authentication.md
Original file line number Diff line number Diff line change
@@ -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.
51 changes: 51 additions & 0 deletions docs/data/toolpad/concepts/rbac.md
Original file line number Diff line number Diff line change
@@ -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 }}
27 changes: 27 additions & 0 deletions docs/data/toolpad/getting-started/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,30 @@ The roadmap does not represent a commitment, obligation, or promise to deliver a
## Global roadmap

To learn more about our plans for Material UI in general, visit the [global roadmap](/material-ui/discover-more/roadmap/).

## Paid Plan

A few features in Toolpad are proposed to be placed under a paid plan. These:

- will not be covered under the free-forever MIT license
- will require the purchase of a paid license to use in production

The following features are currently planned to be included within this scope:

- ### Authorization

Features allowing you to grant conditional access to pages based on user roles are part of this proposed paid plan. Read more about this feature on [authorization](/toolpad/concepts/rbac/).

## How to upgrade

Currently, accessing these features requires you to add the following to your `application.yml`:

```yml
spec: { plan: pro }
```
:::info
Add the above alongside any existing content of the `spec` attribute
:::

Using these features in production will require the purchase of a paid license. Please get in touch with us at [[email protected]](mailto:[email protected]) if you require to do so.
21 changes: 5 additions & 16 deletions docs/next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,24 +14,8 @@ const { findPages } = require('./src/modules/utils/find');

const MONOREPO_PATH = path.resolve(currentDirectory, '../node_modules/@mui/monorepo');
const MONOREPO_PACKAGES = {
'@mui/base': path.resolve(MONOREPO_PATH, './packages/mui-base/src'),
'@mui/codemod': path.resolve(MONOREPO_PATH, './packages/mui-codemod/src'),
'@mui/docs': path.resolve(MONOREPO_PATH, './packages/mui-docs/src'),
'@mui/envinfo': path.resolve(MONOREPO_PATH, './packages/mui-envinfo'),
'@mui/icons-material': path.resolve(MONOREPO_PATH, './packages/mui-icons-material/lib'),
'@mui/joy': path.resolve(MONOREPO_PATH, './packages/mui-joy/src'),
'@mui/lab': path.resolve(MONOREPO_PATH, './packages/mui-lab/src'),
'@mui/material': path.resolve(MONOREPO_PATH, './packages/mui-material/src'),
'@mui/material-next': path.resolve(MONOREPO_PATH, './packages/mui-material-next/src'),
'@mui/material-nextjs': path.resolve(MONOREPO_PATH, './packages/mui-material-nextjs/src'),
'@mui/private-theming': path.resolve(MONOREPO_PATH, './packages/mui-private-theming/src'),
'@mui/styled-engine': path.resolve(MONOREPO_PATH, './packages/mui-styled-engine/src'),
'@mui/styled-engine-sc': path.resolve(MONOREPO_PATH, './packages/mui-styled-engine-sc/src'),
'@mui/styles': path.resolve(MONOREPO_PATH, './packages/mui-styles'),
'@mui/system': path.resolve(MONOREPO_PATH, './packages/mui-system/src'),
'@mui/types': path.resolve(MONOREPO_PATH, './packages/mui-types'),
'@mui/markdown': path.resolve(MONOREPO_PATH, './packages/markdown'),
'@mui/utils': path.resolve(MONOREPO_PATH, './packages/mui-utils/src'),
};

export default withDocsInfra({
Expand Down Expand Up @@ -88,6 +72,11 @@ export default withDocsInfra({
},
],
},
{
test: /\.+(js|jsx|mjs|ts|tsx)$/,
include: [/(@mui[\\/]monorepo)$/, /(@mui[\\/]monorepo)[\\/](?!.*node_modules)/],
use: options.defaultLoaders.babel,
},
]),
},
};
Expand Down
Loading

0 comments on commit 73e1f17

Please sign in to comment.