Hydra example with letsencrypt certificate

[vinckr]

Problem

Users struggle to get from the quickstart to using not self-signed certificates.

Solution

Create a tutorial that uses the quickstart as basis to deploy the login-consent app with letsencrypt.

[gen1us2k]

I suggest writing an SSL guide for hydra. In that guide, we can cover almost all topics about SSL configuration

1. SSL for local development (mkcert/ngrok)
2. Let's encrypt usage
3. Using other certificates

[FredLackeyOfficial]

Creating another quick start guide is simply going to perpetuate the problem. Tossing yet another tech into the mix does not actually fix anything. So, while Let's Encrypt may help that one scenario, the root cause of the problem is that all Ory docs are written from the perspective of one Ory developer to another and none offer any type of primer on how the products work or an equivalent scenario would be in production. The "localhost" keyword is so overused that the Ory noob (like me) is left having to remember port numbers and figure out WHY they work. The use of ambiguous terms for variable names, like "HYDRA_ADMIN" only further complicate the matter.

So, while, yes, this specific ticket will help show someone how to implement SSL, it does not help them understand Hydra or stand it up Hyra in a production environment.

[aeneasr]

I guess the ask here is just too big. We can’t explain how to run a system in production in 5 minutes because everyone has different set ups. Person A uses AWS with EC2, someone else uses Heroku, the next person GKE, the next wants to run it on a raspberry PI with SQLite. Noone actually uses SSL directly in Hydra, most users use TLS Termination at the edge. Running software like Ory in production is like running a database in production, it requires careful consideration and trade offs, and most of all knowledge of the system! If it doesn’t work yet on your local machine, it most likely will not work in production either!

We offer tons of free tooling - from Kubernetes Helm charts to multi arch Docker images and binaries for every OS, but there’s only so much we can do!

But fear not! Ory Hydra will very soon be part of our Ory Cloud offering and consuming it in production will be as straight forward as using it locally. Just two clicks and you can use Ory Hydra‘s APIs without caring about SSL key rotation, zero downtime migrations, rolling releases, and ports :)

And I agree with your sentiment - adding yet another package of config files to Hydra won’t help. Most users do not run Hydra with SSL directly, they use managed solutions such as AWS API Gateway so that they don’t have to worry about SSL at all! I would thus suggest to close this issue :)

[FredLackeyOfficial]

Of everyone that I’ve spoken to off-line, the biggest problem with Ory and the Ory documentation, is that you were trying to satisfy everybody at the same time. The key here is not creating a document that solves every problem. The request is to strip away everything that is not absolutely essential and create a document showing that deployment. That means Linux, your binaries, and some basic routing. People not need to understand how the product functions, not how to use it with specifically Kubernetes.

Conversely, asking somebody wait for yet another cloud offering, or third party hosted solution, does not solve the problem at all. At that point you’re just one more provider, like Auth0.

Rather than discuss the opinions of white people should be using, strip back just the OS, Netwerk, and basic routing. If somebody wants to complicated, by adding other technologies on top of it, or replacing one technology with another, then allow them to make that decision after the basic functionality of the products are understood and demonstrated in a working environment.

[aeneasr]

But isn’t that exactly what the quickstart is? A bare minimum Linux (Alpine), a binary, very simple port-based routing, and a config file :)

ps: not trying to be rude, just want to understand what’s exactly you’d like to have!

[FredLackeyOfficial]

It is. However, you don’t have a quick start. You have a five minute demo that shows how to invoke a bunch of commands using docker compose. What you need is something that just shows how do use the most essential part of the software and tools, without adding additional tooling to the mix. The only example I know of has the word localhost in a slew of port numbers. The user can only follow it to see it run and spit back a status message. They don’t walk away with any understanding of the product itself or what it can do.

[gen1us2k]

We have preparing to production guide that gives recommendations on how to run Hydra in production. It would be great to have some configuration examples for nginx/envoy with a basic setup that can be used as a starting point to a more complex setup.

I think that the main problem is this one.

it does not help them understand Hydra or stand it up Hydra in a production environment.

