PKCE implementation with one-time-code-challenges in a Gitlab client

[HBrendy]

Dear François (@frankie567),

thank you for this great library! I'm using it in for an open source project in a public health context and it helped me a lot.

I'm using the Github httpx-oauth client alongside my self-written Gitlab httpx-oauth client for our self-hosted Gitlab instance. While Github does not (yet?) support PKCE, Gitlab does and it worked almost out of the box:

TLDR

I generate the PKCE code verifiers & challenges on a per-request basis.
To match an incoming callback (including a state JWT) to a code_verifier, I put the code_challenge into the state JWT upon generating the authentication URL.
For this to work, the state JWT needs to be handed over to the class function get_access_token() of the dependency httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback:

self.client.get_access_token(
                code, redirect_url, code_verifier, state  # [@HBrendy] adding --> 'state' <-- is my monkey patch to httpx-oauth for PKCE support with one-time-code-challenges
            )

Reasoning / Background

My current stack includes httpx-oauth v0.16.1, fastapi-users[beanie,redis,oauth] v14.0.1 and fastapi v0.115.6.
To store the code verifier & challenge in the fastapi backend, I created a class similar to fastapi-users RedisStrategy within my httpx_oauth/clients/gitlab.py that handles secret generation, challenge derivation and stores both in REDIS as a key:value pair:

self.redis.set(name = f"{self.key_prefix}{code_challenge_urlsafe}", value = code_verifier, ex = self.lifetime_seconds)

The code_challenge is then added to the state before responding to a get_authorization_url() request and also acts as an identifier when the callback is triggered.
It is a bit hacky to decode the state JWT, add the code_challenge and encode it again, but this way, all logic is confined to the client class [BaseOAuth2].

I still went down that road to get one-time-code_verifiers for trading in access tokens for Authorization Codes.
For this, my custom client.get_access_token() needs the state JWT to exctract the code_challenge to look up the code_verifier in REDIS before sending it to the Authorization Server.

Benefits:

• one-time-code_verifier per authorization url
• more entropy in the state JWT

With above mokey patch, I have a working Oauth2 with PKCE against Gitlab :-)
What do you think of this approach?
Shall I wrap it as a MR?

Cheers from Berlin,
Holger

[frankie567]

Hi @HBrendy 👋

Thank you for your feedback and detailed explanations! Your explanations enlighten something I never saw before: the way we expect code_verifier in the FastAPI integration is completely broken 🙃

httpx-oauth/httpx_oauth/integrations/fastapi.py

Lines 75 to 82 in 26761ec

	async def __call__(
	self,
	request: Request,
	code: Optional[str] = None,
	code_verifier: Optional[str] = None,
	state: Optional[str] = None,
	error: Optional[str] = None,
	) -> tuple[OAuth2Token, Optional[str]]:

This is executed by FastAPI when the callback route is called. Here, it's implemented as if the code_verifier was passed in query parameters by the authentication server; which of course is not how things work.

A working approach would be to expect the end-developer to provide its own function or method to retrieve the code_verifier (depending on their approach, e.g. a Redis storage or a web session). This is something I should definitely revisit.

---

Now, regarding your approach, sounds reasonable. Maybe what's a bit surprising is that you use the code_challenge as your Redis key. Since it's then included in the state JWT, it's very simple to anyone to read that value.

I agree code_challenge is a hashed value so shouldn't be too sensitive but... Well. I would rather encourage you to generate a random identifier for your Redis "session", which will be then included in your JWT or, even better, be your state value directly (no need to have a JWT if you have a reliable server-side mechanism to store session data).

---

Final side note: PKCE was primarily designed for public OAuth2 clients, where you can't use the client_secret. From what I understand here, you seem to be in a pure server-side context where client_secret is used. In this case, while PKCE is a nice plus, it doesn't really add that much security to the implementation :)

[HBrendy]

Hi @frankie567 ,

thank for your instant response! Work carried me away the in last days, but now I can finally reply:

• [code_verifier] : I totally agree with you, a setup where a code together with its code_verifier is sent to the callback endpoint would defy the whole PKCE purpose. The user should provide means to store the code_verifier, as you said.
• [code_challenge in JWT] To give you a bigger picture to my specific setup, a NextJS frontend is requesting the authorization_url, which, by PKCE standard, includes the code_challenge as a query parameter (while my redirect_url is targeting back to the frontend). The FE then sends the state and authorization code to the FastAPI backend to await the Bearer Token from it, assuming all checks (JWT, PCKE) are passed. Thus, storing the one-time code_challenge in the state JWT is rather redundant and does not seem to be an issue to me. But please correct if I have a flawed understanding of the process. Having an independent state value is a good idea - it does not really matter whether a faulty request is stopped by an invalid JWT or a missing state ID in the server DB as long as it has enough entropy. One would just have to adapt the associate handler where the UserID is stored in the JWT.
• [general considerations] I know, my approach is a bit over the top, but I was trying to see, how far I can go and which features are readily adoptable. OAuth.Net, referring to the PKCE RFC7636, recommends using PKCE even in deployments when a client_secret and/or private_key_jwt is used.

Have a great weekend!