I’m creating this thread to keep track of and stay focused on my GSoC 2026 project, “Integrate O3 with the Authentication module”.
First, I’d like to share the project proposal that was selected by my mentors. In the proposal, I have also attached a YouTube video, and to make it easier for everyone, I’ll share the YouTube link here as well.
I hope all of you will take a look at them first and share your thoughts here. Your feedback and suggestions are very valuable to me.
Proposal:
Youtube video :
Now let me dive into my main purpose of this thread.
I will raise questions here regarding my project so everyone can share their ideas and suggestions.
I will share my weekly updates in here (with weekly blog posts)
I will share my doubts and the areas where I get stuck, so anyone can help me and provide suggestions to improve my work.
Through this thread, my work and progress will be tracked publicly. In the future, this can also help newcomers and other developers who may work on similar areas.
Finally, Thank you so much to my mentors @jayasanka and @janithrs for selecting me as your mentee and for trusting my work. I will definitely do my best to successfully complete this project and make you both feel that you made the right choice.
Following up on my GSoC mentor call with @jayasanka and @janithrs , I wanted to bring this discussion to the talk thread so the wider community can weigh in and we can land on the right approach.
The question is: **How should the backend communicate a TOTP challenge?
**
We discussed two possible approaches during the call.
302 redirect with a Location header and a structured body
This pattern already exists in HERE. The idea would be to return a 302 with both a Location header pointing to the challenge page and a structured JSON body that describes the type of challenge required.
401 response with a structured JSON body through the Session API
The second approach works through the existing /ws/rest/v1/session endpoint in SessionController1_9 (HERE). Instead of a redirect, the backend returns a 401 Unauthorized with a JSON body that explicitly communicates that MFA is required and what type of challenge the client should expect.
302s won’t work in the SPA frontend. This is because the Fetch API simply resolves and does not surface 302s to the client, so there’s no way to change the “page” as a result of this. Consequently, the backend needs to communicate a second-factor challenge (and we shouldn’t only be thinking about this in terms of TOTP, but in terms of any second factor the authentication module supports) via basically any status code that is not in the 3xx range.
The user-flow should be configurable and driven by the authentication module setup (see the authentication module docs).
As I’ve mentioned during the call, I’d lean toward the 401 with a structured JSON body via the Session API. That approach treats MFA as an explicit authentication state transition rather than a navigation redirect, which separates the backend’s responsibility (saying “credentials valid, MFA required”) from the frontend’s responsibility (deciding which screen to show).
By the way, I brought this up on today’s platform call. Here’s the TL;DR on the matter.
Communicating this via the session endpoint body would require altering the session JSON body by introducing one or more properties, which means the endpoint would have two shapes: one for 2FA and one for when the user is logged in.
So using a 401 with a Location header is the closest we can get to the standard.
The client should be smart enough to follow the Location header on a 401 if it’s coming from the /session endpoint.
I also listened to the platform call recording and I’ll be going through it again to make sure I fully absorb everything that was discussed. I want to make sure my implementation reflects the right thinking from the ground up.
My next step is to move forward with the 401 + Location header approach in and make sure the O3 client handles it correctly on the frontend side.
