datasette-auth-github 0.13a2

Datasette plugin and ASGI middleware that authenticates users against GitHub

datasette-auth-github

Datasette plugin that authenticates users against GitHub.

The new 0.13a1 alpha release requires Datasette 0.51 or later.

Setup instructions

• Install the plugin - pip install datasette-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/-/github-auth-callback
• Create a metadata.json file with the following structure:

{
    "title": "datasette-auth-github demo",
    "plugins": {
        "datasette-auth-github": {
            "client_id": {"$env": "GITHUB_CLIENT_ID"},
            "client_secret": {"$env": "GITHUB_CLIENT_SECRET"}
        }
    }
}

Now you can start Datasette like this, passing in the secrets as environment variables:

$ GITHUB_CLIENT_ID=XXX GITHUB_CLIENT_SECRET=YYY datasette \
    fixtures.db -m metadata.json

Note that hard-coding secrets in metadata.json is a bad idea as they will be visible to anyone who can navigate to /-/metadata. Instead, we use a new mechanism for adding secret plugin configuration options.

By default anonymous users will still be able to interact with Datasette. If you wish all users to have to sign in with a GitHub account first, add this to your metadata.json:

{
    "allow": {
        "id": "*"
    },
    "plugins": {
        "datasette-auth-github": {
            "...": "..."
        }
    }
}

The authenticated actor

Visit /-/actor when signed in to see the shape of the authenticated actor. It should look something like this:

{
    "actor": {
        "display": "simonw",
        "gh_id": "9599",
        "gh_name": "Simon Willison",
        "gh_login": "simonw",
        "gh_email": "...",
        "gh_orgs": [
            "dogsheep",
            "datasette-project"
        ],
        "gh_teams": [
            "dogsheep/test"
        ]
    }
}

The gh_orgs and gh_teams properties will only be present if you used load_teams or load_orgs, documented below.

Restricting access to specific users

You can use Datasette's permissions mechanism to specify which user or users are allowed to access your instance. Here's how to restrict access to just GitHub user simonw:

{
    "allow": {
        "gh_login": "simonw"
    },
    "plugins": {
        "datasette-auth-github": {
            "...": "..."
        }
    }
}

This "allow" block can be positioned at the database, table or query level instead: see Configuring permissions in metadata.json for details.

Restricting access to specific GitHub organizations or teams

You can also restrict access to users who are members of a specific GitHub organization.

You'll need to configure the plugin to check if the user is a member of that organization when they first sign in. You can do that using the "load_orgs" plugin configuration option.

Then you can use "allow": {"gh_orgs": [...]} to specify which organizations are allowed access.

{
    "plugins": {
        "datasette-auth-github": {
            "...": "...",
            "load_orgs": ["your-organization"]
        }
    },
    "allow": {
        "gh_orgs": "your-organization"
    }
}

If your organization is arranged into teams you can restrict access to a specific team like this:

{
    "plugins": {
        "datasette-auth-github": {
            "...": "...",
            "load_teams": [
                "your-organization/staff",
                "your-organization/engineering",
            ]
        }
    },
    "allows": {
        "gh_team": "your-organization/engineering"
    }
}