Authentication

HTTP Basic auth

Configuration

The HTTP authentication standard includes HTTP Basic authentication, which, as the name implies, is just a basic method that accepts a username and password. As the MDN documentation recommends, HTTP Basic auth should always be used with TLS.

inboard provides utilities for configuring HTTP Basic auth.

For Starlette applications, inboard provides middleware for HTTP Basic auth. Starlette middleware are applied to every request.

Example of HTTP Basic auth with Starlette middleware

from inboard import StarletteBasicAuth
from starlette.applications import Starlette
from starlette.middleware.authentication import AuthenticationMiddleware

app = Starlette()
app.add_middleware(AuthenticationMiddleware, backend=StarletteBasicAuth())

FastAPI is built on Starlette, so a FastAPI app can be configured with middleware as above, substituting FastAPI() for Starlette(). inboard also provides a FastAPI dependency, which can be applied to specific API endpoints or APIRouter objects.

Example of HTTP Basic auth with a FastAPI dependency

from typing import Annotated, Optional

from fastapi import Depends, FastAPI, status
from pydantic import BaseModel

from inboard import fastapi_basic_auth


class GetHealth(BaseModel):
    application: str
    status: str
    message: Optional[str]


BasicAuth = Annotated[str, Depends(fastapi_basic_auth)]
app = FastAPI(title="Example FastAPI app")


@app.get("/health", status_code=status.HTTP_200_OK)
async def get_health(auth: BasicAuth) -> GetHealth:
    return GetHealth(application=app.title, status="active")

Usage

As described in the environment variable reference and contribution guide, when starting the inboard server, the environment variables BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD can be set. The values of these variables can then be passed in with client requests to authenticate.

Server:

docker pull ghcr.io/br3ndonland/inboard
docker run -d -p 80:80 \
  -e "BASIC_AUTH_USERNAME=test_user" \
  -e "BASIC_AUTH_PASSWORD=r4ndom_bUt_memorable" \
  ghcr.io/br3ndonland/inboard

Client (using HTTPie):

http :80/health -a "test_user":"r4ndom_bUt_memorable"

HTTP clients, such as Hoppscotch (formerly known as Postwoman), HTTPie, Insomnia, and Postman provide support for HTTP Basic auth.

HTTP Basic auth can also be useful for load balancer health checks in deployed applications. In AWS, load balancer health checks don't have HTTP Basic auth capabilities, so it is common to configure authentication bypasses for these checks. However, health checks can also be configured to expect a response of 401 instead of 200 for endpoints requiring authentication. Successful health checks therefore provide two pieces of information: the endpoint is up, and authentication is working. Conversely, if the health check endpoint returns 200, this is an indication that basic auth is no longer working, and the service will be taken down immediately.

Further info

For more details on how HTTP Basic auth was implemented, see br3ndonland/inboard#32.

For more advanced security, consider OAuth2 with JSON Web Tokens (JWT), as described in the FastAPI docs.