From 1d391d5b3f179d6c3871aa492f9b8b45cfb40f01 Mon Sep 17 00:00:00 2001 From: Jamie Howard Date: Wed, 17 Sep 2025 15:58:20 +0100 Subject: [PATCH 1/9] feat: add session management and authentication enhancements to CMS documentation --- docusaurus/docs/cms/api/rest.md | 52 +++++ .../examples/authentication.md | 114 ++++++++++ .../docs/cms/configurations/admin-panel.md | 28 ++- .../cms/configurations/session-management.md | 206 ++++++++++++++++++ .../docs/cms/features/users-permissions.md | 67 +++++- 5 files changed, 462 insertions(+), 5 deletions(-) create mode 100644 docusaurus/docs/cms/configurations/session-management.md diff --git a/docusaurus/docs/cms/api/rest.md b/docusaurus/docs/cms/api/rest.md index fc09e4f419..ea6173a6be 100644 --- a/docusaurus/docs/cms/api/rest.md +++ b/docusaurus/docs/cms/api/rest.md @@ -128,6 +128,58 @@ The Upload package (which powers the [Media Library feature](/cms/features/media [Components](/cms/backend-customization/models#components-json) don't have API endpoints. ::: +## Authentication endpoints + +The [Users & Permissions plugin](/cms/features/users-permissions) provides authentication endpoints for user management and content API access. + +### Basic authentication endpoints + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/local` | User login with email/username and password | +| `POST` | `/api/auth/local/register` | User registration | +| `POST` | `/api/auth/forgot-password` | Request password reset | +| `POST` | `/api/auth/reset-password` | Reset password using token | +| `GET` | `/api/auth/email-confirmation` | Confirm user email address | + +### Session management endpoints + +When [session management](/cms/features/users-permissions#jwt-management-modes) is enabled (`jwtManagement: 'refresh'`), additional endpoints are available: + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/refresh` | Refresh access token using refresh token | +| `POST` | `/api/auth/logout` | Revoke user sessions (supports device-specific logout) | + +#### Refresh token example + +```bash +curl -X POST http://localhost:1337/api/auth/refresh \ + -H "Content-Type: application/json" \ + -d '{ + "refreshToken": "your-refresh-token" + }' +``` + +**Response:** +```json +{ + "jwt": "new-access-token" +} +``` + +#### Logout example + +```bash +# Logout all sessions +curl -X POST http://localhost:1337/api/auth/logout \ + -H "Authorization: Bearer your-access-token" +``` + +:::tip +For detailed authentication flow examples, see the [Users & Permissions documentation](/cms/features/users-permissions#api-usage) and [authentication examples](/cms/backend-customization/examples/authentication). +::: + ## Requests :::strapi Strapi 5 vs. Strapi v4 diff --git a/docusaurus/docs/cms/backend-customization/examples/authentication.md b/docusaurus/docs/cms/backend-customization/examples/authentication.md index baf1bfc7b4..a7b38c5d60 100644 --- a/docusaurus/docs/cms/backend-customization/examples/authentication.md +++ b/docusaurus/docs/cms/backend-customization/examples/authentication.md @@ -145,6 +145,120 @@ const Login = () => { export default Login; ``` +## Enhanced Authentication with Session Management + +The above example uses the traditional JWT approach. For enhanced security, you can enable session management mode in your Users & Permissions configuration, which provides shorter-lived access tokens and refresh token functionality. + +### Configuration + +First, enable session management in your `/config/plugins.js`: + +```js title="/config/plugins.js" +module.exports = ({ env }) => ({ + 'users-permissions': { + config: { + jwtManagement: 'refresh', + sessions: { + accessTokenLifespan: 604800, // 1 week (default) + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + }, + }, + }, +}); +``` + +### Enhanced Login Component + +Here's an updated login component that handles both JWT and refresh tokens: + +```jsx title="/client/pages/auth/enhanced-login.js" +import React, { useState } from 'react'; +import { useFormik } from 'formik'; +import { Button, Input } from '@nextui-org/react'; +import Layout from '@/components/layout'; +import { getStrapiURL } from '@/utils'; + +const EnhancedLogin = () => { + const [isLoading, setIsLoading] = useState(false); + + const { handleSubmit, handleChange } = useFormik({ + initialValues: { + identifier: '', + password: '', + }, + onSubmit: async (values) => { + setIsLoading(true); + try { + const res = await fetch(getStrapiURL('/auth/local'), { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify(values), + }); + + const data = await res.json(); + + if (res.ok) { + // Store both tokens (session management mode) + if (data.refreshToken) { + localStorage.setItem('accessToken', data.jwt); + localStorage.setItem('refreshToken', data.refreshToken); + } else { + // Legacy mode - single JWT + localStorage.setItem('token', data.jwt); + } + + // Redirect to protected area + window.location.href = '/dashboard'; + } else { + console.error('Login failed:', data.error); + } + } catch (error) { + console.error('Login error:', error); + } finally { + setIsLoading(false); + } + }, + }); + + return ( + +
+
+

Enhanced Login

+ + + +
+
+ + ); +}; + +export default EnhancedLogin; +``` +``` +
:::strapi What's next? diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index cd2b5ab324..378e54c892 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -204,7 +204,9 @@ For Strapi Cloud customers, the `auditLogs.retentionDays` value stored in the li ## Authentication -The authentication system, including [SSO configuration](/cms/configurations/guides/configure-sso), can be configured with the following parameters: +The authentication system, including [SSO configuration](/cms/configurations/guides/configure-sso) and [session management](/cms/configurations/session-management), can be configured with the following parameters: + +### Basic Authentication | Parameter | Description | Type | Default | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| @@ -218,6 +220,30 @@ The authentication system, including [SSO configuration](/cms/configurations/gui | `auth.events.onConnectionSuccess` | Function called when an admin user log in successfully to the administration panel | function | `undefined` | | `auth.events.onConnectionError` | Function called when an admin user fails to log in to the administration panel | function | `undefined` | +### Session Management + +Admin authentication uses session management by default for enhanced security. Configure session lifespans and behavior: + +| Parameter | Description | Type | Default | +|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `auth.sessions` | Session management configuration | object | `{}` | +| `auth.sessions.accessTokenLifespan` | Access token lifespan in seconds | number | `1800` (30 minutes) | +| `auth.sessions.maxRefreshTokenLifespan` | Maximum refresh token lifespan in seconds | number | `2592000` (30 days, or legacy `expiresIn` value) | +| `auth.sessions.idleRefreshTokenLifespan` | Idle refresh token timeout in seconds | number | `604800` (7 days) | +| `auth.sessions.maxSessionLifespan` | Maximum session duration in seconds | number | `2592000` (30 days, or legacy `expiresIn` value) | +| `auth.sessions.idleSessionLifespan` | Session idle timeout in seconds | number | `3600` (1 hour) | + +### Cookie Configuration + +Configure HTTP cookies for admin authentication: + +| Parameter | Description | Type | Default | +|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `auth.cookie` | Cookie configuration for admin authentication | object | `{}` | +| `auth.cookie.domain` | Cookie domain (inherits from server if not set) | string | `undefined` | +| `auth.cookie.path` | Cookie path | string | `'/admin'` | +| `auth.cookie.sameSite` | SameSite cookie attribute | string | `'lax'` | + ## Feature flags The feature flags can be configured with the following parameters: diff --git a/docusaurus/docs/cms/configurations/session-management.md b/docusaurus/docs/cms/configurations/session-management.md new file mode 100644 index 0000000000..36da64c60d --- /dev/null +++ b/docusaurus/docs/cms/configurations/session-management.md @@ -0,0 +1,206 @@ +--- +title: Session Management Configuration +description: Configure session management for enhanced authentication security in Strapi applications. +displayed_sidebar: cmsSidebar +--- + +# Session Management Configuration + +Session management provides enhanced security for authentication in Strapi applications by using short-lived access tokens paired with longer-lived refresh tokens. This approach reduces the risk of token theft and allows for more granular control over user sessions. + +## Overview + +Strapi's session management system supports both admin panel authentication and content API authentication through the Users & Permissions plugin. The system provides: + +- **Short-lived access tokens** (typically 30 minutes) for API requests +- **Refresh tokens** for obtaining new access tokens +- **Device-specific sessions** for targeted logout +- **Configurable token lifespans** for different security requirements + +## Admin Authentication Configuration + +Admin authentication uses session management by default and is configured in your admin configuration. + +### Basic Configuration + + + + + +```js title="/config/admin.js" +module.exports = ({ env }) => ({ + auth: { + secret: env('ADMIN_JWT_SECRET'), + sessions: { + accessTokenLifespan: 1800, // 30 minutes + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + maxSessionLifespan: 604800, // 7 days + idleSessionLifespan: 3600, // 1 hour + }, + cookie: { + domain: env('ADMIN_COOKIE_DOMAIN'), + path: '/admin', + sameSite: 'lax', + }, + }, +}); +``` + + + + + +```ts title="/config/admin.ts" +export default ({ env }) => ({ + auth: { + secret: env('ADMIN_JWT_SECRET'), + sessions: { + accessTokenLifespan: 1800, // 30 minutes + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + maxSessionLifespan: 604800, // 7 days + idleSessionLifespan: 3600, // 1 hour + }, + cookie: { + domain: env('ADMIN_COOKIE_DOMAIN'), + path: '/admin', + sameSite: 'lax', + }, + }, +}); +``` + + + + + +### Configuration Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `accessTokenLifespan` | number | 1800 | Access token lifespan in seconds | +| `maxRefreshTokenLifespan` | number | 2592000 | Maximum refresh token lifespan in seconds | +| `idleRefreshTokenLifespan` | number | 604800 | Idle refresh token timeout in seconds | +| `maxSessionLifespan` | number | 604800 | Maximum session duration in seconds | +| `idleSessionLifespan` | number | 3600 | Session idle timeout in seconds | + +### Cookie Configuration + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `domain` | string | undefined | Cookie domain (inherits from server if not set) | +| `path` | string | '/admin' | Cookie path | +| `sameSite` | string | 'lax' | SameSite cookie attribute | + +## Users & Permissions Configuration + +The Users & Permissions plugin supports both legacy JWT mode and session management mode. + +### Enabling Session Management + + + + + +```js title="/config/plugins.js" +module.exports = ({ env }) => ({ + 'users-permissions': { + config: { + jwtManagement: 'refresh', // Enable session management + sessions: { + accessTokenLifespan: 604800, // 1 week (default) + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + httpOnly: false, // Set to true for HTTP-only cookies + cookie: { + name: 'strapi_up_refresh', + sameSite: 'lax', + path: '/', + secure: false, // true in production + } + }, + }, + }, +}); +``` + + + + + +```ts title="/config/plugins.ts" +export default ({ env }) => ({ + 'users-permissions': { + config: { + jwtManagement: 'refresh', // Enable session management + sessions: { + accessTokenLifespan: 604800, // 1 week (default) + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + httpOnly: false, // Set to true for HTTP-only cookies + cookie: { + name: 'strapi_up_refresh', + sameSite: 'lax', + path: '/', + secure: false, // true in production + } + }, + }, + }, +}); +``` + + + + + +### Legacy Mode (Default) + +For backwards compatibility, the plugin defaults to legacy mode: + +```js title="/config/plugins.js" +module.exports = ({ env }) => ({ + 'users-permissions': { + config: { + jwtManagement: 'legacy-support', + jwt: { + expiresIn: '7d', // Traditional JWT expiry + }, + }, + }, +}); +``` + +### JWT Management Modes + +| Mode | Description | Use Case | +|------|-------------|----------| +| `legacy-support` | Traditional long-lived JWTs | Existing applications, simple authentication | +| `refresh` | Session management with refresh tokens | New applications, enhanced security requirements | + +## Environment Variables + +Set these environment variables for secure configuration: + +```bash title=".env" +# Admin authentication +ADMIN_JWT_SECRET=your-admin-secret-key + +# Cookie domain (optional) +ADMIN_COOKIE_DOMAIN=yourdomain.com + +# Users & Permissions JWT secret +JWT_SECRET=your-content-api-secret-key + +# Users & Permissions session management +UP_JWT_MANAGEMENT=refresh # or 'legacy-support' +UP_SESSIONS_ACCESS_TTL=604800 # 1 week in seconds +UP_SESSIONS_MAX_REFRESH_TTL=2592000 # 30 days in seconds +UP_SESSIONS_IDLE_REFRESH_TTL=604800 # 7 days in seconds +UP_SESSIONS_HTTPONLY=false # true for HTTP-only cookies +UP_SESSIONS_COOKIE_NAME=strapi_up_refresh +UP_SESSIONS_COOKIE_SAMESITE=lax +UP_SESSIONS_COOKIE_PATH=/ +UP_SESSIONS_COOKIE_SECURE=false # true in production +``` diff --git a/docusaurus/docs/cms/features/users-permissions.md b/docusaurus/docs/cms/features/users-permissions.md index 46ab2b3ee9..56c176a594 100644 --- a/docusaurus/docs/cms/features/users-permissions.md +++ b/docusaurus/docs/cms/features/users-permissions.md @@ -200,10 +200,18 @@ You can configure the JWT generation by using the [plugins configuration file](/ Strapi uses to generate the JWT. +#### JWT Management Modes + +The Users & Permissions plugin supports two JWT management modes: + +- **`legacy-support`** (default): Issues long-lived JWTs using traditional configuration +- **`refresh`**: Uses session management with short-lived access tokens and refresh tokens for enhanced security + Available options: - `jwtSecret`: random string used to create new JWTs, typically set using the `JWT_SECRET` [environment variable](/cms/configurations/environment#strapi). -- `jwt.expiresIn`: expressed in seconds or a string describing a time span.
+- `jwtManagement`: Set to `'refresh'` to enable session management mode, or `'legacy-support'` for traditional JWT handling +- `jwt.expiresIn`: (legacy mode only) 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"). @@ -216,8 +224,23 @@ module.exports = ({ env }) => ({ // ... 'users-permissions': { config: { + // Legacy mode configuration jwt: { - expiresIn: '7d', + expiresIn: '30d', + }, + // OR Session management mode configuration + jwtManagement: 'refresh', + sessions: { + accessTokenLifespan: 604800, // 1 week (default) + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + httpOnly: false, // Set to true for HTTP-only cookies + cookie: { + name: 'strapi_up_refresh', + sameSite: 'lax', + path: '/', + secure: false, // true in production + }, }, }, }, @@ -235,8 +258,23 @@ export default ({ env }) => ({ // ... 'users-permissions': { config: { + // Legacy mode configuration jwt: { - expiresIn: '7d', + expiresIn: '30d', + }, + // OR Session management mode configuration + jwtManagement: 'refresh', + sessions: { + accessTokenLifespan: 604800, // 1 week (default) + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + httpOnly: false, // Set to true for HTTP-only cookies + cookie: { + name: 'strapi_up_refresh', + sameSite: 'lax', + path: '/', + secure: false, // true in production + }, }, }, }, @@ -454,6 +492,13 @@ Each time an API request is sent the server checks if an `Authorization` header When you create a user without a role, or if you use the `/api/auth/local/register` route, the `authenticated` role is given to the user. ::: +#### Authentication Endpoints + +When using session management mode (`jwtManagement: 'refresh'`), additional endpoints are available: + +- `POST /api/auth/refresh` - Refresh an access token using a refresh token +- `POST /api/auth/logout` - Revoke user sessions + #### Identifier The `identifier` param can be an email or username, as in the following examples: @@ -496,8 +541,9 @@ If you use **Postman**, set the **body** to **raw** and select **JSON** as your } ``` -If the request is successful you will receive the **user's JWT** in the `jwt` key: +If the request is successful you will receive the **user's JWT** in the `jwt` key: +**Legacy mode response:** ```json { "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNTc2OTM4MTUwLCJleHAiOjE1Nzk1MzAxNTB9.UgsjjXkAZ-anD257BF7y1hbjuY3ogNceKfTAQtzDEsU", @@ -509,6 +555,19 @@ If the request is successful you will receive the **user's JWT** in the `jwt` ke } ``` +**Session management mode response:** +```json +{ + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Short-lived access token + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Long-lived refresh token + "user": { + "id": 1, + "username": "user", + ... + } +} +``` + From 86a7e4cc830f068f14b5c8244966a7e87255e203 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 18 Sep 2025 17:48:51 +0200 Subject: [PATCH 2/9] Move endpoints to U&P feature docs and rework related sections --- docusaurus/docs/cms/api/rest.md | 54 +---------------- .../docs/cms/features/users-permissions.md | 60 +++++++++++++++++-- docusaurus/static/llms-full.txt | 52 ++++++++++++++++ 3 files changed, 108 insertions(+), 58 deletions(-) diff --git a/docusaurus/docs/cms/api/rest.md b/docusaurus/docs/cms/api/rest.md index ea6173a6be..af0941e238 100644 --- a/docusaurus/docs/cms/api/rest.md +++ b/docusaurus/docs/cms/api/rest.md @@ -16,7 +16,7 @@ tags: The REST API allows accessing the [content-types](/cms/backend-customization/models) through API endpoints. Strapi automatically creates [API endpoints](#endpoints) when a content-type is created. [API parameters](/cms/api/rest/parameters) can be used when querying API endpoints to refine the results. -This section of the documentation is for the REST API reference. We also have [guides](/cms/api/rest/guides/intro) available for specific use cases. +This section of the documentation is for the REST API reference for content-types. We also have [guides](/cms/api/rest/guides/intro) available for specific use cases. :::prerequisites All content types are private by default and need to be either made public or queries need to be authenticated with the proper permissions. See the [Quick Start Guide](/cms/quick-start#step-4-set-roles--permissions), the user guide for the [Users & Permissions feature](/cms/features/users-permissions#roles), and [API tokens configuration documentation](/cms/features/api-tokens) for more details. @@ -128,58 +128,6 @@ The Upload package (which powers the [Media Library feature](/cms/features/media [Components](/cms/backend-customization/models#components-json) don't have API endpoints. ::: -## Authentication endpoints - -The [Users & Permissions plugin](/cms/features/users-permissions) provides authentication endpoints for user management and content API access. - -### Basic authentication endpoints - -| Method | URL | Description | -| ------ | --- | ----------- | -| `POST` | `/api/auth/local` | User login with email/username and password | -| `POST` | `/api/auth/local/register` | User registration | -| `POST` | `/api/auth/forgot-password` | Request password reset | -| `POST` | `/api/auth/reset-password` | Reset password using token | -| `GET` | `/api/auth/email-confirmation` | Confirm user email address | - -### Session management endpoints - -When [session management](/cms/features/users-permissions#jwt-management-modes) is enabled (`jwtManagement: 'refresh'`), additional endpoints are available: - -| Method | URL | Description | -| ------ | --- | ----------- | -| `POST` | `/api/auth/refresh` | Refresh access token using refresh token | -| `POST` | `/api/auth/logout` | Revoke user sessions (supports device-specific logout) | - -#### Refresh token example - -```bash -curl -X POST http://localhost:1337/api/auth/refresh \ - -H "Content-Type: application/json" \ - -d '{ - "refreshToken": "your-refresh-token" - }' -``` - -**Response:** -```json -{ - "jwt": "new-access-token" -} -``` - -#### Logout example - -```bash -# Logout all sessions -curl -X POST http://localhost:1337/api/auth/logout \ - -H "Authorization: Bearer your-access-token" -``` - -:::tip -For detailed authentication flow examples, see the [Users & Permissions documentation](/cms/features/users-permissions#api-usage) and [authentication examples](/cms/backend-customization/examples/authentication). -::: - ## Requests :::strapi Strapi 5 vs. Strapi v4 diff --git a/docusaurus/docs/cms/features/users-permissions.md b/docusaurus/docs/cms/features/users-permissions.md index 56c176a594..0ef9d15145 100644 --- a/docusaurus/docs/cms/features/users-permissions.md +++ b/docusaurus/docs/cms/features/users-permissions.md @@ -486,22 +486,72 @@ If end users can register themselves on your front-end application (see "Enable ### API usage + Each time an API request is sent the server checks if an `Authorization` header is present and verifies if the user making the request has access to the resource. :::note When you create a user without a role, or if you use the `/api/auth/local/register` route, the `authenticated` role is given to the user. ::: -#### Authentication Endpoints +#### Basic authentication endpoints + +The Users & Permissions feature provides the following authentication endpoints for user management and [Content API](/cms/api/rest) access: + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/local` | User login with email/username and password
(see [`identifier` parameter](#identifier)) | +| `POST` | `/api/auth/local/register` | [User registration](#user-registration) | +| `POST` | `/api/auth/forgot-password` | Request password reset | +| `POST` | `/api/auth/reset-password` | Reset password using token | +| `GET` | `/api/auth/email-confirmation` | Confirm user email address | + +#### Session management endpoints + +When [session management](#jwt-management-modes) is enabled (`jwtManagement: 'refresh'`), additional endpoints are available: + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/refresh` | Refresh access token using refresh token | +| `POST` | `/api/auth/logout` | Revoke user sessions (supports device-specific logout) | + +To refresh your authentication token you could for instance send the following request: + + + +``` +curl -X POST http://localhost:1337/api/auth/refresh \ + -H "Content-Type: application/json" \ + -d '{ + "refreshToken": "your-refresh-token" + }' +``` + + + +```json +{ + "jwt": "your-new-access-token" +} +``` + + + +To log out of all sessions, send the following request: -When using session management mode (`jwtManagement: 'refresh'`), additional endpoints are available: + + + +```bash +curl -X POST http://localhost:1337/api/auth/logout \ + -H "Authorization: Bearer your-access-token" +``` -- `POST /api/auth/refresh` - Refresh an access token using a refresh token -- `POST /api/auth/logout` - Revoke user sessions + + #### Identifier -The `identifier` param can be an email or username, as in the following examples: +The `identifier` parameter sent with requests can be an email or username, as in the following examples: diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt index a59c4d7ef8..3297d983ac 100644 --- a/docusaurus/static/llms-full.txt +++ b/docusaurus/static/llms-full.txt @@ -3760,6 +3760,58 @@ The Upload package (which powers the [Media Library feature](/cms/features/media [Components](/cms/backend-customization/models#components-json) don't have API endpoints. ::: +## Authentication endpoints + +The [Users & Permissions plugin](/cms/features/users-permissions) provides authentication endpoints for user management and content API access. + +### Basic authentication endpoints + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/local` | User login with email/username and password | +| `POST` | `/api/auth/local/register` | User registration | +| `POST` | `/api/auth/forgot-password` | Request password reset | +| `POST` | `/api/auth/reset-password` | Reset password using token | +| `GET` | `/api/auth/email-confirmation` | Confirm user email address | + +### Session management endpoints + +When [session management](/cms/features/users-permissions#jwt-management-modes) is enabled (`jwtManagement: 'refresh'`), additional endpoints are available: + +| Method | URL | Description | +| ------ | --- | ----------- | +| `POST` | `/api/auth/refresh` | Refresh access token using refresh token | +| `POST` | `/api/auth/logout` | Revoke user sessions (supports device-specific logout) | + +#### Refresh token example + +```bash +curl -X POST http://localhost:1337/api/auth/refresh \ + -H "Content-Type: application/json" \ + -d '{ + "refreshToken": "your-refresh-token" + }' +``` + +**Response:** +```json +{ + "jwt": "new-access-token" +} +``` + +#### Logout example + +```bash +# Logout all sessions +curl -X POST http://localhost:1337/api/auth/logout \ + -H "Authorization: Bearer your-access-token" +``` + +:::tip +For detailed authentication flow examples, see the [Users & Permissions documentation](/cms/features/users-permissions#api-usage) and [authentication examples](/cms/backend-customization/examples/authentication). +::: + ## Requests :::strapi Strapi 5 vs. Strapi v4 From 10abb7f870b2ec535892b76602d49189a0d1698d Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 18 Sep 2025 18:43:44 +0200 Subject: [PATCH 3/9] Clean up configurations- and environment variables-related content --- .../docs/cms/configurations/admin-panel.md | 57 ++++- .../docs/cms/configurations/environment.md | 33 +++ .../cms/configurations/session-management.md | 206 ------------------ .../docs/cms/features/users-permissions.md | 46 ++-- 4 files changed, 114 insertions(+), 228 deletions(-) delete mode 100644 docusaurus/docs/cms/configurations/session-management.md diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index 378e54c892..dd828354a8 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -2,7 +2,7 @@ title: Admin panel configuration sidebar_label: Admin panel displayed_sidebar: cmsSidebar -toc_max_heading_level: 2 +toc_max_heading_level: 3 description: Strapi's admin panel offers a single entry point file for its configuration. tags: - admin panel @@ -57,7 +57,7 @@ export default { ::: -## Admin panel server +## Admin panel server By default, Strapi's admin panel is exposed via `http://localhost:1337/admin`. For security reasons, the host, port, and path can be updated. @@ -204,9 +204,11 @@ For Strapi Cloud customers, the `auditLogs.retentionDays` value stored in the li ## Authentication -The authentication system, including [SSO configuration](/cms/configurations/guides/configure-sso) and [session management](/cms/configurations/session-management), can be configured with the following parameters: +The authentication system, including [SSO configuration](/cms/configurations/guides/configure-sso) and [session management](#session-management), can be configured with the following parameters: -### Basic Authentication +### Basic authentication + +To configure basic authentication, use the following parameters: | Parameter | Description | Type | Default | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| @@ -220,9 +222,22 @@ The authentication system, including [SSO configuration](/cms/configurations/gui | `auth.events.onConnectionSuccess` | Function called when an admin user log in successfully to the administration panel | function | `undefined` | | `auth.events.onConnectionError` | Function called when an admin user fails to log in to the administration panel | function | `undefined` | -### Session Management +Additional configuration parameters are available for [session management](#session-management) when enabled. + +### Session management + +Admin authentication uses session management by default for enhanced security. + +Session management provides enhanced security for authentication in Strapi applications by using short-lived access tokens paired with longer-lived refresh tokens. This approach reduces the risk of token theft and allows for more granular control over user sessions. + +Strapi's session management system supports both admin panel authentication and Content API authentication through the [Users & Permissions feature](/cms/features/users-permissions). The system provides: -Admin authentication uses session management by default for enhanced security. Configure session lifespans and behavior: +- Short-lived access tokens (typically 30 minutes) for API requests +- Refresh tokens for obtaining new access tokens +- Device-specific sessions for targeted logout +- Configurable token lifespans for different security requirements + +To configure session lifespans and behavior, use the following parameters: | Parameter | Description | Type | Default | |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| @@ -233,16 +248,16 @@ Admin authentication uses session management by default for enhanced security. C | `auth.sessions.maxSessionLifespan` | Maximum session duration in seconds | number | `2592000` (30 days, or legacy `expiresIn` value) | | `auth.sessions.idleSessionLifespan` | Session idle timeout in seconds | number | `3600` (1 hour) | -### Cookie Configuration +### Cookie configuration -Configure HTTP cookies for admin authentication: +To configure HTTP cookies for admin authentication, use the following parameters: | Parameter | Description | Type | Default | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| | `auth.cookie` | Cookie configuration for admin authentication | object | `{}` | | `auth.cookie.domain` | Cookie domain (inherits from server if not set) | string | `undefined` | | `auth.cookie.path` | Cookie path | string | `'/admin'` | -| `auth.cookie.sameSite` | SameSite cookie attribute | string | `'lax'` | +| `auth.cookie.sameSite` | | string | `'lax'` | ## Feature flags @@ -391,6 +406,18 @@ module.exports = ({ env }) => ({ expiresIn: '7d', }, secret: env('ADMIN_JWT_SECRET', 'someSecretKey'), + sessions: { + accessTokenLifespan: 1800, // 30 minutes + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + maxSessionLifespan: 604800, // 7 days + idleSessionLifespan: 3600, // 1 hour + }, + cookie: { + domain: env('ADMIN_COOKIE_DOMAIN'), + path: '/admin', + sameSite: 'lax', + }, }, url: env('PUBLIC_ADMIN_URL', '/dashboard'), autoOpen: false, @@ -449,6 +476,18 @@ export default ({ env }) => ({ expiresIn: '7d', }, secret: env('ADMIN_JWT_SECRET', 'someSecretKey'), + sessions: { + accessTokenLifespan: 1800, // 30 minutes + maxRefreshTokenLifespan: 2592000, // 30 days + idleRefreshTokenLifespan: 604800, // 7 days + maxSessionLifespan: 604800, // 7 days + idleSessionLifespan: 3600, // 1 hour + }, + cookie: { + domain: env('ADMIN_COOKIE_DOMAIN'), + path: '/admin', + sameSite: 'lax', + }, }, url: env('PUBLIC_ADMIN_URL', '/dashboard'), autoOpen: false, diff --git a/docusaurus/docs/cms/configurations/environment.md b/docusaurus/docs/cms/configurations/environment.md index 3b9ba70794..d3a4ceb2ab 100644 --- a/docusaurus/docs/cms/configurations/environment.md +++ b/docusaurus/docs/cms/configurations/environment.md @@ -47,6 +47,15 @@ Strapi provides the following environment variables: | `TRANSFER_TOKEN_SALT` | Salt used for transfer tokens by the [Data Management](/cms/features/data-management) feature | `String` | `auto-generated` | | `DATABASE_CLIENT` | Database client to use (e.g., `sqlite`) | `String` | `sqlite` | | `DATABASE_FILENAME` | Location of the SQLite database file | `String` | `.tmp/data.db` | +| `UP_JWT_MANAGEMENT` | [JWT management mode](/cms/features/users-permissions#jwt-management-modes) | `String` | 'legacy-support' | +| `UP_SESSIONS_ACCESS_TTL` | JWT sessions management access token lifespan in seconds | | `Number` | `604800` (1 week in seconds) | +| `UP_SESSIONS_MAX_REFRESH_TTL` | JWT sessions management maximum refresh token lifespan in seconds| `Number` | `2592000` (30 days in seconds) | +| `UP_SESSIONS_IDLE_REFRESH_TTL` | JWT sessions management idle refresh token timeout in seconds | `Number` | `604800` (7 days in seconds) | +| `UP_SESSIONS_HTTPONLY` | | `Boolean` | `true` for HTTP-only cookies +| `UP_SESSIONS_COOKIE_NAME` | | `String` | `strapi_up_refresh` | +| `UP_SESSIONS_COOKIE_SAMESITE` |
(see [cookie configuration](/cms/configurations/admin-panel#cookie-configuration)) | | `Lax` | +| `UP_SESSIONS_COOKIE_PATH` | Cookie path
(see [cookie configuration](/cms/configurations/admin-panel#cookie-configuration)) | `String` | / | +| `UP_SESSIONS_COOKIE_SECURE` | | `Boolean` | `true` in production | :::tip Prefixing an environment variable name with `STRAPI_ADMIN_` exposes the variable to the admin front end (e.g., `STRAPI_ADMIN_MY_PLUGIN_VARIABLE` is accessible through `process.env.STRAPI_ADMIN_MY_PLUGIN_VARIABLE`). @@ -56,6 +65,30 @@ Prefixing an environment variable name with `STRAPI_ADMIN_` exposes the variable +Set these environment variables for secure authentication with [sessions management](/cms/features/users-permissions#jwt-management-modes) configuration: + +```bash title=".env" +# Admin authentication +ADMIN_JWT_SECRET=your-admin-secret-key + +# Cookie domain (optional) +ADMIN_COOKIE_DOMAIN=yourdomain.com + +# Users & Permissions JWT secret +JWT_SECRET=your-content-api-secret-key + +# Users & Permissions session management +UP_JWT_MANAGEMENT=refresh # or 'legacy-support' +UP_SESSIONS_ACCESS_TTL=604800 # 1 week in seconds +UP_SESSIONS_MAX_REFRESH_TTL=2592000 # 30 days in seconds +UP_SESSIONS_IDLE_REFRESH_TTL=604800 # 7 days in seconds +UP_SESSIONS_HTTPONLY=false # true for HTTP-only cookies +UP_SESSIONS_COOKIE_NAME=strapi_up_refresh +UP_SESSIONS_COOKIE_SAMESITE=lax +UP_SESSIONS_COOKIE_PATH=/ +UP_SESSIONS_COOKIE_SECURE=false # true in production +``` + ## Environment configurations Configurations can be created with the following naming and structure conventions: `./config/env/{environment}/{filename}`. This is useful when you need specific static configurations for specific environments and using environment variables is not the best solution. diff --git a/docusaurus/docs/cms/configurations/session-management.md b/docusaurus/docs/cms/configurations/session-management.md deleted file mode 100644 index 36da64c60d..0000000000 --- a/docusaurus/docs/cms/configurations/session-management.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Session Management Configuration -description: Configure session management for enhanced authentication security in Strapi applications. -displayed_sidebar: cmsSidebar ---- - -# Session Management Configuration - -Session management provides enhanced security for authentication in Strapi applications by using short-lived access tokens paired with longer-lived refresh tokens. This approach reduces the risk of token theft and allows for more granular control over user sessions. - -## Overview - -Strapi's session management system supports both admin panel authentication and content API authentication through the Users & Permissions plugin. The system provides: - -- **Short-lived access tokens** (typically 30 minutes) for API requests -- **Refresh tokens** for obtaining new access tokens -- **Device-specific sessions** for targeted logout -- **Configurable token lifespans** for different security requirements - -## Admin Authentication Configuration - -Admin authentication uses session management by default and is configured in your admin configuration. - -### Basic Configuration - - - - - -```js title="/config/admin.js" -module.exports = ({ env }) => ({ - auth: { - secret: env('ADMIN_JWT_SECRET'), - sessions: { - accessTokenLifespan: 1800, // 30 minutes - maxRefreshTokenLifespan: 2592000, // 30 days - idleRefreshTokenLifespan: 604800, // 7 days - maxSessionLifespan: 604800, // 7 days - idleSessionLifespan: 3600, // 1 hour - }, - cookie: { - domain: env('ADMIN_COOKIE_DOMAIN'), - path: '/admin', - sameSite: 'lax', - }, - }, -}); -``` - - - - - -```ts title="/config/admin.ts" -export default ({ env }) => ({ - auth: { - secret: env('ADMIN_JWT_SECRET'), - sessions: { - accessTokenLifespan: 1800, // 30 minutes - maxRefreshTokenLifespan: 2592000, // 30 days - idleRefreshTokenLifespan: 604800, // 7 days - maxSessionLifespan: 604800, // 7 days - idleSessionLifespan: 3600, // 1 hour - }, - cookie: { - domain: env('ADMIN_COOKIE_DOMAIN'), - path: '/admin', - sameSite: 'lax', - }, - }, -}); -``` - - - - - -### Configuration Options - -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `accessTokenLifespan` | number | 1800 | Access token lifespan in seconds | -| `maxRefreshTokenLifespan` | number | 2592000 | Maximum refresh token lifespan in seconds | -| `idleRefreshTokenLifespan` | number | 604800 | Idle refresh token timeout in seconds | -| `maxSessionLifespan` | number | 604800 | Maximum session duration in seconds | -| `idleSessionLifespan` | number | 3600 | Session idle timeout in seconds | - -### Cookie Configuration - -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `domain` | string | undefined | Cookie domain (inherits from server if not set) | -| `path` | string | '/admin' | Cookie path | -| `sameSite` | string | 'lax' | SameSite cookie attribute | - -## Users & Permissions Configuration - -The Users & Permissions plugin supports both legacy JWT mode and session management mode. - -### Enabling Session Management - - - - - -```js title="/config/plugins.js" -module.exports = ({ env }) => ({ - 'users-permissions': { - config: { - jwtManagement: 'refresh', // Enable session management - sessions: { - accessTokenLifespan: 604800, // 1 week (default) - maxRefreshTokenLifespan: 2592000, // 30 days - idleRefreshTokenLifespan: 604800, // 7 days - httpOnly: false, // Set to true for HTTP-only cookies - cookie: { - name: 'strapi_up_refresh', - sameSite: 'lax', - path: '/', - secure: false, // true in production - } - }, - }, - }, -}); -``` - - - - - -```ts title="/config/plugins.ts" -export default ({ env }) => ({ - 'users-permissions': { - config: { - jwtManagement: 'refresh', // Enable session management - sessions: { - accessTokenLifespan: 604800, // 1 week (default) - maxRefreshTokenLifespan: 2592000, // 30 days - idleRefreshTokenLifespan: 604800, // 7 days - httpOnly: false, // Set to true for HTTP-only cookies - cookie: { - name: 'strapi_up_refresh', - sameSite: 'lax', - path: '/', - secure: false, // true in production - } - }, - }, - }, -}); -``` - - - - - -### Legacy Mode (Default) - -For backwards compatibility, the plugin defaults to legacy mode: - -```js title="/config/plugins.js" -module.exports = ({ env }) => ({ - 'users-permissions': { - config: { - jwtManagement: 'legacy-support', - jwt: { - expiresIn: '7d', // Traditional JWT expiry - }, - }, - }, -}); -``` - -### JWT Management Modes - -| Mode | Description | Use Case | -|------|-------------|----------| -| `legacy-support` | Traditional long-lived JWTs | Existing applications, simple authentication | -| `refresh` | Session management with refresh tokens | New applications, enhanced security requirements | - -## Environment Variables - -Set these environment variables for secure configuration: - -```bash title=".env" -# Admin authentication -ADMIN_JWT_SECRET=your-admin-secret-key - -# Cookie domain (optional) -ADMIN_COOKIE_DOMAIN=yourdomain.com - -# Users & Permissions JWT secret -JWT_SECRET=your-content-api-secret-key - -# Users & Permissions session management -UP_JWT_MANAGEMENT=refresh # or 'legacy-support' -UP_SESSIONS_ACCESS_TTL=604800 # 1 week in seconds -UP_SESSIONS_MAX_REFRESH_TTL=2592000 # 30 days in seconds -UP_SESSIONS_IDLE_REFRESH_TTL=604800 # 7 days in seconds -UP_SESSIONS_HTTPONLY=false # true for HTTP-only cookies -UP_SESSIONS_COOKIE_NAME=strapi_up_refresh -UP_SESSIONS_COOKIE_SAMESITE=lax -UP_SESSIONS_COOKIE_PATH=/ -UP_SESSIONS_COOKIE_SECURE=false # true in production -``` diff --git a/docusaurus/docs/cms/features/users-permissions.md b/docusaurus/docs/cms/features/users-permissions.md index 0ef9d15145..3be1bf0419 100644 --- a/docusaurus/docs/cms/features/users-permissions.md +++ b/docusaurus/docs/cms/features/users-permissions.md @@ -196,23 +196,47 @@ While most of the Users & Permissions settings are handled via the admin panel, ### JWT configuration -You can configure the JWT generation by using the [plugins configuration file](/cms/configurations/plugins). +You can configure the JSON Web Token (JWT) generation by using the [plugins configuration file](/cms/configurations/plugins). Strapi uses to generate the JWT. -#### JWT Management Modes +#### JWT management modes -The Users & Permissions plugin supports two JWT management modes: +The Users & Permissions feature supports 2 JWT management modes. -- **`legacy-support`** (default): Issues long-lived JWTs using traditional configuration -- **`refresh`**: Uses session management with short-lived access tokens and refresh tokens for enhanced security +Defining which mode is used is done by setting the `jwtManagement` property of the `users-permissions.config` object in the [`/config/plugins` file](/cms/confiugurations/plugins). The property accepts either `legacy-support` or `refresh`: -Available options: +| Mode | Description | Use case | +|------|-------------|----------| +| `legacy-support` | (default) Issues long-lived JWTs using traditional configuration | Existing applications, simple authentication | +| `refresh` | Uses session management with short-lived access tokens and refresh tokens for enhanced security | New applications, enhanced security requirements | -- `jwtSecret`: random string used to create new JWTs, typically set using the `JWT_SECRET` [environment variable](/cms/configurations/environment#strapi). -- `jwtManagement`: Set to `'refresh'` to enable session management mode, or `'legacy-support'` for traditional JWT handling -- `jwt.expiresIn`: (legacy mode only) expressed in seconds or a string describing a time span.
+For backwards compatibility, the Users & Permission feature defaults to legacy mode: + +```js title="/config/plugins.js" +module.exports = ({ env }) => ({ + 'users-permissions': { + config: { + jwtManagement: 'legacy-support', + jwt: { + expiresIn: '7d', // Traditional JWT expiry + }, + }, + }, +}); +``` + +:::note Notes +- `jwtSecret` is a random string used to create new JWTs, typically set using the `JWT_SECRET` [environment variable](/cms/configurations/environment#strapi). +- `jwt.expiresIn` is (legacy-mode only) is 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"). +::: + +:::warning +Setting JWT expiry for more than 30 days is not recommended due to security concerns. +::: + +When the `refresh` mode is used, the configuration file could look like as follows: @@ -286,10 +310,6 @@ export default ({ env }) => ({ -:::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 in your User **model** Models, also called content-types in Strapi, define a representation of the content structure.
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](/cms/backend-customization/models) documentation. that need to be accepted on registration, you need to added them to the list of allowed fields in the `config.register` object of [the `/config/plugins` file](/cms/configurations/plugins), otherwise they will not be accepted. From 5aa6673a3b342f3de65f8315484653bdd5be4838 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 18 Sep 2025 18:47:10 +0200 Subject: [PATCH 4/9] Fix typo in link --- docusaurus/docs/cms/features/users-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/features/users-permissions.md b/docusaurus/docs/cms/features/users-permissions.md index 3be1bf0419..0e8bd16ec0 100644 --- a/docusaurus/docs/cms/features/users-permissions.md +++ b/docusaurus/docs/cms/features/users-permissions.md @@ -204,7 +204,7 @@ Strapi uses ({ - // ... + // … 'users-permissions': { config: { - // Legacy mode configuration - jwt: { - expiresIn: '30d', - }, - // OR Session management mode configuration jwtManagement: 'refresh', sessions: { accessTokenLifespan: 604800, // 1 week (default) @@ -279,14 +274,9 @@ module.exports = ({ env }) => ({ ```ts title="/config/plugins.ts" export default ({ env }) => ({ - // ... + // … 'users-permissions': { config: { - // Legacy mode configuration - jwt: { - expiresIn: '30d', - }, - // OR Session management mode configuration jwtManagement: 'refresh', sessions: { accessTokenLifespan: 604800, // 1 week (default) From 8c0aacecf0e0e6c0205b9c29bd0073dc2c3efa2f Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 18 Sep 2025 18:53:08 +0200 Subject: [PATCH 6/9] Update LLMs-full.txt --- docusaurus/static/llms-full.txt | 68 ++++++--------------------------- 1 file changed, 11 insertions(+), 57 deletions(-) diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt index 3297d983ac..70d636406e 100644 --- a/docusaurus/static/llms-full.txt +++ b/docusaurus/static/llms-full.txt @@ -3709,7 +3709,7 @@ Source: https://docs.strapi.io/cms/api/rest The REST API allows accessing the [content-types](/cms/backend-customization/models) through API endpoints. Strapi automatically creates [API endpoints](#endpoints) when a content-type is created. [API parameters](/cms/api/rest/parameters) can be used when querying API endpoints to refine the results. -This section of the documentation is for the REST API reference. We also have [guides](/cms/api/rest/guides/intro) available for specific use cases. +This section of the documentation is for the REST API reference for content-types. We also have [guides](/cms/api/rest/guides/intro) available for specific use cases. :::prerequisites All content types are private by default and need to be either made public or queries need to be authenticated with the proper permissions. See the [Quick Start Guide](/cms/quick-start#step-4-set-roles--permissions), the user guide for the [Users & Permissions feature](/cms/features/users-permissions#roles), and [API tokens configuration documentation](/cms/features/api-tokens) for more details. @@ -3760,58 +3760,6 @@ The Upload package (which powers the [Media Library feature](/cms/features/media [Components](/cms/backend-customization/models#components-json) don't have API endpoints. ::: -## Authentication endpoints - -The [Users & Permissions plugin](/cms/features/users-permissions) provides authentication endpoints for user management and content API access. - -### Basic authentication endpoints - -| Method | URL | Description | -| ------ | --- | ----------- | -| `POST` | `/api/auth/local` | User login with email/username and password | -| `POST` | `/api/auth/local/register` | User registration | -| `POST` | `/api/auth/forgot-password` | Request password reset | -| `POST` | `/api/auth/reset-password` | Reset password using token | -| `GET` | `/api/auth/email-confirmation` | Confirm user email address | - -### Session management endpoints - -When [session management](/cms/features/users-permissions#jwt-management-modes) is enabled (`jwtManagement: 'refresh'`), additional endpoints are available: - -| Method | URL | Description | -| ------ | --- | ----------- | -| `POST` | `/api/auth/refresh` | Refresh access token using refresh token | -| `POST` | `/api/auth/logout` | Revoke user sessions (supports device-specific logout) | - -#### Refresh token example - -```bash -curl -X POST http://localhost:1337/api/auth/refresh \ - -H "Content-Type: application/json" \ - -d '{ - "refreshToken": "your-refresh-token" - }' -``` - -**Response:** -```json -{ - "jwt": "new-access-token" -} -``` - -#### Logout example - -```bash -# Logout all sessions -curl -X POST http://localhost:1337/api/auth/logout \ - -H "Authorization: Bearer your-access-token" -``` - -:::tip -For detailed authentication flow examples, see the [Users & Permissions documentation](/cms/features/users-permissions#api-usage) and [authentication examples](/cms/backend-customization/examples/authentication). -::: - ## Requests :::strapi Strapi 5 vs. Strapi v4 @@ -8887,10 +8835,6 @@ Click the search button -:::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 in your User **model** that need to be accepted on registration, you need to added them to the list of allowed fields in the `config.register` object of [the `/config/plugins` file](/cms/configurations/plugins), otherwise they will not be accepted. @@ -8919,6 +8863,16 @@ By default you can set a `JWT_SECRET` environment variable and it will be used a By default, Strapi SSO only redirects to the redirect URL that is exactly equal to the url in the configuration: + + +To log out of all sessions, send the following request: + + + +#### Identifier + +The `identifier` parameter sent with requests can be an email or username, as in the following examples: + #### Token usage From 8e6a8b51e99db05d63072ec60e54eb77b22051e6 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Fri, 19 Sep 2025 14:26:54 +0200 Subject: [PATCH 7/9] Update docusaurus/docs/cms/configurations/admin-panel.md Co-authored-by: Jamie Howard <48524071+jhoward1994@users.noreply.github.com> --- docusaurus/docs/cms/configurations/admin-panel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index dd828354a8..04d6eaafb9 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -222,7 +222,7 @@ To configure basic authentication, use the following parameters: | `auth.events.onConnectionSuccess` | Function called when an admin user log in successfully to the administration panel | function | `undefined` | | `auth.events.onConnectionError` | Function called when an admin user fails to log in to the administration panel | function | `undefined` | -Additional configuration parameters are available for [session management](#session-management) when enabled. +Additional configuration parameters are available for [session management](#session-management). ### Session management From 2158eaac9fa9fe829bac722cd14c824fe62575bc Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 22 Sep 2025 11:15:58 +0200 Subject: [PATCH 8/9] Remove useless/wrong values from env docs --- docusaurus/docs/cms/configurations/environment.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docusaurus/docs/cms/configurations/environment.md b/docusaurus/docs/cms/configurations/environment.md index d3a4ceb2ab..c83ba0acb1 100644 --- a/docusaurus/docs/cms/configurations/environment.md +++ b/docusaurus/docs/cms/configurations/environment.md @@ -47,15 +47,6 @@ Strapi provides the following environment variables: | `TRANSFER_TOKEN_SALT` | Salt used for transfer tokens by the [Data Management](/cms/features/data-management) feature | `String` | `auto-generated` | | `DATABASE_CLIENT` | Database client to use (e.g., `sqlite`) | `String` | `sqlite` | | `DATABASE_FILENAME` | Location of the SQLite database file | `String` | `.tmp/data.db` | -| `UP_JWT_MANAGEMENT` | [JWT management mode](/cms/features/users-permissions#jwt-management-modes) | `String` | 'legacy-support' | -| `UP_SESSIONS_ACCESS_TTL` | JWT sessions management access token lifespan in seconds | | `Number` | `604800` (1 week in seconds) | -| `UP_SESSIONS_MAX_REFRESH_TTL` | JWT sessions management maximum refresh token lifespan in seconds| `Number` | `2592000` (30 days in seconds) | -| `UP_SESSIONS_IDLE_REFRESH_TTL` | JWT sessions management idle refresh token timeout in seconds | `Number` | `604800` (7 days in seconds) | -| `UP_SESSIONS_HTTPONLY` | | `Boolean` | `true` for HTTP-only cookies -| `UP_SESSIONS_COOKIE_NAME` | | `String` | `strapi_up_refresh` | -| `UP_SESSIONS_COOKIE_SAMESITE` |
(see [cookie configuration](/cms/configurations/admin-panel#cookie-configuration)) | | `Lax` | -| `UP_SESSIONS_COOKIE_PATH` | Cookie path
(see [cookie configuration](/cms/configurations/admin-panel#cookie-configuration)) | `String` | / | -| `UP_SESSIONS_COOKIE_SECURE` | | `Boolean` | `true` in production | :::tip Prefixing an environment variable name with `STRAPI_ADMIN_` exposes the variable to the admin front end (e.g., `STRAPI_ADMIN_MY_PLUGIN_VARIABLE` is accessible through `process.env.STRAPI_ADMIN_MY_PLUGIN_VARIABLE`). From f2b2c31afbc9901b0975203f1b643d934ccda812 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 24 Sep 2025 15:11:38 +0200 Subject: [PATCH 9/9] Update docusaurus/docs/cms/features/users-permissions.md --- docusaurus/docs/cms/features/users-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/features/users-permissions.md b/docusaurus/docs/cms/features/users-permissions.md index 007203ec4e..21bdb14351 100644 --- a/docusaurus/docs/cms/features/users-permissions.md +++ b/docusaurus/docs/cms/features/users-permissions.md @@ -209,7 +209,7 @@ Defining which mode is used is done by setting the `jwtManagement` property of t | Mode | Description | Use case | |------|-------------|----------| | `legacy-support` | (default) Issues long-lived JWTs using traditional configuration | Existing applications, simple authentication | -| `refresh` | Uses session management with short-lived access tokens and refresh tokens for enhanced security | New applications, enhanced security requirements | +| `refresh` | Uses session management with short-lived access tokens and refresh tokens for enhanced security | New applications, enhanced security requirements
(additional information can be found in [admin panel configuration](/cms/configurations/admin-panel#session-management) documentation) | For backwards compatibility, the Users & Permission feature defaults to legacy mode: