-
-
Notifications
You must be signed in to change notification settings - Fork 355
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'upstream/master' into auth-example
- Loading branch information
Showing
93 changed files
with
2,099 additions
and
1,172 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | 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 }} | ||
|
||
|
||
| environment variable name | 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 | 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.