Add authentication addon?

[agjohnson]

This is just a thought, I don't yet have a firm idea of what this looks like. I was considering which direction we should go for in-doc authentication on the new dashboard and realized that maybe authentication fits well here.

The issue we have now, and will hit again on the new dashboard, is that the reader authentication page is straight from our application -- it has our header, top navigation, etc. This is even more true on the new dashboard, as the login page is intended to be the first view logged out users see. One direction we can go here is to remove all of this and provide more of a blank page for login when logging in through documentation. I'd say this is an okay, but not great, approach.

Another direction would be to trigger a popup/modal from addons to attempt login. There are almost certainly some hurdles to work through here, but at least the UI side of things would be straight forward. So far, I see the following benefits:

• Authentication UI is native to docs, instead of feeling like an application page
• Authentication UI could be author customizable through configuration (colors, providers?, etc)
• We've also wanted to include more information on the user in the flyout already, there is overlap in implementation here most likely

[agjohnson]

cc @humitos what would you think of this approach? Could this potentially replace our application login for documentation readers?

[humitos]

I don't want to reply too quickly here -- the idea looks pretty neat, but this seems complex/complicated to me at first sight. There are few points that came to my mind immediately I read this issue:

1. addons work only on documentation pages, which mean to get access to it on a private page, you have to be logged in already --so, I don't think there is too much we can do there
2. in case the documentation is public, the user may want to log in (from inside the documentation page, using an addon as you are describing) to get access (and list them in the flyout, for example) to the private versions of the project ¹

Given these two cases, what is the one you were thinking about?

IMO, it seems that "accessing a private documentation page without being logged" (case 1) implemented as an addons won't add too much over implementing it as a regular Django application page; and will be a lot harder to do.

On the other hand, "logging in from a documentation page to get access to private versions" (case 2) seems interesting at first sight to me, but complex and won't share the same UI which may be confusing in the end.

I'm not convinced this is a good direction to take, at least without thinking more about it and understanding better how all the pieces work together for these cases (and others that I haven't contemplated here).

Footnotes

1. also, will we expose a "Login" button/link to 99% of users that will never click on it since only the 1% of the readers are "member of the organization"? It seems we will be complicating the UI to everybody only for a pretty small group of users. ↩

[agjohnson]

Yeah, I had some same initial thoughts too, and there are a lot of unanswered questions here for me.

But to narrow focus: I am describing an authentication pattern for any user, including/mainly for users of fully-private documentation.

I am using the term addon a bit liberally here too. When I say this could be an addon, I'm considering even 403 responses from our end as potential injection points for addons, not just 200 responses. What I think I'm wanting to lean more into is application views for our product and using addons for additions to user documentation.

Addons could be the wrong framing here too though. This sort of feature could also be implemented as a custom 403 page support, along with an unbranded, nicer default page for authentication and sharing tokens. I can also say the same about our 404 page, it shouldn't look like our website/application.

IMO, it seems that "accessing a private documentation page without being logged" (case 1) implemented as an addons won't add too much over implementing it as a regular Django application page

The benefit I'm describing to a standalone UI is that a standalone UI would not be branded as our application. We are combining our authentication pages more recently, so the distinction between our authentication and documentation authentication is getting less clear. For reader users that do not interact with Read the Docs (organizations with customers, Google SSO organizations, etc), this will be a confusing UI to see:

I'm also not convinced that addons is the best place for this yet. But I do also really like the pattern of implementing our hosting features and feature configuration through addons. I am sure we would have plenty of concerns about how to do cross domain login forms, etc too though.

So, I agree this is something to not write off yet, and would like to continue thinking more on this. Or, at least thinking more on the underlying problem of branded authentication pages -- whether or not this is the approach that solves this.

[humitos]

This sort of feature could also be implemented as a custom 403 page support, along with an unbranded, nicer default page for authentication and sharing tokens. I can also say the same about our 404 page, it shouldn't look like our website/application.

Can't we just provide a way for customers to output a 403.html page and serve that HTML for them? (in a similar way as we do for custom 404.html)

So, I agree this is something to not write off yet, and would like to continue thinking more on this

He, yeah, I'm still not sure to understand what's the goal here 😅 . It seems related to https://github.com/readthedocs/readthedocs-corporate/issues/1360 and https://github.com/readthedocs/readthedocs-corporate/issues/1561 but as some sort of addons implementation. I'm confused 🙃

I think my main problem here is that I'm not fully understanding what problem we want to solve; and I think that "for some unclear interpretation of what you are saying" I think that a custom 403.html page looks like a great solution, but 🤷🏼

[agjohnson]

I'm not entirely sure about a custom 403 page, as it feels like there is a lot to the authentication forms that would really make it very difficult for users to maintain. Just considering all of the various auth patterns, errors, etc we need to support with a page like that, it feels like too much responsibility to give to users.

The most basic version of this is that we should have an unbranded login view, something that does not look like its part of the application. This doesn't need to be customizable in any way.

But if we are aiming for customization, I think the patterns for customization in addons are stronger than the user outputting a custom 403 page. An auth addon would give us control of HTML, JS, and CSS in a shadow DOM, instead of hoping everything we need is included in a user supplied customization.

I think this would take some experimentation to prove or disprove, it's not clear if either pattern would work well yet.