Add session management documentation

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.

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 (
+ <Layout>
+ <div className="h-full w-full flex justify-center items-center my-24">
+ <form onSubmit={handleSubmit} className="flex flex-col gap-y-6 w-4/12">
+ <h1 className="font-bold text-3xl mb-6">Enhanced Login</h1>
+ <Input
+ onChange={handleChange}
+ type="email"
+ name="identifier"
+ label="Email"
+ placeholder="Enter your email"
+ />
+ <Input
+ type="password"
+ name="password"
+ label="Password"
+ placeholder="Enter your password"
+ onChange={handleChange}
+ />
+ <Button
+ type="submit"
+ className="bg-primary rounded-md text-muted"
+ disabled={isLoading}
+ >
+ {isLoading ? 'Logging in...' : 'Login'}
+ </Button>
+ </form>
+ </div>
+ </Layout>
+ );
+};
+
+export default EnhancedLogin;
+```
+```
+
 <br />
 
 :::strapi What's next?

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,7 +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), 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
+
+To configure basic authentication, use the following parameters:
 
 | Parameter | Description | Type | Default |
 |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------|
@@ -218,6 +222,43 @@ 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` |
 
+Additional configuration parameters are available for [session management](#session-management).
+
+### 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:
+
+- 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 |
+|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| `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
+
+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` | <ExternalLink to="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value" text="SameSite cookie attribute"/> | string | `'lax'` |
+
 ## Feature flags
 
 The feature flags can be configured with the following parameters:
@@ -365,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,
@@ -423,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,

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` | <ExternalLink to="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value" text="SameSite cookie attribute"/><br/>(see [cookie configuration](/cms/configurations/admin-panel#cookie-configuration)) | | `Lax` |
+| `UP_SESSIONS_COOKIE_PATH` | Cookie path<br/>(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
 
 <SampleEnv />
 
+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.