Add session management documentation (#2709)

* feat: add session management and authentication enhancements to CMS documentation

* Move endpoints to U&P feature docs and rework related sections

* Clean up configurations- and environment variables-related content

* Fix typo in link

* Clean up examples because they were mixing legacy and session management

* Update LLMs-full.txt

* Update docusaurus/docs/cms/configurations/admin-panel.md

Co-authored-by: Jamie Howard <48524071+jhoward1994@users.noreply.github.com>

* Remove useless/wrong values from env docs

* Update docusaurus/docs/cms/features/users-permissions.md

---------

Co-authored-by: Pierre Wizla <pwizla+github@gmail.com>
Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

Author: 2 people

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

@@ -56,6 +56,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.