Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

christianlupus · 2024-10-03T18:34:15Z

☑️ Resolves

The statement about OCS to be legacy is removed
A comparison with (plain) REST is made

🖼️ Screenshots

T.B.D.

christianlupus · 2024-10-03T18:41:58Z

@provokateurin I started to rephrase the "do not use OCS" in this PR. Does this sound reasonable or am I going completely the wrong direction? I know I need to eventually write a few more words and I for sure have to check the table entries (and wanted to explain them a bit more).

What do you think, makes this sense? Is this to be discussed with some guys from the core team before merging (as it reverts some basic strategic statement)?

provokateurin

Thanks a lot, this is already super helpful!
The RST syntax for the table really messed with my brain, I need to take a closer look at it in proper table shape.

developer_manual/basics/controllers.rst

developer_manual/conf.py

developer_manual/digging_deeper/rest_apis.rst

provokateurin · 2024-10-03T19:28:53Z

developer_manual/digging_deeper/rest_apis.rst

+The following combinations of attributes might be useful for various scenarios:
+
+#. Plain frontend route: No special attribute related to CSRF or CORS
+#. Plain Frontend with CRSF checks disabled: Add the ``#[NoCSRFRequired]`` attribute


CSRF checks should only be disabled when absolutely necessary, this line should have a big warning

These are some of the few words I wanted to add...

developer_manual/digging_deeper/rest_apis.rst

provokateurin · 2024-10-03T19:41:06Z

developer_manual/digging_deeper/rest_apis.rst

+The following combinations of attributes might be useful for various scenarios:
+
+#. Plain frontend route: No special attribute related to CSRF or CORS
+#. Plain Frontend with CRSF checks disabled: Add the ``#[NoCSRFRequired]`` attribute


Suggested change

#. Plain Frontend with CRSF checks disabled: Add the ``#[NoCSRFRequired]`` attribute

#. Plain Frontend with CRSF checks disabled: ``Controller`` class and ``#[NoCSRFRequired]`` attribute on the method

developer_manual/digging_deeper/rest_apis.rst

provokateurin · 2024-10-03T19:42:13Z

developer_manual/digging_deeper/rest_apis.rst

+#. Plain frontend route: No special attribute related to CSRF or CORS
+#. Plain Frontend with CRSF checks disabled: Add the ``#[NoCSRFRequired]`` attribute
+#. REST route with CORS enabled: Add the ``#[CORS]`` attribute
+#. OCS-based route


There is another case with OCS+CSRF

christianlupus · 2024-10-07T22:05:41Z

I tried to address the points discussed here. I decided that the CORS should be better put in a separate section as it seems orthogonal to the original question (what should I use Controller or OCSController?).

For simpler reading, I put screenshots of the current state here:

provokateurin

Looks pretty good now!

developer_manual/basics/controllers.rst

provokateurin · 2024-10-08T07:03:16Z

developer_manual/digging_deeper/rest_apis.rst

+#. Plain frontend route: ``Controller`` class
+#. Plain Frontend with CRSF checks disabled: ``Controller`` class and ``#[NoCSRFRequired]`` attribute on the method
+#. OCS-based route: ``OCSController`` class
+#. OCS-based route with CSRF disabled: ``OCSController`` class and ``#[NoCSRFRequired]`` attribute on the method


I think this case doesn't exist, NoCSRFRequired should not have an effect on OCSController, but I will have to check that in the code to be sure.

I was thinking back and forth on this as well. In the end, I decided to keep the case as there is a certain difference (at least from the implementation):

For methods with NoCSRFRequired, this section is doing nothing.

For the case where the attribute is not given, the strict cookie check boils down to a check on the OCS-APIREQUEST header or no valid session token.

With the header in place (as the OCS controller generally expects), the second part is also skipped: The CSRF check is hardcoded to true, thus isInvalidCSRFRequired returns false.

When the header is not set, you enter the second if block and will check the inner if. The check isinstance OCSController is obviously true. The isValidOCSRequest is somewhat redundant as it can only be reached with the header unset. Alternatively, a bearer authorization header is sufficient to make the CSRF checker happy (even without OCS header and without NoCSRFRequired attribute).

