{icon && } {title}
{description &&{description}
} - +Using optional Strapi features can provide some more filters: -- If the [Internationalization (i18n) plugin](/dev-docs/i18n) is enabled on a content-type, it's possible to filter by locale. +- If the [Internationalization (i18n) plugin](/user-docs/features/internationalization) is enabled on a content-type, it's possible to filter by locale. - If the [Draft & Publish](/user-docs/content-manager/saving-and-publishing-content) is enabled, it's possible to filter based on a `published` (default) or `draft` status. :::tip
-
+
JavaScript query (built with the qs library):
-
+` with your API token generated in the Strapi Admin panel.
:::
-## Security
-
-GraphQL is a query language allowing users to use a broader panel of inputs than traditional REST APIs. GraphQL APIs are inherently prone to security risks, such as credential leakage and denial of service attacks, that can be reduced by taking appropriate precautions.
-
+### GraphQL API
-### Disable introspection and playground in production
-
-In production environments, disabling the GraphQL Playground and the introspection query is recommended.
-If you haven't edited the [configuration file](/dev-docs/configurations/plugins#graphql), it is already disabled in production by default.
+The GraphQL plugin adds a GraphQL endpoint that can accessed through Strapi's GraphQL API:
-### Limit max depth and complexity
-
-A malicious user could send a query with a very high depth, which could overload your server. Use the `depthLimit` [configuration parameter](/dev-docs/configurations/plugins#graphql) to limit the maximum number of nested fields that can be queried in a single request. By default, `depthLimit` is set to 10 but can be set to a higher value during testing and development.
-
-:::tip
-To increase GraphQL security even further, 3rd-party tools can be used. See the guide about [using GraphQL Armor with Strapi on the forum](https://forum.strapi.io/t/use-graphql-armor-with-strapi/).
-:::
+
+
diff --git a/docusaurus/docs/dev-docs/plugins/sentry.md b/docusaurus/docs/dev-docs/plugins/sentry.md
index 261e84de98..93bfd618e2 100644
--- a/docusaurus/docs/dev-docs/plugins/sentry.md
+++ b/docusaurus/docs/dev-docs/plugins/sentry.md
@@ -10,16 +10,20 @@ tags:
# Sentry plugin
-This plugin enables you to track errors in your Strapi application using [Sentry](https://sentry.io/welcome/).
+This plugin enables you to track errors in your Strapi application using Sentry.
+
+:::prerequisites Identity Card of the Plugin
+
+
+
+::: By using the Sentry plugin you can: * Initialize a Sentry instance upon startup of a Strapi application * Send Strapi application errors as events to Sentry * Include additional metadata in Sentry events to assist in debugging -* Expose a [global Sentry service](#global-sentry-service-access) - -Begin by first [installing](#installation) the Sentry plugin, and then [configuring](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. +* Expose a global Sentry service usable by the Strapi server ## Installation @@ -47,21 +51,21 @@ npm install @strapi/plugin-sentry ## Configuration -Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: +Create or edit your `/config/plugins` file to configure the Sentry plugin. The following properties are available: | Property | Type | Default Value | Description | | -------- | ---- | ------------- |------------ | | `dsn` | string | `null` | Your Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). | -| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry. | -| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization. See the official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for all available options. | +| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g., OS, browser, etc.) to the events sent to Sentry. | +| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization (see official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for available options). | -An example configuration: +The following is an example basic configuration:
-```js title="./config/plugins.js"
+```js title="/config/plugins.js"
module.exports = ({ env }) => ({
// ...
@@ -80,7 +84,7 @@ module.exports = ({ env }) => ({
-```ts title="./config/plugins.ts"
+```ts title="/config/plugins.ts"
export default ({ env }) => ({
// ...
@@ -99,22 +103,29 @@ export default ({ env }) => ({
-### Environment configuration
+### Disabling for non-production environments
+
+If the `dsn` property is set to a nil value (`null` or `undefined`) while `sentry.enabled` is true, the Sentry plugin will be available to use in the running Strapi instance, but the service will not actually send errors to Sentry. That allows you to write code that runs on every environment without additional checks, but only send errors to Sentry in production.
+
+When you start Strapi with a nil `dsn` config property, the plugin will print the following warning:
`info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided` -Using the [`env` utility](/dev-docs/configurations/guides/access-cast-environment-variables), you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: +You can make use of that by using the [`env` utility](/dev-docs/configurations/guides/access-cast-environment-variables) to set the `dsn` configuration property depending on the environment.
-```js title="config/plugins.js"
-
+```js title="/config/plugins.js"
module.exports = ({ env }) => ({
- // ...
+ // …
sentry: {
- enabled: env('NODE_ENV') === 'production',
+ enabled: true,
+ config: {
+ // Only set `dsn` property in production
+ dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
+ },
},
- // ...
+ // …
});
```
@@ -122,14 +133,17 @@ module.exports = ({ env }) => ({
-```ts title="./config/plugins.ts"
-
+```ts title="/config/plugins.ts"
export default ({ env }) => ({
- // ...
+ // …
sentry: {
- enabled: env('NODE_ENV') === 'production',
+ enabled: true,
+ config: {
+ // Only set `dsn` property in production
+ dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
+ },
},
- // ...
+ // …
});
```
@@ -137,7 +151,42 @@ export default ({ env }) => ({
-## Global Sentry service access
+### Disabling the plugin completely
+
+Like every other Strapi plugin, you can also disable this plugin in the plugins configuration file. This will cause `strapi.plugins('sentry')` to return `undefined`:
+
+
+
+
+
+```js title="/config/plugins.js"
+module.exports = ({ env }) => ({
+ // …
+ sentry: {
+ enabled: false,
+ },
+ // …
+});
+```
+
+
+
+
+
+```ts title="/config/plugins.ts"
+export default ({ env }) => ({
+ // …
+ sentry: {
+ enabled: false,
+ },
+ // …
+});
+```
+
+
+
+
+## Usage
After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows:
@@ -150,14 +199,9 @@ This service exposes the following methods:
| Method | Description | Parameters |
| ------ | ----------- | ---------- |
| `sendError()` | Manually send errors to Sentry. |
-
-
+The `sendError()` method can be used as follows:
```js
try {
@@ -181,9 +225,7 @@ try {
}
```
-
-
-
+The `getInstance()` method is accessible as follows:
```js
const sentryInstance = strapi
@@ -191,6 +233,3 @@ const sentryInstance = strapi
.service('sentry')
.getInstance();
```
-
-
-
diff --git a/docusaurus/docs/dev-docs/plugins/upload.md b/docusaurus/docs/dev-docs/plugins/upload.md
index 01ca4c6c0d..21a0263e8a 100644
--- a/docusaurus/docs/dev-docs/plugins/upload.md
+++ b/docusaurus/docs/dev-docs/plugins/upload.md
@@ -11,12 +11,8 @@ tags:
---
-import NotV5 from '/docs/snippets/_not-updated-to-v5.md'
-
# Upload plugin
-
-
-
-
-```js
-import axios from 'axios';
-
-// Request API.
-axios
- .post('http://localhost:1337/api/auth/local', {
- identifier: 'user@strapi.io',
- password: 'strapiPassword',
- })
- .then(response => {
- // Handle success.
- console.log('Well done!');
- console.log('User profile', response.data.user);
- console.log('User token', response.data.jwt);
- })
- .catch(error => {
- // Handle error.
- console.log('An error occurred:', error.response);
- });
-```
-
-
-
-
-
-If you use **Postman**, set the **body** to **raw** and select **JSON** as your data format:
-
-```json
-{
- "identifier": "user@strapi.io",
- "password": "strapiPassword"
-}
-```
-
-If the request is successful you will receive the **user's JWT** in the `jwt` key:
-
-```json
-{
- "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNTc2OTM4MTUwLCJleHAiOjE1Nzk1MzAxNTB9.UgsjjXkAZ-anD257BF7y1hbjuY3ogNceKfTAQtzDEsU",
- "user": {
- "id": 1,
- "username": "user",
- ...
- }
-}
-```
-
-
-
-
-### Token usage
-
-The `jwt` may then be used for making permission-restricted API requests. To make an API request as a user place the JWT into an `Authorization` header of the `GET` request.
-
-Any request without a token will assume the `public` role permissions by default. Modify the permissions of each user's role in the admin dashboard.
-
-Authentication failures return a `401 (unauthorized)` error.
-
-#### Usage
-
-The `token` variable is the `data.jwt` received when logging in or registering.
-
-```js
-import axios from 'axios';
-
-const token = 'YOUR_TOKEN_HERE';
-
-// Request API.
-axios
- .get('http://localhost:1337/posts', {
- headers: {
- Authorization: `Bearer ${token}`,
- },
- })
- .then(response => {
- // Handle success.
- console.log('Data: ', response.data);
- })
- .catch(error => {
- // Handle error.
- console.log('An error occurred:', error.response);
- });
-```
-
-### JWT configuration
-
-You can configure the JWT generation by using the [plugins configuration file](/dev-docs/configurations/plugins).
-
-Strapi uses [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) to generate the JWT.
-
-Available options:
-
-- `jwtSecret`: random string used to create new JWTs, typically set using the `JWT_SECRET` [environment variable](/dev-docs/configurations/environment#strapi).
-- `jwt.expiresIn`: expressed in seconds or a string describing a time span.
- Eg: 60, "45m", "10h", "2 days", "7d", "2y". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (minutes, hours, days, years, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms"). - -
-
-
-
-```js title="./config/plugins.js"
-
-module.exports = ({ env }) => ({
- // ...
- 'users-permissions': {
- config: {
- jwt: {
- expiresIn: '7d',
- },
- },
- },
- // ...
-});
-```
-
-
-
-
-
-```ts title="./config/plugins.ts"
-
-export default ({ env }) => ({
- // ...
- 'users-permissions': {
- config: {
- jwt: {
- expiresIn: '7d',
- },
- },
- },
- // ...
-});
-```
-
-
-
-
-
-:::warning
-Setting JWT expiry for more than 30 days is **not recommended** due to security concerns.
-:::
-
-### Registration
-
-#### Configuration
-
-If you have added any additional fields to your user model that need to be accepted on registration, they need to be added to the list of allowed fields in the `register` configuration option, otherwise they will not be accepted.
-
-For example, if you have added a field called "nickname" that you wish to accept from the API on user registration:
-
-
-
-
-
-```js title="./config/plugins.js"
-module.exports = ({ env }) => ({
- // ...
- "users-permissions": {
- config: {
- register: {
- allowedFields: ["nickname"],
- },
- },
- },
- // ...
-});
-```
-
-
-
-
-
-```ts title="./config/plugins.ts"
-export default ({ env }) => ({
- // ...
- "users-permissions": {
- config: {
- register: {
- allowedFields: ["nickname"],
- },
- },
- },
- // ...
-});
-```
-
-
-
-
-
-
-#### Usage
-
-Creates a new user in the database with a default role as 'registered'.
-
-```js
-import axios from 'axios';
-
-// Request API.
-// Add your own code here to customize or restrict how the public can register new users.
-axios
- .post('http://localhost:1337/api/auth/local/register', {
- username: 'Strapi user',
- email: 'user@strapi.io',
- password: 'strapiPassword',
- })
- .then(response => {
- // Handle success.
- console.log('Well done!');
- console.log('User profile', response.data.user);
- console.log('User token', response.data.jwt);
- })
- .catch(error => {
- // Handle error.
- console.log('An error occurred:', error.response);
- });
-```
-
-### Providers
-
- [Grant](https://github.com/simov/grant) and [Purest](https://github.com/simov/purest) allow you to use OAuth and OAuth2 providers to enable authentication in your application.
-
-For a better understanding, review the following description of the login flow. The example uses `github` as the provider but it works the same for other providers.
-
-#### Understanding the login flow
-
-Let's say that:
-* Strapi's backend is located at: `strapi.website.com`, and
-* Your app frontend is located at: `website.com`
-
-1. The user goes on your frontend app (`https://website.com`) and clicks on your button `connect with Github`.
-2. The frontend redirects the tab to the backend URL: `https://strapi.website.com/api/connect/github`.
-3. The backend redirects the tab to the GitHub login page where the user logs in.
-4. Once done, Github redirects the tab to the backend URL:`https://strapi.website.com/api/connect/github/callback?code=abcdef`.
-5. The backend uses the given `code` to get an `access_token` from Github that can be used for a period of time to make authorized requests to Github to get the user info.
-6. Then, the backend redirects the tab to the url of your choice with the param `access_token` (example: `http://website.com/connect/github/redirect?access_token=eyfvg`).
-7. The frontend (`http://website.com/connect/github/redirect`) calls the backend with `https://strapi.website.com/api/auth/github/callback?access_token=eyfvg` that returns the Strapi user profile with its `jwt`.
(Under the hood, the backend asks Github for the user's profile and a match is done on Github user's email address and Strapi user's email address). -8. The frontend now possesses the user's `jwt`, which means the user is connected and the frontend can make authenticated requests to the backend! - -An example of a frontend app that handles this flow can be found here: [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react). - -#### Setting up the server url - -Before setting up a provider you must specify the absolute url of your backend in `server.js`. - -**example -** `config/server.js` - -
-
-
-
-```js title="config/server.js"
-
-module.exports = ({ env }) => ({
- host: env('HOST', '0.0.0.0'),
- port: env.int('PORT', 1337),
- url: env('', 'http://localhost:1337'),
-});
-```
-
-
-
-
-
-```ts title="config/server.ts"
-
-export default ({ env }) => ({
- host: env('HOST', '0.0.0.0'),
- port: env.int('PORT', 1337),
- url: env('', 'http://localhost:1337'),
-});
-```
-
-
-
-
-
-
-:::tip
-Later you will give this url to your provider.
For development, some providers accept the use of localhost urls but many don't. In this case we recommend to use [ngrok](https://ngrok.com/docs) (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (ex: `url: env('', 'https://5299e8514242.ngrok.io'),`). -::: - -#### Setting up the provider - examples - -Instead of a generic explanation we decided to show an example for each provider. You can also [create your own custom provider](#creating-a-custom-provider). - -In the following examples, the frontend app will be the [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react).
-It (the frontend app) will be running on `http://localhost:3000`.
-Strapi (the backend) will be running on `http://localhost:1337`. - -
-
-
-
-
-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **GitHub** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 53de5258f8472c140917 - - **Client Secret**: fb9d0fe1d345d9ac7f83d7a1e646b37c554dae8b - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/github/redirect` - -
-
-
-
-
-
-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) -- Click on **Add a New App** button -- Fill the **Display Name** in the modal and create the app -- Setup a **Facebook Login** product -- Click on the **PRODUCTS > Facebook login > Settings** link in the left menu -- Fill the information and save (replace with your own ngrok url): - - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/facebook/callback` -- Then, click on **Settings** in the left menu -- Then on **Basic** link -- You should see your Application ID and secret, save them for later - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Facebook** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 2408954435875229 - - **Client Secret**: 4fe04b740b69f31ea410b9391ff3b5b0 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/facebook/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://console.developers.google.com/](https://console.developers.google.com/) -- Click on the **Select a project** dropdown in the top menu -- Then click **NEW PROJECT** button -- Fill the **Project name** input and create - -Wait a few seconds while the application is created. - -- On the project dropdown, select your new project -- Click on **Go to APIs overview** under the **APIs** card -- Then click on the **Credentials** link in the left menu -- Click on **OAuth consent screen** button -- Choose **External** and click on **create** -- Fill the **Application name** and save -- Then click on **Create credentials** button -- Choose **OAuth client ID** option -- Fill the information: - - **Name**: `Strapi Auth` - - **Authorized redirect URIs**: `http://localhost:1337/api/connect/google/callback` -- Click on **OAuth 2.0 Client IDs** name of the client you just created -- You should see your Application ID and secret, save them for later - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Google** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 226437944084-o2mojv5i4lfnng9q8kq3jkf5v03avemk.apps.googleusercontent.com - - **Client Secret**: aiTbMoiuJQflSBy6uQrfgsni - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/google/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://aws.amazon.com/console/](https://aws.amazon.com/console/) -- If needed, select your **Region** in the top right corner next to the Support dropdown -- Select the **Services** dropdown in the top left corner -- Click on **Cognito** in the `Security, Identity & Compliance` section -- Then click on the **Manage User Pools** button -- If applicable either create or use an existing user pool. You will find hereafter a tutorial to create a User Pool
[https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) -- Go to the **App clients** section in your cognito user pool and create a new client with the name `Strapi Auth` and set all the parameters and then click on **Create app client** -- You should now have an **App client id** and by clicking on the button **Show Details** you will be able to see the **App client secret**. Do copy those two values **App client id** and **App client secret** somewhere for later use when configuring the AWS Cognito provider in Strapi. -- Go to the **App integration section** and click on **App client settings** -- Look for your app client named `Strapi Auth` and enable Cognito User Pool by checking it in the **Enabled Identity Providers** section of your newly created App client -- Fill in your callback URL and Sign out URL with the value `http://localhost:1337/api/connect/cognito/callback` or the one provided by your AWS Cognito provider in Strapi -- In the **Oauth 2.0** section select `Authorization code grant` and `Implicit grant` for the **Allowed OAuth Flows** and select `email`, `openid` and `profile` for the **Allowed OAuth Scopes** -- You can now click on **Save changes** and if you have already configured your domain name then you should be able to see a link to the **Launch Hosted UI**. You can click on it in order to display the AWS Cognito login page. In case you haven't yet configured your domain name, use the link **Choose domain name** at the bottom right of the page in order to configure your domain name. On that page you will have an `Amazon Cognito Domain` section where a `Domain prefix` is already setup. Type a domain prefix to use for the sign-up and sign-in pages that are hosted by Amazon Cognito, this domain prefix together with the `.auth.YOUR_REGION.amazoncognito.com` will be the **Host URI (Subdomain)** value for your strapi configuration later on. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Cognito** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: fill in the **App client id** (`5bd7a786qdupjmi0b3s10vegdt`) - - **Client Secret**: fill in the **App client secret** (`19c5c78dsfsdfssfsdfhpdb4nkpb145vesdfdsfsffgh7vwd6g45jlipbpb`) - - **Host URI (Subdomain)**: fill in the URL value that you copied earlier (`myapp67b50345-67b50b17-local.auth.eu-central-1.amazoncognito.com`) - - **The redirect URL to your front-end app**: if you are using strapi react-login [https://github.com/strapi/strapi-examples/tree/master/examples/login-react/](https://github.com/strapi/strapi-examples/tree/master/examples/login-react/) use `http://localhost:3000/connect/cognito/redirect` but if you do not yet have a front-end app to test your Cognito configuration you can then use the following URL `http://localhost:1337/api/auth/cognito/callback` - -
-
-
-
-
-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
[https://developer.twitter.com/en/apps](https://developer.twitter.com/en/apps) -- Click on **Create an app** button -- Fill the information (replace with your own ngrok url): - - **App name**: Strapi Twitter auth - - **Application description**: This is a demo app for Strapi auth - - **Tell us how this app will be used**: - here write a message enough long - -- At the end of the process you should see your Application ID and secret, save them for later -- Go to you app setting and click on edit **Authentication settings** -- Enable **3rd party authentication** AND **Request email address from users** -- Fill the information (replace with your own ngrok url): - - **Callback URLs**: `https://65e60559.ngrok.io/api/connect/twitter/callback` - - **Website URL**: `https://65e60559.ngrok.io` - - **Privacy policy**: `https://d73e70e88872.ngrok.io` - - **Terms of service**: `https://d73e70e88872.ngrok.io` - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Twitter** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **API Key**: yfN4ycGGmKXiS1njtIYxuN5IH - - **Api Secret**: Nag1en8S4VwqurBvlW5OaFyKlzqrXFeyWhph6CZlpGA2V3VR3T - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitter/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://discordapp.com/developers/applications/](https://discordapp.com/developers/applications/) -- Click on **New application** button -- Fill the **name** and create -- Click on **OAuth2** in the left menu -- And click on **Add redirect** button -- Fill the **Redirect** input with `http://localhost:1337/api/connect/discord/callback` URL and save -- Click on **General information** in the left menu -- You should see your Application ID and secret, save them for later - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Discord** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 665118465148846081 - - **Client Secret**: iJbr7mkyqyut-J2hGvvSDch_5Dw5U77J - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/discord/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps) -- Click on **Register Your Application** button -- Fill the information: - - **Name**: Strapi auth - - **OAuth Redirect URLs**: `http://localhost:1337/api/connect/twitch/callback` - - **Category**: Choose a category -- Click on **Manage** button of your new app -- Generate a new **Client Secret** with the **New Secret** button -- You should see your Application ID and secret, save them for later - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Twitch** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: amuy279g8wt68qlht3u4gek4oykh5j - - **Client Secret**: dapssh10uo97gg2l25qufr8wen3yr6 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitch/redirect` - -
-
-
-
-
-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/login-react)) with the generated ngrok url. - -
[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) -- Click on **Add a New App** button -- Fill the **Display Name** in the modal and create the app -- Setup an **Instagram** product -- Click on the **PRODUCTS > Instagram > Basic Display** link in the left menu -- Then click on the **Create new application** button (and valid the modal) -- Fill the information (replace with your own ngrok url): - - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/instagram/callback` - - **Deauthorize**: `https://65e60559.ngrok.io` - - **Data Deletion Requests**: `https://65e60559.ngrok.io` -- On the **App Review for Instagram Basic Display** click on **Add to submission** for **instagram_graph_user_profile**. -- You should see your Application ID and secret, save them for later - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Instagram** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 563883201184965 - - **Client Secret**: f5ba10a7dd78c2410ab6b8a35ab28226 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/instagram/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://vk.com/apps?act=manage](https://vk.com/apps?act=manage) -- Click on **Create app** button -- Fill the information: - - **Title**: Strapi auth - - **Platform**: Choose **Website** option - - **Website address**: `http://localhost:1337` - - **Base domain**: `localhost` -- Click on the **Settings** link in the left menu -- Click on the **Open API** link to enable this option -- Fill the information: - - **Authorized redirect URL**: `http://localhost:1337/api/connect/vk/callback` - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **VK** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: 7276416 - - **Client Secret**: cFBUSghLXGuxqnCyw1N3 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/vk/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://www.linkedin.com/developers/apps](https://www.linkedin.com/developers/apps) -- Click on **Create app** button -- Fill the information: - - **App name**: Strapi auth - - **LinkedIn Page**: Enter a LinkedIn page name to associate with the app or click **Create a new LinkedIn Page** to create a new one - - **App Logo**: Upload a square image that is at least 100x100 pixels. -- Click on the **Create app** to create the app -- On the app page click on **Auth** tab -- Fill the information: - - **Authorized redirect URL**: `http://localhost:1337/api/connect/linkedin/callback` -- On the app page click on **Products** tab. -- Select `Sign In with LinkedIn` from the product list to enable it. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **LinkedIn** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: 84witsxk641rlv - - **Client Secret**: HdXO7a7mkrU5a6WN - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/linkedin/redirect` - -
-
-
-
-
[http://localhost:1337/admin/plugins/users-permissions/providers](http://localhost:1337/admin/plugins/users-permissions/providers) -- Click on the **Cas** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: thestrapiclientid - - **Client Secret**: thestrapiclientsecret - - **The redirect URL to your front-end app**: `http://localhost:1337/api/connect/cas/redirect` - - **The Provider Subdomain such that the following URLs are correct for the CAS deployment you are targeting:** - ``` - authorize_url: https://[subdomain]/oidc/authorize - access_url: https://[subdomain]/oidc/token - profile_url: https://[subdomain]/oidc/profile - ``` - For example, if running CAS locally with a login URL of: `https://localhost:8443/cas/login`, the value for the provider subdomain would be `localhost:8443/cas`. - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[https://www.reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) -- Click on the **create another app...** button near the bottom -- Select **web app** for the type -- Fill the **name** and **redirect uri** input in -- Click the **create app** button -- Note that the **Client ID** is located under the app type (web app) - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Reddit** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: hmxSBOit0SCjSQ - - **Client Secret**: gwR9hCjK_PMYVYNGeDLS4WLB8g7xqg - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/reddit/redirect` - -
-
-
-
-
-The use of `ngrok` is not needed. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Auth0** provider -- Fill the information: - - Enable: `ON` - - Client ID: ``
- - Client Secret: ``
- - Subdomain: ``, example it is the part in bold in the following url: https://**my-tenant.eu**.auth0.com/
- - The redirect URL to your front-end app: `http://localhost:3000/connect/auth0`
-
-
-
-
-
-
-Use `ngrok` to serve the backend app. - -```bash -ngrok http 1337 -``` - -Don't forget to update the server url in the Strapi config file `./config/server.js` and the server URL in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok URL. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Patreon** provider -- Fill the information: - - Enable: `ON` - - Client ID: `` - as above
- - Client Secret: `` - as above
-
-
-
-
-
-
-The use of `ngrok` is not needed. - -
[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Keycloak** provider -- Fill the information: - - Enable: `ON` - - Client ID: ``
- - Client Secret: ``
- - Subdomain: ``, example is either `keycloak.example.com/realms/strapitest` or `keycloak.example.com/auth/realms/strapitest` **without the protocol before it**
- - The redirect URL to your front-end app: `http://localhost:3000/connect/keycloak/redirect`
- - (Optional) Set the JWKS URL if you have a custom JWKS URL, example is like `https://keycloak.example.com/auth/realms/strapitest/protocol/openid-connect/certs`
-
-
-
-
-Your configuration is done.
-Launch the backend and the [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react), go to `http://localhost:3000` and try to connect to the provider your configured.
-
-##### Creating a custom provider
-
-You can also use the `register` lifecycle function to create your own custom provider in the `src/index.js|ts` file of your Strapi application. Use the following code example adjusted to your needs:
-
-```js title="/src/index.js"
-module.exports = {
- register({ strapi }) {
- strapi
- .plugin("users-permissions")
- .service("providers-registry")
- .add("example-provider-name", {
- icon: "",
- enabled: true,
- grantConfig: {
- key: "",
- secret: "",
- callback: `${strapi.config.server.url}/auth/example-provider-name/callback`,
- scope: ["email"],
- authorize_url: "https://awesome.com/authorize",
- access_url: "https://awesome.com/token",
- oauth: 2,
- },
- async authCallback({ accessToken, providers, purest }) {
- // use whatever you want here to get the user info
- return {
- username: "test",
- email: "test",
- };
- },
- });
- },
-};
-```
-
-For additional information on parameters passed to `grantConfig`, please refer to the [`grant` documentation](https://github.com/simov/grant). For additional information about `purest` please refer to [`purest` documentation](https://github.com/simov/purest).
-
-#### Setup the frontend
-
-Once you have configured strapi and the provider, in your frontend app you have to :
-
-- Create a button that links to `GET STRAPI_BACKEND_URL/api/connect/${provider}` (ex: `https://strapi.mywebsite/api/connect/github`).
-- Create a frontend route like `FRONTEND_URL/connect/${provider}/redirect` that have to handle the `access_token` param and that have to request `STRAPI_BACKEND_URL/api/auth/${provider}/callback` with the `access_token` parameter.
- The JSON request response will be `{ "jwt": "...", "user": {...} }`. - -Now you can make authenticated requests. More info here: [token usage](#token-usage). - -:::caution Troubleshooting - -- **Error 429**: It's most likely because your login flow fell into a loop. To make new requests to the backend, you need to wait a few minutes or restart the backend. -- **Grant: missing session or misconfigured provider**: It may be due to many things. - - **The redirect url can't be built**: Make sure you have set the backend url in `config/server.js`: [Setting up the server url](#setting-up-the-server-url) - - **A session/cookie/cache problem**: You can try again in a private tab. - - **The incorrect use of a domain with ngrok**: Check your urls and make sure that you use the ngrok url instead of `http://localhost:1337`. Don't forget to check the backend url set in the example app at `src/config.js`. -- **You can't access your admin panel**: It's most likely because you built it with the backend url set with a ngrok url and you stopped/restarted ngrok. You need to replace the backend url with the new ngrok url and run `yarn build` or `npm run build` again. -::: - -### Reset password - -**Can only be used for users registered using the email provider.** - -
-
-
-
-The assumed general flow:
-
-1. The user goes to your **forgotten password page**.
-2. The user enters their email address.
-3. Your forgotten password page sends a request to the backend to send an email with the reset password link to the user.
-4. The user receives the email and clicks on the special link.
-5. The link redirects the user to your **reset password page**.
-6. The user enters their new password.
-7. The **reset password page** sends a request to the backend with the new password.
-8. If the request contains the code contained in the link at step 3, the password is updated.
-9. The user can log in with the new password.
-
-The following section details steps 3 and 7.
-
-#### Forgotten password: ask for the reset password link
-
-This action sends an email to a user with the link to your reset password page. The link will be enriched with the url param `code` that is needed for the [reset password](#reset-password) at step 7.
-
-First, you must specify the following:
-
-- In the admin panel: **Settings > USERS & PERMISSIONS PLUGIN > Advanced Settings > Reset Password** page, the `url` to your reset password page.
-- In the admin panel: **Settings > USERS & PERMISSIONS PLUGIN > Email Template** page, the **Shipper email**.
-
-Then, your **forgotten password page** has to make the following request to your backend:
-
-```js
-import axios from 'axios';
-
-// Request API.
-axios
- .post('http://localhost:1337/api/auth/forgot-password', {
- email: 'user@strapi.io', // user's email
- })
- .then(response => {
- console.log('Your user received an email');
- })
- .catch(error => {
- console.log('An error occurred:', error.response);
- });
-```
-
-#### Reset Password: send the new password
-
-This action will update the user password.
-This also works with the [GraphQL Plugin](./graphql), with the `resetPassword` mutation.
-
-Your **reset password page** has to make the following request to your backend:
-
-```js
-import axios from 'axios';
-
-// Request API.
-axios
- .post('http://localhost:1337/api/auth/reset-password', {
- code: 'privateCode', // code contained in the reset link of step 3.
- password: 'userNewPassword',
- passwordConfirmation: 'userNewPassword',
- })
- .then(response => {
- console.log("Your user's password has been reset.");
- })
- .catch(error => {
- console.log('An error occurred:', error.response);
- });
-```
-
-
-
-
-
-You can also update an authenticated user password through the `/change-password` API endpoint:
-
-```js
-import axios from 'axios';
-
-// Request API.
-axios.post(
- 'http://localhost:1337/api/auth/change-password',
- {
- currentPassword: 'currentPassword',
- password: 'userNewPassword',
- passwordConfirmation: 'userNewPassword',
- },
- {
- headers: {
- Authorization: 'Bearer ',
- },
- }
-);
-```
-
-
-
-
-
-### Email validation
-
-:::note
-In production, make sure the `url` config property is set. Otherwise the validation link will redirect to `localhost`. More info on the config [here](/dev-docs/configurations/server).
-:::
-
-After registering, if you have set **Enable email confirmation** to **ON**, the user will receive a confirmation link by email. The user has to click on it to validate their registration.
-
-Example of the confirmation link: `https://yourwebsite.com/api/auth/email-confirmation?confirmation=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MywiaWF0IjoxNTk0OTgxMTE3LCJleHAiOjE1OTc1NzMxMTd9.0WeB-mvuguMyr4eY8CypTZDkunR--vZYzZH6h6sChFg`
-
-If needed you can re-send the confirmation email by making the following request:
-
-```js
-import axios from 'axios';
-
-// Request API.
-axios
- .post(`http://localhost:1337/api/auth/send-email-confirmation`, {
- email: 'user@strapi.io', // user's email
- })
- .then(response => {
- console.log('Your user received an email');
- })
- .catch(error => {
- console.error('An error occurred:', error.response);
- });
-```
-
-## User object in Strapi context
-
-The `user` object is available to successfully authenticated requests.
-
-The authenticated `user` object is a property of `ctx.state`.
-
-```js
-create: async ctx => {
- const { id } = ctx.state.user;
-
- const depositObj = {
- ...ctx.request.body,
- depositor: id,
- };
-
- const data = await strapi.services.deposit.add(depositObj);
-
- // Send 201 `created`
- ctx.created(data);
-};
-```
-
-
-
-## Templating emails
-
-By default this plugin comes with two templates: reset password and email address confirmation. The templates use Lodash's `template()` method to populate the variables.
-
-You can update these templates under **Plugins** > **Roles & Permissions** > **Email Templates** tab in the admin panel.
-
-### Reset Password
-
-- `USER` (object)
- - `username`
- - `email`
-- `TOKEN` corresponds to the token generated to be able to reset the password.
-- `URL` is the link where the user will be redirected after clicking on it in the email.
-- `SERVER_URL` is the absolute server url (configured in server configuration).
-
-### Email address confirmation
-
-- `USER` (object)
- - `username`
- - `email`
-- `CODE` corresponds to the CODE generated to be able confirm the user email.
-- `URL` is the Strapi backend URL that confirms the code (by default `/auth/email-confirmation`).
-- `SERVER_URL` is the absolute server url (configured in server configuration).
-
-## 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`.
-
-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.
-
-By default you can set a `JWT_SECRET` environment variable and it will be used as secret. If you want to use another variable you can update the configuration file.
-
-
-
-
-
-```js title="./extensions/users-permissions/config/jwt.js"
-
-module.exports = {
- jwtSecret: process.env.SOME_ENV_VAR,
-};
-```
-
-
-
-
-
-```ts title="./extensions/users-permissions/config/jwt.ts"
-
-export default {
- jwtSecret: process.env.SOME_ENV_VAR,
-};
-```
-
-
-
-
-
-:::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:
-
-
-```bash
-#Install the AWS S3 provider for the Upload plugin
+Install the AWS S3 provider for the Upload (Media Library) feature:
+```bash
yarn add @strapi/provider-upload-aws-s3
+```
-# Install the Sendgrid provider for the Email plugin
-yarn add @strapi/provider-email-sendgrid --save
+Install the Sendgrid provider for the Email feature:
+```bash
+yarn add @strapi/provider-email-sendgrid
```
-```bash
-#Install the AWS S3 provider for the Upload plugin
+Install the AWS S3 provider for the Upload (Media Library) feature:
+```bash
npm install @strapi/provider-upload-aws-s3 --save
+```
-# Install the Sendgrid provider for the Email plugin
-npm install @strapi/provider-email-sendgrid --save
+Install the Sendgrid provider for the Email feature:
+```bash
+npm install @strapi/provider-email-sendgrid --save
```
@@ -63,21 +61,21 @@ npm install @strapi/provider-email-sendgrid --save
## Configuring providers
-Newly installed providers are enabled and configured in the `./config/plugins.js` file. If this file does not exist you must create it.
+Newly installed providers are enabled and configured in [the `/config/plugins` file](/dev-docs/configurations/plugins). If this file does not exist you must create it.
Each provider will have different configuration settings available. Review the respective entry for that provider in the [Marketplace](../../../user-docs/plugins/installing-plugins-via-marketplace) or [npm](https://www.npmjs.com/) to learn more.
-Below are example configurations for the Upload and Email plugins.
+The following are example configurations for the Upload (Media Library) and Email features:
-
+
-```js title="./config/plugins.js"
+```js title="/config/plugins.js"
module.exports = ({ env }) => ({
// ...
@@ -115,7 +113,7 @@ module.exports = ({ env }) => ({
-```ts title="./config/plugins.ts"
+```ts title="/config/plugins.ts"
export default ({ env }) => ({
// ...
@@ -147,13 +145,13 @@ Strapi has a default [`security` middleware](/dev-docs/configurations/middleware
-
+
-```js title="./config/plugins.js"
+```js title="/config/plugins.js"
module.exports = ({ env }) => ({
// ...
@@ -178,7 +176,7 @@ module.exports = ({ env }) => ({
-```ts title="./config/plugins.ts"
+```ts title="/config/plugins.ts"
export default ({ env }) => ({
// ...
@@ -205,8 +203,8 @@ export default ({ env }) => ({
:::note
-* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js` (See [Environments](/dev-docs/configurations/environment)).
-* Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js` file is in the correct folder.
+* When using a different provider per environment, specify the correct configuration in `/config/env/${yourEnvironment}/plugins.js|ts` (See [Environments](/dev-docs/configurations/environment)).
+* Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js|ts` file is in the correct folder.
* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test (See [Configure templates locally](/user-docs/settings/configuring-users-permissions-plugin-settings#configuring-email-templates)).
:::
@@ -218,16 +216,16 @@ export default ({ env }) => ({
When configuring your provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials.
-You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the default configuration.
+You can set a specific configuration in the `/config/env/{env}/plugins.js|ts` configuration file and it will be used to overwrite the default configuration.
## Creating providers
To implement your own custom provider you must [create a Node.js module](https://docs.npmjs.com/creating-node-js-modules).
-The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins:
+The interface that must be exported depends on the plugin you are developing the provider for. The following are templates for the Upload (Media Library) and Email features:
-
+
@@ -319,7 +317,7 @@ export default {
-
+
@@ -358,8 +356,8 @@ export {
In the send function you will have access to:
-* `providerOptions` that contains configurations written in `plugins.js`
-* `settings` that contains configurations written in `plugins.js`
+* `providerOptions` that contains configurations written in `plugins.js|ts`
+* `settings` that contains configurations written in `plugins.js|ts`
* `options` that contains options you send when you call the send function from the email plugin service
You can review the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for example implementations.
@@ -371,7 +369,7 @@ After creating your new provider you can [publish it to npm](https://docs.npmjs.
If you want to create your own provider without publishing it on npm you can follow these steps:
1. Create a `providers` folder in your application.
-2. Create your provider (e.g. `./providers/strapi-provider--`)
+2. Create your provider (e.g. `/providers/strapi-provider--`)
3. Then update your `package.json` to link your `strapi-provider--` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider.
```json
@@ -385,10 +383,10 @@ If you want to create your own provider without publishing it on npm you can fol
}
```
-4. Update your `./config/plugins.js` file to [configure the provider](#configuring-providers).
-5. Finally, run `yarn install` or `npm install` to install your new custom provider.
+4. Update your `/config/plugins.js|ts` file to [configure the provider](#configuring-providers).
+5. Finally, run `yarn` or `npm install` to install your new custom provider.
-## Creating private providers
+### Creating private providers
You can set up a private provider, meaning that every asset URL displayed in the Content Manager will be signed for secure access.
@@ -404,7 +402,7 @@ Note that for security reasons, the content API will not provide any signed URLs
To create a private `aws-s3` provider:
-1. Create a `./providers/aws-s3` folder in your application. See [Local Providers](#local-providers) for more information.
+1. Create a `/providers/aws-s3` folder in your application. See [Local Providers](#local-providers) for more information.
2. Implement the `isPrivate()` method in the `aws-s3` provider to return `true`.
3. Implement the `getSignedUrl(file)` method in the `aws-s3` provider to generate a signed URL for the given file.
@@ -412,7 +410,7 @@ To create a private `aws-s3` provider:
-```js title="./providers/aws-s3/index.js"
+```js title="/providers/aws-s3/index.js"
// aws-s3 provider
module.exports = {
@@ -451,7 +449,7 @@ module.exports = {
-```ts title="./providers/aws-s3/index.ts"
+```ts title="/providers/aws-s3/index.ts"
// aws-s3 provider
export = {
diff --git a/docusaurus/docs/dev-docs/quick-start.md b/docusaurus/docs/dev-docs/quick-start.md
index 14b9fd345d..e16e7b6c3a 100644
--- a/docusaurus/docs/dev-docs/quick-start.md
+++ b/docusaurus/docs/dev-docs/quick-start.md
@@ -16,8 +16,6 @@ import InstallPrerequisites from '/docs/snippets/installation-prerequisites.md'
# Quick Start Guide
-
JavaScript query (built with the qs library):
-
+
-```js title"./src/index.js"
+```js title"/src/index.js"
module.exports = {
register({ strapi }) {
@@ -827,7 +839,7 @@ module.exports = {
-```ts title"./src/index.ts"
+```ts title"/src/index.ts"
export default {
register({ strapi }) {
@@ -897,11 +909,32 @@ export default {
-## Usage with the Users & Permissions plugin
+##### Security
+
+GraphQL is a query language allowing users to use a broader panel of inputs than traditional REST APIs. GraphQL APIs are inherently prone to security risks, such as credential leakage and denial of service attacks, that can be reduced by taking appropriate precautions.
+
+###### Disable introspection and playground in production
+
+In production environments, disabling the GraphQL Playground and the introspection query is recommended.
+If you haven't edited the [configuration file](/dev-docs/configurations/plugins#graphql), it is already disabled in production by default.
+
+###### Limit max depth and complexity
+
+A malicious user could send a query with a very high depth, which could overload your server. Use the `depthLimit` [configuration parameter](/dev-docs/configurations/plugins#graphql) to limit the maximum number of nested fields that can be queried in a single request. By default, `depthLimit` is set to 10 but can be set to a higher value during testing and development.
+
+:::tip
+To increase GraphQL security even further, 3rd-party tools can be used. See the guide about [using GraphQL Armor with Strapi on the forum](https://forum.strapi.io/t/use-graphql-armor-with-strapi/).
+:::
+
+## Usage
+
+The GraphQL plugin adds a GraphQL endpoint accessible and provides access to a GraphQL playground, accessing at the `/graphql` route of the Strapi admin panel, to interactively build your queries and mutations and read documentation tailored to your content types. For detailed instructions on how to use the GraphQL Playground, please refer to the official [Apollo Server documentation](https://www.apollographql.com/docs/apollo-server/v2/testing/graphql-playground).
+
+### Usage with the Users & Permissions plugin
The [Users & Permissions plugin](/dev-docs/plugins/users-permissions) is an optional plugin that allows protecting the API with a full authentication process.
-### Registration
+#### Registration
Usually you need to sign up or register before being recognized as a user then perform authorized requests.
@@ -924,7 +957,7 @@ mutation {
You should see a new user is created in the `Users` collection type in your Strapi admin panel.
-### Authentication
+#### Authentication
To perform authorized requests, you must first get a JWT:
@@ -942,8 +975,7 @@ mutation {
Then on each request, send along an `Authorization` header in the form of `{ "Authorization": "Bearer YOUR_JWT_GOES_HERE" }`. This can be set in the HTTP Headers section of your GraphQL Playground.
-
-## API tokens
+#### Usage with API tokens
To use API tokens for authentication, pass the token in the `Authorization` header using the format `Bearer your-api-token`.
@@ -959,20 +991,10 @@ Using API tokens in the the GraphQL playground requires adding the authorization
Replace `JavaScript query (built with the qs library):
-
+
- -
-
-
-`GET /api/articles?status=draft`
-
-
-
-
-
-```json {21}
-{
- "data": [
- // …
- {
- "id": 5,
- "documentId": "znrlzntu9ei5onjvwfaalu2v",
- "Name": "Biscotte Restaurant",
- "Description": [
- {
- "type": "paragraph",
- "children": [
- {
- "type": "text",
- "text": "This is the draft version."
- }
- ]
- }
- ],
- "createdAt": "2024-03-06T13:43:30.172Z",
- "updatedAt": "2024-03-06T21:38:46.353Z",
- "publishedAt": null,
- "locale": "en"
- },
- // …
- ],
- "meta": {
- "pagination": {
- "page": 1,
- "pageSize": 25,
- "pageCount": 1,
- "total": 4
- }
- }
-}
-```
-
-
-
diff --git a/docusaurus/docs/dev-docs/api/rest/guides/intro.md b/docusaurus/docs/dev-docs/api/rest/guides/intro.md
index 2adfb98597..82fd2d71d6 100644
--- a/docusaurus/docs/dev-docs/api/rest/guides/intro.md
+++ b/docusaurus/docs/dev-docs/api/rest/guides/intro.md
@@ -1,7 +1,7 @@
---
title: REST API Guides
description: Deep dive into some specific REST API topics using guides that extensively explain some use cases or give step-by-step instructions.
-displayed_sidebar: restApiSidebar
+displayed_sidebar: cmsSidebar
sidebar_label: Guides
pagination_prev: dev-docs/api/rest
pagination_next: dev-docs/api/rest/guides/understanding-populate
diff --git a/docusaurus/docs/dev-docs/api/rest/guides/populate-creator-fields.md b/docusaurus/docs/dev-docs/api/rest/guides/populate-creator-fields.md
index 582baf8c92..71300269ce 100644
--- a/docusaurus/docs/dev-docs/api/rest/guides/populate-creator-fields.md
+++ b/docusaurus/docs/dev-docs/api/rest/guides/populate-creator-fields.md
@@ -1,6 +1,7 @@
---
title: How to populate creator fields
description: Learn how to populate creator fields such as createdBy and updatedBy by creating a custom controller that leverages the populate parameter.
+displayed_sidebar: cmsSidebar
tags:
- API
- Content API
@@ -13,12 +14,8 @@ tags:
- updatedBy
---
-import NotV5 from '/docs/snippets/_not-updated-to-v5.md'
-
# 🛠️ How to populate creator fields such as `createdBy` and `updatedBy`
-
@@ -137,7 +111,7 @@ The following table lists the new possible use cases added by i18n to the REST A
-### Get a document in a specific locale {#rest-get}
+### `GET` Get a document in a specific locale {#rest-get}
To get a specific document in a given locale, add the `locale` parameter to the query:
@@ -232,7 +206,7 @@ To get a specific single type document in a given locale, add the `locale` param
-### Create a new localized document for a collection type {#rest-create}
+### `POST` Create a new localized document for a collection type {#rest-create}
To create a localized document from scratch, send a POST request to the Content API. Depending on whether you want to create it for the default locale or for another locale, you might need to pass the `locale` parameter in the request's body
@@ -322,7 +296,7 @@ To create a localized entry for a locale different from the default one, add the
-### Create a new, or update an existing, locale version for an existing document {#rest-update}
+### `PUT` Create a new, or update an existing, locale version for an existing document {#rest-update}
With `PUT` requests sent to an existing document, you can:
@@ -434,7 +408,7 @@ To create a new locale for an existing single type document, add the `locale` pa
-### Delete a locale version of a document {#rest-delete} +### `DELETE` Delete a locale version of a document {#rest-delete} To delete a locale version of a document, send a `DELETE` request with the appropriate `locale` parameter. @@ -459,148 +433,3 @@ To delete only a specific locale version of a single type document, add the `loc `DELETE /api/homepage?locale=fr` - -## Use `locale` with the GraphQL API {#graphql} - -The i18n feature adds new features to the [GraphQL API](/dev-docs/api/graphql): - -- The `locale` field is added to the GraphQL schema. -- GraphQL can be used: - - to query documents for a specific locale with the `locale` argument - - for mutations to [create](#graphql-create), [update](#graphql-update), and [delete](#graphql-delete) documents for a specific locale - -### Fetch all documents in a specific locale {#graphql-fetch-all} - -To fetch all documents
-
-
-
-```graphql
-query {
- restaurants(locale: "fr") {
- documentId
- name
- locale
- }
-}
-```
-
-
-
-
-
-```json
-{
- "data": {
- "restaurants": [
- {
- "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
- "name": "Restaurant Biscotte",
- "locale": "fr"
- },
- {
- "documentId": "m9n8o7p6q5r4s3t2u1v0wxyz",
- "name": "Pizzeria Arrivederci",
- "locale": "fr"
- },
- ]
- }
-}
-```
-
-
-
-
-
-### Fetch a document in a specific locale {#graphql-fetch}
-
-To fetch a documents
-
-
-
-```graphql
-query Restaurant($documentId: ID!, $locale: I18NLocaleCode) {
- restaurant(documentId: "a1b2c3d4e5d6f7g8h9i0jkl", locale: "fr") {
- documentId
- name
- description
- locale
- }
-}
-```
-
-
-
-
-
-```json
-{
- "data": {
- "restaurant": {
- "documentId": "lviw819d5htwvga8s3kovdij",
- "name": "Restaurant Biscotte",
- "description": "Bienvenue au restaurant Biscotte!",
- "locale": "fr"
- }
- }
-}
-```
-
-
-
-
-### Create a new localized document {#graphql-create}
-
-The `locale` field can be passed to create a localized document
-```js title="./src/index.js"
+```js title="/src/index.js"
module.exports = {
register({ strapi }) {
@@ -699,7 +711,7 @@ module.exports = {
-```ts title="./src/index.ts"
+```ts title="/src/index.ts"
export default {
register({ strapi }) {
@@ -741,7 +753,7 @@ export default {
-##### Middlewares
+###### Middlewares
[Middlewares](/dev-docs/backend-customization/middlewares) can be applied to a GraphQL resolver through the `resolversConfig.[MyResolverName].middlewares` key. The only difference between the GraphQL and REST implementations is that the `config` key becomes `options`.
@@ -760,7 +772,7 @@ Middlewares with GraphQL can even act on nested resolvers, which offer a more gr
JavaScript query (built with the qs library):
- -
-
-
-
-
--### Delete a locale version of a document {#rest-delete} +### `DELETE` Delete a locale version of a document {#rest-delete} To delete a locale version of a document, send a `DELETE` request with the appropriate `locale` parameter. @@ -459,148 +433,3 @@ To delete only a specific locale version of a single type document, add the `loc `DELETE /api/homepage?locale=fr` - -## Use `locale` with the GraphQL API {#graphql} - -The i18n feature adds new features to the [GraphQL API](/dev-docs/api/graphql): - -- The `locale` field is added to the GraphQL schema. -- GraphQL can be used: - - to query documents for a specific locale with the `locale` argument - - for mutations to [create](#graphql-create), [update](#graphql-update), and [delete](#graphql-delete) documents for a specific locale - -### Fetch all documents in a specific locale {#graphql-fetch-all} - -To fetch all documents
-
+
-```js title="./src/index.js"
+```js title="/src/index.js"
module.exports = {
register({ strapi }) {
@@ -602,7 +614,7 @@ module.exports = {
-```ts title="./src/index.ts"
+```ts title="/src/index.ts"
export default {
register({ strapi }) {
@@ -640,7 +652,7 @@ export default {
-##### Policies
+###### Policies
[Policies](/dev-docs/backend-customization/policies) can be applied to a GraphQL resolver through the `resolversConfig.[MyResolverName].policies` key.
@@ -659,7 +671,7 @@ The `context` object gives access to:
JavaScript query (built with the qs library):
-
+
-```js title="./src/index.js"
+```js title="/src/index.js"
module.exports = {
register({ strapi }) {
@@ -527,7 +539,7 @@ export default {
:::
-#### Custom configuration for resolvers
+###### Custom configuration for resolvers
A resolver is a GraphQL query or mutation handler (i.e. a function, or a collection of functions, that generate(s) a response for a GraphQL query or mutation). Each field has a default resolver.
@@ -537,7 +549,7 @@ When [extending the GraphQL schema](#extending-the-schema), the `resolversConfig
* [policies with the `policies`](#policies) key
* and [middlewares with the `middlewares`](#middlewares) key
-##### Authorization configuration
+###### Authorization configuration
By default, the authorization of a GraphQL request is handled by the registered authorization strategy that can be either [API token](/dev-docs/configurations/api-tokens) or through the [Users & Permissions plugin](#usage-with-the-users--permissions-plugin). The Users & Permissions plugin offers a more granular control.
@@ -565,7 +577,7 @@ To change how the authorization is configured, use the resolver configuration de
JavaScript query (built with the qs library):
-
+
-```js title="./src/index.js"
+```js title="/src/index.js"
module.exports = {
/**
@@ -311,7 +325,7 @@ module.exports = {
-```ts title="./src/index.ts"
+```ts title="/src/index.ts"
export default {
/**
@@ -377,11 +391,9 @@ export default {
-
-
-### Disabling operations in the Shadow CRUD
+##### Disabling operations in the Shadow CRUD
The `extension` [service](/dev-docs/backend-customization/services) provided with the GraphQL plugin exposes functions that can be used to disable operations on Content-Types:
@@ -421,7 +433,7 @@ strapi
.disable()
```
-### Using getters
+##### Using getters
The following getters can be used to retrieve information about operations allowed on content-types:
@@ -446,7 +458,7 @@ The following getters can be used to retrieve information about operations allow
| `hasOutputEnabled()` | Returns whether a field has output enabled |
| `hasFiltersEnabled()` | Returns whether a field has filtering enabled |
-### Extending the schema
+###### Extending the schema
The schema generated by the Content API can be extended by registering an extension.
@@ -472,7 +484,7 @@ The `types` and `plugins` parameters are based on [Nexus](https://nexusjs.org/).
JavaScript query (built with the qs library):
-
+
+ +
+
+
+`GET /api/articles?status=draft`
+
+
+
+
+
+```json {21}
+{
+ "data": [
+ // …
+ {
+ "id": 5,
+ "documentId": "znrlzntu9ei5onjvwfaalu2v",
+ "Name": "Biscotte Restaurant",
+ "Description": [
+ {
+ "type": "paragraph",
+ "children": [
+ {
+ "type": "text",
+ "text": "This is the draft version."
+ }
+ ]
+ }
+ ],
+ "createdAt": "2024-03-06T13:43:30.172Z",
+ "updatedAt": "2024-03-06T21:38:46.353Z",
+ "publishedAt": null,
+ "locale": "en"
+ },
+ // …
+ ],
+ "meta": {
+ "pagination": {
+ "page": 1,
+ "pageSize": 25,
+ "pageCount": 1,
+ "total": 4
+ }
+ }
+}
+```
+
+
+
diff --git a/docusaurus/docs/dev-docs/api/rest/upload.md b/docusaurus/docs/dev-docs/api/rest/upload.md
new file mode 100644
index 0000000000..5fc495749d
--- /dev/null
+++ b/docusaurus/docs/dev-docs/api/rest/upload.md
@@ -0,0 +1,228 @@
+---
+title: Upload files
+description: Learn how to use the /api/upload endpoints to upload files to Strapi with the REST API.
+tags:
+- API
+- Content API
+- upload
+- REST API
+- Media Library
+---
+
+# REST API: Upload files
+
+The [Media Library feature](/user-docs/features/media-library) is powered in the back-end server of Strapi by the `upload` package. To upload files to Strapi, you can either use the Media Library directly from the admin panel, or use the [REST API](/dev-docs/api/rest), with the following available endpoints :
+
+| Method | Path | Description |
+| :----- | :---------------------- | :------------------ |
+| GET | `/api/upload/files` | Get a list of files |
+| GET | `/api/upload/files/:id` | Get a specific file |
+| POST | `/api/upload` | Upload files |
+| POST | `/api/upload?id=x` | Update fileInfo |
+| DELETE | `/api/upload/files/:id` | Delete a file |
+
+:::note Notes
+- [Folders](/user-docs/features/media-library#organizing-assets-with-folders) are an admin panel-only feature and are not part of the Content API (REST or GraphQL). Files uploaded through REST are located in the automatically created "API Uploads" folder.
+- The GraphQL API does not support uploading media files. To upload files, use the REST API or directly add files from the [Media Library](/user-docs/features/media-library) in the admin panel. Some GraphQL mutations to update or delete uploaded media files are still possible (see [GraphQL API documentation](/dev-docs/api/graphql#mutations-on-media-files) for details).
+:::
+
+## Upload files
+
+Upload one or more files to your application.
+
+`files` is the only accepted parameter, and describes the file(s) to upload. The value(s) can be a Buffer or Stream:
+
+
+
+
+```html
+
+
+
+```
+
+
+
+
+
+```js
+import { FormData } from 'formdata-node';
+import fetch, { blobFrom } from 'node-fetch';
+
+const file = await blobFrom('./1.png', 'image/png');
+const form = new FormData();
+
+form.append('files', file, "1.png");
+
+const response = await fetch('http://localhost:1337/api/upload', {
+ method: 'post',
+ body: form,
+});
+
+```
+
+
+
+
+
+:::caution
+You have to send FormData in your request body.
+:::
+
+## Upload entry files
+
+Upload one or more files that will be linked to a specific entry.
+
+The following parameters are accepted:
+
+| Parameter | Description |
+| --------- | ----------- |
+|`files` | The file(s) to upload. The value(s) can be a Buffer or Stream. |
+|`path` (optional) | The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). |
+| `refId` | The ID of the entry which the file(s) will be linked to. |
+| `ref` | The unique ID (uid) of the model which the file(s) will be linked to (see more below). |
+| `source` (optional) | The name of the plugin where the model is located. |
+| `field` | The field of the entry which the file(s) will be precisely linked to. |
+
+For example, given the `Restaurant` model attributes:
+
+```json title="/src/api/restaurant/content-types/restaurant/schema.json"
+{
+ // ...
+ "attributes": {
+ "name": {
+ "type": "string"
+ },
+ "cover": {
+ "type": "media",
+ "multiple": false,
+ }
+ }
+// ...
+}
+```
+
+The following is an example of a corresponding front-end code:
+
+```html
+
+
+
+```
+
+:::caution
+You have to send FormData in your request body.
+:::
+
+## Update fileInfo
+
+Update a file in your application.
+
+`fileInfo` is the only accepted parameter, and describes the fileInfo to update:
+
+```js
+import { FormData } from 'formdata-node';
+import fetch from 'node-fetch';
+
+const fileId = 50;
+const newFileData = {
+ alternativeText: 'My new alternative text for this image!',
+};
+
+const form = new FormData();
+
+form.append('fileInfo', JSON.stringify(newFileData));
+
+const response = await fetch(`http://localhost:1337/api/upload?id=${fileId}`, {
+ method: 'post',
+ body: form,
+});
+
+```
+
+## Models definition
+
+Adding a file attribute to a [model](/dev-docs/backend-customization/models) (or the model of another plugin) is like adding a new association.
+
+The following example lets you upload and attach one file to the `avatar` attribute:
+
+```json title="/src/api/restaurant/content-types/restaurant/schema.json"
+
+{
+ // ...
+ {
+ "attributes": {
+ "pseudo": {
+ "type": "string",
+ "required": true
+ },
+ "email": {
+ "type": "email",
+ "required": true,
+ "unique": true
+ },
+ "avatar": {
+ "type": "media",
+ "multiple": false,
+ }
+ }
+ }
+ // ...
+}
+
+```
+
+The following example lets you upload and attach multiple pictures to the `restaurant` content-type:
+
+```json title="/src/api/restaurant/content-types/restaurant/schema.json"
+{
+ // ...
+ {
+ "attributes": {
+ "name": {
+ "type": "string",
+ "required": true
+ },
+ "covers": {
+ "type": "media",
+ "multiple": true,
+ }
+ }
+ }
+ // ...
+}
+```
+
diff --git a/docusaurus/docs/dev-docs/backend-customization/examples/services-and-controllers.md b/docusaurus/docs/dev-docs/backend-customization/examples/services-and-controllers.md
index 76b196bf5f..70508428b9 100644
--- a/docusaurus/docs/dev-docs/backend-customization/examples/services-and-controllers.md
+++ b/docusaurus/docs/dev-docs/backend-customization/examples/services-and-controllers.md
@@ -303,14 +303,14 @@ Out of the box, [FoodAdvisor](https://github.com/strapi/foodadvisor) does not pr
Let's create an `email.js` service file to send an email. We could use it in a [custom controller](#custom-controller) to notify the restaurant owner whenever a new review is created on the front-end website.
:::callout 🤗 Optional service
-This service is an advanced code example using the [Email](/dev-docs/plugins/email) plugin and requires understanding how [plugins](/dev-docs/plugins) and [providers](/dev-docs/providers) work with Strapi. If you don't need an email service to notify the restaurant's owner, you can skip this part and jump next to the custom [controller](#custom-controller) example.
+This service is an advanced code example using the [Email](/user-docs/features/email) plugin and requires understanding how [plugins](/dev-docs/plugins) and [providers](/dev-docs/providers) work with Strapi. If you don't need an email service to notify the restaurant's owner, you can skip this part and jump next to the custom [controller](#custom-controller) example.
:::
:::prerequisites
-- You have setup a [provider for the Email plugin](/dev-docs/plugins/email), for instance the [Sendmail](https://www.npmjs.com/package/@strapi/provider-email-sendmail) provider.
+- You have setup a [provider for the Email plugin](/user-docs/features/email), for instance the [Sendmail](https://www.npmjs.com/package/@strapi/provider-email-sendmail) provider.
- In Strapi's admin panel, you have [created an `Email` single type](/user-docs/content-type-builder/creating-new-content-type#creating-a-new-content-type) that contains a `from` Text field to define the sender email address.
:::
@@ -343,7 +343,7 @@ This service is an advanced code example using the [Email](/dev-docs/plugins/ema
-Additional information can be found in the [Services](/dev-docs/backend-customization/services), [Entity Service API](/dev-docs/api/entity-service), [Email plugin](/dev-docs/plugins/email) and [Providers](/dev-docs/providers) documentation.
+Additional information can be found in the [Services](/dev-docs/backend-customization/services), [Entity Service API](/dev-docs/api/entity-service), [Email plugin](/user-docs/features/email) and [Providers](/dev-docs/providers) documentation.
diff --git a/docusaurus/docs/dev-docs/backend-customization/models.md b/docusaurus/docs/dev-docs/backend-customization/models.md
index 0f1da8d007..6e82b8f5b6 100644
--- a/docusaurus/docs/dev-docs/backend-customization/models.md
+++ b/docusaurus/docs/dev-docs/backend-customization/models.md
@@ -116,7 +116,7 @@ Many types of attributes are available:
- `customField` to describe [custom fields](#custom-fields) and their specific keys
- `component` to define a [component](#components-json) (i.e. a data structure usable in multiple content-types)
- `dynamiczone` to define a [dynamic zone](#dynamic-zones) (i.e. a flexible space based on a list of components)
- - and the `locale` and `localizations` types, only used by the [Internationalization (i18n) plugin](/dev-docs/i18n)
+ - and the `locale` and `localizations` types, only used by the [Internationalization (i18n) plugin](/user-docs/features/internationalization)
The `type` parameter of an attribute should be one of the following values:
@@ -127,7 +127,7 @@ The `type` parameter of an attribute should be one of the following values:
| Number types |
_Can only be used if the [i18n](/dev-docs/i18n) is enabled on the content-type_|
_Can only be used if the [i18n](/user-docs/features/internationalization) is enabled on the content-type_|
`ctx.query` | The whole query object. | `Object` | | `ctx.request.query.sort` | Parameters to [sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) | `String` or `Array` | -| `ctx.request.query.filters` | Parameters to [filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) | `Object` | +| `ctx.request.query.filters` | Parameters to [filter the response](/dev-docs/api/rest/filters) | `Object` | | `ctx.request.query.populate` | Parameters to [populate relations, components, or dynamic zones](/dev-docs/api/rest/populate-select#population) | `String` or `Object` | | `ctx.request.query.fields` | Parameters to [select only specific fields to return with the response](/dev-docs/api/rest/populate-select#field-selection) | `Array` | | `ctx.request.query.pagination` | Parameter to [page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) | `Object` | -| `ctx.request.query.publicationState` | Parameter to [select the Draft & Publish state](/dev-docs/api/rest/filters-locale-publication#status) | `String` | -| `ctx.request.query.locale` | Parameter to [select one or multiple locales](/dev-docs/api/rest/filters-locale-publication#locale) | `String` or `Array` | +| `ctx.request.query.publicationState` | Parameter to [select the Draft & Publish state](/dev-docs/api/rest/status) | `String` | +| `ctx.request.query.locale` | Parameter to [select one or multiple locales](/dev-docs/api/rest/locale) | `String` or `Array` | ## `ctx.state` diff --git a/docusaurus/docs/dev-docs/backend-customization/webhooks.md b/docusaurus/docs/dev-docs/backend-customization/webhooks.md index 859a637124..b8ada1a816 100644 --- a/docusaurus/docs/dev-docs/backend-customization/webhooks.md +++ b/docusaurus/docs/dev-docs/backend-customization/webhooks.md @@ -13,12 +13,8 @@ tags: - webhooks --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # Webhooks -
This event is only available with the
This event is only available with the
This event is only available with the
The event is triggered when content is moved to a new review stage (see [Review Workflows](/user-docs/settings/review-workflows)). +This event is only available with the
The event is triggered when content is moved to a new review stage (see [Review Workflows](/user-docs/settings/review-workflows)). **Example payload** @@ -477,7 +473,7 @@ This event is only available with the
your [provider configuration](/dev-docs/providers#configuring-providers) | | `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in
your [provider configuration](/dev-docs/providers#configuring-providers) | | `rateLimit` | Settings to customize the rate limiting of the admin panel's authentication endpoints, additional configuration options come from [`koa2-ratelimit`](https://www.npmjs.com/package/koa2-ratelimit) | object | {} | diff --git a/docusaurus/docs/dev-docs/configurations/api-tokens.md b/docusaurus/docs/dev-docs/configurations/api-tokens.md index 1b06f23085..3ae709e474 100644 --- a/docusaurus/docs/dev-docs/configurations/api-tokens.md +++ b/docusaurus/docs/dev-docs/configurations/api-tokens.md @@ -12,12 +12,8 @@ tags: - REST API --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # API tokens -
`production` enables specific behaviors (see [Node.js documentation](https://nodejs.org/en/learn/getting-started/nodejs-the-difference-between-development-and-production) for details) | `String` | `'development'` | | `BROWSER` | Open the admin panel in the browser after startup | `Boolean` | `true` | | `ENV_PATH` | Path to the file that contains your environment variables | `String` | `'./.env'` | -| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE`
_Optional_ | Initialization locale for the application, if the [Internationalization (i18n) plugin](/dev-docs/i18n) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/dev-docs/i18n#configuration-of-the-default-locale)) | `String` | `'en'` | +| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE`
_Optional_ | Initialization locale for the application, if the [Internationalization (i18n) plugin](/user-docs/features/internationalization) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/user-docs/features/internationalization#configuration)) | `String` | `'en'` | | `STRAPI_ENFORCE_SOURCEMAPS` | Forces the bundler to emit source-maps, which is helpful for debugging errors in the admin app. | `boolean` | `false` | | `FAST_REFRESH` | _(Only applies to webpack)_
Use [react-refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) to enable "Fast Refresh" for near-instant feedback while developing the Strapi admin panel. | `boolean` | `true` | diff --git a/docusaurus/docs/dev-docs/configurations/functions.md b/docusaurus/docs/dev-docs/configurations/functions.md index 389b0745e0..75bdae11fa 100644 --- a/docusaurus/docs/dev-docs/configurations/functions.md +++ b/docusaurus/docs/dev-docs/configurations/functions.md @@ -167,7 +167,7 @@ It can be used to: - extend [content-types](/dev-docs/backend-customization/models) programmatically - load some [environment variables](/dev-docs/configurations/environment) - register a [custom field](/dev-docs/custom-fields) that would be used only by the current Strapi application, -- register a [custom provider for the Users & Permissions plugin](/dev-docs/plugins/users-permissions#creating-a-custom-provider). +- register a [custom provider for the Users & Permissions plugin](/dev-docs/configurations/users-and-permissions-providers/new-provider-guide). `register()` is the very first thing that happens when a Strapi application is starting. This happens _before_ any setup process and you don't have any access to database, routes, policies, or any other backend server elements within the `register()` function. diff --git a/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md b/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md index 1cefc94f9d..99b4376881 100644 --- a/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md +++ b/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md @@ -1,5 +1,5 @@ --- -title: Access and cast environment variables +title: Access and cast env variables description: Learn how to cast environment variables in Strapi 5 with the env() utility. displayed_sidebar: cmsSidebar tags: @@ -10,12 +10,8 @@ tags: - environment --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # How to access and cast environment variables -
(See [local server configuration](/dev-docs/plugins/upload#local-server) in Upload documentation for additional details) | Object | - | -| `sizeLimit` | Maximum file size in bytes.
(See [max file size configuration](/dev-docs/plugins/upload#max-file-size) in Upload plugin documentation for additional information) | Integer | `209715200`
(200 MB in bytes, i.e., 200 x 1024 x 1024 bytes) | -| `breakpoints` | Allows to override the breakpoints sizes at which responsive images are generated when the "Responsive friendly upload" option is set to `true`.
(See [responsive images configuration](/dev-docs/plugins/upload#responsive-images) in Upload plugin documentation for additional information) | Object | `{ large: 1000, medium: 750, small: 500 }` | - -:::note Notes -* Some configuration options can also be set directly from the Admin Panel (see [User Guide](/user-docs/settings/media-library-settings)). -* The Upload request timeout is defined in the server options, not in the Upload plugin options, as it's not specific to the Upload plugin but is applied to the whole Strapi server instance. See [upload request timeout configuration](/dev-docs/plugins/upload#upload-request-timeout) in the Upload documentation for additional details. -* When using a different upload provider, additional configuration options might be available. For Upload providers maintained by Strapi, see the [Amazon S3 provider](https://market.strapi.io/providers/@strapi-provider-upload-aws-s3) and [Cloudinary provider](https://market.strapi.io/providers/@strapi-provider-upload-cloudinary) documentations for additional information about available options. -::: - -**Example custom configuration**: - -The following is an example of a custom configuration for the Upload plugin when using the default upload provider: - -
-
-
-
-```js title="/config/plugins.js"
-
-module.exports = ({ env })=>({
- upload: {
- config: {
- providerOptions: {
- localServer: {
- maxage: 300000
- },
- },
- sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
- breakpoints: {
- xlarge: 1920,
- large: 1000,
- medium: 750,
- small: 500,
- xsmall: 64
- },
- },
- },
-});
-```
-
-
-
-
-
-```ts title="/config/plugins.ts"
-
-export default () => ({
- upload: {
- config: {
- providerOptions: {
- localServer: {
- maxage: 300000
- },
- },
- sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
- breakpoints: {
- xlarge: 1920,
- large: 1000,
- medium: 750,
- small: 500,
- xsmall: 64
- },
- },
- },
-})
-```
-
-
-
-
diff --git a/docusaurus/docs/dev-docs/configurations/server.md b/docusaurus/docs/dev-docs/configurations/server.md
index a9b774783c..b39783d7a8 100644
--- a/docusaurus/docs/dev-docs/configurations/server.md
+++ b/docusaurus/docs/dev-docs/configurations/server.md
@@ -12,12 +12,8 @@ tags:
- port
---
-import NotV5 from '/docs/snippets/\_not-updated-to-v5.md'
-
# Server configuration
-
(Under the hood, the backend asks Github for the user's profile and a match is done on Github user's email address and Strapi user's email address). +8. The frontend now possesses the user's `jwt`, which means the user is connected and the frontend can make authenticated requests to the backend! + +An example of a frontend app that handles this flow can be found here: [react login example application](https://github.com/strapi/strapi-examples/tree/master/examples/login-react). + +## Setting up the server URL + +Before setting up a provider you must specify the absolute URL of your backend in `/config/server`: + +
+
+
+
+```js title="/config/server.js"
+module.exports = ({ env }) => ({
+ host: env('HOST', '0.0.0.0'),
+ port: env.int('PORT', 1337),
+ url: env('', 'http://localhost:1337'),
+});
+```
+
+
+
+
+
+```ts title="/config/server.ts"
+export default ({ env }) => ({
+ host: env('HOST', '0.0.0.0'),
+ port: env.int('PORT', 1337),
+ url: env('', 'http://localhost:1337'),
+});
+```
+
+
+
+
+
+:::tip
+Later you will give this URL to your provider.
For development, some providers accept the use of localhost urls but many don't. In this case we recommend to use [ngrok](https://ngrok.com/docs) (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (e.g., `url: env('', 'https://5299e8514242.ngrok.io'),`). +::: + +## Setting up the provider - Examples + +Instead of a generic explanation we decided to show an example for each provider. You can also [create your own custom provider](/dev-docs/configurations/users-and-permissions-providers/new-provider-guide). + +In the following examples, the frontend application will be the [react login example application](https://github.com/strapi/strapi-examples/tree/master/examples/login-react) running on `http://localhost:3000`, while Strapi (i.e., the backend server) will be running on `http://localhost:1337`. + +
+
+
+If you want to create and add a new custom provider, please refer to the following guide:
+
+
+
diff --git a/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/auth-zero.md b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/auth-zero.md
new file mode 100644
index 0000000000..2056255bf8
--- /dev/null
+++ b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/auth-zero.md
@@ -0,0 +1,53 @@
+---
+title: Auth0 provider setup for Users & Permissions
+# description: todo
+displayed_sidebar: cmsSidebar
+tags:
+- users and permissions
+- providers
+- configuration
+- customization
+---
+
+import ConfigDone from '/docs/snippets/u-and-p-provider-config-done.md'
+
+# Auth0 provider setup for Users & Permissions
+
+The present page explains how to setup the Auth0 provider for the [Users & Permissions feature](/user-docs/features/users-permissions).
+
+:::prerequisites
+You have the [Users & Permissions providers documentation](/dev-docs/configurations/users-and-permissions-providers).
+:::
+
+## Auth0 configuration
+
+:::note
+AWS Cognito accepts the `localhost` urls.
+The use of `ngrok` is not needed. +::: + +1. Visit your Auth0 tenant dashboard +2. In API section, create a new API +3. In application, create a `machine-to-machine` application and select the API that you have just created +4. In settings of this app set these values: + - **Allowed Callback URLs**: `http://localhost:1337/api/connect/auth0/callback` + - **Allowed Logout URLs**: `http://localhost:3000` + - **Allowed Web Origins**: `http://localhost:3000` +5. At the bottom of settings, show "Advanced Settings" and go to the "Grant Types". Ensure that these grants are checked/enabled: + - Implicit + - Authorization Code + - Refresh Token + - Client Credentials + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Auth0** provider +3. Fill the information: + - Enable: `ON` + - Client ID: ``
+ - Client Secret: ``
+ - Subdomain: ``, example it is the part in bold in the following url: https://**my-tenant.eu**.auth0.com/
+ - The redirect URL to your front-end app: `http://localhost:3000/connect/auth0`
+
+
+The use of `ngrok` is not needed. +::: + +1. Visit the AWS Management Console
[https://aws.amazon.com/console/](https://aws.amazon.com/console/) +2. If needed, select your **Region** in the top right corner next to the Support dropdown +3. Select the **Services** dropdown in the top left corner +4. Click on **Cognito** in the `Security, Identity & Compliance` section +5. Then click on the **Manage User Pools** button +6. If applicable either create or use an existing user pool. You will find hereafter a tutorial to create a User Pool
[https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) +7. Go to the **App clients** section in your cognito user pool and create a new client with the name `Strapi Auth` and set all the parameters and then click on **Create app client** +8. You should now have an **App client id** and by clicking on the button **Show Details** you will be able to see the **App client secret**. Do copy those two values **App client id** and **App client secret** somewhere for later use when configuring the AWS Cognito provider in Strapi. +9. Go to the **App integration section** and click on **App client settings** +10. Look for your app client named `Strapi Auth` and enable Cognito User Pool by checking it in the **Enabled Identity Providers** section of your newly created App client +11. Fill in your callback URL and Sign out URL with the value `http://localhost:1337/api/connect/cognito/callback` or the one provided by your AWS Cognito provider in Strapi +12. In the **Oauth 2.0** section select `Authorization code grant` and `Implicit grant` for the **Allowed OAuth Flows** and select `email`, `openid` and `profile` for the **Allowed OAuth Scopes** +13. You can now click on **Save changes** and if you have already configured your domain name then you should be able to see a link to the **Launch Hosted UI**. You can click on it in order to display the AWS Cognito login page. In case you haven't yet configured your domain name, use the link **Choose domain name** at the bottom right of the page in order to configure your domain name. On that page you will have an `Amazon Cognito Domain` section where a `Domain prefix` is already setup. Type a domain prefix to use for the sign-up and sign-in pages that are hosted by Amazon Cognito, this domain prefix together with the `.auth.YOUR_REGION.amazoncognito.com` will be the **Host URI (Subdomain)** value for your strapi configuration later on. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Cognito** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: fill in the **App client id** (`5bd7a786qdupjmi0b3s10vegdt`) + - **Client Secret**: fill in the **App client secret** (`19c5c78dsfsdfssfsdfhpdb4nkpb145vesdfdsfsffgh7vwd6g45jlipbpb`) + - **Host URI (Subdomain)**: fill in the URL value that you copied earlier (`myapp67b50345-67b50b17-local.auth.eu-central-1.amazoncognito.com`) + - **The redirect URL to your front-end app**: if you are using strapi react-login [https://github.com/strapi/strapi-examples/tree/master/examples/login-react/](https://github.com/strapi/strapi-examples/tree/master/examples/login-react/) use `http://localhost:3000/connect/cognito/redirect` but if you do not yet have a front-end app to test your Cognito configuration you can then use the following URL `http://localhost:1337/api/auth/cognito/callback` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page on the developer portal at [https://discordapp.com/developers/applications/](https://discordapp.com/developers/applications/) +2. Click on **New application** button +3. Fill the **name** and create +4. Click on **OAuth2** in the left menu +5. And click on **Add redirect** button +6. Fill the **Redirect** input with `http://localhost:1337/api/connect/discord/callback` URL and save +7. Click on **General information** in the left menu +8. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Discord** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 665118465148846081 + - **Client Secret**: iJbr7mkyqyut-J2hGvvSDch_5Dw5U77J + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/discord/redirect` + +
+Use [ngrok](https://ngrok.com/docs) to serve the backend app (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (e.g., `url: env('', 'https://5299e8514242.ngrok.io'),`). + +``` +ngrok http 1337 +``` + +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. + +1. Visit the Developer Apps list page at [https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) +2. Click on **Add a New App** button +3. Fill the **Display Name** in the modal and create the app +4. Setup a **Facebook Login** product +5. Click on the **PRODUCTS > Facebook login > Settings** link in the left menu +6. Fill the information and save (replace with your own ngrok url): + - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/facebook/callback` +7. Then, click on **Settings** in the left menu +8. Then on **Basic** link +9. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Facebook** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 2408954435875229 + - **Client Secret**: 4fe04b740b69f31ea410b9391ff3b5b0 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/facebook/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. +::: + +1. Visit the OAuth Apps list page [https://github.com/settings/developers](https://github.com/settings/developers) +2. Click on **New OAuth App** button +3. Fill the information (replace with your own ngrok url): + - **Application name**: Strapi GitHub auth + - **Homepage URL**: `https://65e60559.ngrok.io` + - **Application description**: Strapi provider auth description + - **Authorization callback URL**: `https://65e60559.ngrok.io/api/connect/github/callback` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **GitHub** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 53de5258f8472c140917 + - **Client Secret**: fb9d0fe1d345d9ac7f83d7a1e646b37c554dae8b + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/github/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Google Developer Console at [https://console.developers.google.com/](https://console.developers.google.com/) +2. Click on the **Select a project** dropdown in the top menu +3. Then click **NEW PROJECT** button +4. Fill the **Project name** input and create + +Wait a few seconds while the application is created. + +5. On the project dropdown, select your new project +6. Click on **Go to APIs overview** under the **APIs** card +7. Then click on the **Credentials** link in the left menu +8. Click on **OAuth consent screen** button +9. Choose **External** and click on **create** +10. Fill the **Application name** and save +11. Then click on **Create credentials** button +12. Choose **OAuth client ID** option +13. Fill the information: + - **Name**: `Strapi Auth` + - **Authorized redirect URIs**: `http://localhost:1337/api/connect/google/callback` +14. Click on **OAuth 2.0 Client IDs** name of the client you just created +15. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Google** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 226437944084-o2mojv5i4lfnng9q8kq3jkf5v03avemk.apps.googleusercontent.com + - **Client Secret**: aiTbMoiuJQflSBy6uQrfgsni + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/google/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/login-react)) with the generated ngrok url. +::: + +1. Visit the Developer Apps list page at [https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) +2. Click on **Add a New App** button +3. Fill the **Display Name** in the modal and create the app +4. Setup an **Instagram** product +5. Click on the **PRODUCTS > Instagram > Basic Display** link in the left menu +6. Then click on the **Create new application** button (and valid the modal) +7. Fill the information (replace with your own ngrok url): + - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/instagram/callback` + - **Deauthorize**: `https://65e60559.ngrok.io` + - **Data Deletion Requests**: `https://65e60559.ngrok.io` +8. On the **App Review for Instagram Basic Display** click on **Add to submission** for **instagram_graph_user_profile**. +9. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Instagram** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 563883201184965 + - **Client Secret**: f5ba10a7dd78c2410ab6b8a35ab28226 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/instagram/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit your Keycloak admin dashboard +2. If you don't already have a realm, you'll want to create one +3. In the Clients section of your realm, create a new client +4. Under the capability config, ensure you set `Client Authentication` to on to ensure you can create a private key +5. Under the access settings, ensure you set the following values: + - **Valid redirect URIs**: `http://localhost:1337/api/connect/keycloak/callback` and `http://localhost:1337/api/connect/keycloak` + - **Allowed Web Origins**: `http://localhost:3000` and `http://localhost:1337` +6. In the Client Scopes section, ensure you have the `email` and `profile` scopes set to default +7. In the Client Scopes section, ensure you have the `openid` scope set to default, if you don't have this you will need to manually create it in the global Client Scopes + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Keycloak** provider +3. Fill the information: + - Enable: `ON` + - Client ID: ``
+ - Client Secret: ``
+ - Subdomain: ``, example is either `keycloak.example.com/realms/strapitest` or `keycloak.example.com/auth/realms/strapitest` **without the protocol before it**
+ - The redirect URL to your front-end app: `http://localhost:3000/connect/keycloak/redirect`
+ - (Optional) Set the JWKS URL if you have a custom JWKS URL, example is like `https://keycloak.example.com/auth/realms/strapitest/protocol/openid-connect/certs`
+
+
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page at [https://www.linkedin.com/developers/apps](https://www.linkedin.com/developers/apps) +2. Click on **Create app** button +3. Fill the information: + - **App name**: Strapi auth + - **LinkedIn Page**: Enter a LinkedIn page name to associate with the app or click **Create a new LinkedIn Page** to create a new one + - **App Logo**: Upload a square image that is at least 100x100 pixels. +4. Click on the **Create app** to create the app +5. On the app page click on **Auth** tab +6. Fill the information: + - **Authorized redirect URL**: `http://localhost:1337/api/connect/linkedin/callback` +7. On the app page click on **Products** tab. +8. Select `Sign In with LinkedIn` from the product list to enable it. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **LinkedIn** provider +3. Fill the information: + - **Enable**: `ON` + - **Client ID**: 84witsxk641rlv + - **Client Secret**: HdXO7a7mkrU5a6WN + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/linkedin/redirect` + +
+ The JSON request response will be `{ "jwt": "...", "user": {...} }`. + +Now you can make authenticated requests, as described in [token usage](/user-docs/features/users-permissions#token-usage). + +:::caution Troubleshooting + +- **Error 429**: It's most likely because your login flow fell into a loop. To make new requests to the backend, you need to wait a few minutes or restart the backend. +- **Grant: missing session or misconfigured provider**: It may be due to many things. + - **The redirect url can't be built**: Make sure you have set the backend url in `config/server.js`: [Setting up the server url](/dev-docs/configurations/users-and-permissions-providers#setting-up-the-server-url) + - **A session/cookie/cache problem**: You can try again in a private tab. + - **The incorrect use of a domain with ngrok**: Check your urls and make sure that you use the ngrok url instead of `http://localhost:1337`. Don't forget to check the backend url set in the example app at `src/config.js`. +- **You can't access your admin panel**: It's most likely because you built it with the backend url set with a ngrok url and you stopped/restarted ngrok. You need to replace the backend url with the new ngrok url and run `yarn build` or `npm run build` again. +::: + +### Reset password + +**Can only be used for users registered using the email provider.** + +
+
+
+
+The assumed general flow:
+
+1. The user goes to your **forgotten password page**.
+2. The user enters their email address.
+3. Your forgotten password page sends a request to the backend to send an email with the reset password link to the user.
+4. The user receives the email and clicks on the special link.
+5. The link redirects the user to your **reset password page**.
+6. The user enters their new password.
+7. The **reset password page** sends a request to the backend with the new password.
+8. If the request contains the code contained in the link at step 3, the password is updated.
+9. The user can log in with the new password.
+
+The following section details steps 3 and 7.
+
+#### Forgotten password: ask for the reset password link
+
+This action sends an email to a user with the link to your reset password page. The link will be enriched with the url param `code` that is needed for the [reset password](#reset-password) at step 7.
+
+First, you must specify the following:
+
+- In the admin panel: _Settings > USERS & PERMISSIONS PLUGIN > Advanced Settings > Reset Password_ page, the `url` to your reset password page.
+- In the admin panel: _Settings > USERS & PERMISSIONS PLUGIN > Email Template_ page, the _Shipper email_.
+
+Then, your **forgotten password page** has to make the following request to your backend:
+
+```js
+import axios from 'axios';
+
+// Request API.
+axios
+ .post('http://localhost:1337/api/auth/forgot-password', {
+ email: 'user@strapi.io', // user's email
+ })
+ .then(response => {
+ console.log('Your user received an email');
+ })
+ .catch(error => {
+ console.log('An error occurred:', error.response);
+ });
+```
+
+#### Reset Password: Send the new password
+
+This action will update the user password.
+This also works with the [GraphQL Plugin](/dev-docs/plugins/graphql), with the `resetPassword` mutation.
+
+Your **reset password page** has to make the following request to your backend:
+
+```js
+import axios from 'axios';
+
+// Request API.
+axios
+ .post('http://localhost:1337/api/auth/reset-password', {
+ code: 'privateCode', // code contained in the reset link of step 3.
+ password: 'userNewPassword',
+ passwordConfirmation: 'userNewPassword',
+ })
+ .then(response => {
+ console.log("Your user's password has been reset.");
+ })
+ .catch(error => {
+ console.log('An error occurred:', error.response);
+ });
+```
+
+
+
+
+
+You can also update an authenticated user password through the `/change-password` API endpoint:
+
+```js
+import axios from 'axios';
+
+// Request API.
+axios.post(
+ 'http://localhost:1337/api/auth/change-password',
+ {
+ currentPassword: 'currentPassword',
+ password: 'userNewPassword',
+ passwordConfirmation: 'userNewPassword',
+ },
+ {
+ headers: {
+ Authorization: 'Bearer ',
+ },
+ }
+);
+```
+
+
+
+
+
+### Email validation
+
+:::note
+In production, make sure the `url` config property is set. Otherwise the validation link will redirect to `localhost`. More info on the config [here](/dev-docs/configurations/server).
+:::
+
+After registering, if you have set **Enable email confirmation** to **ON**, the user will receive a confirmation link by email. The user has to click on it to validate their registration.
+
+Example of the confirmation link: `https://yourwebsite.com/api/auth/email-confirmation?confirmation=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MywiaWF0IjoxNTk0OTgxMTE3LCJleHAiOjE1OTc1NzMxMTd9.0WeB-mvuguMyr4eY8CypTZDkunR--vZYzZH6h6sChFg`
+
+If needed you can re-send the confirmation email by making the following request:
+
+```js
+import axios from 'axios';
+
+// Request API.
+axios
+ .post(`http://localhost:1337/api/auth/send-email-confirmation`, {
+ email: 'user@strapi.io', // user's email
+ })
+ .then(response => {
+ console.log('Your user received an email');
+ })
+ .catch(error => {
+ console.error('An error occurred:', error.response);
+ });
+```
+
+## Adding a new provider to your Strapi application
+
+:::info
+This documentation might not up-to-date with Strapi 5 and is a work in progress. In the meantime, [contributions](https://github.com/strapi/documentation/blob/main/CONTRIBUTING.md) are most welcome.
+:::
+
+**[Grant](https://github.com/simov/grant) supplies configuration for a number of commonly used OAuth providers. [Custom](https://github.com/simov/grant#misc-custom-providers) providers are also supported**.
You can view and try out the 200+ supported providers here: [OAuth Playground](https://grant.outofindex.com/). + +### Prepare your files + +To add a new provider on Strapi, you will need to perform changes to the following files: + +``` +extensions/users-permissions/services/Providers.js +extensions/users-permissions/config/functions/bootstrap.js +``` + +If these files don't exist you will need to copy from your `node_modules` or the Strapi mono-repo. You can see [plugin extensions](/dev-docs/plugins-extension) for more information on how it works. + +We will go step by step. + +### Configure your Provider Request + +Configure the new provider in the `Provider.js` file at the `getProfile` function. + +The `getProfile` takes three params: + +- **provider**: The name of the used provider as a string. +- **query**: The query is the result of the provider callback. +- **callback**: The callback function who will continue the internal Strapi login logic. + +Here is an example that uses the `discord` provider. + +### Configure your oauth generic information + +```js +case 'discord': { + const discord = new Purest({ + provider: 'discord', + config: { + 'discord': { + 'https://discordapp.com/api/': { + '__domain': { + 'auth': { + 'auth': {'bearer': '[0]'} + } + }, + '{endpoint}': { + '__path': { + 'alias': '__default' + } + } + } + } + } + }); +} +``` + +This code creates a `Purest` object that gives us a generic way to interact with the provider's REST API. + +For more specs on using the `Purest` module, please refer to the [Official Purest Documentation](https://github.com/simov/purest) + +You may also want to take a look onto the numerous already made configurations [here](https://github.com/simov/purest-providers/blob/master/config/providers.json). + +### Retrieve your user's information + +For our Discord provider it will look like the following: + +```js + discord.query().get('users/@me').auth(access_token).request((err, res, body) => { + if (err) { + callback(err); + } else { + // Combine username and discriminator because discord username is not unique + const username = `${body.username}#${body.discriminator}`; + callback(null, { + username, + email: body.email + }); + } + }); + break; +} +``` + +Here is the next part of our switch. Now that we have properly configured our provider, we want to use it to retrieve +user information. + +Here you see the real power of `purest`, you can simply make a get request on the desired URL, using the `access_token` +from the `query` parameter to authenticate. + +That way, you should be able to retrieve the user info you need. + +Now, you can simply call the `callback` function with the username and email of your user. That way, Strapi will be able +to retrieve your user from the database and log you in. + +### Configure the new provider model onto database + +Now, we need to configure our 'model' for our new provider. That way, our settings can be stored in the database, and +managed from the admin panel. + +Open the file `packages/strapi-plugin-users-permissions/config/functions/bootstrap.js` + +Add the fields your provider needs into the `grantConfig` object. +For our discord provider it will look like: + +```js +discord: { + enabled: false, // make this provider disabled by default + icon: 'comments', // The icon to use on the UI + key: '', // our provider app id (leave it blank, you will fill it with the Content Manager) + secret: '', // our provider secret key (leave it blank, you will fill it with the Content Manager) + callback: '/auth/discord/callback', // the callback endpoint of our provider + scope: [ // the scope that we need from our user to retrieve information + 'identify', + 'email' + ] +}, +``` diff --git a/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md new file mode 100644 index 0000000000..f9818cbd00 --- /dev/null +++ b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md @@ -0,0 +1,55 @@ +--- +title: Patreon provider setup for Users & Permissions +# description: todo +displayed_sidebar: cmsSidebar +tags: +- users and permissions +- providers +- configuration +- customization +--- + +import ConfigDone from '/docs/snippets/u-and-p-provider-config-done.md' + +# Patreon provider setup for Users & Permissions + +The present page explains how to setup the Patreon provider for the [Users & Permissions feature](/user-docs/features/users-permissions). + +:::prerequisites +You have the [Users & Permissions providers documentation](/dev-docs/configurations/users-and-permissions-providers). +::: + +## Patreon configuration + +:::note +Patreon does not accept `localhost` urls.
+Use `ngrok` to serve the backend app. +```bash +ngrok http 1337 +``` +Don't forget to update the server url in the Strapi config file `./config/server.js` and the server URL in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok URL. +::: + +1. You must be a Patreon Creator in order to register an Oauth client. +2. Go to the [Patreon developer portal](https://www.patreon.com/portal) +3. Click on [Clients & API Keys](https://www.patreon.com/portal/registration/register-clients) +4. Click on "Create Client" +5. Enter the details of your organization and website. +6. There is a drop-down for "App Category" but no explanation of what the different categories mean. +"Community" seems to work fine. +7. 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 +[developer docs](https://docs.patreon.com/#introduction) for more detail. +8. Under "Redirect URI's" enter `https://your-site.com/api/connect/patreon/callback` +9. Save the client details and you will then see the Client ID and Client Secret. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Patreon** provider +3. Fill the information: + - Enable: `ON` + - Client ID: `` - as above
+ - Client Secret: `` - as above
+
+
+The use of `ngrok` is not needed. +::: + +1. Visit the Reddit authorized applications preferences page at [https://www.reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) +2. Click on the **create another app...** button near the bottom +3. Select **web app** for the type +4. Fill the **name** and **redirect uri** input in +5. Click the **create app** button +6. Note that the **Client ID** is located under the app type (web app) + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Reddit** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: hmxSBOit0SCjSQ + - **Client Secret**: gwR9hCjK_PMYVYNGeDLS4WLB8g7xqg + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/reddit/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page on the developer console at [https://dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps) +2. Click on **Register Your Application** button +3. Fill the information: + - **Name**: Strapi auth + - **OAuth Redirect URLs**: `http://localhost:1337/api/connect/twitch/callback` + - **Category**: Choose a category +4. Click on **Manage** button of your new app +5. Generate a new **Client Secret** with the **New Secret** button +6. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Twitch** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: amuy279g8wt68qlht3u4gek4oykh5j + - **Client Secret**: dapssh10uo97gg2l25qufr8wen3yr6 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitch/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. +::: + +1. Visit the Apps list page at [https://developer.twitter.com/en/apps](https://developer.twitter.com/en/apps) +2. Click on **Create an app** button +3. Fill the information (replace with your own ngrok url): + - **App name**: Strapi Twitter auth + - **Application description**: This is a demo app for Strapi auth + - **Tell us how this app will be used**: - here write a message enough long - +4. At the end of the process you should see your Application ID and secret, save them for later +5. Go to you app setting and click on edit **Authentication settings** +6. Enable **3rd party authentication** AND **Request email address from users** +7. Fill the information (replace with your own ngrok url): + - **Callback URLs**: `https://65e60559.ngrok.io/api/connect/twitter/callback` + - **Website URL**: `https://65e60559.ngrok.io` + - **Privacy policy**: `https://d73e70e88872.ngrok.io` + - **Terms of service**: `https://d73e70e88872.ngrok.io` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Twitter** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **API Key**: yfN4ycGGmKXiS1njtIYxuN5IH + - **Api Secret**: Nag1en8S4VwqurBvlW5OaFyKlzqrXFeyWhph6CZlpGA2V3VR3T + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitter/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page at [https://vk.com/apps?act=manage](https://vk.com/apps?act=manage) +2. Click on **Create app** button +3. Fill the information: + - **Title**: Strapi auth + - **Platform**: Choose **Website** option + - **Website address**: `http://localhost:1337` + - **Base domain**: `localhost` +4. Click on the **Settings** link in the left menu +5. Click on the **Open API** link to enable this option +6. Fill the information: + - **Authorized redirect URL**: `http://localhost:1337/api/connect/vk/callback` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **VK** provider +3. Fill the information: + - **Enable**: `ON` + - **Client ID**: 7276416 + - **Client Secret**: cFBUSghLXGuxqnCyw1N3 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/vk/redirect` + +
+
+
+::: -The Documentation plugin is useful to document the available endpoints once you created an API. +/full_documentation.json`
+The generated documentation JSON file can be found in your application at the following path: `src/extensions/documentation/documentation//full_documentation.json`
## Installation
-To install the plugin run following command in your terminal:
+To install the documentation plugin, run following command in your terminal:
@@ -49,29 +54,24 @@ npm install @strapi/plugin-documentation
-Once the plugin is installed, starting the application generates the API documentation.
-
-## Swagger UI
-
-The Documentation plugin visualizes your API using [Swagger UI](https://swagger.io/tools/swagger-ui/). To access the UI, select *Plugins > Documentation* in the main navigation of the admin panel. Then click **Open documentation** to open the Swagger UI. Using the Swagger UI you can view all of the endpoints available on your API and trigger API calls.
+Once the plugin is installed, starting Strapi generates the API documentation.
-:::tip
-Once installed, the Documentation plugin UI can be accessed at the following URL:
-`:/documentation/`
-(e.g., [`localhost:1337/documentation/v1.0.0`](http://localhost:1337/documentation/v1.0.0)).
-:::
+## Configuration
-### Authenticated requests
+Most configuration options for the Documentation plugin are handled via your Strapi project's code. A few settings are available in the admin panel.
-Strapi is secured by default, which means that most of your end-points require the user to be authorized. If the action has not been set to public in users and permission then you must provide your JWT. To do this, click the “Authorize” button and paste your JWT.
+### Admin panel settings
-## Administration panel
+The Documentation plugin affects multiple parts of the admin panel. The following table lists all the additional options and settings that are added to a Strapi application once the plugin has been installed:
-This plugin comes with an interface that is available in your administration panel and a configuration file.
+| Section impacted | Options and settings |
+|------------------|-------------------------------------------------------------|
+| Documentation | :/documentation/`
+(e.g., [`localhost:1337/documentation/v1.0.0`](http://localhost:1337/documentation/v1.0.0)).
+:::
+
+### Regenerating documentation
+
+There are 2 ways to update the documentation after making changes to your API:
+
+- restart your application to regenerate the version of the documentation specified in the Documentation plugin's configuration,
+- or go to the Documentation plugin page and click the **regenerate** button for the documentation version you want to regenerate.
+
+### Authenticating requests
+
+Strapi is secured by default, which means that most of your endpoints require the user to be authorized. If the CRUD action has not been set to Public in the [Users & Permissions plugin](/user-docs/features/users-permissions#configuring-end-user-roles) then you must provide your JSON web token (JWT). To do this, while viewing the API Documentation, click the **Authorize** button and paste your JWT in the _bearerAuth_ _value_ field.
diff --git a/docusaurus/docs/dev-docs/plugins/email.md b/docusaurus/docs/dev-docs/plugins/email.md
deleted file mode 100644
index 146820ede7..0000000000
--- a/docusaurus/docs/dev-docs/plugins/email.md
+++ /dev/null
@@ -1,164 +0,0 @@
----
-title: Email plugin
-displayed_sidebar: cmsSidebar
-description: Send email from your server or externals providers.
-tags:
-- admin panel
-- controllers
-- email plugin
-- lifecycle hooks
-- plugins
-- services
-- send() function
-- sendTemplatedEmail() function
----
-
-# Email plugin
-
-The Email plugin enables applications to send emails from a server or an external provider. The Email plugin uses the Strapi global API, meaning it can be called from anywhere inside a Strapi application. Two of the most common use cases are in the Strapi back end and in the admin panel. The following documentation describes how to use the Email plugin in a controller or service for back-end use cases and using a lifecycle hook for admin panel use cases.
-
-:::prerequisites
-
-The Email plugin requires a provider and a provider configuration in the `config/plugins.js` file or `config/plugins.ts` file. See the [Providers](/dev-docs/providers) documentation for detailed installation and configuration instructions.
-
-:::
-
-:::note
-[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi Email plugin. It provides functionality for the local development environment but is not production-ready in the default configuration. For production stage applications you need to further configure `Sendmail` or change providers. The [Providers](/dev-docs/providers) documentation has instructions for changing providers, configuring providers, and creating a new email provider.
-:::
-
-## Sending emails with a controller or service
-
-The Email plugin has an `email` [service](/dev-docs/backend-customization/services) that contains 2 functions to send emails:
-
-* `send()` directly contains the email contents,
-* `sendTemplatedEmail()` consumes data from the Content Manager to populate emails, streamlining programmatic emails.
-
-### Using the `send()` function
-
-To trigger an email in response to a user action add the `send()` function to a [controller](/dev-docs/backend-customization/controllers) or [service](/dev-docs/backend-customization/services). The send function has the following properties:
-
-| Property | Type | Format | Description |
-|-----------|----------|---------------|-------------------------------------------------------|
-| `from` | `string` | email address | If not specified, uses `defaultFrom` in `plugins.js`. |
-| `to` | `string` | email address | Required |
-| `cc` | `string` | email address | Optional |
-| `bcc` | `string` | email address | Optional |
-| `replyTo` | `string` | email address | Optional |
-| `subject` | `string` | - | Required |
-| `text` | `string` | - | Either `text` or `html` is required. |
-| `html` | `string` | HTML | Either `text` or `html` is required. |
-
-```js title="This code example can be used in a controller or a service path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.js"
-
- await strapi.plugins['email'].services.email.send({
- to: 'valid email address',
- from: 'your verified email address', //e.g. single sender verification in SendGrid
- cc: 'valid email address',
- bcc: 'valid email address',
- replyTo: 'valid email address',
- subject: 'The Strapi Email plugin worked successfully',
- text: 'Hello world!',
- html: 'Hello world!',
- }),
-```
-
-### Using the `sendTemplatedEmail()` function
-
-The `sendTemplatedEmail()` function is used to compose emails from a template. The function compiles the email from the available properties and then sends the email. To use the `sendTemplatedEmail()` function, define the `emailTemplate` object and add the function to a controller or service. The function calls the `emailTemplate` object, and can optionally call the `emailOptions` and `data` objects:
-
-| Parameter | Description | Type | Default |
-|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|
-| `emailOptions`
Optional | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | -| `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | { } | -| `data`
Optional | Contains the data used to compile the templates | `object` | { } | - -```js title="This code example can be used in a controller or a service path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.js" - - -const emailTemplate = { - subject: 'Welcome <%= user.firstname %>', - text: `Welcome to mywebsite.fr! - Your account is now linked with: <%= user.email %>.`, - html: `
-## Customization
+#### Customization
Strapi provides a programmatic API to customize GraphQL, which allows:
@@ -245,7 +259,7 @@ Strapi provides a programmatic API to customize GraphQL, which allows:
JavaScript query (built with the qs library):
+ +
+
+
+JavaScript query (built with the qs library):
+ +- `integer`
- `biginteger`
- `float`
- `decimal`
- `boolean`
- `json`
- `media`
- [`relation`](#relations)
- [`customField`](#custom-fields)
- [`component`](#components-json)
- [`dynamiczone`](#dynamic-zones)
_Can only be used if the [i18n](/dev-docs/i18n) is enabled on the content-type_|
- `locale`
- `localizations`
_Can only be used if the [i18n](/user-docs/features/internationalization) is enabled on the content-type_|
- `locale`
- `localizations`
`ctx.query` | The whole query object. | `Object` | | `ctx.request.query.sort` | Parameters to [sort the response](/dev-docs/api/rest/sort-pagination.md#sorting) | `String` or `Array` | -| `ctx.request.query.filters` | Parameters to [filter the response](/dev-docs/api/rest/filters-locale-publication#filtering) | `Object` | +| `ctx.request.query.filters` | Parameters to [filter the response](/dev-docs/api/rest/filters) | `Object` | | `ctx.request.query.populate` | Parameters to [populate relations, components, or dynamic zones](/dev-docs/api/rest/populate-select#population) | `String` or `Object` | | `ctx.request.query.fields` | Parameters to [select only specific fields to return with the response](/dev-docs/api/rest/populate-select#field-selection) | `Array` | | `ctx.request.query.pagination` | Parameter to [page through entries](/dev-docs/api/rest/sort-pagination.md#pagination) | `Object` | -| `ctx.request.query.publicationState` | Parameter to [select the Draft & Publish state](/dev-docs/api/rest/filters-locale-publication#status) | `String` | -| `ctx.request.query.locale` | Parameter to [select one or multiple locales](/dev-docs/api/rest/filters-locale-publication#locale) | `String` or `Array` | +| `ctx.request.query.publicationState` | Parameter to [select the Draft & Publish state](/dev-docs/api/rest/status) | `String` | +| `ctx.request.query.locale` | Parameter to [select one or multiple locales](/dev-docs/api/rest/locale) | `String` or `Array` | ## `ctx.state` diff --git a/docusaurus/docs/dev-docs/backend-customization/webhooks.md b/docusaurus/docs/dev-docs/backend-customization/webhooks.md index 859a637124..b8ada1a816 100644 --- a/docusaurus/docs/dev-docs/backend-customization/webhooks.md +++ b/docusaurus/docs/dev-docs/backend-customization/webhooks.md @@ -13,12 +13,8 @@ tags: - webhooks --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # Webhooks -
This event is only available with the
This event is only available with the
This event is only available with the
The event is triggered when content is moved to a new review stage (see [Review Workflows](/user-docs/settings/review-workflows)). +This event is only available with the
The event is triggered when content is moved to a new review stage (see [Review Workflows](/user-docs/settings/review-workflows)). **Example payload** @@ -477,7 +473,7 @@ This event is only available with the
your [provider configuration](/dev-docs/providers#configuring-providers) | | `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in
your [provider configuration](/dev-docs/providers#configuring-providers) | | `rateLimit` | Settings to customize the rate limiting of the admin panel's authentication endpoints, additional configuration options come from [`koa2-ratelimit`](https://www.npmjs.com/package/koa2-ratelimit) | object | {} | diff --git a/docusaurus/docs/dev-docs/configurations/api-tokens.md b/docusaurus/docs/dev-docs/configurations/api-tokens.md index 1b06f23085..3ae709e474 100644 --- a/docusaurus/docs/dev-docs/configurations/api-tokens.md +++ b/docusaurus/docs/dev-docs/configurations/api-tokens.md @@ -12,12 +12,8 @@ tags: - REST API --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # API tokens -
`production` enables specific behaviors (see [Node.js documentation](https://nodejs.org/en/learn/getting-started/nodejs-the-difference-between-development-and-production) for details) | `String` | `'development'` | | `BROWSER` | Open the admin panel in the browser after startup | `Boolean` | `true` | | `ENV_PATH` | Path to the file that contains your environment variables | `String` | `'./.env'` | -| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE`
_Optional_ | Initialization locale for the application, if the [Internationalization (i18n) plugin](/dev-docs/i18n) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/dev-docs/i18n#configuration-of-the-default-locale)) | `String` | `'en'` | +| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE`
_Optional_ | Initialization locale for the application, if the [Internationalization (i18n) plugin](/user-docs/features/internationalization) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/user-docs/features/internationalization#configuration)) | `String` | `'en'` | | `STRAPI_ENFORCE_SOURCEMAPS` | Forces the bundler to emit source-maps, which is helpful for debugging errors in the admin app. | `boolean` | `false` | | `FAST_REFRESH` | _(Only applies to webpack)_
Use [react-refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) to enable "Fast Refresh" for near-instant feedback while developing the Strapi admin panel. | `boolean` | `true` | diff --git a/docusaurus/docs/dev-docs/configurations/functions.md b/docusaurus/docs/dev-docs/configurations/functions.md index 389b0745e0..75bdae11fa 100644 --- a/docusaurus/docs/dev-docs/configurations/functions.md +++ b/docusaurus/docs/dev-docs/configurations/functions.md @@ -167,7 +167,7 @@ It can be used to: - extend [content-types](/dev-docs/backend-customization/models) programmatically - load some [environment variables](/dev-docs/configurations/environment) - register a [custom field](/dev-docs/custom-fields) that would be used only by the current Strapi application, -- register a [custom provider for the Users & Permissions plugin](/dev-docs/plugins/users-permissions#creating-a-custom-provider). +- register a [custom provider for the Users & Permissions plugin](/dev-docs/configurations/users-and-permissions-providers/new-provider-guide). `register()` is the very first thing that happens when a Strapi application is starting. This happens _before_ any setup process and you don't have any access to database, routes, policies, or any other backend server elements within the `register()` function. diff --git a/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md b/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md index 1cefc94f9d..99b4376881 100644 --- a/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md +++ b/docusaurus/docs/dev-docs/configurations/guides/access-cast-environment-variables.md @@ -1,5 +1,5 @@ --- -title: Access and cast environment variables +title: Access and cast env variables description: Learn how to cast environment variables in Strapi 5 with the env() utility. displayed_sidebar: cmsSidebar tags: @@ -10,12 +10,8 @@ tags: - environment --- -import NotV5 from '/docs/snippets/_not-updated-to-v5.md' - # How to access and cast environment variables -
(See [local server configuration](/dev-docs/plugins/upload#local-server) in Upload documentation for additional details) | Object | - | -| `sizeLimit` | Maximum file size in bytes.
(See [max file size configuration](/dev-docs/plugins/upload#max-file-size) in Upload plugin documentation for additional information) | Integer | `209715200`
(200 MB in bytes, i.e., 200 x 1024 x 1024 bytes) | -| `breakpoints` | Allows to override the breakpoints sizes at which responsive images are generated when the "Responsive friendly upload" option is set to `true`.
(See [responsive images configuration](/dev-docs/plugins/upload#responsive-images) in Upload plugin documentation for additional information) | Object | `{ large: 1000, medium: 750, small: 500 }` | - -:::note Notes -* Some configuration options can also be set directly from the Admin Panel (see [User Guide](/user-docs/settings/media-library-settings)). -* The Upload request timeout is defined in the server options, not in the Upload plugin options, as it's not specific to the Upload plugin but is applied to the whole Strapi server instance. See [upload request timeout configuration](/dev-docs/plugins/upload#upload-request-timeout) in the Upload documentation for additional details. -* When using a different upload provider, additional configuration options might be available. For Upload providers maintained by Strapi, see the [Amazon S3 provider](https://market.strapi.io/providers/@strapi-provider-upload-aws-s3) and [Cloudinary provider](https://market.strapi.io/providers/@strapi-provider-upload-cloudinary) documentations for additional information about available options. -::: - -**Example custom configuration**: - -The following is an example of a custom configuration for the Upload plugin when using the default upload provider: - -
(Under the hood, the backend asks Github for the user's profile and a match is done on Github user's email address and Strapi user's email address). +8. The frontend now possesses the user's `jwt`, which means the user is connected and the frontend can make authenticated requests to the backend! + +An example of a frontend app that handles this flow can be found here: [react login example application](https://github.com/strapi/strapi-examples/tree/master/examples/login-react). + +## Setting up the server URL + +Before setting up a provider you must specify the absolute URL of your backend in `/config/server`: + +
For development, some providers accept the use of localhost urls but many don't. In this case we recommend to use [ngrok](https://ngrok.com/docs) (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (e.g., `url: env('', 'https://5299e8514242.ngrok.io'),`). +::: + +## Setting up the provider - Examples + +Instead of a generic explanation we decided to show an example for each provider. You can also [create your own custom provider](/dev-docs/configurations/users-and-permissions-providers/new-provider-guide). + +In the following examples, the frontend application will be the [react login example application](https://github.com/strapi/strapi-examples/tree/master/examples/login-react) running on `http://localhost:3000`, while Strapi (i.e., the backend server) will be running on `http://localhost:1337`. + +
+The use of `ngrok` is not needed. +::: + +1. Visit your Auth0 tenant dashboard +2. In API section, create a new API +3. In application, create a `machine-to-machine` application and select the API that you have just created +4. In settings of this app set these values: + - **Allowed Callback URLs**: `http://localhost:1337/api/connect/auth0/callback` + - **Allowed Logout URLs**: `http://localhost:3000` + - **Allowed Web Origins**: `http://localhost:3000` +5. At the bottom of settings, show "Advanced Settings" and go to the "Grant Types". Ensure that these grants are checked/enabled: + - Implicit + - Authorization Code + - Refresh Token + - Client Credentials + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Auth0** provider +3. Fill the information: + - Enable: `ON` + - Client ID: `
+The use of `ngrok` is not needed. +::: + +1. Visit the AWS Management Console
[https://aws.amazon.com/console/](https://aws.amazon.com/console/) +2. If needed, select your **Region** in the top right corner next to the Support dropdown +3. Select the **Services** dropdown in the top left corner +4. Click on **Cognito** in the `Security, Identity & Compliance` section +5. Then click on the **Manage User Pools** button +6. If applicable either create or use an existing user pool. You will find hereafter a tutorial to create a User Pool
[https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) +7. Go to the **App clients** section in your cognito user pool and create a new client with the name `Strapi Auth` and set all the parameters and then click on **Create app client** +8. You should now have an **App client id** and by clicking on the button **Show Details** you will be able to see the **App client secret**. Do copy those two values **App client id** and **App client secret** somewhere for later use when configuring the AWS Cognito provider in Strapi. +9. Go to the **App integration section** and click on **App client settings** +10. Look for your app client named `Strapi Auth` and enable Cognito User Pool by checking it in the **Enabled Identity Providers** section of your newly created App client +11. Fill in your callback URL and Sign out URL with the value `http://localhost:1337/api/connect/cognito/callback` or the one provided by your AWS Cognito provider in Strapi +12. In the **Oauth 2.0** section select `Authorization code grant` and `Implicit grant` for the **Allowed OAuth Flows** and select `email`, `openid` and `profile` for the **Allowed OAuth Scopes** +13. You can now click on **Save changes** and if you have already configured your domain name then you should be able to see a link to the **Launch Hosted UI**. You can click on it in order to display the AWS Cognito login page. In case you haven't yet configured your domain name, use the link **Choose domain name** at the bottom right of the page in order to configure your domain name. On that page you will have an `Amazon Cognito Domain` section where a `Domain prefix` is already setup. Type a domain prefix to use for the sign-up and sign-in pages that are hosted by Amazon Cognito, this domain prefix together with the `.auth.YOUR_REGION.amazoncognito.com` will be the **Host URI (Subdomain)** value for your strapi configuration later on. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Cognito** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: fill in the **App client id** (`5bd7a786qdupjmi0b3s10vegdt`) + - **Client Secret**: fill in the **App client secret** (`19c5c78dsfsdfssfsdfhpdb4nkpb145vesdfdsfsffgh7vwd6g45jlipbpb`) + - **Host URI (Subdomain)**: fill in the URL value that you copied earlier (`myapp67b50345-67b50b17-local.auth.eu-central-1.amazoncognito.com`) + - **The redirect URL to your front-end app**: if you are using strapi react-login [https://github.com/strapi/strapi-examples/tree/master/examples/login-react/](https://github.com/strapi/strapi-examples/tree/master/examples/login-react/) use `http://localhost:3000/connect/cognito/redirect` but if you do not yet have a front-end app to test your Cognito configuration you can then use the following URL `http://localhost:1337/api/auth/cognito/callback` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page on the developer portal at [https://discordapp.com/developers/applications/](https://discordapp.com/developers/applications/) +2. Click on **New application** button +3. Fill the **name** and create +4. Click on **OAuth2** in the left menu +5. And click on **Add redirect** button +6. Fill the **Redirect** input with `http://localhost:1337/api/connect/discord/callback` URL and save +7. Click on **General information** in the left menu +8. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Discord** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 665118465148846081 + - **Client Secret**: iJbr7mkyqyut-J2hGvvSDch_5Dw5U77J + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/discord/redirect` + +
+Use [ngrok](https://ngrok.com/docs) to serve the backend app (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (e.g., `url: env('', 'https://5299e8514242.ngrok.io'),`). + +``` +ngrok http 1337 +``` + +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. + +1. Visit the Developer Apps list page at [https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) +2. Click on **Add a New App** button +3. Fill the **Display Name** in the modal and create the app +4. Setup a **Facebook Login** product +5. Click on the **PRODUCTS > Facebook login > Settings** link in the left menu +6. Fill the information and save (replace with your own ngrok url): + - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/facebook/callback` +7. Then, click on **Settings** in the left menu +8. Then on **Basic** link +9. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Facebook** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 2408954435875229 + - **Client Secret**: 4fe04b740b69f31ea410b9391ff3b5b0 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/facebook/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. +::: + +1. Visit the OAuth Apps list page [https://github.com/settings/developers](https://github.com/settings/developers) +2. Click on **New OAuth App** button +3. Fill the information (replace with your own ngrok url): + - **Application name**: Strapi GitHub auth + - **Homepage URL**: `https://65e60559.ngrok.io` + - **Application description**: Strapi provider auth description + - **Authorization callback URL**: `https://65e60559.ngrok.io/api/connect/github/callback` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **GitHub** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 53de5258f8472c140917 + - **Client Secret**: fb9d0fe1d345d9ac7f83d7a1e646b37c554dae8b + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/github/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Google Developer Console at [https://console.developers.google.com/](https://console.developers.google.com/) +2. Click on the **Select a project** dropdown in the top menu +3. Then click **NEW PROJECT** button +4. Fill the **Project name** input and create + +Wait a few seconds while the application is created. + +5. On the project dropdown, select your new project +6. Click on **Go to APIs overview** under the **APIs** card +7. Then click on the **Credentials** link in the left menu +8. Click on **OAuth consent screen** button +9. Choose **External** and click on **create** +10. Fill the **Application name** and save +11. Then click on **Create credentials** button +12. Choose **OAuth client ID** option +13. Fill the information: + - **Name**: `Strapi Auth` + - **Authorized redirect URIs**: `http://localhost:1337/api/connect/google/callback` +14. Click on **OAuth 2.0 Client IDs** name of the client you just created +15. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Google** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 226437944084-o2mojv5i4lfnng9q8kq3jkf5v03avemk.apps.googleusercontent.com + - **Client Secret**: aiTbMoiuJQflSBy6uQrfgsni + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/google/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/login-react)) with the generated ngrok url. +::: + +1. Visit the Developer Apps list page at [https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) +2. Click on **Add a New App** button +3. Fill the **Display Name** in the modal and create the app +4. Setup an **Instagram** product +5. Click on the **PRODUCTS > Instagram > Basic Display** link in the left menu +6. Then click on the **Create new application** button (and valid the modal) +7. Fill the information (replace with your own ngrok url): + - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/instagram/callback` + - **Deauthorize**: `https://65e60559.ngrok.io` + - **Data Deletion Requests**: `https://65e60559.ngrok.io` +8. On the **App Review for Instagram Basic Display** click on **Add to submission** for **instagram_graph_user_profile**. +9. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Instagram** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: 563883201184965 + - **Client Secret**: f5ba10a7dd78c2410ab6b8a35ab28226 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/instagram/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit your Keycloak admin dashboard +2. If you don't already have a realm, you'll want to create one +3. In the Clients section of your realm, create a new client +4. Under the capability config, ensure you set `Client Authentication` to on to ensure you can create a private key +5. Under the access settings, ensure you set the following values: + - **Valid redirect URIs**: `http://localhost:1337/api/connect/keycloak/callback` and `http://localhost:1337/api/connect/keycloak` + - **Allowed Web Origins**: `http://localhost:3000` and `http://localhost:1337` +6. In the Client Scopes section, ensure you have the `email` and `profile` scopes set to default +7. In the Client Scopes section, ensure you have the `openid` scope set to default, if you don't have this you will need to manually create it in the global Client Scopes + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Keycloak** provider +3. Fill the information: + - Enable: `ON` + - Client ID: `
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page at [https://www.linkedin.com/developers/apps](https://www.linkedin.com/developers/apps) +2. Click on **Create app** button +3. Fill the information: + - **App name**: Strapi auth + - **LinkedIn Page**: Enter a LinkedIn page name to associate with the app or click **Create a new LinkedIn Page** to create a new one + - **App Logo**: Upload a square image that is at least 100x100 pixels. +4. Click on the **Create app** to create the app +5. On the app page click on **Auth** tab +6. Fill the information: + - **Authorized redirect URL**: `http://localhost:1337/api/connect/linkedin/callback` +7. On the app page click on **Products** tab. +8. Select `Sign In with LinkedIn` from the product list to enable it. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **LinkedIn** provider +3. Fill the information: + - **Enable**: `ON` + - **Client ID**: 84witsxk641rlv + - **Client Secret**: HdXO7a7mkrU5a6WN + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/linkedin/redirect` + +
+ The JSON request response will be `{ "jwt": "...", "user": {...} }`. + +Now you can make authenticated requests, as described in [token usage](/user-docs/features/users-permissions#token-usage). + +:::caution Troubleshooting + +- **Error 429**: It's most likely because your login flow fell into a loop. To make new requests to the backend, you need to wait a few minutes or restart the backend. +- **Grant: missing session or misconfigured provider**: It may be due to many things. + - **The redirect url can't be built**: Make sure you have set the backend url in `config/server.js`: [Setting up the server url](/dev-docs/configurations/users-and-permissions-providers#setting-up-the-server-url) + - **A session/cookie/cache problem**: You can try again in a private tab. + - **The incorrect use of a domain with ngrok**: Check your urls and make sure that you use the ngrok url instead of `http://localhost:1337`. Don't forget to check the backend url set in the example app at `src/config.js`. +- **You can't access your admin panel**: It's most likely because you built it with the backend url set with a ngrok url and you stopped/restarted ngrok. You need to replace the backend url with the new ngrok url and run `yarn build` or `npm run build` again. +::: + +### Reset password + +**Can only be used for users registered using the email provider.** + +
You can view and try out the 200+ supported providers here: [OAuth Playground](https://grant.outofindex.com/). + +### Prepare your files + +To add a new provider on Strapi, you will need to perform changes to the following files: + +``` +extensions/users-permissions/services/Providers.js +extensions/users-permissions/config/functions/bootstrap.js +``` + +If these files don't exist you will need to copy from your `node_modules` or the Strapi mono-repo. You can see [plugin extensions](/dev-docs/plugins-extension) for more information on how it works. + +We will go step by step. + +### Configure your Provider Request + +Configure the new provider in the `Provider.js` file at the `getProfile` function. + +The `getProfile` takes three params: + +- **provider**: The name of the used provider as a string. +- **query**: The query is the result of the provider callback. +- **callback**: The callback function who will continue the internal Strapi login logic. + +Here is an example that uses the `discord` provider. + +### Configure your oauth generic information + +```js +case 'discord': { + const discord = new Purest({ + provider: 'discord', + config: { + 'discord': { + 'https://discordapp.com/api/': { + '__domain': { + 'auth': { + 'auth': {'bearer': '[0]'} + } + }, + '{endpoint}': { + '__path': { + 'alias': '__default' + } + } + } + } + } + }); +} +``` + +This code creates a `Purest` object that gives us a generic way to interact with the provider's REST API. + +For more specs on using the `Purest` module, please refer to the [Official Purest Documentation](https://github.com/simov/purest) + +You may also want to take a look onto the numerous already made configurations [here](https://github.com/simov/purest-providers/blob/master/config/providers.json). + +### Retrieve your user's information + +For our Discord provider it will look like the following: + +```js + discord.query().get('users/@me').auth(access_token).request((err, res, body) => { + if (err) { + callback(err); + } else { + // Combine username and discriminator because discord username is not unique + const username = `${body.username}#${body.discriminator}`; + callback(null, { + username, + email: body.email + }); + } + }); + break; +} +``` + +Here is the next part of our switch. Now that we have properly configured our provider, we want to use it to retrieve +user information. + +Here you see the real power of `purest`, you can simply make a get request on the desired URL, using the `access_token` +from the `query` parameter to authenticate. + +That way, you should be able to retrieve the user info you need. + +Now, you can simply call the `callback` function with the username and email of your user. That way, Strapi will be able +to retrieve your user from the database and log you in. + +### Configure the new provider model onto database + +Now, we need to configure our 'model' for our new provider. That way, our settings can be stored in the database, and +managed from the admin panel. + +Open the file `packages/strapi-plugin-users-permissions/config/functions/bootstrap.js` + +Add the fields your provider needs into the `grantConfig` object. +For our discord provider it will look like: + +```js +discord: { + enabled: false, // make this provider disabled by default + icon: 'comments', // The icon to use on the UI + key: '', // our provider app id (leave it blank, you will fill it with the Content Manager) + secret: '', // our provider secret key (leave it blank, you will fill it with the Content Manager) + callback: '/auth/discord/callback', // the callback endpoint of our provider + scope: [ // the scope that we need from our user to retrieve information + 'identify', + 'email' + ] +}, +``` diff --git a/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md new file mode 100644 index 0000000000..f9818cbd00 --- /dev/null +++ b/docusaurus/docs/dev-docs/configurations/users-and-permissions-providers/patreon.md @@ -0,0 +1,55 @@ +--- +title: Patreon provider setup for Users & Permissions +# description: todo +displayed_sidebar: cmsSidebar +tags: +- users and permissions +- providers +- configuration +- customization +--- + +import ConfigDone from '/docs/snippets/u-and-p-provider-config-done.md' + +# Patreon provider setup for Users & Permissions + +The present page explains how to setup the Patreon provider for the [Users & Permissions feature](/user-docs/features/users-permissions). + +:::prerequisites +You have the [Users & Permissions providers documentation](/dev-docs/configurations/users-and-permissions-providers). +::: + +## Patreon configuration + +:::note +Patreon does not accept `localhost` urls.
+Use `ngrok` to serve the backend app. +```bash +ngrok http 1337 +``` +Don't forget to update the server url in the Strapi config file `./config/server.js` and the server URL in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok URL. +::: + +1. You must be a Patreon Creator in order to register an Oauth client. +2. Go to the [Patreon developer portal](https://www.patreon.com/portal) +3. Click on [Clients & API Keys](https://www.patreon.com/portal/registration/register-clients) +4. Click on "Create Client" +5. Enter the details of your organization and website. +6. There is a drop-down for "App Category" but no explanation of what the different categories mean. +"Community" seems to work fine. +7. 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 +[developer docs](https://docs.patreon.com/#introduction) for more detail. +8. Under "Redirect URI's" enter `https://your-site.com/api/connect/patreon/callback` +9. Save the client details and you will then see the Client ID and Client Secret. + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Patreon** provider +3. Fill the information: + - Enable: `ON` + - Client ID: `
+The use of `ngrok` is not needed. +::: + +1. Visit the Reddit authorized applications preferences page at [https://www.reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) +2. Click on the **create another app...** button near the bottom +3. Select **web app** for the type +4. Fill the **name** and **redirect uri** input in +5. Click the **create app** button +6. Note that the **Client ID** is located under the app type (web app) + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Reddit** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: hmxSBOit0SCjSQ + - **Client Secret**: gwR9hCjK_PMYVYNGeDLS4WLB8g7xqg + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/reddit/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page on the developer console at [https://dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps) +2. Click on **Register Your Application** button +3. Fill the information: + - **Name**: Strapi auth + - **OAuth Redirect URLs**: `http://localhost:1337/api/connect/twitch/callback` + - **Category**: Choose a category +4. Click on **Manage** button of your new app +5. Generate a new **Client Secret** with the **New Secret** button +6. You should see your Application ID and secret, save them for later + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Twitch** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **Client ID**: amuy279g8wt68qlht3u4gek4oykh5j + - **Client Secret**: dapssh10uo97gg2l25qufr8wen3yr6 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitch/redirect` + +
+Use `ngrok` to serve the backend app. +``` +ngrok http 1337 +``` +Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. +::: + +1. Visit the Apps list page at [https://developer.twitter.com/en/apps](https://developer.twitter.com/en/apps) +2. Click on **Create an app** button +3. Fill the information (replace with your own ngrok url): + - **App name**: Strapi Twitter auth + - **Application description**: This is a demo app for Strapi auth + - **Tell us how this app will be used**: - here write a message enough long - +4. At the end of the process you should see your Application ID and secret, save them for later +5. Go to you app setting and click on edit **Authentication settings** +6. Enable **3rd party authentication** AND **Request email address from users** +7. Fill the information (replace with your own ngrok url): + - **Callback URLs**: `https://65e60559.ngrok.io/api/connect/twitter/callback` + - **Website URL**: `https://65e60559.ngrok.io` + - **Privacy policy**: `https://d73e70e88872.ngrok.io` + - **Terms of service**: `https://d73e70e88872.ngrok.io` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **Twitter** provider +3. Fill the information (replace with your own client ID and secret): + - **Enable**: `ON` + - **API Key**: yfN4ycGGmKXiS1njtIYxuN5IH + - **Api Secret**: Nag1en8S4VwqurBvlW5OaFyKlzqrXFeyWhph6CZlpGA2V3VR3T + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitter/redirect` + +
+The use of `ngrok` is not needed. +::: + +1. Visit the Apps list page at [https://vk.com/apps?act=manage](https://vk.com/apps?act=manage) +2. Click on **Create app** button +3. Fill the information: + - **Title**: Strapi auth + - **Platform**: Choose **Website** option + - **Website address**: `http://localhost:1337` + - **Base domain**: `localhost` +4. Click on the **Settings** link in the left menu +5. Click on the **Open API** link to enable this option +6. Fill the information: + - **Authorized redirect URL**: `http://localhost:1337/api/connect/vk/callback` + +## Strapi configuration + +1. Visit the User & Permissions provider settings page at [http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) +2. Click on the **VK** provider +3. Fill the information: + - **Enable**: `ON` + - **Client ID**: 7276416 + - **Client Secret**: cFBUSghLXGuxqnCyw1N3 + - **The redirect URL to your front-end app**: `http://localhost:3000/connect/vk/redirect` + +
+
+
+::: -The Documentation plugin is useful to document the available endpoints once you created an API. +
- Addition of a new Documentation option in the main navigation  which shows a panel with buttons to  open and  regenerate the documentation.
- Addition of a "Documentation plugin" setting section, which controls whether the documentation endpoint is private or not (see [restricting access](#restricting-access)).
👉 Path reminder:  *Settings > Documentation plugin* - Activation of role based access control for accessing, updating, deleting, and regenerating the documentation. Administrators can authorize different access levels to different types of users in the *Plugins* tab and the *Settings* tab (see [Users & Permissions documentation](/user-docs/users-roles-permissions/configuring-administrator-roles#editing-a-role)).
👉 Path reminder:  *Settings > Administration Panel > Roles*
Optional | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | -| `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | { } | -| `data`
Optional | Contains the data used to compile the templates | `object` | { } | - -```js title="This code example can be used in a controller or a service path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.js" - - -const emailTemplate = { - subject: 'Welcome <%= user.firstname %>', - text: `Welcome to mywebsite.fr! - Your account is now linked with: <%= user.email %>.`, - html: `
Welcome to mywebsite.fr!
-Your account is now linked with: <%= user.email %>.
`,
-};
-
-await strapi.plugins['email'].services.email.sendTemplatedEmail(
- {
- to: user.email,
- // from: is not specified, the defaultFrom is used.
- },
- emailTemplate,
- {
- user: _.pick(user, ['username', 'email', 'firstname', 'lastname']),
- }
-);
-```
-
-## Sending emails from a lifecycle hook
-
- To trigger an email based on administrator actions in the admin panel use [lifecycle hooks](/dev-docs/backend-customization/models#lifecycle-hooks) and the [`send()` function](#using-the-send-function). For example, to send an email each time a new content entry is added in the Content Manager use the `afterCreate` lifecycle hook:
-
-
+
+
:::
-## Usage
+
+
+
+::: By using the Sentry plugin you can: * Initialize a Sentry instance upon startup of a Strapi application * Send Strapi application errors as events to Sentry * Include additional metadata in Sentry events to assist in debugging -* Expose a [global Sentry service](#global-sentry-service-access) - -Begin by first [installing](#installation) the Sentry plugin, and then [configuring](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. +* Expose a global Sentry service usable by the Strapi server ## Installation @@ -47,21 +51,21 @@ npm install @strapi/plugin-sentry ## Configuration -Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: +Create or edit your `/config/plugins` file to configure the Sentry plugin. The following properties are available: | Property | Type | Default Value | Description | | -------- | ---- | ------------- |------------ | | `dsn` | string | `null` | Your Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). | -| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry. | -| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization. See the official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for all available options. | +| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g., OS, browser, etc.) to the events sent to Sentry. | +| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization (see official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for available options). | -An example configuration: +The following is an example basic configuration:
`info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided` -Using the [`env` utility](/dev-docs/configurations/guides/access-cast-environment-variables), you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: +You can make use of that by using the [`env` utility](/dev-docs/configurations/guides/access-cast-environment-variables) to set the `dsn` configuration property depending on the environment.
error: The error to be sent.configureScope: Optional. Enables you to customize the error event.
- Eg: 60, "45m", "10h", "2 days", "7d", "2y". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (minutes, hours, days, years, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms"). - -
(Under the hood, the backend asks Github for the user's profile and a match is done on Github user's email address and Strapi user's email address). -8. The frontend now possesses the user's `jwt`, which means the user is connected and the frontend can make authenticated requests to the backend! - -An example of a frontend app that handles this flow can be found here: [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react). - -#### Setting up the server url - -Before setting up a provider you must specify the absolute url of your backend in `server.js`. - -**example -** `config/server.js` - -
For development, some providers accept the use of localhost urls but many don't. In this case we recommend to use [ngrok](https://ngrok.com/docs) (`ngrok http 1337`) that will make a proxy tunnel from a url it created to your localhost url (ex: `url: env('', 'https://5299e8514242.ngrok.io'),`). -::: - -#### Setting up the provider - examples - -Instead of a generic explanation we decided to show an example for each provider. You can also [create your own custom provider](#creating-a-custom-provider). - -In the following examples, the frontend app will be the [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react).
-It (the frontend app) will be running on `http://localhost:3000`.
-Strapi (the backend) will be running on `http://localhost:1337`. - -
Using ngrok
- -Github doesn't accept `localhost` urls.-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
Github configuration
- -- Visit the OAuth Apps list page [https://github.com/settings/developers](https://github.com/settings/developers) -- Click on **New OAuth App** button -- Fill the information (replace with your own ngrok url): - - **Application name**: Strapi GitHub auth - - **Homepage URL**: `https://65e60559.ngrok.io` - - **Application description**: Strapi provider auth description - - **Authorization callback URL**: `https://65e60559.ngrok.io/api/connect/github/callback` - -Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **GitHub** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 53de5258f8472c140917 - - **Client Secret**: fb9d0fe1d345d9ac7f83d7a1e646b37c554dae8b - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/github/redirect` - -
Using ngrok
- -Facebook doesn't accept `localhost` urls.-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
Facebook configuration
- -- Visit the Developer Apps list page[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) -- Click on **Add a New App** button -- Fill the **Display Name** in the modal and create the app -- Setup a **Facebook Login** product -- Click on the **PRODUCTS > Facebook login > Settings** link in the left menu -- Fill the information and save (replace with your own ngrok url): - - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/facebook/callback` -- Then, click on **Settings** in the left menu -- Then on **Basic** link -- You should see your Application ID and secret, save them for later - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Facebook** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 2408954435875229 - - **Client Secret**: 4fe04b740b69f31ea410b9391ff3b5b0 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/facebook/redirect` - -
Using ngrok
- -Google accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Google configuration
- -- Visit the Google Developer Console[https://console.developers.google.com/](https://console.developers.google.com/) -- Click on the **Select a project** dropdown in the top menu -- Then click **NEW PROJECT** button -- Fill the **Project name** input and create - -Wait a few seconds while the application is created. - -- On the project dropdown, select your new project -- Click on **Go to APIs overview** under the **APIs** card -- Then click on the **Credentials** link in the left menu -- Click on **OAuth consent screen** button -- Choose **External** and click on **create** -- Fill the **Application name** and save -- Then click on **Create credentials** button -- Choose **OAuth client ID** option -- Fill the information: - - **Name**: `Strapi Auth` - - **Authorized redirect URIs**: `http://localhost:1337/api/connect/google/callback` -- Click on **OAuth 2.0 Client IDs** name of the client you just created -- You should see your Application ID and secret, save them for later - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Google** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 226437944084-o2mojv5i4lfnng9q8kq3jkf5v03avemk.apps.googleusercontent.com - - **Client Secret**: aiTbMoiuJQflSBy6uQrfgsni - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/google/redirect` - -
Using ngrok
- -AWS Cognito accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
AWS Cognito configuration
- -- Visit the AWS Management Console[https://aws.amazon.com/console/](https://aws.amazon.com/console/) -- If needed, select your **Region** in the top right corner next to the Support dropdown -- Select the **Services** dropdown in the top left corner -- Click on **Cognito** in the `Security, Identity & Compliance` section -- Then click on the **Manage User Pools** button -- If applicable either create or use an existing user pool. You will find hereafter a tutorial to create a User Pool
[https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) -- Go to the **App clients** section in your cognito user pool and create a new client with the name `Strapi Auth` and set all the parameters and then click on **Create app client** -- You should now have an **App client id** and by clicking on the button **Show Details** you will be able to see the **App client secret**. Do copy those two values **App client id** and **App client secret** somewhere for later use when configuring the AWS Cognito provider in Strapi. -- Go to the **App integration section** and click on **App client settings** -- Look for your app client named `Strapi Auth` and enable Cognito User Pool by checking it in the **Enabled Identity Providers** section of your newly created App client -- Fill in your callback URL and Sign out URL with the value `http://localhost:1337/api/connect/cognito/callback` or the one provided by your AWS Cognito provider in Strapi -- In the **Oauth 2.0** section select `Authorization code grant` and `Implicit grant` for the **Allowed OAuth Flows** and select `email`, `openid` and `profile` for the **Allowed OAuth Scopes** -- You can now click on **Save changes** and if you have already configured your domain name then you should be able to see a link to the **Launch Hosted UI**. You can click on it in order to display the AWS Cognito login page. In case you haven't yet configured your domain name, use the link **Choose domain name** at the bottom right of the page in order to configure your domain name. On that page you will have an `Amazon Cognito Domain` section where a `Domain prefix` is already setup. Type a domain prefix to use for the sign-up and sign-in pages that are hosted by Amazon Cognito, this domain prefix together with the `.auth.YOUR_REGION.amazoncognito.com` will be the **Host URI (Subdomain)** value for your strapi configuration later on. - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Cognito** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: fill in the **App client id** (`5bd7a786qdupjmi0b3s10vegdt`) - - **Client Secret**: fill in the **App client secret** (`19c5c78dsfsdfssfsdfhpdb4nkpb145vesdfdsfsffgh7vwd6g45jlipbpb`) - - **Host URI (Subdomain)**: fill in the URL value that you copied earlier (`myapp67b50345-67b50b17-local.auth.eu-central-1.amazoncognito.com`) - - **The redirect URL to your front-end app**: if you are using strapi react-login [https://github.com/strapi/strapi-examples/tree/master/examples/login-react/](https://github.com/strapi/strapi-examples/tree/master/examples/login-react/) use `http://localhost:3000/connect/cognito/redirect` but if you do not yet have a front-end app to test your Cognito configuration you can then use the following URL `http://localhost:1337/api/auth/cognito/callback` - -
Using ngrok
- -Twitter doesn't accept `localhost` urls.-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok url. - -
Twitter configuration
- -- Visit the Apps list page[https://developer.twitter.com/en/apps](https://developer.twitter.com/en/apps) -- Click on **Create an app** button -- Fill the information (replace with your own ngrok url): - - **App name**: Strapi Twitter auth - - **Application description**: This is a demo app for Strapi auth - - **Tell us how this app will be used**: - here write a message enough long - -- At the end of the process you should see your Application ID and secret, save them for later -- Go to you app setting and click on edit **Authentication settings** -- Enable **3rd party authentication** AND **Request email address from users** -- Fill the information (replace with your own ngrok url): - - **Callback URLs**: `https://65e60559.ngrok.io/api/connect/twitter/callback` - - **Website URL**: `https://65e60559.ngrok.io` - - **Privacy policy**: `https://d73e70e88872.ngrok.io` - - **Terms of service**: `https://d73e70e88872.ngrok.io` - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Twitter** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **API Key**: yfN4ycGGmKXiS1njtIYxuN5IH - - **Api Secret**: Nag1en8S4VwqurBvlW5OaFyKlzqrXFeyWhph6CZlpGA2V3VR3T - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitter/redirect` - -
Using ngrok
- -Discord accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Discord configuration
- -- Visit the Apps list page on the developer portal[https://discordapp.com/developers/applications/](https://discordapp.com/developers/applications/) -- Click on **New application** button -- Fill the **name** and create -- Click on **OAuth2** in the left menu -- And click on **Add redirect** button -- Fill the **Redirect** input with `http://localhost:1337/api/connect/discord/callback` URL and save -- Click on **General information** in the left menu -- You should see your Application ID and secret, save them for later - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Discord** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 665118465148846081 - - **Client Secret**: iJbr7mkyqyut-J2hGvvSDch_5Dw5U77J - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/discord/redirect` - -
Using ngrok
- -Twitch accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Twitch configuration
- -- Visit the Apps list page on the developer console[https://dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps) -- Click on **Register Your Application** button -- Fill the information: - - **Name**: Strapi auth - - **OAuth Redirect URLs**: `http://localhost:1337/api/connect/twitch/callback` - - **Category**: Choose a category -- Click on **Manage** button of your new app -- Generate a new **Client Secret** with the **New Secret** button -- You should see your Application ID and secret, save them for later - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Twitch** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: amuy279g8wt68qlht3u4gek4oykh5j - - **Client Secret**: dapssh10uo97gg2l25qufr8wen3yr6 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/twitch/redirect` - -
Using ngrok
- -Facebook doesn't accept `localhost` urls.-Use `ngrok` to serve the backend app. - -``` -ngrok http 1337 -``` - -Don't forget to update the server url in the backend config file `config/server.js` and the server url in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/login-react)) with the generated ngrok url. - -
Instagram configuration
- -- Visit the Developer Apps list page[https://developers.facebook.com/apps/](https://developers.facebook.com/apps/) -- Click on **Add a New App** button -- Fill the **Display Name** in the modal and create the app -- Setup an **Instagram** product -- Click on the **PRODUCTS > Instagram > Basic Display** link in the left menu -- Then click on the **Create new application** button (and valid the modal) -- Fill the information (replace with your own ngrok url): - - **Valid OAuth Redirect URIs**: `https://65e60559.ngrok.io/api/connect/instagram/callback` - - **Deauthorize**: `https://65e60559.ngrok.io` - - **Data Deletion Requests**: `https://65e60559.ngrok.io` -- On the **App Review for Instagram Basic Display** click on **Add to submission** for **instagram_graph_user_profile**. -- You should see your Application ID and secret, save them for later - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Instagram** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: 563883201184965 - - **Client Secret**: f5ba10a7dd78c2410ab6b8a35ab28226 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/instagram/redirect` - -
Using ngrok
- -VK accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
VK configuration
- -- Visit the Apps list page[https://vk.com/apps?act=manage](https://vk.com/apps?act=manage) -- Click on **Create app** button -- Fill the information: - - **Title**: Strapi auth - - **Platform**: Choose **Website** option - - **Website address**: `http://localhost:1337` - - **Base domain**: `localhost` -- Click on the **Settings** link in the left menu -- Click on the **Open API** link to enable this option -- Fill the information: - - **Authorized redirect URL**: `http://localhost:1337/api/connect/vk/callback` - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **VK** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: 7276416 - - **Client Secret**: cFBUSghLXGuxqnCyw1N3 - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/vk/redirect` - -
Using ngrok
- -LinkedIn accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
LinkedIn configuration
- -- Visit the Apps list page[https://www.linkedin.com/developers/apps](https://www.linkedin.com/developers/apps) -- Click on **Create app** button -- Fill the information: - - **App name**: Strapi auth - - **LinkedIn Page**: Enter a LinkedIn page name to associate with the app or click **Create a new LinkedIn Page** to create a new one - - **App Logo**: Upload a square image that is at least 100x100 pixels. -- Click on the **Create app** to create the app -- On the app page click on **Auth** tab -- Fill the information: - - **Authorized redirect URL**: `http://localhost:1337/api/connect/linkedin/callback` -- On the app page click on **Products** tab. -- Select `Sign In with LinkedIn` from the product list to enable it. - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **LinkedIn** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: 84witsxk641rlv - - **Client Secret**: HdXO7a7mkrU5a6WN - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/linkedin/redirect` - -
Using ngrok
- -A remote CAS server can be configured to accept `localhost` URLs or you can run your own CAS server locally that accepts them. - -The use of `ngrok` is not needed. - -CAS configuration
- -- [CAS](https://github.com/apereo/cas) is an SSO server that supports many different methods of verifying a users identity, - retrieving attributes out the user and communicating that information to applications via protocols such as SAML, OIDC, and the CAS protocol. Strapi can use a CAS server for authentication if CAS is deployed with support for OIDC. -- [CAS](https://github.com/apereo/cas) could already be used by your company or organization or you can setup a local CAS server by cloning the [CAS Overlay](https://github.com/apereo/cas-overlay-template) project or using the newer [CAS Initializr](https://github.com/apereo/cas-initializr) to create an overlay project. -- The CAS server must be configured so it can act as an [OpenID Connect Provider](https://apereo.github.io/cas/6.6.x/installation/OIDC-Authentication.html) -- CAS version 6.3.x and higher is known to work with Strapi but older versions that support OIDC may work. -- Define a CAS OIDC service for Strapi and store it in whichever CAS service registry is being used. -- The CAS service definition might look something like this for a local strapi deployment: - -```json -{ - "@class": "org.apereo.cas.services.OidcRegisteredService", - "clientId": "thestrapiclientid", - "clientSecret": "thestrapiclientsecret", - "bypassApprovalPrompt": true, - "serviceId": "^http(|s)://localhost:1337/.*", - "name": "Local Strapi", - "id": 20201103, - "evaluationOrder": 50, - "attributeReleasePolicy": { - "@class": "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy", - "allowedAttributes": { - "@class": "java.util.TreeMap", - "strapiemail": "groovy { return attributes['mail'].get(0) }", - "strapiusername": "groovy { return attributes['username'].get(0) }" - } - } -} -``` - -Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/plugins/users-permissions/providers](http://localhost:1337/admin/plugins/users-permissions/providers) -- Click on the **Cas** provider -- Fill the information: - - **Enable**: `ON` - - **Client ID**: thestrapiclientid - - **Client Secret**: thestrapiclientsecret - - **The redirect URL to your front-end app**: `http://localhost:1337/api/connect/cas/redirect` - - **The Provider Subdomain such that the following URLs are correct for the CAS deployment you are targeting:** - ``` - authorize_url: https://[subdomain]/oidc/authorize - access_url: https://[subdomain]/oidc/token - profile_url: https://[subdomain]/oidc/profile - ``` - For example, if running CAS locally with a login URL of: `https://localhost:8443/cas/login`, the value for the provider subdomain would be `localhost:8443/cas`. - -
Using ngrok
- -Reddit accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Reddit configuration
- -- Visit the Reddit authorized applications preferences page[https://www.reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) -- Click on the **create another app...** button near the bottom -- Select **web app** for the type -- Fill the **name** and **redirect uri** input in -- Click the **create app** button -- Note that the **Client ID** is located under the app type (web app) - -
Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Reddit** provider -- Fill the information (replace with your own client ID and secret): - - **Enable**: `ON` - - **Client ID**: hmxSBOit0SCjSQ - - **Client Secret**: gwR9hCjK_PMYVYNGeDLS4WLB8g7xqg - - **The redirect URL to your front-end app**: `http://localhost:3000/connect/reddit/redirect` - -
Using ngrok
- -Auth0 accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Auth0 configuration
- -- Visit your Auth0 tenant dashboard -- In API section, create a new API -- In application, create a `machine-to-machine` application and select the API that you have just created -- In settings of this app set these values: - - **Allowed Callback URLs**: `http://localhost:1337/api/connect/auth0/callback` - - **Allowed Logout URLs**: `http://localhost:3000` - - **Allowed Web Origins**: `http://localhost:3000` -- At the bottom of settings, show "Advanced Settings" and go to the "Grant Types". Ensure that these grants are checked/enabled: - - Implicit - - Authorization Code - - Refresh Token - - Client Credentials - -Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Auth0** provider -- Fill the information: - - Enable: `ON` - - Client ID: `
Using ngrok
- -Patreon does not accept `localhost` urls.-Use `ngrok` to serve the backend app. - -```bash -ngrok http 1337 -``` - -Don't forget to update the server url in the Strapi config file `./config/server.js` and the server URL in your frontend app (environment variable `REACT_APP_BACKEND_URL` if you use [react login example app](https://github.com/strapi/strapi-examples/tree/master/examples/login-react)) with the generated ngrok URL. - -
Patreon configuration
- -- You must be a Patreon Creator in order to register an Oauth client. -- Go to the [Patreon developer portal](https://www.patreon.com/portal) -- Click on [Clients & API Keys](https://www.patreon.com/portal/registration/register-clients) -- 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. -- 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 -[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. - -Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Patreon** provider -- Fill the information: - - Enable: `ON` - - Client ID: `
Using ngrok
- -Keycloak accepts the `localhost` urls.-The use of `ngrok` is not needed. - -
Keycloak configuration
- -- Visit your Keycloak admin dashboard -- If you don't already have a realm, you'll want to create one -- In the Clients section of your realm, create a new client -- Under the capability config, ensure you set `Client Authentication` to on to ensure you can create a private key -- Under the access settings, ensure you set the following values: - - **Valid redirect URIs**: `http://localhost:1337/api/connect/keycloak/callback` and `http://localhost:1337/api/connect/keycloak` - - **Allowed Web Origins**: `http://localhost:3000` and `http://localhost:1337` -- In the Client Scopes section, ensure you have the `email` and `profile` scopes set to default -- In the Client Scopes section, ensure you have the `openid` scope set to default, if you don't have this you will need to manually create it in the global Client Scopes - -Strapi configuration
- -- Visit the User Permissions provider settings page[http://localhost:1337/admin/settings/users-permissions/providers](http://localhost:1337/admin/settings/users-permissions/providers) -- Click on the **Keycloak** provider -- Fill the information: - - Enable: `ON` - - Client ID: `
- The JSON request response will be `{ "jwt": "...", "user": {...} }`. - -Now you can make authenticated requests. More info here: [token usage](#token-usage). - -:::caution Troubleshooting - -- **Error 429**: It's most likely because your login flow fell into a loop. To make new requests to the backend, you need to wait a few minutes or restart the backend. -- **Grant: missing session or misconfigured provider**: It may be due to many things. - - **The redirect url can't be built**: Make sure you have set the backend url in `config/server.js`: [Setting up the server url](#setting-up-the-server-url) - - **A session/cookie/cache problem**: You can try again in a private tab. - - **The incorrect use of a domain with ngrok**: Check your urls and make sure that you use the ngrok url instead of `http://localhost:1337`. Don't forget to check the backend url set in the example app at `src/config.js`. -- **You can't access your admin panel**: It's most likely because you built it with the backend url set with a ngrok url and you stopped/restarted ngrok. You need to replace the backend url with the new ngrok url and run `yarn build` or `npm run build` again. -::: - -### Reset password - -**Can only be used for users registered using the email provider.** - -
+
+
+
+
+
+
+
+By default, plugins permissions can be configured for the Content-type Builder, the Upload (i.e. Media Library) plugin, the Content Manager, and Users Permissions (i.e. the Users & Permissions plugin allowing to manage end users). Each plugin has its own specific set of permissions.
+
+| Plugin name | Permissions |
+| -------------------- | ----------- |
+| Content-Releases
*(Releases)* |
*(Media Library)* |
*General > Settings > Users & Permissions plugin* | + +
+
+
+
+Settings permissions can be configured for all settings accessible from *General > Settings* from the main navigation of the admin panel: Media Library and Webhooks (*Global settings* section) and Users & Roles (*Administration panel* section, to configure the settings of the RBAC feature). Settings permissions also allow to configure access to the Plugins and Marketplace sections of the admin panel. Each setting has its own specific set of permissions.
+
+| Setting name | Permissions |
+| ----------------------- | ----------- |
+| Content Releases |
*General > Settings > Global Settings - Releases* | +| Email |
*General > Settings > Users & Permissions plugin - Email templates* | +| Media Library |
*General > Settings > Global Settings - Media Library* | +| Internationalization |
*General > Settings > Global Settings - Internationalization* | +| Review Workflows
*General > Settings > Global Settings - Review workflows* | +| Single sign on
*General > Settings > Global Settings - Single Sign-On* | +| Audit Logs |
*General > Settings > Admin Panel - Audit Logs* | +| Plugins and Marketplace |
*General > Settings > Global Settings - Webhook* | +| Users and Roles |
*General > Settings > Administration Panel* | +| API Tokens |
*General > Settings > Global Settings - API Tokens* | +| Project |
*General > Settings > Global Settings - Transfer Tokens* | + +
+
+
+
+4. Click on the **Save** button on the top right corner.
+
+#### Setting custom conditions for permissions
+
+For each permission of each category, a  **Settings** button is displayed. It allows to push the permission configuration further by defining additional conditions for the administrators to be granted the permission. There are 2 default additional conditions:
+
+- the administrator must be the creator,
+- the administrator must have the same role as the creator.
+
+:::note
+Other custom conditions can be available if they have been created beforehand for your Strapi application (see [Role-Based Access Control](/dev-docs/configurations/guides/rbac)).
+:::
+
+
+
+
+
Users locked out of local authentication will be forced to use SSO to login and will not be able to change or reset their password. | + +3. Click the **Save** button. + +:::danger +Don't select _Super Admin_ in the roles list for the _Local authentication lock-out_. If _Super Admin_ is selected, it becomes possible to accidentally lock oneself out of the Strapi admin panel entirely. A fix will be provided soon. + +In the meantime, the only way to get in if the Super Admin can't log in is to temporarily disable the SSO feature entirely, log in with username and password to remove the _Super Admin_ role from the _Local authentication lock-out_ list, and then re-enable SSO. +::: + +
+
+
+
+
+
+
+
+
+
From the edit view of a content type: click  (top right corner) then  **Content History**. + +### Browsing Content History + + + +With Content History, you can browse your content through: + +- The main view on the left, which lists the fields and their content for the version selected in the sidebar on the right. +- The sidebar on the right, which lists the total number of versions available, and for each version: + - the date and time when the version was created, + - the user who created it, + - and whether its status is Draft, Modified, or Published (see [Draft & Publish](/user-docs/content-manager/saving-and-publishing-content#saving--publishing-content) for more information about document statuses). + + +
+
+ +Note also that the explanations below explain how to permanently configure which fields are displayed in the table of the list view of your collection type. It is also possible to configure the displayed fields temporarily (see [Introduction to Content Manager](/user-docs/content-manager)). +::: + +
💡 The box can be expanded by clicking on **Expand** in the bottom bar. It displays side by side, at the same time, the textbox that you can edit and the preview. | +| Rich text (Blocks) | Write and manage your content in the editor, which automatically renders live all additions/updates. In the Blocks editor, paragraphs behave as blocks of text: hovering on a paragraph will display an icon  on which to click to reorder the content. Options to format or enrich the content are also accessible from the top bar of the editor (basic formatting options, code, links, image etc.).
💡 You can use text formatting keyboard shortcuts in the Blocks editor (e.g. bold, italics, underline, and pasting link). | +| Number | Write your number in the textbox. Up and down arrows, displayed on the right of the box, allow to increase or decrease the current number indicated in the textbox. | +| Date | 1. Click the date and/or time box.
2. Type the date and time or choose a date using the calendar and/or a time from the list. The calendar view fully supports keyboard-based navigation. | +| Media | 1. Click the media area.
2. Choose an asset from the [Media Library](/user-docs/media-library) or from a [folder](/user-docs/media-library/organizing-assets-with-folders.md) if you created some, or click the **Add more assets** button to add a new file to the Media Library.
💡 It is possible to drag and drop the chosen file in the media area. | +| Relation | Choose an entry from the drop-down list. See [Managing relational fields](/user-docs/content-manager/managing-relational-fields.md) for more information. | +| Boolean | Click on **TRUE** or **FALSE**. | +| JSON | Write your content, in JSON format, in the code textbox. | +| Email | Write a complete and valid email address. | +| Password | Write a password.
💡 Click the  icon, displayed on the right of the box, to show the password. | +| Enumeration | 1. Click the drop-down list.
2. Choose an entry from the list. | +| UID | Write a unique identifier in the textbox. A "Regenerate" button, displayed on the right of the box, allows automatically generating a UID based on the content type name. | + +:::note +Filling out a [custom field](/user-docs/content-type-builder/configuring-fields-content-type.md#custom-fields) depends on the type of content handled by the field. Please refer to the dedicated documentation for each custom field hosted on the [Marketplace](https://market.strapi.io). +::: + +#### Components + +Components are a combination of several fields, which are grouped together in the edit view. Writing their content works exactly like for independent fields, but there are some specificities to components. + +There are 2 types of components: non-repeatable and repeatable components. + +##### Non-repeatable components + +
If Internationalization is enabled for the content-type, you can also choose to delete only the currently selected locale by clicking on the **Delete locale** button. +2. In the window that pops up, click on the **Confirm** button to confirm the deletion. + +:::tip +You can delete entries from the list view of a collection type, by clicking on  on the right side of the entry's record in the table, then choosing the  **Delete document** button.
If Internationalization is enabled for the content-type, **Delete document** deletes all locales while **Delete locale** only deletes the currently listed locale. diff --git a/docusaurus/docs/user-docs/features/content-type-builder.md b/docusaurus/docs/user-docs/features/content-type-builder.md new file mode 100644 index 0000000000..92b6cc0876 --- /dev/null +++ b/docusaurus/docs/user-docs/features/content-type-builder.md @@ -0,0 +1,730 @@ +--- +title: Content-type Builder +description: Learn to use the Content-type Builder. +toc_max_heading_level: 5 +tags: +- admin panel +- content type builder +--- + +import ScreenshotNumberReference from '/src/components/ScreenshotNumberReference.jsx'; + +# Content-type Builder + +The Content-type Builder is from where the users of the admin panel create and edit their content types. + +:::prerequisites Identity Card of the Content-type Builder +
+
Text {#text}
+
+The Text field displays a textbox that can contain small text. This field can be used for titles, descriptions, etc.
+
+
+
+
+
+| Setting name | Instructions |
+|--------------|---------------------------------------------------------------------------------------------------------|
+| Name | Write the name of the Text field. |
+| Type | Choose between *Short text* (255 characters maximum) and *Long text*, to allow more or less space to fill up the Text field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-------------------------------------------------------------------------------|
+| Default value | Write the default value of the Text field. |
+| RegExp pattern | Write a regular expression to make sure the value of the Text field matches a specific format. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+##### 
Rich Text (Blocks) {#rich-text-blocks}
+
+The Rich Text (Blocks) field displays an editor with live rendering and various options to manage rich text. This field can be used for long written content, even including images and code.
+
+
+
+
+
+| Setting name | Instructions |
+|--------------|-------------------------------------------------|
+| Name | Write the name of the Rich Text (Blocks) field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+
+
+
+
+
+:::strapi React renderer
+If using the Blocks editor, we recommend that you also use the [Strapi Blocks React Renderer](https://github.com/strapi/blocks-react-renderer) to easily render the content in a React frontend.
+:::
+
+##### 
Number {#number}
+
+The Number field displays a field for any kind of number: integer, decimal and float.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Number field. |
+| Number format | Choose between *integer*, *big integer*, *decimal* and *float*. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Number field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+| Maximum value | Tick to define a maximum value allowed. |
+| Minimum value | Tick to define a minimum value allowed. |
+
+
+
+
+
+##### 
Date {#date}
+
+The Date field can display a date (year, month, day), time (hour, minute, second) or datetime (year, month, day, hour, minute, and second) picker.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Date field. |
+| Type | Choose between *date*, *datetime* and *time* |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Date field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+
+
+
+
+
+##### 
Password
+
+The Password field displays a password field that is encrypted.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Password field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Password field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+
+##### 
Media {#media}
+
+The Media field allows to choose one or more media files (e.g. image, video) from those uploaded in the Media Library of the application.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Media field. |
+| Type | Choose between *Multiple media* to allow multiple media uploads, and *Single media* to only allow one media upload. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Select allowed types of media | Click on the drop-down list to untick media types not allowed for this field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+
+
+
+
+
+##### 
Relation {#relation}
+
+The Relation field allows to establish a relation with another content-type, that must be a collection type.
+
+There are 6 different types of relations:
+
+- 
One way: Content-type A *has one* Content-type B
+- 
One-to-one: Content-type A *has and belong to one* Content-type B
+- 
One-to-many: Content-type A *belongs to many* Content-type B
+- 
Many-to-one: Content-type B *has many* Content-type A
+- 
Many-to-many: Content-type A *has and belongs to many* Content-type B
+- 
Many way: Content-type A *has many* Content-type B
+
+
+
+
+
+Configuring the base settings of the Relation field consists in choosing with which existing content-type the relation should be established and the kind of relation. The edition window of the Relation field displays 2 grey boxes, each representing one of the content-types in relation. Between the grey boxes are displayed all possible relation types.
+
+1. Click on the 2nd grey box to define the content-type B. It must be an already created collection type.
+2. Click on the icon representing the relation to establish between the content-types.
+3. Choose the *Field name* of the content-type A, meaning the name that will be used for the field in the content-type A.
+4. (optional if disabled by the relation type) Choose the *Field name* of the content-type B.
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+
+
+
+
+
+##### 
Boolean {#boolean}
+
+The Boolean field displays a toggle button to manage boolean values (e.g. Yes or No, 1 or 0, True or False).
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Boolean field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Choose the default value of the Boolean field: *true*, *null* or *false*. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+
+
+
+
+
+##### 
JSON {#json}
+
+The JSON field allows to configure data in a JSON format, to store JSON objects or arrays.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the JSON field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+
+
+
+
+
+##### 
Email {#email}
+
+The Email field displays an email address field with format validation to ensure the email address is valid.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Email field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Email field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Unique field | Tick to prevent another field to be identical to this one. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+##### Password {#password}
+
+The Password field displays a password field that is encrypted.
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Password field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Password field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+##### 
Enumeration {#enum}
+
+The Enumeration field allows to configure a list of values displayed in a drop-down list.
+
+
+
+
+
+
+
+| Setting name | Instructions |
+|---------------|-----------------------------------------------------------------|
+| Name | Write the name of the Enumeration field. |
+| Values | Write the values of the enumeration, one per line. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Choose the default value of the Enumeration field. |
+| Name override for GraphQL | Write a custom GraphQL schema type to override the default one for the field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+
+
+
+
+
+:::caution
+Since Strapi v4.1.3, enumeration values should always have an alphabetical character preceding any number as it could otherwise cause the server to crash without notice when the GraphQL plugin is installed.
+:::
+
+##### 
UID {#uid}
+
+The UID field displays a field that sets a unique identifier, optionally based on an existing other field from the same content-type.
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------|
+| Name | Write the name of the UID field. It must not contain special characters or spaces. |
+| Attached field | Choose what existing field to attach to the UID field. Choose *None* to not attach any specific field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the UID field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+:::tip
+The UID field can be used to create a slug based on the Attached field.
+:::
+
+##### 
Rich Text (Markdown) {#rich-text-markdown}
+
+The Rich Text (Markdown) field displays an editor with basic formatting options to manage rich text written in Markdown. This field can be used for long written content.
+
+
+
+
+
+| Setting name | Instructions |
+|--------------|---------------------------------------------------|
+| Name | Write the name of the Rich Text (Markdown) field. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------|
+| Default value | Write the default value of the Rich Text field. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the field to have a different value per locale. |
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Maximum length | Tick to define a maximum number of characters allowed. |
+| Minimum length | Tick to define a minimum number of characters allowed. |
+
+
+
+
+
+#### Custom fields
+
+Custom fields are a way to extend Strapi’s capabilities by adding new types of fields to content-types or components. Once installed (see [Marketplace](/user-docs/plugins/installing-plugins-via-marketplace.md) documentation), custom fields are listed in the _Custom_ tab when selecting a field for a content-type.
+
+Each custom field type can have basic and advanced settings. The [Marketplace](https://market.strapi.io/plugins?categories=Custom+fields) lists available custom fields, and hosts dedicated documentation for each custom field, including specific settings.
+
+#### 
Components {#components}
+
+Components are a combination of several fields. Components allow to create reusable sets of fields, that can be quickly added to content-types, dynamic zones but also nested into other components.
+
+When configuring a component through the Content-type Builder, it is possible to either:
+
+- create a new component by clicking on *Create a new component* (see [Creating a new component](/user-docs/content-type-builder/creating-new-content-type#creating-a-new-component)),
+- or use an existing one by clicking on *Use an existing component*.
+
+
+
+
+
+| Setting name | Instructions |
+|--------------------|-----------------------------------------------------------------|
+| Name | Write the name of the component for the content-type. |
+| Select a component | When using an existing component only - Select from the drop-down list an existing component. |
+| Type | Choose between *Repeatable component* to be able to use several times the component for the content-type, or *Single component* to limit to only one time the use of the component. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------------------|
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Private field | Tick to make the field private and prevent it from being found via the API. |
+| Maximum value | For repeatable components only - Tick to define a maximum number of characters allowed. |
+| Minimum value | For repeatable components only - Tick to define a minimum number of characters allowed. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the component to be translated per available locale. |
+
+
+
+
+
+#### 
Dynamic zones {#dynamiczones}
+
+Dynamic zones are a combination of components that can be added to content-types. They allow a flexible content structure as once in the Content Manager, administrators have the choice of composing and rearranging the components of the dynamic zone how they want.
+
+
+
+
+
+| Setting name | Instructions |
+|--------------------|-----------------------------------------------------------------|
+| Name | Write the name of the dynamic zone for the content-type. |
+
+
+
+
+
+| Setting name | Instructions |
+|----------------|-----------------------------------------------------------------------------------------|
+| Required field | Tick to prevent creating or saving an entry if the field is not filled in. |
+| Maximum value | Tick to define a maximum number of characters allowed. |
+| Minimum value | Tick to define a minimum number of characters allowed. |
+| Enable localization for this field | (if [Internationalization plugin](/user-docs/plugins/strapi-plugins#i18n) is enabled for the content-type) Allow the dynamic zone to be translated per available locale. |
+
+
+
+
+
+After configuring the settings of the dynamic zone, its components must be configured as well. It is possible to either choose an existing component or create a new one.
+
+:::caution
+When using dynamic zones, different components cannot have the same field name with different types (or with enumeration fields, different values).
+:::
+
+### Managing content-types
+
+:::note development-only
+The Content-type Builder is only accessible to create and update content-types when your Strapi application is in a development environment, else it will be in a read-only mode in other environments.
+:::
+
+The Content-type Builder allows to manage any existing content-type or component, even if it is already being used in the Content Manager. They can only be managed one at a time.
+
+To manage a content-type or a component, click on its name in the Collection types, Single types or Components category.
+
+#### Editing content-types
+
+Managing a content-type or component can include editing the general settings and the fields, but also deleting the whole content-type or component. For any chosen content-type or component, the right side of the Content-type Builder interface displays all available editing options.
+
+
+
+
+
+
+
+
+```js title="/config/admin.js"
+module.exports = ({ env }) => ({
+ // …
+ transfer: {
+ token: {
+ salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
+ }
+ },
+});
+
+```
+
+
+
+
+
+```ts title="/config/admin.ts"
+export default ({ env }) => ({
+ // …
+ transfer: {
+ token: {
+ salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
+ }
+ },
+});
+```
+
+
+
+
+
+## Usage
+
+The Data Management system is CLI-based only, meaning any import, export, or transfer command must be executed from the terminal. Exhaustive documentation for each command is accessible from the following pages:
+
+
+
diff --git a/docusaurus/docs/user-docs/features/draft-and-publish.md b/docusaurus/docs/user-docs/features/draft-and-publish.md
new file mode 100644
index 0000000000..b9d41ceaeb
--- /dev/null
+++ b/docusaurus/docs/user-docs/features/draft-and-publish.md
@@ -0,0 +1,202 @@
+---
+title: Draft & Publish
+description: Learn how you can use the Draft & Publish feature of Strapi 5 to manage drafts for content.
+displayed_sidebar: cmsSidebar
+toc_max_heading_level: 5
+tags:
+ - Content Manager
+ - Content type Builder
+ - Draft & Publish
+ - publishing a draft
+ - unpublishing content
+---
+
+# Draft & Publish
+
+The Draft & Publish feature allows to manage drafts for your content.
+
+:::prerequisites Identity Card of the Feature
+
+
+
+
+
+
+On the back-end server of Strapi, the Document Service API can also be used to interact with localized content:
+
+
+
+
diff --git a/docusaurus/docs/user-docs/features/email.md b/docusaurus/docs/user-docs/features/email.md
new file mode 100644
index 0000000000..3f91299642
--- /dev/null
+++ b/docusaurus/docs/user-docs/features/email.md
@@ -0,0 +1,204 @@
+---
+title: Email
+displayed_sidebar: cmsSidebar
+description: Send email from your server or externals providers.
+tags:
+- admin panel
+- controllers
+- email
+- lifecycle hooks
+- services
+---
+
+# Email
+
+The Email feature enables Strapi applications to send emails from a server or an external provider.
+
+:::prerequisites Identity Card of the Feature
+
+
+
+
+
+
+[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi Email feature. It provides functionality for the local development environment but is not production-ready in the default configuration. For production stage applications you need to further configure `Sendmail` or change providers.
+
+## Usage
+
+The Email feature uses the Strapi global API, meaning it can be called from anywhere inside a Strapi application, either from the back-end server itself through a [controller or service](#controller-service), or from the admin panel, for example in response to an event (using [lifecycle hooks](#lifecycle-hook)).
+
+### Sending emails with a controller or service {#controller-service}
+
+The Email feature has an `email` [service](/dev-docs/backend-customization/services) that contains 2 functions to send emails:
+
+* `send()` directly contains the email contents,
+* `sendTemplatedEmail()` consumes data from the Content Manager to populate emails, streamlining programmatic emails.
+
+#### Using the `send()` function
+
+To trigger an email in response to a user action add the `send()` function to a [controller](/dev-docs/backend-customization/controllers) or [service](/dev-docs/backend-customization/services). The send function has the following properties:
+
+| Property | Type | Format | Description |
+|-----------|----------|---------------|-------------------------------------------------------|
+| `from` | `string` | email address | If not specified, uses `defaultFrom` in `plugins.js`. |
+| `to` | `string` | email address | Required |
+| `cc` | `string` | email address | Optional |
+| `bcc` | `string` | email address | Optional |
+| `replyTo` | `string` | email address | Optional |
+| `subject` | `string` | - | Required |
+| `text` | `string` | - | Either `text` or `html` is required. |
+| `html` | `string` | HTML | Either `text` or `html` is required. |
+
+The following code example can be used in a controller or a service:
+
+```js title="/src/api/my-api-name/controllers/my-api-name.ts|js (or /src/api/my-api-name/services/my-api-name.ts|js)"
+await strapi.plugins['email'].services.email.send({
+ to: 'valid email address',
+ from: 'your verified email address', //e.g. single sender verification in SendGrid
+ cc: 'valid email address',
+ bcc: 'valid email address',
+ replyTo: 'valid email address',
+ subject: 'The Strapi Email feature worked successfully',
+ text: 'Hello world!',
+ html: 'Hello world!',
+}),
+```
+
+#### Using the `sendTemplatedEmail()` function
+
+The `sendTemplatedEmail()` function is used to compose emails from a template. The function compiles the email from the available properties and then sends the email.
+
+To use the `sendTemplatedEmail()` function, define the `emailTemplate` object and add the function to a controller or service. The function calls the `emailTemplate` object, and can optionally call the `emailOptions` and `data` objects:
+
+| Parameter | Description | Type | Default |
+|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|
+| `emailOptions`
Optional | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | +| `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | { } | +| `data`
Optional | Contains the data used to compile the templates | `object` | { } | + +The following code example can be used in a controller or a service: + +```js title="/src/api/my-api-name/controllers/my-api-name.js (or ./src/api/my-api-name/services/my-api-name.js)" +const emailTemplate = { + subject: 'Welcome <%= user.firstname %>', + text: `Welcome to mywebsite.fr! + Your account is now linked with: <%= user.email %>.`, + html: `
Email plugin {#email}
+
## Additional plugins
diff --git a/docusaurus/docs/user-docs/releases/creating-a-release.md b/docusaurus/docs/user-docs/releases/creating-a-release.md
index 57239157f7..d4b594e21e 100644
--- a/docusaurus/docs/user-docs/releases/creating-a-release.md
+++ b/docusaurus/docs/user-docs/releases/creating-a-release.md
@@ -8,10 +8,8 @@ tags:
- Strapi Cloud
---
-import NotV5 from '/docs/snippets/_not-updated-to-v5.md'
-
# Creating a release
-
-
+
);
}
diff --git a/docusaurus/src/components/Guideflow.js b/docusaurus/src/components/Guideflow.js
new file mode 100644
index 0000000000..4dd475dc96
--- /dev/null
+++ b/docusaurus/src/components/Guideflow.js
@@ -0,0 +1,51 @@
+import React from 'react';
+import { useColorMode } from '@docusaurus/theme-common';
+
+export default function Guideflow({ lightId, darkId }) {
+ const { isDarkTheme } = useColorMode();
+
+ if (!lightId) return null;
+
+ const iframeStyle = {
+ overflow: 'hidden',
+ position: 'absolute',
+ border: 'none',
+ width: '100%',
+ height: '100%',
+ transition: 'opacity 0.2s'
+ };
+
+ return (
+
Step 1: Run the installation script and create a Strapi Cloud account
### Step 1: Run the installation script and create a Strapi Cloud account @@ -444,7 +442,7 @@ Keep on creating amazing content! ::: :::tip Tip: Transfer data between your local and Strapi Cloud projects -The databases for your Strapi Cloud project and your local project are different. This means that data is not automatically synchronized between your Strapi Cloud and local projects. You can use the [data management system](/dev-docs/data-management) to transfer data between projects. +The databases for your Strapi Cloud project and your local project are different. This means that data is not automatically synchronized between your Strapi Cloud and local projects. You can use the [data management system](/user-docs/features/data-management) to transfer data between projects. ::: ##+
+
+
*(Releases)* |
- General
- "Read" - gives access to the Releases feature
- "Create" - allows to create releases
- "Edit" - allows to edit releases
- "Delete" - allows to delete releases
- "Publish" - allows to publish releases
- "Remove an entry from a release"
- "Add an entry to a release"
- Single types
- "Configure view" - allows to configure the edit view of a single type
- Collection types
- "Configure view" - allows to configure the edit view of a collection type
- Components
- "Configure Layout" - allows to configure the layout of a component
- General
- "Read" - gives access to the Content-type Builder plugin in read-only mode
*(Media Library)* |
- General
- "Access the Media Library" - gives access to the Media Library plugin
- "Configure view" - allows to configure the view of the Media Library
- Assets
- "Create (upload)" - allows to upload media files
- "Update (crop, details, replace) + delete" - allows to edit uploaded media files
- "Download" - allows to download uploaded media files
- "Copy link" - allows to copy the link of an uploaded media file
- Roles
- "Create" - allows to create end-user roles
- "Read" - allows to see created end-user roles
- "Update" - allows to edit end-user roles
- "Delete" - allows to delete end-user roles
- Providers
- "Read" - allows to see providers
- "Edit" - allows to edit providers
- Email Templates
- "Read" - allows to access the email templates
- "Edit" - allows to edit email templates
- Advanced settings
- "Read" - allows to access the advanced settings of the Users & Permissions plugin
- "Edit" - allows to edit advanced settings
*General > Settings > Users & Permissions plugin* | + +
- Options
- "Read" - allows to access the Releases settings
- "Edit" - allows to edit the Releases settings
*General > Settings > Global Settings - Releases* | +| Email |
- General
- "Access the Email settings page" - gives access to Email settings
*General > Settings > Users & Permissions plugin - Email templates* | +| Media Library |
- General
- "Access the Media Library settings page" - gives access to Media Library settings
*General > Settings > Global Settings - Media Library* | +| Internationalization |
- Locales
- "Create" - allows to create new locales
- "Read" - allows to see available locales
- "Update" - allows to edit available locales
- "Delete" - allows to delete locales
*General > Settings > Global Settings - Internationalization* | +| Review Workflows
- "Create" - allows to create workflows
- "Read" - allows to see created workflows
- "Update" - allows to edit workflows
- "Delete" - allows to delete workflows
*General > Settings > Global Settings - Review workflows* | +| Single sign on
- Options
- "Read" - allows to access the SSO settings
- "Update" - allows to edit the SSO settings
*General > Settings > Global Settings - Single Sign-On* | +| Audit Logs |
- Options
- "Read" - allows to access the Audit Logs settings
*General > Settings > Admin Panel - Audit Logs* | +| Plugins and Marketplace |
- Marketplace
- "Access the Marketplace" - gives access to the Marketplace
- General
- "Create" - allows to create webhooks
- "Read" - allows to see created webhooks
- "Update" - allows to edit webhooks
- "Delete" - allows to delete webhooks
*General > Settings > Global Settings - Webhook* | +| Users and Roles |
- Users
- "Create (invite)" - allows to create administrator accounts
- "Read" - allows to see existing administrator accounts
- "Update" - allows to edit administrator accounts
- "Delete" - allows to delete administrator accounts
- Roles
- "Create" - allows to create administrator roles
- "Read" - allows to see created administrator roles
- "Update" - allows to edit administrator roles
- "Delete" - allows to delete administrator roles
*General > Settings > Administration Panel* | +| API Tokens |
- API tokens
- "Access the API tokens settings page" - toggles access to the API tokens page
- General
- "Create (generate)" - allows the creation of API tokens
- "Read" - allows you to see created API tokens (disabling this permission will disable access to the *Global Settings - API Tokens* settings)
- "Update" - allows editing of API tokens
- "Delete (revoke)" - allows deletion of API tokens
- "Regenerate" - allows regeneration of the API token
*General > Settings > Global Settings - API Tokens* | +| Project |
- General
- "Update the project level settings" - allows to edit the settings of the project
- "Read the project level settings" - gives access to settings of the project
- Transfer tokens
- "Access the Transfer tokens settings page" - toggles access to the Transfer tokens page
- General
- "Create (generate)" - allows the creation of Transfer tokens
- "Read" - allows you to see created Transfer tokens (disabling this permission will disable access to the *Global Settings - Transfer Tokens* settings)
- "Update" - allows editing of Transfer tokens
- "Delete (revoke)" - allows deletion of Transfer tokens
- "Regenerate" - allows regeneration of the Transfer token
*General > Settings > Global Settings - Transfer Tokens* | + +
+
+
+
Users locked out of local authentication will be forced to use SSO to login and will not be able to change or reset their password. | + +3. Click the **Save** button. + +:::danger +Don't select _Super Admin_ in the roles list for the _Local authentication lock-out_. If _Super Admin_ is selected, it becomes possible to accidentally lock oneself out of the Strapi admin panel entirely. A fix will be provided soon. + +In the meantime, the only way to get in if the Super Admin can't log in is to temporarily disable the SSO feature entirely, log in with username and password to remove the _Super Admin_ role from the _Local authentication lock-out_ list, and then re-enable SSO. +::: + +
+
+
+
+
+
+
+
+
+
From the edit view of a content type: click  (top right corner) then  **Content History**. + +### Browsing Content History + + + +With Content History, you can browse your content through: + +- The main view on the left, which lists the fields and their content for the version selected in the sidebar on the right. +- The sidebar on the right, which lists the total number of versions available, and for each version: + - the date and time when the version was created, + - the user who created it, + - and whether its status is Draft, Modified, or Published (see [Draft & Publish](/user-docs/content-manager/saving-and-publishing-content#saving--publishing-content) for more information about document statuses). + + +
+
+
+
+
+The Content Manager is accessible from  *Content Manager* in the main navigation, which opens a sub navigation displaying 2 categories: _Collection types_ and _Single types_. Each category contains the available collection and single content-types which were created beforehand using the [Content-type Builder](/user-docs/content-type-builder/introduction-to-content-types-builder.md). From these 2 categories, administrators can create, manage, and publish content.
+
+:::tip
+Click the search icon  in the sub navigation to use a text search and find one of your content-types more quickly!
+:::
+
+### Collection types {#collection-types}
+
+The _Collection types_ category of the Content Manager displays the list of available collection types which are accessible from the  Content Manager sub navigation.
+
+For each available collection type multiple entries can be created which is why each collection type is divided into 2 interfaces: the list view and the edit view (see [Writing content](/user-docs/content-manager/writing-content)).
+
+The list view of a collection type displays all entries created for that collection type.
+
++ +Note also that the explanations below explain how to permanently configure which fields are displayed in the table of the list view of your collection type. It is also possible to configure the displayed fields temporarily (see [Introduction to Content Manager](/user-docs/content-manager)). +::: + +
💡 The box can be expanded by clicking on **Expand** in the bottom bar. It displays side by side, at the same time, the textbox that you can edit and the preview. | +| Rich text (Blocks) | Write and manage your content in the editor, which automatically renders live all additions/updates. In the Blocks editor, paragraphs behave as blocks of text: hovering on a paragraph will display an icon  on which to click to reorder the content. Options to format or enrich the content are also accessible from the top bar of the editor (basic formatting options, code, links, image etc.).
💡 You can use text formatting keyboard shortcuts in the Blocks editor (e.g. bold, italics, underline, and pasting link). | +| Number | Write your number in the textbox. Up and down arrows, displayed on the right of the box, allow to increase or decrease the current number indicated in the textbox. | +| Date | 1. Click the date and/or time box.
2. Type the date and time or choose a date using the calendar and/or a time from the list. The calendar view fully supports keyboard-based navigation. | +| Media | 1. Click the media area.
2. Choose an asset from the [Media Library](/user-docs/media-library) or from a [folder](/user-docs/media-library/organizing-assets-with-folders.md) if you created some, or click the **Add more assets** button to add a new file to the Media Library.
💡 It is possible to drag and drop the chosen file in the media area. | +| Relation | Choose an entry from the drop-down list. See [Managing relational fields](/user-docs/content-manager/managing-relational-fields.md) for more information. | +| Boolean | Click on **TRUE** or **FALSE**. | +| JSON | Write your content, in JSON format, in the code textbox. | +| Email | Write a complete and valid email address. | +| Password | Write a password.
💡 Click the  icon, displayed on the right of the box, to show the password. | +| Enumeration | 1. Click the drop-down list.
2. Choose an entry from the list. | +| UID | Write a unique identifier in the textbox. A "Regenerate" button, displayed on the right of the box, allows automatically generating a UID based on the content type name. | + +:::note +Filling out a [custom field](/user-docs/content-type-builder/configuring-fields-content-type.md#custom-fields) depends on the type of content handled by the field. Please refer to the dedicated documentation for each custom field hosted on the [Marketplace](https://market.strapi.io). +::: + +#### Components + +Components are a combination of several fields, which are grouped together in the edit view. Writing their content works exactly like for independent fields, but there are some specificities to components. + +There are 2 types of components: non-repeatable and repeatable components. + +##### Non-repeatable components + +
+
+
+Example
+ +In my Strapi admin panel I have created 2 collection types: + +- Restaurant, where each entry is a restaurant +- Category, where each entry is a type of restaurant + +I want to assign a category to each of my restaurants, therefore I have established a relation between my 2 collection types: restaurants can have one category. + +In the Content Manager, from the edit view of my Restaurant entries, I can manage the Category relational field, and choose which entry of Category is relevant for my restaurant. +If Internationalization is enabled for the content-type, you can also choose to delete only the currently selected locale by clicking on the **Delete locale** button. +2. In the window that pops up, click on the **Confirm** button to confirm the deletion. + +:::tip +You can delete entries from the list view of a collection type, by clicking on  on the right side of the entry's record in the table, then choosing the  **Delete document** button.
If Internationalization is enabled for the content-type, **Delete document** deletes all locales while **Delete locale** only deletes the currently listed locale. diff --git a/docusaurus/docs/user-docs/features/content-type-builder.md b/docusaurus/docs/user-docs/features/content-type-builder.md new file mode 100644 index 0000000000..92b6cc0876 --- /dev/null +++ b/docusaurus/docs/user-docs/features/content-type-builder.md @@ -0,0 +1,730 @@ +--- +title: Content-type Builder +description: Learn to use the Content-type Builder. +toc_max_heading_level: 5 +tags: +- admin panel +- content type builder +--- + +import ScreenshotNumberReference from '/src/components/ScreenshotNumberReference.jsx'; + +# Content-type Builder + +The Content-type Builder is from where the users of the admin panel create and edit their content types. + +:::prerequisites Identity Card of the Content-type Builder +
+
Text {#text}
+
+The Text field displays a textbox that can contain small text. This field can be used for titles, descriptions, etc.
+
+ Rich Text (Blocks) {#rich-text-blocks}
+
+The Rich Text (Blocks) field displays an editor with live rendering and various options to manage rich text. This field can be used for long written content, even including images and code.
+
+ Number {#number}
+
+The Number field displays a field for any kind of number: integer, decimal and float.
+
+ Date {#date}
+
+The Date field can display a date (year, month, day), time (hour, minute, second) or datetime (year, month, day, hour, minute, and second) picker.
+
+ Password
+
+The Password field displays a password field that is encrypted.
+
+ Media {#media}
+
+The Media field allows to choose one or more media files (e.g. image, video) from those uploaded in the Media Library of the application.
+
+ Relation {#relation}
+
+The Relation field allows to establish a relation with another content-type, that must be a collection type.
+
+There are 6 different types of relations:
+
+- One way: Content-type A *has one* Content-type B
+- One-to-one: Content-type A *has and belong to one* Content-type B
+- One-to-many: Content-type A *belongs to many* Content-type B
+- Many-to-one: Content-type B *has many* Content-type A
+- Many-to-many: Content-type A *has and belongs to many* Content-type B
+- Many way: Content-type A *has many* Content-type B
+
+ Boolean {#boolean}
+
+The Boolean field displays a toggle button to manage boolean values (e.g. Yes or No, 1 or 0, True or False).
+
+ JSON {#json}
+
+The JSON field allows to configure data in a JSON format, to store JSON objects or arrays.
+
+ Email {#email}
+
+The Email field displays an email address field with format validation to ensure the email address is valid.
+
+ Password {#password}
+
+The Password field displays a password field that is encrypted.
+
+ Enumeration {#enum}
+
+The Enumeration field allows to configure a list of values displayed in a drop-down list.
+
+
+
+ UID {#uid}
+
+The UID field displays a field that sets a unique identifier, optionally based on an existing other field from the same content-type.
+
+ Rich Text (Markdown) {#rich-text-markdown}
+
+The Rich Text (Markdown) field displays an editor with basic formatting options to manage rich text written in Markdown. This field can be used for long written content.
+
+ Components {#components}
+
+Components are a combination of several fields. Components allow to create reusable sets of fields, that can be quickly added to content-types, dynamic zones but also nested into other components.
+
+When configuring a component through the Content-type Builder, it is possible to either:
+
+- create a new component by clicking on *Create a new component* (see [Creating a new component](/user-docs/content-type-builder/creating-new-content-type#creating-a-new-component)),
+- or use an existing one by clicking on *Use an existing component*.
+
+ Dynamic zones {#dynamiczones}
+
+Dynamic zones are a combination of components that can be added to content-types. They allow a flexible content structure as once in the Content Manager, administrators have the choice of composing and rearranging the components of the dynamic zone how they want.
+
++
+
+
- *Push* to allow transfers from local to remote instances only,
- *Pull* to allow transfers from remote to local instances only,
- or *Full Access* to allow both types of transfer.
+
+
+
+
+
+
Optional | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | +| `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | { } | +| `data`
Optional | Contains the data used to compile the templates | `object` | { } | + +The following code example can be used in a controller or a service: + +```js title="/src/api/my-api-name/controllers/my-api-name.js (or ./src/api/my-api-name/services/my-api-name.js)" +const emailTemplate = { + subject: 'Welcome <%= user.firstname %>', + text: `Welcome to mywebsite.fr! + Your account is now linked with: <%= user.email %>.`, + html: `
Welcome to mywebsite.fr!
+Your account is now linked with: <%= user.email %>.
`,
+};
+
+await strapi.plugins['email'].services.email.sendTemplatedEmail(
+ {
+ to: user.email,
+ // from: is not specified, the defaultFrom is used.
+ },
+ emailTemplate,
+ {
+ user: _.pick(user, ['username', 'email', 'firstname', 'lastname']),
+ }
+);
+```
+
+### Sending emails from a lifecycle hook {#lifecycle-hook}
+
+ To trigger an email based on administrator actions in the admin panel use [lifecycle hooks](/dev-docs/backend-customization/models#lifecycle-hooks) and the [`send()` function](#using-the-send-function).
+
+ The following example illustrates how to send an email each time a new content entry is added in the Content Manager use the `afterCreate` lifecycle hook:
+
+
+
+
+
+
+
+
Default sizes for each format can be [configured through the code](#responsive-images). | True |
+ | Size optimization | Enabling this option will reduce the image size and slightly reduce its quality. | True |
+ | Auto orientation | Enabling this option will automatically rotate the image according to EXIF orientation tag. | False |
+
+3. Click on the **Save** button.
+
+### Code-based configuration
+
+The Media Library is powered in the backend server by the Upload package, which can be configured and extended through providers.
+
+#### Additional providers
+
+By default Strapi provides a [provider](/dev-docs/providers) that uploads files to a local `public/uploads/` directory in your Strapi project. Additional providers are available should you want to upload your files to another location.
+
+The providers maintained by Strapi are the following. Clicking on a card will redirect you to their Strapi Marketplace page:
+
+
(200 MB in bytes, i.e., 200 x 1024 x 1024 bytes) |
+| `breakpoints` | Allows to override the breakpoints sizes at which responsive images are generated when the "Responsive friendly upload" option is set to `true` (see [responsive images](#responsive-images)) | Object | `{ large: 1000, medium: 750, small: 500 }` |
+
+:::note
+The Upload request timeout is defined in the server options, not in the Upload plugin options, as it's not specific to the Upload plugin but is applied to the whole Strapi server instance (see [upload request timeout](#upload-request-timeout)).
+:::
+
+#### Example custom configuration
+
+The following is an example of a custom configuration for the Upload plugin when using the default upload provider:
+
+
- PNG
- GIF
- SVG
- TIFF
- ICO
- DVU |
+| Video | - MPEG
- MP4
- MOV (Quicktime)
- WMV
- AVI
- FLV |
+| Audio | - MP3
- WAV
- OGG |
+| File | - CSV
- ZIP
- PDF
- XLS, XLSX
- JSON |
+
+### Managing individual assets
+
+The Media Library allows managing assets, which includes modifying assets' file details and location, downloading and copying the link of the assets file, and deleting assets. Image files can also be cropped. To manage an asset, click on its Edit  button.
+
+#### Editing assets
+
+Clicking on the edit  button of an asset opens up a "Details" window, with all the available options.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Configuring end-user roles
+
+
+
+The configurations of the end-user roles and permissions are available in the *Users & Permissions plugin* section of the  _Settings_ sub navigation.
+
+
+ Eg: 60, "45m", "10h", "2 days", "7d", "2y". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (minutes, hours, days, years, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms").
+
+
Users are a special type of built-in content-type found in any new Strapi application. You can customize the Users model, adding more fields for instance, like any other models.
For more information, please refer to the [models](/dev-docs/backend-customization/models) documentation.
+- `USER` (object)
+ - `username`
+ - `email`
+- `TOKEN` corresponds to the token generated to be able to reset the password.
+- `URL` is the link where the user will be redirected after clicking on it in the email.
+- `SERVER_URL` is the absolute server url (configured in server configuration).
+
+
+- `USER` (object)
+ - `username`
+ - `email`
+- `CODE` corresponds to the CODE generated to be able confirm the user email.
+- `URL` is the Strapi backend URL that confirms the code (by default `/auth/email-confirmation`).
+- `SERVER_URL` is the absolute server url (configured in server configuration).
+
+
Strapi is constantly evolving and growing. This implies that new releases are quite frequent, to improve what is already available but also to add new features to Strapi. For every new Strapi version, we communicate through our main channels and by sending notifications both on your terminal (when launching your Strapi application), and on your application's admin panel. We always recommend to use the latest version. However, we always keep live both the documentation of the current Strapi version, and the documentation of the previous major version — the latter being officially and actively maintained for up to 12 months after the release of the newest Strapi version.
-- **License and Pricing Plans**
As a Strapi user you have the choice between using the Community Edition, which is entirely free, or the [Enterprise Edition](https://strapi.io/pricing-self-hosted). In this user guide, if a feature is only available for the Enterprise Edition, an
As a Strapi user you have the choice between using the Community Edition, which is entirely free, the [Growth plan](https://strapi.io/pricing-self-hosted), or the [Enterprise plan](https://strapi.io/pricing-self-hosted). In this user guide, if a feature is available for the Growth plan, or for the Enterprise plan, then respectively a
Some incoming Strapi features are not yet ready to be shipped to all users, but Strapi still offers community users the opportunity to provide early feedback on these new features or changes. This feedback is invaluable in enhancing the feature before the final release. Such experimental features are indicated by a
- Creation of a default collection type "User" which allows for the management of the end users, the end-user roles and their permissions. This collection type cannot be deleted and the composing fields cannot be edited, but the addition of new fields is possible.
- Addition of the default "User" collection type that allows for the management of end-user accounts (see [Managing end-user accounts](/user-docs/users-roles-permissions/managing-end-users)).
- By default, the following fields are available: Username, Email, Password, as well as Confirmed and Blocked as boolean fields.
- The "User" collection type has a relation established with the "Role" collection type. All end-user accounts must have a designated role: by default, the end user is attributed the end-user role set as default, but that role can be changed via the end-user entries directly in the Content Manager.
Email plugin {#email}
+
## Additional plugins
diff --git a/docusaurus/docs/user-docs/releases/creating-a-release.md b/docusaurus/docs/user-docs/releases/creating-a-release.md
index 57239157f7..d4b594e21e 100644
--- a/docusaurus/docs/user-docs/releases/creating-a-release.md
+++ b/docusaurus/docs/user-docs/releases/creating-a-release.md
@@ -8,10 +8,8 @@ tags:
- Strapi Cloud
---
-import NotV5 from '/docs/snippets/_not-updated-to-v5.md'
-
# Creating a release
-
+
+
+ {darkId && (
+
+ )}
+
+ );
+}
diff --git a/docusaurus/src/pages/home/_home.content.js b/docusaurus/src/pages/home/_home.content.js
index b0a9a9ce1e..f495a50728 100644
--- a/docusaurus/src/pages/home/_home.content.js
+++ b/docusaurus/src/pages/home/_home.content.js
@@ -2,8 +2,8 @@ import React from 'react';
export default {
page: {
- title: 'Strapi Docs',
- description: 'Get set up in minutes to build any projects in hours instead of weeks.',
+ title: 'Strapi 5 Docs',
+ // description: 'Get set up in minutes to build any projects in hours instead of weeks.',
},
carousel: [
{
diff --git a/docusaurus/src/scss/admonition.scss b/docusaurus/src/scss/admonition.scss
index fb605c4dfe..aa9eadbff6 100644
--- a/docusaurus/src/scss/admonition.scss
+++ b/docusaurus/src/scss/admonition.scss
@@ -170,7 +170,8 @@
}
& + h2 {
- margin-top: 74px;
+ margin-top: 0;
+ padding-top: 0 !important;
}
}
diff --git a/docusaurus/src/scss/announcement-bar.scss b/docusaurus/src/scss/announcement-bar.scss
index 430a795bb5..36e1c18082 100644
--- a/docusaurus/src/scss/announcement-bar.scss
+++ b/docusaurus/src/scss/announcement-bar.scss
@@ -18,6 +18,7 @@
opacity: 1;
svg {
+ display: initial;
width: 11px;
height: 11px;
diff --git a/docusaurus/src/scss/api-call.scss b/docusaurus/src/scss/api-call.scss
index 6c2d1f6dfa..a3af227800 100644
--- a/docusaurus/src/scss/api-call.scss
+++ b/docusaurus/src/scss/api-call.scss
@@ -97,6 +97,7 @@
--custom-code-block-background-color: var(--custom-api-call-response-content-background-color);
}
+
}
.theme-code-block {
diff --git a/docusaurus/src/scss/badge.scss b/docusaurus/src/scss/badge.scss
index 264176791d..cf95f17268 100644
--- a/docusaurus/src/scss/badge.scss
+++ b/docusaurus/src/scss/badge.scss
@@ -152,6 +152,13 @@
--custom-badge-tooltip-color: var(--custom-badge-background-color);
}
+ &--growth {
+ --custom-badge-background-color: var(--strapi-primary-600);
+ --custom-badge-color: white;
+ --custom-badge-tooltip-background-color: var(--strapi-primary-100);
+ --custom-badge-tooltip-color: var(--custom-badge-background-color);
+ }
+
&--pro {
--custom-badge-background-color: var(--strapi-primary-600);
--custom-badge-color: #fff;
@@ -173,6 +180,12 @@
--custom-badge-tooltip-color: var(--custom-badge-background-color);
}
+ &__link {
+ .strapi-icons {
+ // vertical-align: bottom;
+ }
+ }
+
&--content {
height: 20px;
font-weight: 500;
@@ -253,6 +266,7 @@ main .badge--developer,
main .badge--team,
main .badge--pro,
main .badge--enterprise,
+main .badge--growth,
main .badge--version {
.badge__tooltip {
@include badge-tooltip();
@@ -509,6 +523,11 @@ h2 .badge {
--custom-badge-tooltip-background-color: var(--strapi-neutral-100);
--custom-badge-tooltip-color: var(--strapi-warning-100);
}
+ &--growth {
+ --custom-badge-background-color: #4945ff;
+ --custom-badge-color: white;
+ --custom-badge-tooltip-background-color: var(--strapi-neutral-100);
+ }
&--alpha,
&--beta,
&--featureflag,
diff --git a/docusaurus/src/scss/code-block.scss b/docusaurus/src/scss/code-block.scss
index 493eb39d8e..c26a12cdb8 100644
--- a/docusaurus/src/scss/code-block.scss
+++ b/docusaurus/src/scss/code-block.scss
@@ -99,7 +99,8 @@ pre.prism-code {
&.method,
&.property-access,
- &.function {
+ &.function,
+ &.attr-name {
color: var(--custom-code-block-function-color) !important;
}
@@ -134,6 +135,10 @@ pre.prism-code {
[class*="highlighted-line"] {
background-color: var(--custom-code-block-background-color-highlighted);
}
+
+ code {
+ background-color: var(--custom-code-block-background-color);
+ }
}
}
@@ -155,6 +160,10 @@ pre.prism-code {
}
}
}
+
+ svg {
+ display: initial;
+ }
}
[class*="codeBlockTitle"] {
@@ -315,7 +324,7 @@ pre.prism-code {
}
.clean-btn {
- background-color: var(--strapi-neutral-100);
+ background-color: transparent;
svg {
color: var(--strapi-neutral-900);
diff --git a/docusaurus/src/scss/code.scss b/docusaurus/src/scss/code.scss
index 9f8d16b4d5..754f1dfbd7 100644
--- a/docusaurus/src/scss/code.scss
+++ b/docusaurus/src/scss/code.scss
@@ -36,6 +36,10 @@ pre {
}
}
+h1, h2, h3, h4, h5 {
+ display: inline-block !important;
+}
+
h1, h2, h3, li, p, table {
code {
background-color: var(--custom-code-background-color);
@@ -53,6 +57,16 @@ h1, h2, h3, li, p, table {
}
}
+h2, h3 {
+ code {
+ padding: 4px 8px;
+ vertical-align: baseline;
+ position: relative;
+ top: -2px;
+ margin-right: 6px;
+ }
+}
+
/** Special styles when using the tag `code` inside a HTML table. */
table {
code {
diff --git a/docusaurus/src/scss/custom-search-bar.scss b/docusaurus/src/scss/custom-search-bar.scss
index f1ae96a68c..79ffaabadc 100644
--- a/docusaurus/src/scss/custom-search-bar.scss
+++ b/docusaurus/src/scss/custom-search-bar.scss
@@ -8,10 +8,10 @@
background-color: white;
position: relative;
top: 60px;
- left: 24px;
+ left: 23px;
margin-top: 20px;
margin-bottom: 20px;
- max-width: 238px;
+ max-width: 232px;
box-shadow: 0px 2px 2px rgba(0, 0, 0, 0.04);
.DocSearch.DocSearch-Button:hover {
@@ -23,6 +23,7 @@
font-size: var(--strapi-font-size-sm);
line-height: var(--strapi-font-size-sm);
flex: 1 1 50%;
+ height: 34px !important;
}
.DocSearch.DocSearch-Button {
@@ -43,7 +44,7 @@
.DocSearch-Button-Placeholder::before {
content:'\E30C';
- color: var(--strapi-primary-500) !important;
+ color: var(--strapi-neutral-500) !important;
}
}
}
@@ -165,6 +166,7 @@
left: -26px;
right: -16px;
top: 40px;
+ pointer-events: none;
background: linear-gradient(360deg, rgba(255, 255, 255, 0) 0%, var(--strapi-neutral-0) 100%);
}
}
diff --git a/docusaurus/src/scss/footer.scss b/docusaurus/src/scss/footer.scss
index be6dbeed87..23a1b18107 100644
--- a/docusaurus/src/scss/footer.scss
+++ b/docusaurus/src/scss/footer.scss
@@ -2,7 +2,7 @@
.footer {
position: relative;
- padding: 40px;
+ padding: 40px 40px 0 40px;
border-top: solid 1px var(--strapi-neutral-200);
&::before {
diff --git a/docusaurus/src/scss/kapa.scss b/docusaurus/src/scss/kapa.scss
index 69721aa693..9eebc151e3 100644
--- a/docusaurus/src/scss/kapa.scss
+++ b/docusaurus/src/scss/kapa.scss
@@ -6,10 +6,118 @@
background-color: #7B79FF;
}
+// Modal
+
+.mantine-Paper-root {
+ box-shadow: 0px 24px 40px rgba(0, 0, 0, 0.2);
+ // border: 1px solid var(--strapi-neutral-150);
+}
+
+// Header
+
+.mantine-Modal-header {
+ background-color: var(--strapi-neutral-0);
+ border-bottom: solid 1px var(--strapi-neutral-150);
+
+ // Close button
+
+ .mantine-CloseButton-root {
+ background-color: var(--strapi-neutral-0);
+
+ &:hover {
+ background-color: var(--strapi-neutral-100);
+ }
+ }
+}
+
+// Disclaimer
+
+.mantine-Modal-body>.mantine-Modal-body>div:first-of-type>div:first-of-type {
+ background-color: var(--strapi-neutral-100);
+ margin-top: 0;
+ margin-bottom: 4px;
+ padding: 12px;
+
+ .mantine-Group-root {
+ background-color: var(--strapi-neutral-100);
+
+ .mantine-Text-root {
+ color: var(--strapi-neutral-600);
+ }
+ }
+}
+
+// Input
+
+.mantine-InputWrapper-root {
+
+ textarea {
+ background-color: var(--strapi-neutral-0);
+ border-radius: 8px;
+
+ &::placeholder {
+ color: var(--strapi-neutral-300) !important;
+ }
+ }
+
+ // Button
+
+ .mantine-UnstyledButton-root {
+ border: solid 1px var(--strapi-primary-600);
+ border-radius: 4px;
+ }
+}
+
+// Buttons
+
+.mantine-Button-root {
+ background-color: var(--strapi-neutral-100) !important;
+ border-radius: 4px; // Changing the border radius to match the DS
+
+ &:hover {
+ background-color: var(--strapi-neutral-150) !important;
+ }
+}
+
+// Last texts
+
+.mantine-Modal-body>.mantine-Modal-body>div:last-of-type>div:last-of-type {
+
+ .mantine-Text-root {
+ color: var(--strapi-neutral-600);
+ }
+}
+
+.mantine-Popover-dropdown {
+ border: solid 1px var(--strapi-neutral-150);
+}
+
@include dark {
+
+ // Modal
+ .mantine-Paper-root {
+ background-color: #181826;
+ box-shadow: 0px 24px 40px rgba(0, 0, 0, 0.8);
+ }
+
+ // Header
+ .mantine-Modal-header {
+ background-color: var(--strapi-neutral-100);
+ border-bottom: solid 1px var(--strapi-neutral-150);
+
+ // Close button
+ .mantine-CloseButton-root {
+ background-color: var(--strapi-neutral-100);
+
+ &:hover {
+ background-color: var(--strapi-neutral-0);
+ }
+ }
+ }
+
+ // Body
.mantine-Modal-body * {
- background-color: transparent;
- color: white;
+ color: var(--strapi-neutral-800);
}
.mantine-Popover-dropdown {
@@ -20,51 +128,75 @@
.mantine-Modal-body,
.mantine-Modal-header,
.mantine-Group-root {
- background-color: #181826;
- color: #F6F6F9;
-
- code, span, ol {
- color: #F6F6F9;
- }
code {
background-color: black;
}
- a {
- color: var(--strapi-primary-500);
- }
-
pre {
border: solid 1px var(--strapi-input-border-color);
}
}
.mantine-Modal-body {
+
.mantine-InputWrapper-root {
- background-color: black;
- border-radius: 8px;
+
textarea {
+ background-color: var(--strapi-neutral-100);
border-color: var(--strapi-neutral-200);
- &::placeholder {
- color: var(--strapi-neutral-300);
- }
+
&:focus {
- border-color: var(--strapi-neutral-800);
+ border-color: var(--strapi-primary-600);
}
}
+
+ // Button
+ .mantine-UnstyledButton-root {
+ border: solid 1px #4945FF;
+ border-radius: 4px;
+ }
}
}
- .mantine-Modal-body > .mantine-Modal-body > div:first-of-type > div:first-of-type {
- background-color: var(--strapi-neutral-150);
+
+ .mantine-Alert-root {
+ background-color: transparent;
+ border: solid 1px var(--strapi-neutral-200);
+ }
+
+ // Disclaimer
+ .mantine-Modal-body>.mantine-Modal-body>div:first-of-type>div:first-of-type {
+ background-color: var(--strapi-neutral-0);
+
.mantine-Group-root {
- background-color: var(--strapi-neutral-150);
+ background-color: var(--strapi-neutral-0);
+
+ .mantine-Text-root {
+ color: var(--strapi-neutral-700);
+ }
+ }
+ }
+
+ .mantine-Stack-root>div:first-of-type {
+ // background-color: aqua;
+ }
+
+ // Last texts
+ .mantine-Modal-body>.mantine-Modal-body>div:last-of-type>div:last-of-type {
+
+ .mantine-Text-root {
+ color: var(--strapi-neutral-600);
}
}
+ // Buttons
.mantine-Button-root,
- .mantine-Tooltip-tooltip {
- background-color: black !important;
+ .mantine-UnstyledButton-root {
+ background-color: var(--strapi-neutral-0) !important;
+
+ &:hover {
+ background-color: var(--strapi-neutral-150) !important;
+ }
}
}
diff --git a/docusaurus/src/scss/navbar.scss b/docusaurus/src/scss/navbar.scss
index c95b628ce7..df814fb0e5 100644
--- a/docusaurus/src/scss/navbar.scss
+++ b/docusaurus/src/scss/navbar.scss
@@ -96,6 +96,10 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
font-size: var(--custom-navbar-items-font-size);
border-radius: 4px;
border: solid 1px transparent;
+ i {
+ position: relative;
+ top: 1px;
+ }
&--active {
color: var(--strapi-primary-600);
diff --git a/docusaurus/src/scss/sidebar.scss b/docusaurus/src/scss/sidebar.scss
index b3565c9e16..c100009780 100644
--- a/docusaurus/src/scss/sidebar.scss
+++ b/docusaurus/src/scss/sidebar.scss
@@ -59,6 +59,11 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
padding-left: 14px;
padding-right: 2px;
+ &.thin-scrollbar {
+ padding-left: 16px;
+ padding-right: 16px;
+ }
+
&__caret {
margin: 0 0 0 3px;
padding: 0;
@@ -69,11 +74,25 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
}
&__caret,
- &__caret:before {
+ &__caret:before,
+ &__link--sublist-caret::after,
+ &__list-item-collapsible .menu__link--sublist-caret::after {
+ background: var(--ifm-menu-link-sublist-icon) 50% / 1.25rem 1.25rem;;
height: 16px;
width: 16px;
}
+ .menu__list-item-collapsible {
+ a {
+ color: var(--strapi-neutral-600);
+ }
+
+ button.clean-btn.menu__caret {
+ position: inherit;
+ top: 5px;
+ }
+ }
+
&__list {
padding-left: 0;
@@ -124,7 +143,7 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
--ifm-menu-color-active: var(--strapi-neutral-800);
&:after {
- display: none;
+ // display: none;
}
}
@@ -242,6 +261,10 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
font-size: var(--strapi-font-size-md);
// TODO: use fill version
}
+ /**
+ * Note: The pointer-events: none declarations below are used to
+ * disabling click on categories, but we need to keep the link for the breadcrumbs
+ */
/**
* Custom icons for categories
* Using https://phosphoricons.com
@@ -255,21 +278,25 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
}
}
.theme-doc-sidebar-item-category-level-1.category-features > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: '\E922';
}
}
.theme-doc-sidebar-item-category-level-1.category-configurations > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: '\E87C';
}
}
.theme-doc-sidebar-item-category-level-1.category-development > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: '\E586';
}
}
.theme-doc-sidebar-item-category-level-1.category-plugins > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: url("data:image/svg+xml;charset=UTF-8,");
position: relative;
@@ -277,12 +304,14 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
}
}
.theme-doc-sidebar-item-category-level-1.category-api > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: url("data:image/svg+xml;charset=UTF-8,");
// content: '\E1DA';
}
}
.theme-doc-sidebar-item-category-level-1.category-upgrade > .menu__list-item-collapsible a {
+ pointer-events: none;
&::before {
content: url("data:image/svg+xml;charset=UTF-8,");
}
@@ -305,8 +334,34 @@ $selector-color-mode-toggle-wrapper: 'div[class*="ColorModeToggle"]';
}
@include medium-up {
+ [class*="collapseSidebar"]::after,
+ [class*="expandButton"]::after {
+ font-family: "Phosphor";
+ position: relative;
+ top: 0;
+ left: 0;
+ color: var(--strapi-neutral-600);
+ font-weight: 500;
+ }
+
[class*="collapseSidebar"] {
border-bottom: none;
+ min-height: 38px;
+
+ &::after {
+ content:'\E128';
+ }
+ }
+ // svg {
+ // display: none;
+ // }
+ [class*="expandButton"] {
+ svg {
+ display: none;
+ }
+ &::after {
+ content:'\E12A';
+ }
}
}
}
diff --git a/docusaurus/src/scss/table-of-contents.scss b/docusaurus/src/scss/table-of-contents.scss
index e35af86922..3fb526e005 100644
--- a/docusaurus/src/scss/table-of-contents.scss
+++ b/docusaurus/src/scss/table-of-contents.scss
@@ -71,27 +71,34 @@
*/
main .table-of-contents {
code {
- font-size: var(--strapi-font-size-xs);
+ font-size: var(--strapi-font-size-xxs);
background-color: transparent;
border: none;
color: inherit;
padding: 0;
- font-weight: 500;
+ font-weight: 600;
+ position: relative;
+ top: -1px;
}
}
+ul.table-of-contents__left-border {
+ margin-bottom: -10px;
+}
+
/** Responsive */
@include medium-up {
.table-of-contents {
--custom-toc-items-py: var(--strapi-spacing-2);
margin-top: 74px;
+ font-weight: 500;
&::before {
content: '\e484';
font-family: "Phosphor";
font-size: 16px;
position: relative;
- top: -8px;
+ top: -9px;
left: 6px;
}
&::after {
diff --git a/docusaurus/src/theme/MDXComponents.js b/docusaurus/src/theme/MDXComponents.js
index cc4b167701..df37bfe65e 100644
--- a/docusaurus/src/theme/MDXComponents.js
+++ b/docusaurus/src/theme/MDXComponents.js
@@ -18,7 +18,7 @@ import FeedbackPlaceholder from '../components/FeedbackPlaceholder';
import CustomDocCard from '../components/CustomDocCard';
import CustomDocCardsWrapper from '../components/CustomDocCardsWrapper';
import { InteractiveQueryBuilder } from '../components/InteractiveQueryBuilder/InteractiveQueryBuilder';
-import { AlphaBadge, BetaBadge, FeatureFlagBadge, EnterpriseBadge, CloudDevBadge, CloudProBadge, CloudTeamBadge, NewBadge, UpdatedBadge, VersionBadge } from '../components/Badge';
+import { AlphaBadge, BetaBadge, FeatureFlagBadge, EnterpriseBadge, GrowthBadge, CloudDevBadge, CloudProBadge, CloudTeamBadge, NewBadge, UpdatedBadge, VersionBadge } from '../components/Badge';
import { SideBySideColumn, SideBySideContainer } from '../components';
import ThemedImage from '@theme/ThemedImage';
import {
@@ -30,6 +30,7 @@ import { Annotation } from '../components/Annotation';
import SubtleCallout from '../components/SubtleCallout';
import { PluginsConfigurationFile, HeadlessCms, DocumentDefinition, Codemods } from '../components/ReusableAnnotationComponents/ReusableAnnotationComponents';
import Icon from '../components/Icon';
+import Guideflow from '../components/Guideflow';
export default {
// Re-use the default mapping
@@ -51,6 +52,7 @@ export default {
BetaBadge,
FeatureFlagBadge,
EnterpriseBadge,
+ GrowthBadge,
NewBadge,
UpdatedBadge,
CloudDevBadge,
@@ -71,6 +73,7 @@ export default {
MultiLanguageSwitcher,
MultiLanguageSwitcherRequest,
MultiLanguageSwitcherResponse,
+ Guideflow,
Annotation,
Icon,
/**
diff --git a/docusaurus/static/img/assets/content-manager-guideflow.gif b/docusaurus/static/img/assets/content-manager-guideflow.gif
new file mode 100644
index 0000000000..94f7131d3e
Binary files /dev/null and b/docusaurus/static/img/assets/content-manager-guideflow.gif differ
diff --git a/docusaurus/static/img/assets/content-manager-guideflow2.gif b/docusaurus/static/img/assets/content-manager-guideflow2.gif
new file mode 100644
index 0000000000..d82ac9dc76
Binary files /dev/null and b/docusaurus/static/img/assets/content-manager-guideflow2.gif differ
diff --git a/docusaurus/static/img/assets/content-manager/previewing-content.gif b/docusaurus/static/img/assets/content-manager/previewing-content.gif
new file mode 100644
index 0000000000..f8224f90d4
Binary files /dev/null and b/docusaurus/static/img/assets/content-manager/previewing-content.gif differ
diff --git a/docusaurus/static/img/assets/content-manager/previewing-content.png b/docusaurus/static/img/assets/content-manager/previewing-content.png
new file mode 100644
index 0000000000..97d369f075
Binary files /dev/null and b/docusaurus/static/img/assets/content-manager/previewing-content.png differ
diff --git a/docusaurus/static/img/assets/icons/v5/info.svg b/docusaurus/static/img/assets/icons/v5/info.svg
new file mode 100644
index 0000000000..d9f23bf50d
--- /dev/null
+++ b/docusaurus/static/img/assets/icons/v5/info.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docusaurus/static/img/assets/plugins/documentation-plugin.gif b/docusaurus/static/img/assets/plugins/documentation-plugin.gif
new file mode 100644
index 0000000000..06c06b8bf7
Binary files /dev/null and b/docusaurus/static/img/assets/plugins/documentation-plugin.gif differ
diff --git a/docusaurus/static/img/assets/plugins/documentation-plugin_DARK.gif b/docusaurus/static/img/assets/plugins/documentation-plugin_DARK.gif
new file mode 100644
index 0000000000..8aea63e672
Binary files /dev/null and b/docusaurus/static/img/assets/plugins/documentation-plugin_DARK.gif differ
diff --git a/docusaurus/static/img/assets/settings/settings-email-config-role.png b/docusaurus/static/img/assets/settings/settings-email-config-role.png
new file mode 100644
index 0000000000..3e28904072
Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings-email-config-role.png differ
diff --git a/docusaurus/static/img/assets/settings/settings-email-config-role_DARK.png b/docusaurus/static/img/assets/settings/settings-email-config-role_DARK.png
new file mode 100644
index 0000000000..3ba4840bbf
Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings-email-config-role_DARK.png differ
diff --git a/docusaurus/static/img/assets/settings/settings-email.png b/docusaurus/static/img/assets/settings/settings-email.png
new file mode 100644
index 0000000000..a527f64d68
Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings-email.png differ
diff --git a/docusaurus/static/img/assets/settings/settings-email_DARK.png b/docusaurus/static/img/assets/settings/settings-email_DARK.png
new file mode 100644
index 0000000000..f7acb7a140
Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings-email_DARK.png differ
diff --git a/docusaurus/vercel.json b/docusaurus/vercel.json
index e28253febc..4c928277a4 100644
--- a/docusaurus/vercel.json
+++ b/docusaurus/vercel.json
@@ -210,7 +210,7 @@
},
{
"source": "/developer-docs/latest/developer-resources/data-management.html",
- "destination": "/dev-docs/data-management"
+ "destination": "/user-docs/features/data-management"
},
{
"source": "/developer-docs/latest/developer-resources/database-migrations.html",
@@ -515,7 +515,7 @@
},
{
"source": "/developer-docs/latest/plugins/i18n.html",
- "destination": "/dev-docs/i18n"
+ "destination": "/user-docs/features/internationalization"
},
{
"source": "/developer-docs/latest/development/plugins-development.html",
@@ -1235,7 +1235,7 @@
},
{
"source": "/dev-docs/api/rest/filters-locale-publication#publication-state",
- "destination": "/dev-docs/api/rest/filters-locale-publication#status"
+ "destination": "/dev-docs/api/rest/status"
},
{
"source": "/dev-docs/admin-panel-customization#access-url",
@@ -1315,79 +1315,79 @@
},
{
"source": "/dev-docs/plugins/i18n",
- "destination": "/dev-docs/i18n"
+ "destination": "/user-docs/features/internationalization"
},
{
"source": "/dev-docs/plugins/i18n#configuration-of-the-default-locale",
- "destination": "/dev-docs/i18n"
+ "destination": "/user-docs/features/internationalization"
},
{
"source": "/dev-docs/plugins/i18n#installation",
- "destination": "/dev-docs/i18n"
+ "destination": "/user-docs/features/internationalization"
},
{
"source": "/dev-docs/plugins/i18n#usage-with-the-rest-api",
- "destination": "/dev-docs/i18n#rest"
+ "destination": "/dev-docs/api/rest/locale"
},
{
"source": "/dev-docs/plugins/i18n#getting-localized-entries-with-the-locale-parameter",
- "destination": "/dev-docs/i18n#rest-get-all"
+ "destination": "/dev-docs/api/rest/locale-get-all"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-new-localized-entry",
- "destination": "/dev-docs/i18n#rest-create"
+ "destination": "/dev-docs/api/rest/locale#rest-delete"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-localization-for-an-existing-entry",
- "destination": "/dev-docs/i18n#rest-put"
+ "destination": "/dev-docs/api/rest/locale-put"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-localization-for-a-collection-type",
- "destination": "/dev-docs/i18n#rest-put-collection-type"
+ "destination": "/dev-docs/api/rest/locale-put-collection-type"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-localization-for-a-single-type",
- "destination": "/dev-docs/i18n#rest-put-single-type"
+ "destination": "/dev-docs/api/rest/locale-put-single-type"
},
{
"source": "/dev-docs/plugins/i18n#updating-an-entry",
- "destination": "/dev-docs/i18n#rest-put"
+ "destination": "/dev-docs/api/rest/locale-put"
},
{
"source": "/dev-docs/plugins/i18n#usage-with-the-graphql-plugin",
- "destination": "/dev-docs/i18n#graphql"
+ "destination": "/user-docs/features/internationalization#graphql"
},
{
"source": "/dev-docs/plugins/i18n#getting-localized-entries-with-graphql",
- "destination": "/dev-docs/i18n#graphql-fetch-all"
+ "destination": "/user-docs/features/internationalization#graphql-fetch-all"
},
{
"source": "/dev-docs/plugins/i18n#fetching-a-collection-type",
- "destination": "/dev-docs/i18n#graphql-fetch-all"
+ "destination": "/user-docs/features/internationalization#graphql-fetch-all"
},
{
"source": "dev-docs/plugins/i18n#fetching-a-single-type",
- "destination": "/dev-docs/i18n#graphql-fetch-all"
+ "destination": "/user-docs/features/internationalization#graphql-fetch-all"
},
{
"source": "/dev-docs/plugins/i18n#creating-new-localized-entries-with-graphql",
- "destination": "/dev-docs/i18n#graphql-create"
+ "destination": "/dev-docs/api/graphql#graphql-create"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-new-localization-for-a-collection-type",
- "destination": "/dev-docs/i18n#graphql-create"
+ "destination": "/dev-docs/api/graphql#graphql-create"
},
{
"source": "/dev-docs/plugins/i18n#creating-a-new-localization-for-a-single-type",
- "destination": "/dev-docs/i18n#graphql-create"
+ "destination": "/dev-docs/api/graphql#graphql-create"
},
{
"source": "/dev-docs/plugins/i18n#updating-a-localized-single-type-with-graphql",
- "destination": "/dev-docs/i18n#graphl-update"
+ "destination": "/user-docs/features/internationalization#graphl-update"
},
{
"source": "/dev-docs/plugins/i18n#deleting-a-localization-for-a-single-type-with-graphql",
- "destination": "/dev-docs/i18n#graphql-delete"
+ "destination": "/dev-docs/api/graphql#graphql-delete"
},
{
"source": "/dev-docs/migration/v3-to-v4/code/configuration",