craftercms · alhambrav · Apr 16, 2024 · Sep 24, 2024 · Sep 25, 2024
diff --git a/source/_static/api/studio.html b/source/_static/api/studio.html
diff --git a/source/by-role/system-admin/configuration.rst b/source/by-role/system-admin/configuration.rst
@@ -743,7 +743,7 @@ See the following for more information on using the configuration files encrypti
 
 - :ref:`change-the-defaults`
 - :ref:`crafter-deployer-administration`
-- :ref:`cipher-configuration`
+- :ref:`studio-cipher-configuration`
 
 .. _env-var-database-encryption:
 
@@ -765,7 +765,7 @@ Here are the environment variables used to encrypt and decrypt values in the dat
       - Salt used for encrypting database values
       - \<someDefaultSaltValue\>
 
-See - :ref:`cipher-configuration` for more information on using the above environment variables.
+See - :ref:`studio-cipher-configuration` for more information on using the above environment variables.
 
 .. _env-var-serverless-deployments:
 

diff --git a/source/reference/modules/engine/security.rst b/source/reference/modules/engine/security.rst
@@ -1,5 +1,5 @@
 :is-up-to-date: True
-:last-updated: 4.1.2
+:last-updated: 4.2.0
 
 .. _engine-security:
 
@@ -1282,4 +1282,66 @@ and :javadoc_base_url:`AccessRestrictionExpressionRoot.java <profile/org/crafter
           <expression /> (Spring EL expression)
         </restriction>
       </urlRestrictions>
-    </security>
+    </security>
+
+|hr|
+
+----------------------------
+Other Security Configuration
+----------------------------
+.. _engine-security-preview-mode:
+
+^^^^^^^^^^^^
+Preview Mode
+^^^^^^^^^^^^
+.. version_tag::
+    :label: Since
+    :version: 4.2.0
+
+In preview mode, CrafterCMS provides a security filter that can be enabled to intercept all requests and validates the following:
+
+- ``crafterPreview`` cookie exists
+- ``crafterPreview`` cookie decrypted value contains a site name and an expiration timestamp
+- Site name matches the one from ``SiteContextResolver``
+- Expiration timestamp is in the future
+
+To enable the Engine Preview Mode security filters, set ``crafter.security.preview.enabled`` to true.
+
+.. code-block:: properties
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+
+    #######################
+    # Security Properties #
+    #######################
+    # If the preview security filters should be enabled
+    crafter.security.preview.enabled=true
+
+There may be some URLs that may not need filtering in Preview mode by the security filter when it is enabled.
+To exclude a URL from being intercepted and validated by the security filter, add the URL to the
+``crafter.security.preview.urlsToExclude`` property:
+
+.. code-block:: properties
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+
+    # The URLs to be excluded from preview security checks
+    crafter.security.preview.urlsToExclude=\
+      /api/1/monitoring/**,\
+      /api/1/site/context/**,\
+      /api/1/site/cache/**
+
+Enabling the security filter in Preview Mode requires the configuration encryption configurations (which are shared
+between Studio and Engine) and admins will need to update the default configurations for the encryption key and salt in
+:ref:`Studio <studio-cipher-configuration>` and in :ref:`Engine <engine-configuration-properties-encryption>`.
+
+.. _engine-configuration-properties-encryption:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration Properties Encryption
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: properties
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+
+    # The key used for encryption of configuration properties
+    crafter.security.encryption.key=${CRAFTER_ENCRYPTION_KEY}
+    # The salt used for encryption of configuration properties
+    crafter.security.encryption.salt=${CRAFTER_ENCRYPTION_SALT}
diff --git a/source/reference/modules/studio/security.rst b/source/reference/modules/studio/security.rst
@@ -1,5 +1,5 @@
 :is-up-to-date: True
-:last-updated: 4.1.4
+:last-updated: 4.2.0
 
 .. index:: Studio Security
 
@@ -845,7 +845,7 @@ You can also change the Studio session timeouts from the |mainMenu| **Main Menu*
 
 |hr|
 
-.. _cipher-configuration:
+.. _studio-cipher-configuration:
 
 ^^^^^^^^^^^^^^^^^^^^
 Cipher Configuration
@@ -922,4 +922,45 @@ The following section of Studio's configuration overrides allows you to configur
 
 |
 
+.. _studio-preview cookie:
+
+^^^^^^^^^^^^^^
+Preview Cookie
+^^^^^^^^^^^^^^
+.. version_tag::
+    :label: Since
+    :version: 4.2.0
+
+The following section of Studio's configuration overrides allows you to configure settings for the Preview cookie.
+Studio adds a short-lived encrypted cookie called ``crafterPreview`` with the current preview site. This cookie gets
+re-issued along with the JWT auth token (if ``crafterSite`` is already set).
+
+.. code-block:: yaml
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml*
+    :linenos:
+
+    ##############################################################
+    ##                      Preview Cookie                      ##
+    ##############################################################
+    # Name of the preview
+    studio.security.token.previewCookie.name: crafterPreview
+    # Time in seconds for the expiration of the preview cookie
+    studio.security.token.previewCookie.maxAge: 600
+    # The path used to set the preview cookie
+    studio.security.token.previewCookie.path: /
+    # The domain used to set the preview cookie (if set to null or empty the domain will be detected from the request)
+    studio.security.token.previewCookie.domain: null
+    # Indicates if the preview cookie should be secure (should be true for production environments behind HTTPS)
+    studio.security.token.previewCookie.secure: false
+    # Indicates if the preview cookie should be HTTPOnly
+    studio.security.token.previewCookie.httpOnly: true
+    Password requirements validation allows the admin to setup rules that ensures users create passwords based on an organization’s password security policy.
+
+The Preview cookie  ``crafterPreview`` is encrypted using the encryption option for configuration files (which are
+shared between Studio and Engine) and admins will need to update the default configurations for the encryption key and
+salt in :ref:`Studio <studio-cipher-configuration>` and in :ref:`Engine <engine-configuration-properties-encryption>`.
+
+Use the API `switchPreviewSite <../../../_static/api/studio.html#tag/users/operation/getCurrentUserSites>`__ to refresh
+the ``crafterPreview`` cookie. This API must be called whenever the ``crafterSite`` cookie value is updated
+
 |hr|