Protect API docs behind authentication?

[ghost]

Basic Question

Does FastAPI provide a method for implementing authentication middleware or similar on the docs themselves (e.g. to protect access to /docs and /redoc)?

Additional context

My company is currently relying on a needlessly-complex Django backend, whose main purpose is serving an API via the Django REST framework. However, it feels like half the bugs the frontend app folks are running into are caused by a disconnect between what the Django app is doing and the API documentation wiki (which is maintained by hand; it's a monster).

FastAPI thus looks like a perfect alternative. However, it's a requirement for us that the API documentation only be accessible to specific authenticated users. It looks like I could easily disable the docs when run in a production environment (as opposed to a local testing environment), but if it's possible to serve the docs on production but explicitly protect them that would be ideal (the API in part facilitates interaction between frontend apps and IOT devices, so the interactive portions of the docs would be a lot easier to use and maintain on specific hosted servers; setting up working local environments is complicated).

In my ideal world, I'd love to also auto-populate the initial authentication credentials for the interactive queries with the current user's authentication token (to allow no-configuration usage of them immediately upon access). I wasn't able to find anything in the FastAPI docs about meddling with the way the documentation is handled, but if I missed it I'd love a link!

[euri10]

You can look in the docs, there's a list of articles, one of them by niels does that, will edit if you can't find it Le mer. 3 juil. 2019 à 8:18 AM, ianbeck <[email protected]> a écrit :

…

*Basic Question* Does FastAPI provide a method for implementing authentication middleware or similar on the docs themselves (e.g. to protect access to /docs and /redoc)? *Additional context* My company is currently relying on a needlessly-complex Django backend, whose main purpose is serving an API via the Django REST framework. However, it feels like half the bugs the frontend app folks are running into are caused by a disconnect between what the Django app is doing and the API documentation wiki (which is maintained by hand; it's a monster). FastAPI thus looks like a perfect alternative. However, it's a requirement for us that the API documentation only be accessible to specific authenticated users. It looks like I could easily disable the docs when run in a production environment (as opposed to a local testing environment), but if it's possible to serve the docs on production but explicitly protect them that would be ideal (the API in part facilitates interaction between frontend apps and IOT devices, so the interactive portions of the docs would be a lot easier to use and maintain on specific hosted servers; setting up working local environments is complicated). In my ideal world, I'd love to also auto-populate the initial authentication credentials for the interactive queries with the current user's authentication token (to allow no-configuration usage of them immediately upon access). I wasn't able to find anything in the FastAPI docs about meddling with the way the documentation is handled, but if I missed it I'd love a link! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#364>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAINSPS7OVVHVUODRHMOAPTP5RABXANCNFSM4H5CISYQ> .

[euri10]

https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3

[ghost]

Thank you, that was exactly what I was looking for!

[tiangolo]

Thanks @euri10 for your help here! 🍰 🚀

Thanks @ianbeck for reporting back and closing the issue. 🎉

[ericcgu]

Put Traefik in front of it.

[imjohsep]

Medium put the article behind a paywall. Is there another source for that information?

[bastianh]

The solution discussed in the article is to disabled the automatic generated endpoints and create your own with authentication

[smentek]

https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3

I do not think it is good policy to give links to sources where you have to pay?! :(

[ericcgu]

use traefik forward auth

…

On Thu, Feb 18, 2021 at 3:57 AM Paweł Graczyk ***@***.***> wrote: https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3 I do not think it is good policy to for giving link to sources where you have to pay?! :( — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#364 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABFW7DYVVTLTX2UV7GXY4IDS7TI7VANCNFSM4H5CISYQ> .

[dxm1337]

I struggled for several hours, but I still couldn't get the hang of Forward Auth in Traefik. It either completely disables the whole site or lets everything through for unauthorized users. Apparently, I don't know how to cook it properly.

My settings were approximately like this:

- traefik.http.middlewares.auth-docs.forwardauth.address=http://back:80/api/v1/users/me
- traefik.http.middlewares.auth-docs.forwardauth.authResponseHeaders=X-Forwarded-User
- traefik.http.middlewares.auth-docs.forwardauth.trustForwardHeader=true

- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.middlewares=auth-docs

[EasonC13]

Hi there, I just find an easy solution to this question.

You can simply disable default /docs and create docs behind authentication

Example code:

from fastapi import FastAPI

from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.openapi.utils import get_openapi

import secrets

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

app = FastAPI(docs_url=None, redoc_url=None, openapi_url = None)

security = HTTPBasic()


def get_current_username(credentials: HTTPBasicCredentials = Depends(security)):
    correct_username = secrets.compare_digest(credentials.username, "user")
    correct_password = secrets.compare_digest(credentials.password, "password")
    if not (correct_username and correct_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect email or password",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username


@app.get("/docs")
async def get_documentation(username: str = Depends(get_current_username)):
    return get_swagger_ui_html(openapi_url="/openapi.json", title="docs")


@app.get("/openapi.json")
async def openapi(username: str = Depends(get_current_username)):
    return get_openapi(title = "FastAPI", version="0.1.0", routes=app.routes)

[MuslemRahimi]

thank you so much

[kennylajara]

Pro tips

Using ReDoc
If you prefer ReDoc, you can use it just replacing get_swagger_ui_html by get_redoc_html... Or you can use both...

Hiding those endpoints
You are adding 2 new endpoints to your API and, almost for sure, it won't be very useful to show them in your documentation. You can hide them by including the parameter include_in_schema=False to the @app.get( ... ) decorators.

A small improvement for code mantainance
It might be a bit better to define the title and version in the inside of app = FastAPI( ... ) and use:

return get_openapi(title=app.title, version=app.version, routes=app.routes)

instead of

return get_openapi(title = "FastAPI", version="0.1.0", routes=app.routes)

This way, every-time you change the version (or if you need to change the title in the future), you can do it where you would normally do it and you won't have to remember where is that defined. Save time for the future you.

Final code
After does changes, this would be the final code:

from fastapi import FastAPI

from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
from fastapi.openapi.utils import get_openapi

import secrets

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

app = FastAPI(
    title="FastAPI",
    version="0.1.0",
    docs_url=None,
    redoc_url=None,
    openapi_url = None,
)

security = HTTPBasic()


def get_current_username(credentials: HTTPBasicCredentials = Depends(security)):
    correct_username = secrets.compare_digest(credentials.username, "user")
    correct_password = secrets.compare_digest(credentials.password, "password")
    if not (correct_username and correct_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect email or password",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username


@app.get("/docs", include_in_schema=False)
async def get_swagger_documentation(username: str = Depends(get_current_username)):
    return get_swagger_ui_html(openapi_url="/openapi.json", title="docs")


@app.get("/redoc", include_in_schema=False)
async def get_redoc_documentation(username: str = Depends(get_current_username)):
    return get_redoc_html(openapi_url="/openapi.json", title="docs")


@app.get("/openapi.json", include_in_schema=False)
async def openapi(username: str = Depends(get_current_username)):
    return get_openapi(title=app.title, version=app.version, routes=app.routes

Final words: Just remember this is an example and you still need to connect this small authentication code to your real login system or, at least, use environment variables. If you are protecting your API documentation, just don't hard code your credentials...

[qaixerabbas]

I was looking for this. Nice information Thank you @kennylajara

[lsmith77]

Any hint if I want to only require basic auth for prod but not for development?

[ghost]

Hi there, I just find an easy solution to this question.

You can simply disable default /docs and create docs behind authentication

This did not work for me. The doc page still opens up. And I can still test out the endpoints. I do see an Authorize button on the right now. Not sure if that was the intended outcome.
How can I add a username and password prompt when trying to open the docs page?

[StanlyLife]

Medium put the article behind a paywall. Is there another source for that information?

Just delete your cookies & local storage or use incognito

[bedirhansahin]

Hi there, how can I do this for versioned documentation. I am using fastapi-versioning

[whchi]

For anyone who wants to enable HTTP basic authentication modal, here is a workaround:

Assuming the environment is set to 'prod', follow these steps:

1. Make sure your openapi_url, redoc_url, and docs_url are set to None when app_env == 'prod'.
2. Create a middleware using the following Python code:

import base64
import secrets

from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.requests import Request
from starlette.responses import Response


class ApidocBasicAuthMiddleware(BaseHTTPMiddleware):

    async def dispatch(  # type: ignore
            self, request: Request, call_next: RequestResponseEndpoint):
        if request.url.path in ['/docs', '/redoc', '/openapi.json']:
            auth_header = request.headers.get('Authorization')
            if auth_header:
                try:
                    scheme, credentials = auth_header.split()
                    if scheme.lower() == 'basic':
                        decoded = base64.b64decode(credentials).decode('ascii')
                        username, password = decoded.split(':')
                        correct_username = secrets.compare_digest(
                            username, 'your-username')
                        correct_password = secrets.compare_digest(
                            password, 'your-password')
                        if correct_username and correct_password:
                            return await call_next(request)
                except:
                    pass
            response = Response(content='Unauthorized', status_code=401)
            response.headers['WWW-Authenticate'] = 'Basic'
            return response
        return await call_next(request)

3. register /docs, /redoc and /openapi.json to render html and data, as mentioned before
4. add middle to your app when app_env == 'prod'

app = FastAPI()
if app_env == 'production':
    @app.get(
        '/docs',
        tags=['documentation'],
        include_in_schema=False,
    )
    async def get_swagger_documentation() -> HTMLResponse:
        return get_swagger_ui_html(openapi_url='/openapi.json', title='docs')

    @app.get(
        '/openapi.json',
        tags=['documentation'],
        include_in_schema=False,
    )
    async def openapi() -> Dict[str, Any]:
        return get_openapi(title='FastAPI', version='0.1.0', routes=app.routes)

  @app.get(
        '/redoc',
        tags=['documentation'],
        include_in_schema=False,
    )
    async def get_redoc() -> Dict[str, Any]:
        return get_redoc_html(openapi_url="/openapi.json", title="docs")


    app.add_middleware(ApidocBasicAuthMiddleware)

then the authentication modal shows up correctly

[mroedder-d7]

Any hints if it might be possible to use something simple like Basic Auth for protecting the /docs as first stage and then have the endpoints protected via a JWT token? Preferably it should be possible to use the nice OAuth2/OpenID mechanisms within Swagger to create and refresh the token.

[Wildhammer]

[hasansezertasan]

What do you mean by playground pages?

[Wildhammer]

Ignore, I should post the question elsewhere