asgi-auth-github

ASGI middleware that authenticates users against GitHub.

(Originally part of datasette-auth-github, now split off as a separate project.)

Setup instructions

• Install the package - pip install asgi-auth-github
• Create a GitHub OAuth app: https://github.com/settings/applications/new
• Set the Authorization callback URL to http://127.0.0.1:8001/-/auth-callback

Adding this to your ASGI application

from asgi_auth_github import GitHubAuth
from your_asgi_app import asgi_app


app = GitHubAuth(
    asgi_app,
    client_id="github_client_id",
    client_secret="github_client_secret",
    require_auth=True,
    # Other options:
    # cookie_ttl=24 * 60 * 60,
    # disable_auto_login=True,
    # allow_users=["simonw"],
    # allow_orgs=["my-org"],
    # allow_teams=["my-org/engineering"],
)

See the datasette-auth-github 0.12 documentation for documentation of the other parameters.

Once wrapped in this way, your application will redirect users to GitHub to authenticate if they are not yet signed in. Authentication is recorded using a signed cookie.

The middleware adds a new "auth" key to the scope containing details of the signed-in user, which is then passed to your application. The contents of the scope["auth"] key will look like this:

{
    "id": "1234 (their GitHub user ID)",
    "name": "Their Display Name",
    "username": "their-github-username",
    "email": "their-github@email-address.com",
    "ts": 1562602415
}

The "ts" value is an integer time.time() timestamp representing when the user last signed in.

If the user is not signed in (and you are not using required authentication) the "auth" scope key will be set to None.

Example using Starlette

Here's an example using the Starlette ASGI framework. You'll need to add your client_id and client_secret to this code before running it.

Save the following as starlette_demo.py:

from asgi_auth_github import GitHubAuth
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
import uvicorn

app = Starlette(debug=True)


async def homepage(request):
    return JSONResponse({"auth": request.scope["auth"]})


app = Starlette(debug=True, routes=[Route("/", homepage),])


authenticated_app = GitHubAuth(
    app,
    client_id="...",
    client_secret="...",
    require_auth=True,
)

if __name__ == "__main__":
    uvicorn.run(authenticated_app, host="0.0.0.0", port=8001)

Install the dependencies like this:

pip install uvicorn starlette asgi-auth-github

Then run it with:

python starlette_demo.py