Authentication for private pages

[arrowak]

🚀 Feature

Add the authentication layer to support hosting the private pages in the same documentation site.

A simple example:

• Let's say we have an "API integration guide" which is generic and open to anyone who wants to integrate it.

• Let's say we have some premium partners for whom we have some custom APIs documented with some confidential parameters and values (on and above public ones), which are not to be exposed to the world.

We would want to enable auth for these premium partners for such pages.

I guess this would make a very reasonable addition to the product

Have you read the Contributing Guidelines on issues?

YES

Motivation

We have stumbled upon a request from one of our premium partners that, in addition to the public API documentation we are having, they want us to enable authentication based documentation which encapsulates custom APIs and Parameters implemented exclusively for them. Also, this is seemingly becoming a common ask among such premium partners.

Also, I don't think this is an uncommon request. Many people/organisations might just fly-by and not report this feature request and move on to something else to fulfil their requirements.

Pitch

This feature will enable a secure access to some private documents while still using all the goodness of the Docusaurus system. Basically, the private documentation should not become a reason for people to look for alternatives and eventually end up using a much complicated, paid service/product.

Supporting feedback from one of the users - https://v2.docusaurus.io/feedback/p/could-we-add-an-authentication

[lex111]

Docusaurus is a static site generator, it is not a server, so we cannot control access to pages. What you want, I think, can be done through a reverse proxy, for example, https://github.com/bitly/oauth2_proxy

[arrowak]

It appears that https://github.com/bitly/oauth2_proxy repo is not maintained anymore. It has also been marked read-only by its owner.

I am not sure if I want to use it for production purposes.

[lex111]

See other projects, there are links in that repo. Moreover if that project is no longer maintained, this does not mean that this is not a working solution.

In any case, that was only the first example I know, you can find other options. I mean, this issue still doesn't apply to Docusuarus directly.

[arrowak]

See other projects, there are links in that repo. Moreover if that project is no longer maintained, this does not mean that this is not a working solution.

In any case, that was only the first example I know, you can find other options. I mean, this issue still doesn't apply to Docusuarus directly.

Whoops! Boy, did I miss that notice. Thanks again. I understand the static only nature of Docusaurus. May be we should let it be what it is.

Closing the ticket on that note.

[ashemez]

You can make authentication work in a stateless manner like the APIs do. You can either use a 3rd party authenticator or use your own API authentication and do a stateless authentication. Docusaurus can be static but in the end every site is generating a static content. If your static site shows some data from API or backend you can authenticate yourself. But yes, not concern of Docusaurus.

[LexxLuey]

You can make authentication work in a stateless manner like the APIs do. You can either use a 3rd party authenticator or use your own API authentication and do a stateless authentication. Docusaurus can be static but in the end every site is generating a static content. If your static site shows some data from API or backend you can authenticate yourself. But yes, not concern of Docusaurus.

I was thinking along the same lines and even have User Management System API built with Flask. It handles all the work of authentication. But now I wonder,

1. How do I make the request from docusaurus to my API?
2. Suppose I make this request and store the response data in my client via cookies or something, how do I use this data in my docusaurus app? Specifically, hide certain pages if the user does not have the required credentials or authorization to view the page?

[ashemez]

Yes you can do anything authorized and authenticated using this way. If you are able to provide a hash to the user like JWT or any other authentication service token, since you can store in the cookie as you mentioned, you can store some basic user attributes like roles etc in the cookies and according to the user role you can show or hide content in docusaurus. And let's say user wanted to change in their cookie and revealed some menu items like another user role's menu item or page style. When they submit the altered cookie or user auth token to your API you still won't authorize to show the data they try to hack. Once you can authorize every request at the backend side you will never reveal sensitive data.

Let's revisit how you can customize the content according to the user role. Let's assume you get the user role from the cookie as it is taken from the token or your auth api and you know the current user is Role-A user. Show role-a pages, menu items to the user that is all. You can show different docusaurus top menu items using this method. If you don't want a user view a specific page even if they alter the cookie, just authorize the page at the begining using your Auth API and get the authorized or unauthorized response and show a message or redirect. That is all.

[ashemez]

If you are asking how to send API requests from docusaurus, I suggest you to use axios module in docusaurus and use accordingly.

[LexxLuey]

Yes you can do anything authorized and authenticated using this way. If you are able to provide a hash to the user like JWT or any other authentication service token, since you can store in the cookie as you mentioned, you can store some basic user attributes like roles etc in the cookies and according to the user role you can show or hide content in docusaurus. And let's say user wanted to change in their cookie and revealed some menu items like another user role's menu item or page style. When they submit the altered cookie or user auth token to your API you still won't authorize to show the data they try to hack. Once you can authorize every request at the backend side you will never reveal sensitive data.

