More content on Ory Proxy and local development

[Benehiko]

Preflight checklist

• [X] I could not find a solution in the existing issues, docs, nor discussions.
• [X] I agree to follow this project's Code of Conduct.
• [X] I have read and am following this repository's Contribution Guidelines.
• [ ] This issue affects my Ory Cloud project.
• [X] I have joined the Ory Community Slack.
• [X] I am signed up to the Ory Security Patch Newsletter.

Context and scope

We get a lot of questions from the community over the usage of the Ory Proxy in local development and how this would look for them when going to production.

Some examples from the Ory slack include:

• https://ory-community.slack.com/archives/C012RJ2MQ1H/p1646068594127949
• https://ory-community.slack.com/archives/C02MR4DEEGH/p1646863463579309
• https://ory-community.slack.com/archives/C02MR4DEEGH/p1646623854027749
• https://ory-community.slack.com/archives/C02MR4DEEGH/p1646681514211979

@vinckr @tomekpapiernik

Goals and non-goals

Goals

• Clear up what the Ory Proxy is
• Why certain errors happen in the browser and not in cURL
• Going to Production and how that looks with the current proxy configuration

Non-Goals

• Navigating rate limiting
• Custom UI setup and Redirects (differences between proxy setup and cname)

The design

The problems seem to stem from not knowing what the Ory Proxy is really doing behind the scenes. Some questions we are not answering in the docs are as follows:

1. Why do I need to use the Ory Proxy if I can just call the Ory API directly using cURL?
2. What happens in production to say redirect URL now after I have tested this using the Ory Proxy?
3. Do I need to configure any redirect URLs when using the Ory Proxy on the Console?
4. Why do I get CORS errors?
5. I get CSRF cookie problems?
6. What does 429 Too Many Requests mean when using the Ory playground project?
7. Can I use the Ory Proxy for production instead of CNAME and why should I use a CNAME? - The docs actually are outdated here since it says you can use the Ory Proxy for production (see here).
8. Why does the Ory Proxy issue a JWT token? Do I need to use that in my React App instead of Cookies?

So all of these questions are related to the Ory proxy (even CORS). We need to answer these questions in our documentation. We can already use some of the answers and feedback on slack to improve it, but I will also answer some of the questions above.

