diff --git a/docs/developer-docs/latest/guides/api-token.md b/docs/developer-docs/latest/guides/api-token.md deleted file mode 100644 index d3948d9706..0000000000 --- a/docs/developer-docs/latest/guides/api-token.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: API Tokens - Strapi Developer Documentation -description: Learn in this guide how to create an API token system in your Strapi project to execute request as an authenticated user. ---- - -# API tokens - -In this guide we will see how you can create an API token system to execute request as an authenticated user. - -This feature is in our [roadmap](https://portal.productboard.com/strapi/1-public-roadmap/c/40-api-access-token-with-permissions). -This guide is a workaround to achieve this feature before we support it natively in strapi. - -## Introduction - -The goal is to be able to request API endpoints with a query parameter `token` that authenticates as a user. `eg. /restaurants?token=my-secret-token`. - -To achieve this feature in development, we will have to customize the `users-permissions` plugin. This guide will help you understand how to customize all your applications. You can read more about [Strapi plugins and customization](/developer-docs/latest/development/plugins-extension.md). - -## Create the Token Content Type - -To manage your tokens, you will have to create a new Content Type named `token`. - -- `string` attribute named `token` -- `relation` attribute **Token** (`user`) - **Token** has and belongs to one **User** - **User** (`token`) - -Then add some users and create some token linked to these users. - -## Setup the file to override - -We now have to customize the function that verifies the `token` token. Strapi has an Authentication process that uses `JWT` tokens, we will reuse this function to customize the verification. - -[Here is the function](https://github.com/strapi/strapi/blob/master/packages/strapi-plugin-users-permissions/config/policies/permissions.js) that manages the JWT validation. - -To be able to customize it, you will have to create a new file in your application `./extensions/users-permissions/config/policies/permissions.js`. - -Then copy the original function that is on GitHub and paste it in your new file. - -When it's done, the Strapi application will use this function instead of the core one. We are ready to customize it. - -## Add token validation logic - -You will have to update the first lines of this function. - -**Path —** `./extensions/users-permissions/config/policies/permissions.js` - -```js -const _ = require('lodash'); - -module.exports = async (ctx, next) => { - let role; - - if (ctx.state.user) { - // request is already authenticated in a different way - return next(); - } - - // add the detection of `token` query parameter - if ( - (ctx.request && ctx.request.header && ctx.request.header.authorization) || - (ctx.request.query && ctx.request.query.token) - ) { - try { - // init `id` and `isAdmin` outside of validation blocks - let id; - let isAdmin; - - if (ctx.request.query && ctx.request.query.token) { - // find the token entry that match the token from the request - const [token] = await strapi.query('token').find({token: ctx.request.query.token}); - - if (!token) { - throw new Error(`Invalid token: This token doesn't exist`); - } else { - if (token.user && typeof token.token === 'string') { - id = token.user.id; - } - isAdmin = false; - } - - delete ctx.request.query.token; - } else if (ctx.request && ctx.request.header && ctx.request.header.authorization) { - // use the current system with JWT in the header - const decoded = await strapi.plugins[ - 'users-permissions' - ].services.jwt.getToken(ctx); - - id = decoded.id; - isAdmin = decoded.isAdmin || false; - } - - // this is the line that already exist in the code - if (id === undefined) { - throw new Error('Invalid token: Token did not contain required fields'); - } - - ... -``` - -And tada! You can now create a token, link it to a user and use it in your URLs with `token` as query parameters. diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md index b764267130..e55e9d8a30 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md @@ -69,7 +69,8 @@ Some settings can only be modified through environment variables: | `NODE_ENV` | String | Type of environment where the app is running | `'development'` | | `BROWSER` | Boolean | Open the admin panel in the browser after startup | `true` | | `ENV_PATH` | String | Path to the file that contains your environment variables | `'./.env'` | -| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE` | String | _Optional_

Initialization locale for the app, if the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/developer-docs/latest/plugins/i18n.md#configuration-in-production-environments)) | `'en'` | +| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE`

_Optional_| String | Initialization locale for the app, if the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/developer-docs/latest/plugins/i18n.md#configuration-in-production-environments)) | `'en'` | +| `API_TOKEN_SALT`

_Optional_ | String | Salt to use to generate [API tokens](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md#api-tokens) | - | ### Configuration using environment variables diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md index 64dea8758b..5d31e37770 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md @@ -24,6 +24,9 @@ module.exports = ({ env }) => ({ host: env('HOST', '0.0.0.0'), port: env.int('PORT', 1337), admin: { + apiToken: { + salt: env('API_TOKEN_SALT','random_string_used_as_a_salt'), + }, auth: { secret: env('ADMIN_JWT_SECRET', 'someSecretKey'), }, @@ -53,6 +56,9 @@ module.exports = ({ env }) => ({ enabled: env.bool('CRON_ENABLED', false), }, admin: { + apiToken: { + salt: env('API_TOKEN_SALT','random_string_used_as_a_salt'), + }, auth: { events: { onConnectionSuccess(e) { @@ -100,6 +106,7 @@ module.exports = ({ env }) => ({ | `cron` | Cron configuration (powered by [`node-schedule`](https://github.com/node-schedule/node-schedule)) | Object | | | `cron.enabled` | Enable or disable CRON tasks to schedule jobs at specific dates. | boolean | `false` | | `admin` | Admin panel configuration | Object | | +| `admin.apiToken.salt` | Salt used to generate [API tokens](#api-tokens) | String | (A random string
generated
by Strapi) | | `admin.auth` | Authentication configuration | Object | | | `admin.auth.secret` | Secret used to encode JWT tokens | string | `undefined` | | `admin.auth.events` | Record of all the events subscribers registered for the authentication | object | `{}` | @@ -115,3 +122,22 @@ module.exports = ({ env }) => ({ | `admin.forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#programmatic-usage) | Object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | | `admin.forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | | `admin.forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | + +## API tokens + +Authentication strategies in Strapi can either be based on the use of the [Users & Permissions plugin](/user-docs/latest/users-roles-permissions/introduction-to-users-roles-permissions.md) or on the built-in [API token]() feature. + + + +Using API tokens allows executing a request on [REST API](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md) endpoints as an authenticated user. The API token should be added to the request's `Authorization` header with the following syntax: `bearer your-api-token`. + +New API tokens are generated from the admin panel using a salt. This salt is automatically generated by Strapi and stored in `./config/server.js` as `admin.api-tokens.salt`. + +The salt can be customized: + +- either by updating the string value for `admin.api-tokens.salt` in `./config/server.js` +- or by creating an `API_TOKEN_SALT` [environment variable](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md#environment-variables) in the `.env` file of the project + +::: caution +Changing the salt invalidates all the existing API tokens. +:::