Skip to content

Quick Setup

Setup Django Settings

To add this package in your Django Project, please modify the INSTALLED_APPS in your settings.py:

# settings.py

INSTALLED_APPS = [
    # other django apps
    "django.contrib.messages",  # Need for Auth messages
    "django_github_sso",  # Add django_github_sso
]

Setup GitHub OAuth App

Navigate to https://github.com/organizations/<YOUR ORGANIZATION>/settings/applications, then select or create a new Org OAuth App. In this tutorial we will create a new App.

In the field Authorization callback URI add the address: https://your-domain.com/github_sso/callback/ replacing your-domain.com with your real domain (and Port). For example, if you're running locally, you can use http://localhost:8000/github_sso/callback/.

Do not forget the trailing slash!

register_new_github_oauth_app_example.png

With this, you can retrieve your Client ID. For the Client Secret please generate a new secret clicking on button Generate a new client secret:

register_new_github_oauth_app_example.png

Configuring your Django Project

After that, add the credentials in your settings.py file:

# settings.py
GITHUB_SSO_CLIENT_ID = "your Application (client) Id here"
GITHUB_SSO_CLIENT_SECRET = "your client secret value here"

Don't commit this info in your repository. This permits you to have different credentials for each environment and mitigates security breaches. That's why we recommend you to use environment variables to store this info. To read this data, we recommend you to install and use a Twelve-factor compatible library in your project.

For example, you can use our project Stela to load the environment variables from a .env.local file, like this:

# .env.local
GITHUB_SSO_CLIENT_ID="your Application (client) Id here"
GITHUB_SSO_CLIENT_SECRET="your client secret value here"

# Django settings.py
from stela import env

GITHUB_SSO_CLIENT_ID = env.GITHUB_SSO_CLIENT_ID
GITHUB_SSO_CLIENT_SECRET = env.GITHUB_SSO_CLIENT_SECRET

But in fact, you can use any library you want, like django-environ, django-constance, python-dotenv, etc...

Setup Auto-Create Users

The next option is to set up the auto-create users from Django GitHub SSO. At least one of the following filters must be set:

  • GITHUB_SSO_ALLOWABLE_DOMAINS: will check against user's primary email
  • GITHUB_SSO_ALLOWABLE_ORGS: user needs to be a member of all orgs listed
  • GITHUB_SSO_NEEDED_REPOS: user needs to be a member of all repos listed

Any combination of these filters can be used.

# settings.py

GITHUB_SSO_ALLOWABLE_DOMAINS = ["example.com"]  # will check against user's primary email
GITHUB_SSO_ALLOWABLE_ORGS = ["example"]  # user needs to be a member of all orgs listed
GITHUB_SSO_NEEDED_REPOS = ["example/example-repo"]  # user needs to be a member of all repos listed

If the GitHub user is invalid, the user will be redirected to the login page.

How can I allow any GitHub user in my Django Admin?

To do this, use the option GITHUB_SSO_ALLOW_ALL_USERS = True in your settings.py. Please make sure you understand the security implications of this option.

Setup Django URLs

And in your urls.py please add the Django-GitHub-SSO views:

# urls.py

from django.urls import include, path

urlpatterns = [
    # other urlpatterns...
    path(
        "github_sso/", include(
            "django_github_sso.urls",
            namespace="django_github_sso"
        )
    ),
]

Run Django migrations

Finally, run migrations

$ python manage.py migrate

And, that's it: Django GitHub SSO is ready for use. When you open the admin page, you will see the "Login with GitHub" button:

How about Django Admin skins, like Grappelli?

Django GitHub SSO will works with any Django Admin skin which calls the original Django login template, like Grappelli, Django Jazzmin, Django Admin Interface and Django Jet Reboot.

If the skin uses his own login template, you will need create your own admin/login.html template to add both HTML from custom login.html from the custom package and from this library.

For the next pages, let's see each one of these steps with more details.