I was adding this case as a reaction on your statement

There is another case with OCS+CSRF

In my opinion the last case could be dropped (and was never planned in the first round) but I do not see clearly the motivation of it, to be honest. Did I misunderstand your statement above?

In my opinion the last case could be dropped (and was never planned in the first round) but I do not see clearly the motivation of it, to be honest. Did I misunderstand your statement above?

I messed up, I meant OCS+CORS...
Currently the CORS cases are completely missing in the list.

Yeah, okay, then that makes more sense. I can read the cors posts and extend by the OCS+cors as well.

I will add a warning about cors in general similar to csrf of you do not mind.

If you have any idea how to describe the case Access from external website more precisely or otherwise better, feel free to comment 😉.

christianlupus · 2024-10-09T22:47:26Z

Updated text:

github-actions · 2024-10-18T02:39:11Z

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

christianlupus · 2024-10-26T08:15:44Z

@provokateurin are you still looking some things up, is there any action from my side required at the moment, or was there simply no time to review/prepare merging?

provokateurin · 2024-10-27T14:25:28Z

No sorry, I was just busy with other things. I'll take another look in the coming days 👍

provokateurin

Some links to general resources like these would be nice:
https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
https://developer.mozilla.org/en-US/docs/Glossary/CSRF

developer_manual/basics/controllers.rst

developer_manual/digging_deeper/rest_apis.rst

provokateurin · 2024-10-28T07:34:37Z

developer_manual/digging_deeper/rest_apis.rst

+- *Access from an external app* indicates that the user is not using the normal browser (as logged in) but directly navigates a certain URL.
+  This can be in a new browser tab or an external program (like an Android app or simply a curl command line).


I don't understand what these two cases have in common.
Security wise they are also a bit different, since you need CSRF protection to prevent redirect attacks via GET while this is completely irrelevant for non-browser use cases like curl.

They have in common that the CSRF token is not (guaranteed to be) known as part of the Cookie header and that the user is doing a dedicated action to navigate there (not by using a JS/AJAX request).
You are right these might be considered as separate cases. From user perspective (what can be done? not what is secure?), both navigate to an arbitrary URL and fetch the data. Examples:

The user navigates to http://cloud.example.com/apps/cookbook/recipe/1234 the basic HTML template should be rendered in the browser and load the recipe 1234. If the actual call to the HTML template would be CSRF-protected any bookmarked link would break.

An app wants to fetch data from the cookbook using a REST-based API http://cloud.example.com/apps/cookbook/api/v1/recipes/1234. Here, the CSRF checks might cause trouble as well prohibiting legitimate access to the endpoint.

I have not worked out the security side of this. What do you mean by redirect attacks via GET?

"requests from non-browser"

I reread this and we are focusing on the data responses. Thus, the browser bookmark issue is no longer an issue. Instead, a reference to the restructured controller section was added. Thus it boils down to non-browser access as far as I see.

developer_manual/digging_deeper/rest_apis.rst

christianlupus · 2025-01-20T16:57:59Z

OK, unfortunately, I had the impression that I needed to restructure the controller chapter. This was a bit back and forth. Many of the changes are just rearrangements. Sorry for the mess. I tried to separate the data from the template requests.

As the changes are lengthy, I would have to copy&paste the complete section here. Thus, instead, I post the built documentation for download: Developer manual.zip

If it helps, I could postpone this PR, rebase the restructuring of thee controller class into a new PR, get that merged, and then come back to this PR here.

provokateurin · 2025-01-27T14:51:34Z

Hm yes this is indeed getting a bit hard to review. A separate PR with only the restructuring would be very appreciated.

christianlupus · 2025-01-29T13:18:58Z

Yeah, I see that. I opened #12549 mostly as a cherry-pick from this to first do the restructuring. Then, this can be worked on easier. Until #12549 is resolved, let's freeze this PR.

provokateurin · 2025-02-28T17:49:17Z

Needs a rebase :)

mejo- · 2025-06-11T06:52:32Z

