Add Vert.x OIDC to Quarkus OIDC migration guide

[sberyozkin]

Fixes #45011.

This PR introduces the guide which explains to Vert.x OIDC users how to migrate to Quarkus OIDC.

It starts with going through the original Vert.x guide: https://how-to.vertx.io/web-and-oauth2-oidc/, putting different tutorial code fragments into the final MainVerticle code and clarifying some points.
Next it explains how to move to Quarkus, with Qute replacing Handlebars, while retaining Vert.x OIDC code if the users prefer it.

Finally, the guide shows how the example can be reworked with Quarkus OIDC, with JAX-RS also introduced, and gives 2 options of how to achieve it, one where Quarkus OIDC restores the original request URL as in the Vert.x OIDC tutorial, and another one where the control is given to the callback endpoint but after Quarkus OIDC completes the code flow.

Here, I've been also considering for a while if I should provide one more example, where original Vert.x application code route remains, but decided to avoid it for now, but I can probably add it later.

Next, there is a section explaining how Quarkus OIDC can be tuned easily to follow a stateful approach, given it is how Vert.x OIDC stores the session state.

I've also postponed creating any quickstarts code, as this guide is not a single quickstart, the guide uses several code fragments showing the possible migration path in the iterative way.

The guide will evolve.

[github-actions]

🙈 The PR is closed and the preview is expired.

[Copilot]

Pull Request Overview

Adds a reference to the new Vert.x OIDC to Quarkus OIDC migration guide in the authorization code flow documentation.

• Introduces a cross-reference for Vert.x OIDC users to the migration guide.

[michalvavrik]

I don't use vanilla standalone Vert.x, so you may want to ask for a review someone from their perspective. From my POV Vert.x OIDC on Quarkus is Quarkus without Quarkus Security. I expected that we could use Vert.X OIDC for authentication and adapt it on Quarkus Security. On the other hand, not sure why should we support that. It should only be good for users to avoid the migration effort (otherwise we can just improve Quarkus OIDC). Maybe due to https://vertx.io/docs/guides/vertx-5-migration-guide/#_setting_a_user Quarkus will soon need to use authentication handlers as well, and then, it would be easier.

The guide is great and helpful, so +1 for merging this.

[sberyozkin]

Thanks @gastaldi @michalvavrik.

This guide is added as a response to the Quarkus OIDC survey we did awhile ago, with one of the comments being that it was unclear how to migrate from Vert.x OIDC to Quarkus OIDC.

I don't use vanilla standalone Vert.x, so you may want to ask for a review someone from their perspective.

The vanilla Vert.x example is just a copy and paste of the Vert.x OIDC guide, 100% one to one, except that here in this PR I assemble various pieces of code from the guide into the final MainVerticle class, nothing new there :-).

From my POV Vert.x OIDC on Quarkus is Quarkus without Quarkus Security.

I added that example to show Vert.x users they don't have to switch everything immediately, but start gently with some basic iterative movement to Quarkus.

I expected that we could use Vert.X OIDC for authentication and adapt it on Quarkus Security.

This is how Quarkus OIDC was done initially, and a lot has already been said and discussed in depth since then why we moved to Quarkus specific OIDC implementation and this is reason for this PR, to help Vert.x OIDC users to migrate.

Going in the reverse direction is not going to work for Quarkus OIDC, but as I said to Max @maxandersen and Clement @cescoffier before, this is their decision if they would like to see the Vert.x team to introduce an alternative Vertx OIDC centric Quarkus extension, if some users will remain reluctant to migrate to Quarkus OIDC, which is fine with me for sure, I'll support that effort should that go ahead with some advice re how some things are done in Quarkus OIDC.

In the meantime, let me merge the PR and I'm sure we'll keep improving it, I'd like to see some initial user feedback and then see what to improve