django-github-sso 5.0.2

Easily add GitHub Authentication to your Django Projects

Easily integrate GitHub Authentication into your Django projects

Welcome to Django GitHub SSO

This library simplifies the process of authenticating users with GitHub in Django projects. It adds a "Login with GitHub" button to your Django admin login page, allowing users to authenticate using their GitHub accounts.

Unlike more complex solutions like django-allauth, Django GitHub SSO focuses on simplicity and ease of use, with minimal configuration required.

Features

• Simple integration with Django admin
• Automatic user creation based on GitHub credentials
• Customizable authentication filters (by domain, organization, or repository)
• Compatible with various Django admin skins
• Support for multiple SSO providers
• Light and dark mode support

---

Documentation

Full documentation is available at: https://megalus.github.io/django-github-sso/

---

Requirements

• Python 3.11+
• Django 4.2+
• A GitHub account or organization

Installation

$ pip install django-github-sso

Compatibility

• Python 3.11, 3.12, 3.13
• Django 4.2, 5.0, 5.1, 5.2

Older python/django versions are not supported.

Quick Configuration

1. Add the following to your settings.py INSTALLED_APPS:

# settings.py

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

2. Navigate to https://github.com/organizations/<YOUR ORGANIZATION>/settings/applications, then select or create a new OAuth App.

3. On the GitHub OAuth App settings page, add the address http://localhost:8000/github_sso/callback/ (or your domain) in the "Authorization callback URL" field.

4. Add your GitHub OAuth credentials to your settings.py:

# settings.py

GITHUB_SSO_CLIENT_ID = "your Client ID here"
GITHUB_SSO_CLIENT_SECRET = "your Client Secret here"

5. Configure user authorization filters (at least one is required):

# settings.py

# Choose one or more of these options:
GITHUB_SSO_ALLOWABLE_DOMAINS = ["example.com"]  # Check against user's primary email
GITHUB_SSO_ALLOWABLE_ORGS = ["example"]  # User must be a member of all orgs listed
GITHUB_SSO_NEEDED_REPOS = ["example/example-repo"]  # User must have access to all repos listed

6. Add the Django GitHub SSO URLs to your urls.py:

# urls.py

from django.urls import include, path

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

7. Run migrations:

$ python manage.py migrate

That's it! Start Django and navigate to http://localhost:8000/admin/login to see the GitHub SSO button:

Environment Variables

For security, it's recommended to use environment variables for your GitHub credentials:

# settings.py
import os

GITHUB_SSO_CLIENT_ID = os.environ.get("GITHUB_SSO_CLIENT_ID")
GITHUB_SSO_CLIENT_SECRET = os.environ.get("GITHUB_SSO_CLIENT_SECRET")

Example project

A minimal Django project using this library is included in this repository under example_github_app/.

• Read the step-by-step instructions in example_github_app/README.md
• Use it as a reference to configure your own project settings and URLs

---

License

This project is licensed under the terms of the MIT license.