Just a short note from someone who just started to migrate their app to OCS API with OpenAPI support: getting this PR merged would be a great improvement already. Maybe further improvements can be done in follow-up PRs later on to already profit from the clarifications done so far 😊

Signed-off-by: Christian Wolf <[email protected]>

Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

Signed-off-by: Christian Wolf <[email protected]>

Fix typos and other errors in the code as suggested by review process Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

Signed-off-by: Christian Wolf <[email protected]>

christianlupus · 2025-06-13T17:09:56Z

The main part is in REST vs OCS is this part:

The updated code in the security guidelines:

provokateurin · 2025-06-13T17:44:26Z

I'm a bit busy at the moment, but will give this a proper review in the week after next. I expect that everything will be fine, since we already discussed most changes intensively.

provokateurin

Only found some minor things that need to be changed, otherwise this looks really good!
Feel free to squash everything in the end (or leave it as-is).

developer_manual/digging_deeper/rest_apis.rst

provokateurin · 2025-06-20T05:19:13Z

developer_manual/prologue/security.rst

+
+Additionally, it is advised to carefully select the HTTP method used for requests.
+Requests of type ``GET`` should not alter data but just read existing data.
+As long as no other attack is involved, any non-``GET`` request requires at least user interaction (transmitting a form).


Not sure how relevant this is, since it's easy to submit a form via JS, so it does not really need any user interaction. The two sentences above are good though, maybe they should also mention HTML templates again?

developer_manual/prologue/security.rst

developer_manual/basics/controllers.rst

developer_manual/conf.py

developer_manual/digging_deeper/rest_apis.rst

nickvergessen · 2025-06-20T05:58:36Z

developer_manual/prologue/security.rst

+CORS
+----
+
+`Cross-origin resource sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ (see also on `MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`__) is a method implemented by browser to access resources from different domains at the same time.


Suggested change

`Cross-origin resource sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ (see also on `MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`__) is a method implemented by browser to access resources from different domains at the same time.

`Cross-origin resource sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ (see also on `MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_) is a method implemented by browser to access resources from different domains at the same time.

Please add a screenshot if the URL renders with 2 underscores or one

developer_manual/prologue/security.rst

nickvergessen · 2025-06-20T06:04:24Z

developer_manual/basics/controllers.rst

@@ -434,6 +438,9 @@ A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an
 developers can implement their own types of menu renderings by adding a custom
 class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.

+As the public template is also some HTML template, the same argumentation as for :ref:`regular templates<controller_template>` regarding the CSRF checks hold true:
+The usage of ``#[NoCSRFRequired]`` for public pages is considered acceptable and is actually needed to visit the page without an active account.


This is not true as an isolated statement!?
Not every page for guests should have NoCSRFRequired.
It should at least be limited to such that return templates again, but I'm not sure that is correct. I think it is only necessary (and therefore should be limited to) pages that are entry points.
You can have multiple pages that return HTML templates but you reach the next page by submitting a form or something, then it should only be the first page that has it?
Basically it's:

Only GET requests returning HTML that do not perform any data manipulation.

Or did I misunderstand something?

You can have multiple pages that return HTML templates but you reach the next page by submitting a form or something, then it should only be the first page that has it?

But the user could reload the page manually, so I think it's necessary to disable csrf for all templates.

But the user could reload the page manually, so I think it's necessary to disable csrf for all templates.

In which case they would see a "Form expired …" page from the browser. Otherwise this is exactly what CSRF is about. It should prevent being tricked into a page that is "deep linking" into a flow or to a page that is not a non-interactive frontpage

Add modifications from reviews Co-authored-by: Joas Schilling <[email protected]> Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

christianlupus added 2. developing manual: developer labels Oct 3, 2024

provokateurin requested changes Oct 3, 2024

View reviewed changes

christianlupus mentioned this pull request Oct 7, 2024

REST or OCS #12157

Open

provokateurin requested changes Oct 8, 2024

View reviewed changes

christianlupus force-pushed the fix/clarification-rest-ocs branch from 08e4aab to ca6794c Compare October 8, 2024 22:33

github-actions bot added the feedback-requested label Oct 18, 2024

provokateurin requested changes Oct 28, 2024