Since Oauth2 is a complex topic to understand, I think that the documentation about discussing OAuth flows, revisiting some quickstart, and building simple demos with going to production tips would be useful. I think that we'll update some parts of Hydra documentation in Q2 to make it easier to understand and use Hydra.

[aeneasr]

Thank you @gen1us2k , I was about to ask a similar question.

Is the problem that the resources do not explain how OAuth2 works, or that they do not explain how the process and production set up work?

[FredLackeyOfficial]

No, in my opinion, teaching someone how OAuth2 works is beyond the scope. There are plenty of primers out there explaining the different flows. At most, give them links to those.

Going back to the question @aeneasr posed as to the "quick start," the goal of such an effort is to ensure the reader can start using the product, hence the "start" aspect. Today that is not possible. The reader can only blindly follow a few commands and see the resulting status messages. While this may prove the tool will function in the specific scenario outlined in the guide, the reader does not learn enough about the product to start using it outside of that guide.

Take, for example, the act of creating a client ID as shown in the "5 minute" guide. It shows a docker-compose command being used to invoke a command. A few questions stand out...

• Why is the reader using this command and not a web interface or RESTful endpoint?
• What is the syntax of the command?
• How do they use the command in a stand-alone environment without a Docker image bringing with it a slew of dependencies?

The same type of questions starts bubbling up with environment variables. Names like HYDRA_ADMIN are so generic that the reader is left at the mercy of their imagination...

• Is this a private endpoint that should be tucked behind the firewall?
• What functions is it used for within the workflow?

Since, within the document, everything is running on localhost, there is no way for a reader to understand what should be public versus private.

The "Preparing for Production" document only makes matters worse. Earlier on in this thread it was mentioned that eveyone's environment is different and that is impossible to account for those scenarios. I could not agree more. Unofrtunately, this document specifically begins to impart opinions on the reader that they have no choice but to follow. In fact, I would go so far as it is written in such as way as to explain why the document will NOT discuss anything technical.

Paragraph #1 of this document immediately explains, "We strongly recommend running ORY Hydra behind an API gateway or a load balancer" however you don't provide any examples of said load balancer. And, yes, providing THAT level of detail is overkill. However, the document does NOT show how to use it WITHOUT a load balancer.

The same holds true for TLS. The document mentions the reader may "choose to set Hydra to HTTPS mode without actually accepting TLS connections" but then strays off without ever showing an example of how to run it with or without TLS.

In the end, the user needs the ability to walk away with a BASIC YET USABLE install of Hydra without the need to load in other technologies. Don't go down the TLS route unless it's absolutely required. Don't use Docker, a load balancer, or anything else unless those specific technologies are needed for the product to run out of the box. Instead, give them an example of the most basic Linux-only deployment explaining public versus private communication of the components. Let them decide if they want to bundle the product into a package and use Podman, Docker, Kubernetes, etc. Let them decide if they want to leave it wide open and rely on HTTP/HTTPS for everything. The key is ensuring they can run the product before making them understand additional technologies or concepts.

[aeneasr]

Thank you @FredLackeyOfficial , that is extremely helpful! I have to think a bit about your input and we’ll try to come up with some good ideas and also direct feedback to the points raised.

Brainstorming about this quickly we could have an outline like:

• install hydra without docker
• run hydra serve all -c clnfig.yaml (using some default config) to start the service and
• explain the most important config options and maybe database options
• show what the public/admin APIs are for
• do some of the tasks from the 5 min tutorial but maybe without docker and just the regular binary
• an exemplary guide of how a prod set up would look like (eg private subnet, public aws api gateway)
• useful links for next steps

The current 5 minute demo could then be used to showcase the tech like in a tech demo, which might be useful if you just need to show something to your team.

[gen1us2k]

Some of the cases in this discussion were covered with this PR .

[vinckr]

I am closing this as there is noone working on it at the moment. If you have an idea or motivation to improve the current self-hosted Ory Hydra guides and examples, feel free to open an issue with more details or reach out to me directly via email or Slack. Thanks!