Supply an Option for an Authentication Backend

[ghost]

tl;dr: Please offer authentication back ends to the usual providers of OAuth2 services

Unfinished Business?

https://app.gitbook.com/o/<org id>/c/<collection id>/~/share/audience shows an option for an Authentication backend. Right now the only option in the select is Custom. This means an organization that wishes to only share documents with an authenticated user must:

1. create a completely separate "authenticator" that handles both authentication with a service (like OpenID, Azure, whatever)
2. assure the authenticator has enough gumption to create a JSON Web Token, and keep it updated
3. handle lots of routing

You'll end up with a plate with a little spaghetti on it, that is a bit more complicated than the example.

flowchart LR
    subgraph authflow[Authentication Flow]
        subgraph user[me-at-foobar.com]
            BROWSER[User's Browser]
        end

        subgraph gitbook[Hosted on Gitbook.com]
            COLLECTION[collection url]
        end

        subgraph azure
            AUTH[App Registration,<br>i.e. <q>OAuth2 service</q>]
            subgraph resource_group[Resource Group]
                WEB_APP[Web App,<br>i.e. <q>the container</q>]
                REDIS[Azure Cache for Redis]
            end
        end
    end

    BROWSER -->|1. I want to see a<br>collection page| COLLECTION
    COLLECTION -->|2. JWT required!<br>redirect to Web App| BROWSER
    BROWSER -->|3. May I have<br>a JWT?| WEB_APP
    WEB_APP -->|4. Can I give<br>this browser<br>a JWT?| AUTH
    AUTH -->|5. Who are you| BROWSER
    BROWSER -->|6. me-at-foobar.com| AUTH
    AUTH -->|7. I hereby approve of me-at-foobar.com| WEB_APP
    WEB_APP -->|8. I made a JWT with<br>the key supplied by<br>gitbook.com,<br>store it.| REDIS
    REDIS -->|9. Okay, JWT stored.<br>Returning it to you.| WEB_APP
    WEB_APP -->|10. me-at-foobar.com,<br>here is your url with a<br>JWT added| BROWSER
    BROWSER -->|11. I have a JWT<br>added to my url!| COLLECTION
    COLLECTION -->|12. I approve of your JWT,<br>here's your page.| BROWSER

classDef authflowsubgraph fill:white, color black;
classDef azuresubgraph fill:azure, color:black;
classDef usersubgraph fill: white, color: black;
classDef browser fill:black,color:white;
classDef gitbooksubgraph fill: #90b0ff, color:black;
classDef standard fill: white, color:black;

class resource_group resourcegroupsubgraph;
class azure azuresubgraph;
class user usersubgraph;
class BROWSER browser;
class gitbook gitbooksubgraph;
class authflow standard;
class COLLECTION standard;
class WEB_APP standard;
class REDIS standard;
class AUTH standard;

Loading

We were surprised that we ended up having to go outside gitbook to authenticate our user base and fiddle with JWT. We ended up having to deploy it on/from azure, and otherwise lose half the gains in essential laziness achieved when we moved off of our internal markdown-based documentation system to gitbook.

This was very nearly a show-stopper for our adoption of gitbook.

The Unhelpful Lecture

Our particular authenticator was written in Python/Flask in a few hours. A "real" service using libraries that support multiple authorization services and branding (authlib and a judicious use of flask blueprints, respectively) would not take much longer to create. A "really real" service that can modularly support authentication sources with lots of tests and all the usual goodies might be knocked out in FastAPI in a few weeks. The language and platform are not important. What is important is that a client-facing configuration not much more complicated than what you have now could be finished and perhaps gain you some larger customers that have a less relaxed view of maintaining custom code just to safely distribute their own documentation. Love the product! Just wish we didn't have to write our own "Authentication backend".

[ghost]

I did look into the visitor authentication suggestion in your docs, and took a look at the example code. Writing the code is not the problem, it's maintaining the code, and futzing about with all the rest that we want to pay you for!