django-rest-github-oauth

A simple python library to authenticate users with github in Django applications.

• Free software: MIT license
• Documentation: https://django-rest-github-oauth.readthedocs.io.

Requirements

• Python (3.7, 3.8, 3.9)
• Django (2.x, 3.x, 4.x)
• Django REST Framework (3.10, 3.11, 3.12)

Setup

Install the package in your python environment using pip.

pip install django-rest-github-oauth

For detailed information regarding the installation, see the installation guide.

Then your django project must be configured to use the library. For that include it in INSTALLED_APPS of your settings.py. Besides that, you will have to include the auth handler app in installed apps.

Currently, django-rest-github-oauth supports the following authentication backends:

• Token Authentication using djangorestframework token authentication
• JWT Authentication using djangorestframework simple jwt

Using JWT

INSTALLED_APPS = [
    # ...
    'rest_framework_simplejwt',
    'django_rest_github_oauth',
    # ...
]

Using Token Authentication

INSTALLED_APPS = [
    # ...
    'rest_framework.authtoken',
    'django_rest_github_oauth',
    # ...
]

Note

• If you are using Token Authentication, please header over to djangorestframework token authentication and add related settings to your settings.py
• If you are using JWT Authentication, please header over to djangorestframework simple jwt and add related settings to your settings.py

Then add the following to your settings.py:

GITHUB_AUTH_KEY = "<your_github_app_key>"
GITHUB_AUTH_SECRET = "<your_github_app_secret>"
GITHUB_AUTH_USE_JWT = True    # False if you're using token based authentication

GITHUB_AUTH_CALLBACK_URL = "http://localhost:3000/auth/success/"    # url of the frontend handling redirects from github
GITHUB_AUTH_ALLOWED_REDIRECT_URIS = [
        GITHUB_AUTH_CALLBACK_URL
    ]

Note

If you have not yet created an app on github, you need to create an app to get the client id and secret. register app with github.

Warning

You need to set the GITHUB_AUTH_CALLBACK_URL the same value you set on github while creating the app.

Then add the following to you main urls.py file.

urlpatterns = [
  # ...
  path('admin/', admin.site.urls),
  path('auth/github/', include('django_rest_github_oauth.urls')),
  # ...
]

Run migrations

python manage.py migrate

That's all you have to do on the backend.

Usage

To get authorizaition_uri, make a GET request to the following url:

http://localhost:8000/auth/github?redirect_uri=http://localhost:3000/auth/success/

This will return a payload of the form

{
    "data": {
        "authorization_uri": "https://github.com/login/oauth/authorize?client_id=shlf898f7dsfsd0f90wer9fs&redirect_uri=http://localhost:3000/auth/success/&state=dac7944888d140e19280&response_type=code&scope=user:email,read:user"
         },
    "message": "success",
    "error": false
}

Redirect your user to authorization_uri.

Then, after the user has authorized your app, they will be redirected to the GITHUB_AUTH_CALLBACK_URL you specified with two query parameters:

• code
• state

In your frontend javascript, read those query parameters. Here is a quick snippet how you can achieve that.

const query = new URLSearchParams(window.location.search);
const code = query.get("code");
const state = query.get("state");

Then make a POST request to the following url with code and state in the request body:

http://localhost:8000/auth/github

The reuturn payload will have user informations and appropriate tokens.

Here is a snippet how you can make call using axios.

const query = new URLSearchParams(window.location.search);
const code = query.get("code");
const state = query.get("state");

const details = {
  code: code,
  state: state,
};

const url = "http://127.0.0.1:8000/auth/github/";

axios({
  method: "post",
  url: url,
  data: details,
  })
  .then((response) => {
    console.log(response)
    // login the user and save token for further request to the backend
  })
  .catch((err) => console.log(err));