From 9fea69da8b9eab44e8c9df4ca2d3b6c130ca64a8 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 19 Oct 2023 17:21:00 -0500 Subject: [PATCH 1/3] Docs: document CORS policies Closes https://github.com/readthedocs/readthedocs.org/issues/10836 --- docs/user/security-implications.rst | 61 +++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/user/security-implications.rst diff --git a/docs/user/security-implications.rst b/docs/user/security-implications.rst new file mode 100644 index 00000000000..899c187d9bd --- /dev/null +++ b/docs/user/security-implications.rst @@ -0,0 +1,61 @@ +Understanding the security implications of documentation pages +============================================================== + +This article explains the security implications of documentation pages, +this doesn't apply to the main website (readthedocs.org/readthedocs.com), +only to documentation pages. + +.. seealso:: + + :doc:`/api/cross-site-requests` + Learn about cross-origin requests in our public APIs. + +Cross-origin requests +--------------------- + +Read the Docs allows `cross-origin requests`_ for documentation resource it serves. +However, internal and proxied APIs, typically found under the ``/_/`` path don't allow cross-origin requests. + +To facilitate this, the following headers are added to all responses from documentation pages: + +- ``Access-Control-Allow-Origin: *`` +- ``Access-Control-Allow-Methods: GET, HEAD, OPTIONS`` + +These headers allow cross-origin requests from any origin +and only allow the GET, HEAD and OPTIONS methods. +It's important to note that passing credentials (such as cookies or HTTP authentication) +in cross-origin requests is not allowed, +ensuring access to public resources only. + +Having cross-origin requests enabled allows third-party websites to make use of files from your documentation, +which allows various third-party integrations to work. + +If needed, these headers can be changed for your documentation pages by :doc:`contacting support `. + +.. _cross-origin requests: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing + +Cookies +------- + +On |org_brand|, we don't use cookies, as all resources are public. + +On |com_brand|, we use cookies to store user sessions. +These cookies are set when a user authenticates to access private documentation. +Session cookies have the ``SameSite`` attribute set to ``None``, +which allows them to be sent in cross-origin requests where allowed. + +Embedding documentation pages +----------------------------- + +Embedding documentation pages in an iframe is allowed. +Read the Docs doesn't set the ``X-Frame-Options`` header, +which means that the browser's default behavior is used. + +Embedding private documentation pages in an iframe is possible, +but it requires users to be previously authenticated in the embedded domain. + +It's important to note that embedding documentation pages in an iframe does not grant the parent page access the iframe's content. +Documentation pages serve static content only, and the exposed APIs are read-only, +making the exploitation of a clickjacking vulnerability very unlikely. + +If needed, this header can be set on your documentation pages by :doc:`contacting support `. From dbfb6365c3daaae64744a518be1fc7c2f3bac727 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 18 Jan 2024 15:10:32 -0500 Subject: [PATCH 2/3] Updates from review --- docs/user/security-implications.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/user/security-implications.rst b/docs/user/security-implications.rst index 899c187d9bd..749992db3c9 100644 --- a/docs/user/security-implications.rst +++ b/docs/user/security-implications.rst @@ -2,8 +2,8 @@ Understanding the security implications of documentation pages ============================================================== This article explains the security implications of documentation pages, -this doesn't apply to the main website (readthedocs.org/readthedocs.com), -only to documentation pages. +this doesn't apply to the main dashboard (readthedocs.org/readthedocs.com), +only to documentation pages (readthedocs.io, readthedocs-hosted.com, and custom domains). .. seealso:: @@ -13,7 +13,7 @@ only to documentation pages. Cross-origin requests --------------------- -Read the Docs allows `cross-origin requests`_ for documentation resource it serves. +Read the Docs allows `cross-origin requests`_ for documentation resources it serves. However, internal and proxied APIs, typically found under the ``/_/`` path don't allow cross-origin requests. To facilitate this, the following headers are added to all responses from documentation pages: @@ -27,10 +27,11 @@ It's important to note that passing credentials (such as cookies or HTTP authent in cross-origin requests is not allowed, ensuring access to public resources only. -Having cross-origin requests enabled allows third-party websites to make use of files from your documentation, +Having cross-origin requests enabled allows third-party websites to make use of files from your documentation (as long as they are public), which allows various third-party integrations to work. -If needed, these headers can be changed for your documentation pages by :doc:`contacting support `. +If needed, the ``Access-Control`` headers can be changed for your documentation pages by :doc:`contacting support `. +**You are responsible for providing the correct values for these headers, and making sure they don't break your documentation pages.** .. _cross-origin requests: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing @@ -42,13 +43,16 @@ On |org_brand|, we don't use cookies, as all resources are public. On |com_brand|, we use cookies to store user sessions. These cookies are set when a user authenticates to access private documentation. Session cookies have the ``SameSite`` attribute set to ``None``, -which allows them to be sent in cross-origin requests where allowed. +which allows them to be sent in cross-origin requests where allowed +(see :ref:`security-implications:Cross-origin requests`), +for example, when embedding private documentation pages in an iframe +(see :ref:`security-implications:Embedding documentation pages`). Embedding documentation pages ----------------------------- Embedding documentation pages in an iframe is allowed. -Read the Docs doesn't set the ``X-Frame-Options`` header, +Read the Docs doesn't set the ``X-Frame-Options`` or ``Content-Security-Policy`` headers, which means that the browser's default behavior is used. Embedding private documentation pages in an iframe is possible, @@ -58,4 +62,5 @@ It's important to note that embedding documentation pages in an iframe does not Documentation pages serve static content only, and the exposed APIs are read-only, making the exploitation of a clickjacking vulnerability very unlikely. -If needed, this header can be set on your documentation pages by :doc:`contacting support `. +If needed, the ``X-Frame-Options`` and ``Content-Security-Policy`` headers can be set on your documentation pages by :doc:`contacting support `. +**You are responsible for providing the correct values for these headers, and making sure they don't break your documentation pages.** From 753577222ca91260b07aa471364ddc9bfe41d884 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 18 Jan 2024 15:20:24 -0500 Subject: [PATCH 3/3] Include in toctree --- docs/user/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/index.rst b/docs/user/index.rst index 800bb8fffc8..40fe7369742 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -26,6 +26,7 @@ Read the Docs: documentation simplified /localization /explanation/advanced /explanation/methodology + /security-implications .. toctree:: :maxdepth: 2