Let's revisit how you can customize the content according to the user role. Let's assume you get the user role from the cookie as it is taken from the token or your auth api and you know the current user is Role-A user. Show role-a pages, menu items to the user that is all. You can show different docusaurus top menu items using this method. If you don't want a user view a specific page even if they alter the cookie, just authorize the page at the begining using your Auth API and get the authorized or unauthorized response and show a message or redirect. That is all.

Thank you for such a succinct high level overview. So now here lies the crunch point: specifics.

1. In which page/file do I add the login button that makes the request to my UMS API?
2. In which page/file can I manipulate the pages to be shown on the sidebar based on my user details?

Thank you for any light you shed.

[slorber]

Not 100% sure I agree with everything here.

Docusaurus builds a static site. IE the content is exactly the same for all users.

If you want different content displayed for different user roles, you have to:

• make that content dynamic for each user: ie render it only on the client side by swizzling React components and fetching your dynamic data yourself, like in any React app)
• build one different static site per user role, each containing a different set of visible pages. You can use serverless edge functions (Cloudflare Workers for example) to serve one static deployment or another based on the role of the user and pages they can access.

Remember all these are concerns that are outside the scope of Docusaurus. In the end, we just build a static React site.

[ashemez]

@LexxLuey well, in any page you can make the http (API) requests. If a page is supposed to be authorized by the API you should call your api from that page (Reactjs pages not markdown pages I am saying).
I was able to do this myself actually. I implemented a JWT authentication in the API side, created some pages for different roles. When a user is not logged you can identify it, when a user is logged in you can identify it too.
Finally, the site is static that's right but you don't have to show every content you have for instance if they are provided by API (in a DB for example). Ajax calls are used for this and you static side can pick data by utilizing fully authorized APIs.

[LexxLuey]

Not 100% sure I agree with everything here.

Docusaurus builds a static site. IE the content is exactly the same for all users.

If you want different content displayed for different user roles, you have to:

* make that content dynamic for each user: ie render it only on the client side by swizzling React components and fetching your dynamic data yourself, like in any React app)

* build one different static site per user role, each containing a different set of visible pages. You can use serverless edge functions (Cloudflare Workers for example) to serve one static deployment or another based on the role of the user and pages they can access.

Remember all these are concerns that are outside the scope of Docusaurus. In the end, we just build a static React site.

I understand this is a static site generator. no doubt. i am only asking if it is possible. If it is not, then that's okay. I felt it was possible to limit what pages are displayed.

[vsk-abi]

I am trying to add Keycloak identity provider to my docusaurus website through plugin configuration. can anyone suggest which package to use to create plugin?

[godmar]

As a side note: what does not work is to add http basic authentication to subdirectories of what Docusaurus builds.
That is because it doesn't behave like a true static app, it actually behaves like a single page app.

For instance, if you add HTTP authentication to /membersonly, then only direct invocations of that path will hit the authentication, but it will not be hit upon navigation via a link from elsewhere in the site.

So it appears that protecting part of a site (as in one or more subdirectories) is fundamentally not possible with how Docusaurus is currently designed, is that correct?

[slorber]

@godmar the problem is that you don't only want to protect the html static pages, but also protect the JS code that permits to generate those pages dynamically on the client. That JS is code-split into the /assets/js folder and unfortunately it is not easy to do.

If you want to have a /membersonly/ section on your site, my recommendation would be to not use static pages for this part of your site but instead create a plugin with a dynamic route path like /membersonly/*, let it render an empty /membersonly/index.html static page shell, and then use React-Router in your <MembersOnly> route component to decide what to render using regular React code, eventually fetching protected API data or displaying a login screen. What I mean is: you can use Docusaurus in the same way as you would use Create-React-App, for a subset of your site.

Regarding dynamic client-side routes, one example to take inspiration from is our feature request page. The data you see on this page is not static, it is only loaded later, after the initial React hydration:

https://docusaurus.io/feature-requests/p/comments-in-documents-or-blogs

Plugin code: https://github.com/facebook/docusaurus/tree/main/website/src/plugins/featureRequests

[wade-liwei]

@slorber

do you have document about how to use the [featureRequests] plugin? (https://github.com/facebook/docusaurus/tree/main/website/src/plugins/featureRequests)

[slorber]

The feature request plugin is not an officially distributed plugin. I mentioned it above only as an open-source example so that you can take a look at its code.

[levino]

Since I recently succeeded in protecting (the whole) docusaurus deployment for private documentation sites with user login, I thought I would share my example. It is using docusaurus, PocketBase for user management and auth and vercel for (more or less static) deployment. I might also add a blog post about it soonish.

One could then have private.docs.example.com for private docs and docs.example.com for public docs.