Add a blog post about Quarkus OIDC proxy

Author: sberyozkin

_data/authors.yaml

@@ -520,4 +520,11 @@ andreatp:
   emailhash: "6250a4b95ad7ddcf2ba7c3f84ba47995"
   job_title: "Principal Software Engineer"
   twitter: "and_prf"
-  bio: "Principal Software Engineer at Red Hat, working in Middleware Application Services on the Apicurio projects. Involved in the development of Microsoft's Kiota and Dylibso's Chicory."
+  bio: "Principal Software Engineer at Red Hat, working in Middleware Application Services on the Apicurio projects. Involved in the development of Microsoft's Kiota and Dylibso's Chicory."
+sberyozkin:
+  name: "Sergey Beryozkin"
+  email: "[email protected]"
+  emailhash: "7941c5788c2e02a4f7f51409afca3090"
+  job_title: "Software Engineer"
+  twitter: "sberyozkin"
+  bio: "Software Engineer, working at Red Hat on Quarkus Security."

_posts/2024-04-01-oidc-proxy.adoc

@@ -0,0 +1,245 @@
+---
+layout: post
+title: 'Use OIDC Proxy to integrate OIDC service endpoints with custom ChatGPT'
+date: 2024-04-01
+tags: extension oidc security chatgpt development-tips
+synopsis: 'Explain how OIDC Proxy can help to integrate OIDC service endpoints with custom ChatGPT'
+author: sberyozkin
+---
+:imagesdir: /assets/images/posts/oidc-proxy
+
+
+== Introduction
+
+https://github.com/quarkiverse/quarkus-oidc-proxy[Quarkus OIDC Proxy] is a new https://github.com/quarkiverse[Quarkiverse] extension which can help to integrate https://quarkus.io/guides/security-oidc-bearer-token-authentication[OIDC service endpoints] with external Single-page applications (SPA). SPA uses the OIDC authorization code flow itself (without relying on Quarkus) to authenticate the current user, and accesses the Quarkus OIDC service endpoint with the access token on behalf of the authenticated user.
+
+This is a simple diagram which shows how this process works, copied to this post from the https://quarkus.io/guides/security-oidc-bearer-token-authentication[OIDC Bearer token guide] for your convenience: 
+
+image::security-bearer-token-spa.png
+
+You can see that OIDC provider is used to authenticate the current user to SPA. SPA acquires ID and access tokens as part of the authorization code flow and uses the access token to access the Quarkus OIDC service endpoint. 
+
+SPA must know the OIDC provider connection details, including the registered OIDC application's client id, secret and other OIDC specific details required to complete the authorization code flow successfully. You must also allow an SPA specific callback URL in your registered OIDC application which may not always be acceptable.  
+
+https://github.com/quarkiverse/quarkus-oidc-proxy[Quarkus OIDC Proxy] emulates the OIDC provider in the diagram above. It interposes over Quarkus OIDC service endpoints and delegates to the real OIDC provider. It can help to integrate OIDC service endpoints with SPA without having to expose the internal OIDC connection details to this SPA. It relies on Quarkus OIDC to let SPA athenticate its users to OIDC and OAuth2 providers which may be technically challenging to support directly at the SPA level.
+
+Another user case for OIDC Proxy is to have several frontend https://quarkus.io/guides/security-oidc-code-flow-authentication[Quarkus OIDC web-app] endpoints to authenticate users using the same OIDC proxy configuration  before accessing the OIDC service endpoint.
+
+So how does OIDC proxy actually work ? Sure, we'll look at it shortly, but first, let's talk about custom ChatGPT actions.
+
+== Custom ChatGPT Actions
+
+https://chat.openai.com[ChatGPT] has introduced https://platform.openai.com/docs/actions/introduction[Actions], which can be used to create custom ChatGPT. For example, you can augment ChatGPT by connectng it to your API endponts.
+
+The key challenge is how a custom GPT can be https://platform.openai.com/docs/actions/authentication[authenticated] to access the API. The https://platform.openai.com/docs/actions/authentication/oauth[OAuth] is the best option when you need a user-specific permission to access the API, and this is what https://github.com/quarkiverse/quarkus-oidc-proxy[Quarkus OIDC Proxy] will help you to support without exposing all the OIDC/OAuth2 connection details to ChatGPT.
+
+Now all is ready for creating <<Quarkus Fitness Adviser>>.
+
+Please be aware that currently, custom ChatGPT actions can not be created with a free ChatGPT subscription, but only starting from the ChatGPT Plus subscription.
+ 
+== Quarkus Fitness Adviser
+
+In this section we will create `Quarkus Fitness Adviser`, a custom ChatGPT which analyzes activities recorded in Strava and other social providers which track physical exercise.
+
+We'll do it by creating a https://quarkus.io/guides/security-openid-connect-providers#strava[Strava] Quarkus OIDC Service endpoint, adding OIDC proxy to it, providing an HTTPS tunnel with https://ngrok.com/[NGrok] and creating a custom ChatGPT action which uses https://github.com/quarkiverse/quarkus-oidc-proxy[Quarkus OIDC Proxy] to autenticate users to Strava and use access tokens to the OIDC service Strava endpoint to analyze the recorded activities.
+
+=== Quarkus Strava Service
+
+Quarkus OIDC supports https://quarkus.io/guides/security-openid-connect-providers#strava[Strava OAuth2 provider] by hiding Srava OAuth2 specific details in a single configuration line, `quarkus.oidc.provider=strava`.
+
+Strava provider is mostly OAuth2 compliant but it uses HTTP query parameters to complete the authorization code flow POST token request, when using the form parameters is a usual option. It also uses a comma `,` separator when multiple scopes are requested during the initial redirect to Strava, with a space ` ` being a typical separator character.
+
+Quarkus OIDC proxy can handle it because it can use the Quarkus OIDC knowledge about these details. An SPA such as a custom ChatGPT does not support these options with its OAuth authentication option.
+
+We'll start by registering a new `Quarkus Fitness Adviser` application in Strava:
+
+image::strava-application-registration.png
+
+Note that the `Authorization Callback Domain` points to your free NGrok (or in production, the real) domain representing the domain where OIDC Proxy will be available, likely to be the same domain where your Quarkus micro-services are hosted as well. It is an important feature of OIDC Proxy as it lets OIDC provider administrators to point to a trusted domain and not a 3rd party domain.
+
+After completing the application registration, and noting the generated client id and secret, we create the OIDC configuration:
+
+[source,properties]
+----
+quarkus.oidc.provider=strava
+quarkus.oidc.application-type=service
+quarkus.oidc.client-id=${strava-client-id}
+quarkus.oidc.credentials.secret=${strava-client-secret}
+quarkus.oidc.authentication.extra-params.scope=profile:read_all,activity:read_all
+----
+
+Note, by default, `quarkus.oidc.provider=strava` will enable a Quarkus OIDC `web-app` endpoint capable of supporting the authorization code flow. But this endpoint has to act as a Quarkus OIDC `service` which accepts the bearer access tokens from ChatGPT, so we add `quarkus.oidc.application-type=service`. It will be OIDC Proxy which will manage the authorization code flow instead.
+
+See how the extra scopes to make the most of the https://developers.strava.com/docs/reference/[Strava API] are added to the scopes which are already enabledby `quarkus.oidc.provider=strava`, instead of overriding them, see https://quarkus.io/guides/security-openid-connect-providers#provider-scope[Provider scopes] for more information.
+
+We also add the following properties:
+
+[source,properties]
+----
+quarkus.rest-client.strava-client.url=https://www.strava.com/api/v3
+
+quarkus.smallrye-openapi.operation-id-strategy=method
+quarkus.smallrye-openapi.auto-add-security=false
+quarkus.smallrye-openapi.servers=https://manatee-apparent-mayfly.ngrok-free.app
+----
+
+First, we configure a Strava RESTClient to point to the base Strava API endpoint. And we tune a little bit the way an [OpenAPI document is generated by Quarkus] to have it acceptable by custom ChatGPT configuration process.
+
+Lets support this configuration by the actual code.
+
+Add the following Maven dependencies:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-oidc</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-oidc-token-propagation-reactive</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-resteasy-reactive</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-smallrye-openapi</artifactId>
+</dependency>
+----
+
+Here is a REST client which https://quarkus.io/guides/security-openid-connect-providers#access-provider-services-with-token-propagation[propagates] Strava access tokens to Strava:
+
+[source,java]
+----
+package org.acme.security.openid.connect.plugin;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import io.quarkus.oidc.token.propagation.AccessToken;
+import io.smallrye.mutiny.Uni;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@RegisterRestClient(configKey="strava-client")
+@AccessToken
+@Path("/")
+public interface StravaClient {
+
+	@GET
+	@Path("athlete/activities")
+	@Produces(MediaType.APPLICATION_JSON)
+	Uni<String> athleteActivities();
+
+	@GET
+	@Path("activities/{id}")
+	@Produces(MediaType.APPLICATION_JSON)
+	Uni<String> athleteActivity(@PathParam("id") long activityId);
+
+	// Etc for other Strava API
+}
+----
+
+and here is the actual service endpoint which accepts access tokens from a custom ChatGPT and uses the REST client to forward them to Strava:
+
+[source,java]
+----
+package org.acme.security.openid.connect.plugin;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+import io.quarkus.logging.Log;
+import io.quarkus.oidc.UserInfo;
+import io.quarkus.security.Authenticated;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+
+@Path("/athlete")
+@Authenticated
+public class FitnessAdviserService {
+
+    @Inject
+    UserInfo athlete;
+
+    @Inject
+    @RestClient
+    StravaClient stravaClient;
+
+    @GET
+    @Produces("application/json")
+    public Uni<String> athlete() {
+        Log.info("Fitness adviser: athlete");
+        return Uni.createFrom().item(athlete.getJsonObject().toString());
+    }
+
+    @GET
+    @Produces("application/json")
+    @Path("/activities")
+    public Uni<String> activities() {
+        Log.info("Fitness adviser: activities");
+        return stravaClient.athleteActivities();
+    }
+
+    @GET
+    @Produces("application/json")
+    @Path("/activity/{id}")
+    public Uni<String> activity(@PathParam("id") long activityId) {
+        Log.infof("Fitness adviser: activity %d", activityId);
+        return stravaClient.athleteActivity(activityId);
+    }
+
+    // Etc for other Strava API
+}
+----
+
+Not that, in order to accept the binary Strava access tokens, this endpoint is verifying them indirectly by requesting `UserInfo` from Strava, during the token authentication process. In this case `UserInfo` represents a Strava athlete profile.
+
+=== OIDC Proxy
+
+Now that we have created the OIDC Strava service endpoint, it is time to make easily accessible via an authorization code flow with the OIDC Proxy. 
+All you have to do is to add
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkiverse.oidc-proxy</groupId>
+    <artifactId>quarkus-oidc-proxy</artifactId>
+</dependency>
+----
+
+and it will enable OIDC `/q/oidc/authorize` for accepting authentication redirects, `/q/oidc/token` for exchanging an authorization code for tokens,
+and other OIDC endpoints at the `/q/oidc` root path.
+
+Let's update the application configuration:
+
+[source,properties]
+----
+quarkus.oidc.authentication.redirect-path=/callback
+quarkus.oidc.authentication.force-redirect-https-scheme=true
+quarkus.oidc-proxy.external-redirect-uri=https://chat.openai.com/aip/g-2faf163d359505ecb63596f17baa3dfe53ea3cb9/oauth/callback
+quarkus.oidc-proxy.root-path=/oidc
+quarkus.oidc-proxy.external-client-id=external-client-id
+quarkus.oidc-proxy.external-client-secret=external-client-secret
+----
+
+=== NGrok
+=== Custom ChatGPT
+
+== Security Considerations
+
+== Conclusion
+
+In this post we have looked at how https://github.com/quarkiverse/quarkus-oidc-proxy[Quarkus OIDC Proxy] can help to integrate OIDC service endpoints with SPA without having to expose the internal OIDC connection details. We have built `Quarkus Fitness Adviser`, a https://platform.openai.com/docs/actions/introduction[Custom ChatGPT action] which uses OIDC proxy to authenticate users with https://quarkus.io/guides/security-openid-connect-providers#strava[Strava] and provides fitness advice by reading the user specific data from the Quarkus OIDC Strava service.
+
+To learn more what Quarkus does around AI, see an innovative https://github.com/quarkiverse/quarkus-langchain4j[Quarkus LangChain4j] project which provides a top class integration between Quarkus and the https://github.com/langchain4j/langchain4j[LangChain4j] library.
+One possible idea to try is to use custom ChatGPT and OIDC Proxy to talk to the Quarkus OIDC service endpoint powered by https://github.com/quarkiverse/quarkus-langchain4j[Quarkus LangChain4j].
+
+Enjoy Quarkus, and, as `Quarkus Fitness Adviser` recommends, enjoy the ride !