View reviewed changes

christianlupus force-pushed the fix/clarification-rest-ocs branch from adef92f to b7ee67f Compare December 26, 2024 12:34

christianlupus force-pushed the fix/clarification-rest-ocs branch from b7ee67f to 857ad30 Compare January 20, 2025 16:39

christianlupus mentioned this pull request Jan 29, 2025

Restructure significant part of the controller documentation #12549

Merged

christianlupus force-pushed the fix/clarification-rest-ocs branch from 26a5d3f to b0084a7 Compare March 3, 2025 17:16

christianlupus and others added 7 commits June 13, 2025 18:14

Started to fix unclear statements about OCS and REST

1e63339

Signed-off-by: Christian Wolf <[email protected]>

Fix some sphinx build watrnings

6a9fb9d

Signed-off-by: Christian Wolf <[email protected]>

Apply suggestions from code review

9b817ad

Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

Fix OCS description after some research

5fd856f

Signed-off-by: Christian Wolf <[email protected]>

Adding CORS back into the mix

64453ed

Signed-off-by: Christian Wolf <[email protected]>

Apply suggestions from code review

5e0e926

Fix typos and other errors in the code as suggested by review process Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

Restructure significant part of the controller documentation

2fdeb0b

Signed-off-by: Christian Wolf <[email protected]>

christianlupus added 6 commits June 13, 2025 18:14

Add basic introduction to CORS in security introduction

86d6bae

Signed-off-by: Christian Wolf <[email protected]>

Add some paragraph on GET vs other verbs in HTTP

08a8920

Signed-off-by: Christian Wolf <[email protected]>

Adding some text on historic routing with REST routes

845e062

Signed-off-by: Christian Wolf <[email protected]>

Add MDN links

146e624

Signed-off-by: Christian Wolf <[email protected]>

Fix warning in RST code

bda070d

Signed-off-by: Christian Wolf <[email protected]>

Fix typo

5203eaa

Signed-off-by: Christian Wolf <[email protected]>

christianlupus force-pushed the fix/clarification-rest-ocs branch from b0084a7 to 5203eaa Compare June 13, 2025 16:16

Reword external app to non-browser

3071dbf

Signed-off-by: Christian Wolf <[email protected]>

christianlupus marked this pull request as ready for review June 13, 2025 17:04

provokateurin requested changes Jun 20, 2025

View reviewed changes

nickvergessen requested changes Jun 20, 2025

View reviewed changes

Apply suggestions from code review

34756e2

Add modifications from reviews Co-authored-by: Joas Schilling <[email protected]> Co-authored-by: Kate <[email protected]> Signed-off-by: Christian Wolf <[email protected]>

	#. Plain Frontend with CRSF checks disabled: Add the ``#[NoCSRFRequired]`` attribute
	#. Plain Frontend with CRSF checks disabled: ``Controller`` class and ``#[NoCSRFRequired]`` attribute on the method

		- Access from an external app indicates that the user is not using the normal browser (as logged in) but directly navigates a certain URL.
		This can be in a new browser tab or an external program (like an Android app or simply a curl command line).

	`Cross-origin resource sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ (see also on `MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`__) is a method implemented by browser to access resources from different domains at the same time.
	`Cross-origin resource sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ (see also on `MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_) is a method implemented by browser to access resources from different domains at the same time.

Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

Are you sure you want to change the base?

Clarify the description of REST vs OCS in accordance to sugestions discussed #12264

Uh oh!

Conversation

christianlupus commented Oct 3, 2024

☑️ Resolves

🖼️ Screenshots

Uh oh!

christianlupus commented Oct 3, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christianlupus commented Oct 7, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christianlupus commented Oct 9, 2024

Uh oh!

github-actions bot commented Oct 18, 2024

Uh oh!

christianlupus commented Oct 26, 2024

Uh oh!

provokateurin commented Oct 27, 2024

Uh oh!

provokateurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christianlupus commented Jan 20, 2025

Uh oh!

provokateurin commented Jan 27, 2025

Uh oh!

christianlupus commented Jan 29, 2025

Uh oh!

provokateurin commented Feb 28, 2025