1. The browser does not allow calling resources (such as Ory APIs) from a different origin (e.g. localhost). That is why one gets CORS errors. The proxy in this case works like cURL in the background (where there is no browser) to make the call to the Ory APIs on your browsers' behalf.
2. We can setup the redirect URLs on the console to be relative which would always redirect back to the proxy base URL and then once you add your domain to the Ory Console everything will just go through your domain as it would have through the proxy.
3. No you don't need to, but if you are developing a server-side rendered application, then you will need to configure where the user should be redirected to after say login or registration etc.
4. CORS errors are a browser specific error. The browser does not allow requests to be made across origins e.g. the browser is on localhost:4000 but the request is going to the origin oryapis.com. The proxy takes care of this since our application is now contacting the proxy on localhost:4000 and the user is on localhost:400 which is also the proxy - the origin is now the same.
5. All requests on your application and all requests from the user should be going through the Proxy. The proxy rewrites the cookie domain so that it seems to your browser like the cookie was set by the proxy instead of Ory.
6. These are rate limiting errors and it could happen that the playground project has many users interacting with it or if you are requesting the Ory APIs too many times per second. This is temporary and after some time (a couple of seconds) it should be accessible again. If you experience too many of these errors on the playground - please create your own developer project (it's free!).
7. No, we do not recommend using the Ory Proxy for production since its purpose is only to make local development easier. It is not battle tested. We recommend you add your domain to the Ory Console so that you do not need the Ory Proxy.
8. This was added for a specific internal goal - it is not guaranteed that the JWT token support will stay in the Ory Proxy in the future. Always use the cookie the Ory Proxy gives you instead.

APIs

No response

Data storage

No response

Code and pseudo-code

No response

Degree of constraint

No response

Alternatives considered

No response

[tomekpapiernik]

Many of these questions/doubts have been explained in the new CLI documentation, wouldn't you say?

https://www.ory.sh/docs/guides/cli/installation https://www.ory.sh/docs/guides/protect-page-login/expressjs#why-do-i-need-the-ory-cli

[Benehiko]

@tomekpapiernik I don't think so.

We don't properly address the issues you would get in setting up a local environment with the cloud. Yes we point to some loose resources, but it isn't (in my opinion) as substantial as I would like it to be. For instance, lots of developers still struggle with CORS issues, why we cannot just call from localhost to the oryapis directly. How does this affect things like local development and testing (e.g. staging, production environments). Why you cannot use the Ory Proxy in production (well you can but we don't cater for it).

From the resources we currently have I will strike out the answered questions below:

1. Why do I need to use the Ory Proxy if I can just call the Ory API directly using cURL? (we don't actually answer this in detail - such as what is CORS and why you should care about it we only link to the MDN about CORS. We need an example here of "you can use cURL but then when using the browser ajax calls we get CORS errors")
2. What happens in production to say redirect URL now after I have tested this using the Ory Proxy? (we don't actually show people why and when you need it in relation to the proxy and how the migration from local development to production looks like)
3. Do I need to configure any redirect URLs when using the Ory Proxy on the Console? (we don't mention this - check redirects)
4. Why do I get CORS errors? (we sort of explain it but i think it needs its own concepts page - this relates to question 1)
5. I get CSRF cookie problems? (we address this in open source but not in cloud)
6. What does 429 Too Many Requests mean - I get it a lot with the Ory playground project. (we don't explain rate limiting)
7. ~~Can I use the Ory Proxy for production instead of CNAME and why should I use a CNAME?~~
8. Why does the Ory Proxy issue a JWT token? Do I need to use that in my React App instead of Cookies? (we still don't answer this question in the cli proxy documentation, we say you can use JWT but not the use case - see proxy zero trust)

[tomekpapiernik]

we don't actually answer this in detail - such as what is CORS and why you should care about it we only link to the MDN about CORS.

I don't agree - the documentation should be focused on Ory rather than explaining different security-related topics and concepts in depth. Whatever explanation of external systems or security mechanisms we might need, we should keep them to a minimum. If someone doesn't know what CORS is, they can go to many different places to learn all about it. When people visit Ory docs, they should be getting information about Ory, not the "Ultimate Guide to Security and Relevant Concepts" ;)

Think about it this way - when you buy a car and you open the car's manual, you get information about the relevant technical data, service intervals, troubleshooting, configuration, and warnings. You don't get essays about how to safely change lanes, do parallel parking (and the history of parallel parking while we're at it), or an overview of what overtaking is.

If all that information was there, it'd be really hard to find the actual information you might need when using a car - for example, how to mount a roof rack or how much oil you need to perform oil change.

[tomekpapiernik]

Keeping that in mind, I think we could work together to extend the docs to better explain some of these matters. I think in our "protect page w/ login" examples we could have that in the "going to production" section. The same information could be then added as a separate CLI category document or as an additional section in one of the existing documents.

Since you're very knowledgeable about these matters, I think it'd be great if you could prepare a write-up of things that we should cover which I'd then edit and add to the docs.

You don't have to try and write something that can be added to the docs right away - I can work with a bunch of notes and try to come up with a way to add them to the docs. We can then do some back and forth to see if my vision gets all the points across.

WDYT?

[aeneasr]

If lots of people struggle with this (the linked resources paint such a picture), and come to the community over and over to ask these questions, we need to provide sufficient information because it clearly is not visible enough, or not available. One thing to always keep in mind is that developers do not follow your documentation step by step. They start, get distracted, try something out. If there is noone telling you "You need this tool or X does not work", someone will try to do it without the tool because it's work to install it and the value is not clear to the user of why you need it.

For every person complaining about this problem, there will be 2x-5x people who will think that the product is just hard to use. Let's try to address these issues, and also define how we measure the success of such an effort transparently. Where it's located does not really matter to me, it's just important that people see it in the right context, at the right time. I think the "get login working" guides are a good starting point!

[vinckr]

I think Tom has a good point that the docs should be product-focused. We can cover things like

"what is CORS and why you should care about it we only link to the MDN about CORS with examples of "you can use cURL but then when using the browser ajax calls we get CORS errors"

on our blog. then we can link to the resource like ory.sh/why-cors-matters whenever we think its needed/helpful in the docs. Then when we have enough content covering relevant things we create a page on the website or docs that gathers all these for a general "networking with Ory" overview.

that way we have the content neatly seperated into product and learning and still can provide good resources for everything on our domain, (also blog is more approachable for contributions IMO) 👍 / 👎 ?

[gen1us2k]

If someone doesn't know what CORS is, they can go to many different places to learn all about it.

I think it would be great to have links to the external resources (like MDN or something similar). This would be an external resource, but people can find information about the topic.

[aeneasr]

The website and blog is not more approachable for contributions than the docs which has an easy interface to edit any page. We have way more contributors on the docs than on the blog, too.

The developer documentation has to explain (it is ok to link to MDN for further read up) why you need to do a certain thing, or you will forever have to deal with questions like this:

My set up fails because of CORS errors.

Ok, did you use the Ory Proxy?

No, I didn't know I need it.

If we can't explain why you need the Ory Proxy, and only that you need it, a lot of people won't see the benefit of using it, and will end up with frustrating experiences. I've heard this feedback even from people that work in Ory. "Oh I didn't know that I can use the Ory Proxy it's really easy now!"

[aeneasr]

Let me give you an example, you can't use Stripe's recurring billing feature, if you do not understand how the billing cycle works. You can try to use it, but you will use it incorrectly, and things will not work.

In Ory, one of the most important aspects of integration is that cookies work. The Ory Proxy is essential for local development. You can not use Ory without the Ory Proxy on local development, unless we have some type of integration for your framework that does what the Ory Proxy in the framework's language and platform (e.g. NextJS). For 99% of use cases, we have no native integration and you need to use the Ory Proxy.

In conclusion, even if CORS is "technical" and "you don't really need to care" that's just not true. And that's why people struggle, because if you fail to set it up (and you will fail if you don't use Ory Proxy or Ory CNAME), then you just won't be able to use Ory at all. A blog article is also good, and additionally we need to establish this knowledge in the right context, at the right time (as early as possible).

[Benehiko]

I fully agree with @aeneasr. I also like the idea @vinckr, but we need to also be realistic in how developers operate. I am one so I know :laughing:.

Developers aren't going to read a lengthy blog post about a topic while setting up their Authentication in their project. Not actively anyway. It will be more of a "oh i came across a blog post in my free time that explains CORS" - and maybe if they are really stuck will start googling or reading more in-depth.

But since we are a security company and we sell the idea of "easy integration" just 1, 2 and 3 and you're setup - we need to "force" people to read certain topics inside the setup of their Ory project or Ory integration journey.

I would vote on adding at least some information on why you need some things inside the docs and also have blog articles to draw developers to us. We are a so called "developer-first" company which means that we are here to teach people topics in security and best practices in software (through our blog posts and open source). The docs don't need to be a full on technical manual on for example how Kratos internal libraries work or the reasoning behind that. We just need to make the user journey of Ory integration easier.

@tomekpapiernik I would be happy to help with these, but I cannot write them and develop software :) So let's pick a topic we see is lacking from the list of questions and start tackling them one by one in a PR. We can even schedule some meets to really get into the background information of the topic so that we can deliver high quality documentation.

[tomekpapiernik]

Let me give you an example, you can't use Stripe's recurring billing feature, if you do not understand how the billing cycle works. You can try to use it, but you will use it incorrectly, and things will not work.

In conclusion, even if CORS is "technical" and "you don't really need to care" that's just not true.

I never said that things like this shouldn't be in our docs bc you don't really need to care. What I'm saying is that our documentation should focus on what Ory does, and if there are any other concepts users need to know to get their setups better and more secure (concepts that are NOT Ory-specific), we should point them to sources that have done that and had the freedom to dedicate entire blogposts/webinars/websites/sample projects to certain topics.

Also, I'm not dismissing the fact that some of the concepts should be explained in a condensed form. Just have a look at the "social sign-in" overview document - I'm thinking about explanations like this.

@tomekpapiernik I would be happy to help with these, but I cannot write them and develop software :)

Sure, I understand. That's why I suggested that you write general notes, simple sentences, remarks rather than edit existing documents and try to fit into the existing structure. I think that such an approach is more time-efficient than setting up meetings ;)

[github-actions[bot]]

Hello contributors!

I am marking this issue as stale as it has not received any engagement from the community or maintainers for a year. That does not imply that the issue has no merit! If you feel strongly about this issue

• open a PR referencing and resolving the issue;
• leave a comment on it and discuss ideas on how you could contribute towards resolving it;
• leave a comment and describe in detail why this issue is critical for your use case;
• open a new issue with updated details and a plan for resolving the issue.

Throughout its lifetime, Ory has received over 10.000 issues and PRs. To sustain that growth, we need to prioritize and focus on issues that are important to the community. A good indication of importance, and thus priority, is activity on a topic.

Unfortunately, burnout has become a topic of concern amongst open-source projects.

It can lead to severe personal and health issues as well as opening catastrophic attack vectors.

The motivation for this automation is to help prioritize issues in the backlog and not ignore, reject, or belittle anyone.

If this issue was marked as stale erroneously you can exempt it by adding the backlog label, assigning someone, or setting a milestone for it.

Thank you for your understanding and to anyone who participated in the conversation! And as written above, please do participate in the conversation if this topic is important to you!

Thank you 🙏✌️