# forge-oauth
**Add OAuth login support to your Django project.**
[Watch on YouTube (3 mins) →](https://www.youtube.com/watch?v=UxbxBa6AFsU)
This library is intentionally minimal.
It has no dependencies and a single database model.
If you simply want users to log in with GitHub, Google, Twitter, etc. (and maybe use that access token for API calls),
then this is the library for you.
There are three OAuth flows that it makes possible:
1. Signup via OAuth (new user, new OAuth connection)
2. Login via OAuth (existing user, existing OAuth connection)
3. Connect/disconnect OAuth accounts to a user (existing user, new OAuth connection)
## Usage
Install the package from PyPi:
```sh
pip install forge-oauth
```
Add `forgeoauth` to your `INSTALLED_APPS` in `settings.py`:
```python
INSTALLED_APPS = [
...
"forgeoauth",
]
```
In your `urls.py`, include `forgeoauth.urls`:
```python
urlpatterns = [
path("oauth/", include("forgeoauth.urls")),
...
]
```
Then run migrations:
```sh
python manage.py migrate forgeoauth
```
Create a new OAuth provider ([or copy one from our examples](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples)):
```python
# yourapp/oauth.py
import requests
from forgeoauth.providers import OAuthProvider, OAuthToken, OAuthUser
class ExampleOAuthProvider(OAuthProvider):
authorization_url = "https://example.com/login/oauth/authorize"
def get_oauth_token(self, *, code, request):
response = requests.post(
"https://example.com/login/oauth/token",
headers={
"Accept": "application/json",
},
data={
"client_id": self.get_client_id(),
"client_secret": self.get_client_secret(),
"code": code,
},
)
response.raise_for_status()
data = response.json()
return OAuthToken(
access_token=data["access_token"],
)
def get_oauth_user(self, *, oauth_token):
response = requests.get(
"https://example.com/api/user",
headers={
"Accept": "application/json",
"Authorization": f"token {oauth_token.access_token}",
},
)
response.raise_for_status()
data = response.json()
return OAuthUser(
id=data["id"],
username=data["username"],
email=data["email"],
)
```
Create your OAuth app/consumer on the provider's site (GitHub, Google, etc.).
When setting it up, you'll likely need to give it a callback URL.
In development this can be `http://localhost:8000/oauth/github/callback/` (if you name it `"github"` like in the example below).
At the end you should get some sort of "client id" and "client secret" which you can then use in your `settings.py`:
```python
OAUTH_LOGIN_PROVIDERS = {
"github": {
"class": "yourapp.oauth.GitHubOAuthProvider",
"kwargs": {
"client_id": environ["GITHUB_CLIENT_ID"],
"client_secret": environ["GITHUB_CLIENT_SECRET"],
# "scope" is optional, defaults to ""
# You can add other fields if you have additional kwargs in your class __init__
# def __init__(self, *args, custom_arg="default", **kwargs):
# self.custom_arg = custom_arg
# super().__init__(*args, **kwargs)
},
},
}
```
Then add a login button (which is a form using POST rather than a basic link, for security purposes):
```html
<h1>Login</h1>
<form action="{% url 'forgeoauth:login' 'github' %}" method="post">
{% csrf_token %}
<button type="submit">Login with GitHub</button>
</form>
```
Depending on your URL and provider names,
your OAuth callback will be something like `https://example.com/oauth/{provider}/callback/`.
That's pretty much it!
## Advanced usage
### Email addresses should be unique
When you're integrating with an OAuth provider,
we think that the user's email address is the best "primary key" when linking to your `User` model in your app.
Unfortunately in Django, by default an email address is not required to be unique!
**We strongly recommend you require email addresses to be unique in your app.**
[As suggested by the Django docs](https://docs.djangoproject.com/en/4.0/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project),
one way to do this is to have your own `User` model:
```python
# In an app named "users", for example
from django.contrib.auth.models import AbstractUser
class User(AbstractUser):
email = models.EmailField(unique=True)
# In settings.py
AUTH_USER_MODEL = 'users.User'
```
You'll also notice that there are no "email confirmation" or "email verification" flows in this library.
This is also intentional.
You can implement something like that yourself if you need to,
but the easier solution in our opinion is to use an OAuth provider you *trust to have done that already*.
If you look at our [provider examples](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples) you'll notice how we often use provider APIs to get the email address which is "primary" and "verified" already.
If they've already done that work,
then we can just use that information.
### Handling OAuth errors
The most common error you'll run into is if an existing user clicks a login button,
but they haven't yet connected that provider to their account.
For security reasons,
the required flow here is that the user actually logs in with another method (however they signed up) and then *connects* the OAuth provider from a settings page.
For this error (and a couple others),
there is an error template that is rendered.
You can customize this by copying `oauth/error.html` to one of your own template directories:
```html
{% extends "base.html" %}
{% block content %}
<h1>OAuth Error</h1>
<p>{{ oauth_error }}</p>
{% endblock %}
```
### Connecting and disconnecting OAuth accounts
To connect and disconnect OAuth accounts,
you can add a series of forms to a user/profile settings page.
Here's an very basic example:
```html
{% extends "base.html" %}
{% block content %}
Hello {{ request.user }}!
<h2>Existing connections</h2>
<ul>
{% for connection in request.user.oauth_connections.all %}
<li>
{{ connection.provider_key }} [ID: {{ connection.provider_user_id }}]
{% if connection.can_be_disconnected %}
<form action="{% url 'forgeoauth:disconnect' connection.provider_key %}" method="post">
{% csrf_token %}
<input type="hidden" name="provider_user_id" value="{{ connection.provider_user_id }}">
<button type="submit">Disconnect</button>
</form>
{% endif %}
</li>
{% endfor %}
</ul>
<h2>Add a connection</h2>
<ul>
{% for provider_key in oauth_provider_keys %}
<li>
{{ provider_key}}
<form action="{% url 'forgeoauth:connect' provider_key %}" method="post">
{% csrf_token %}
<button type="submit">Connect</button>
</form>
</li>
{% endfor %}
</ul>
{% endblock %}
```
The `get_provider_keys` function can help populate the list of options:
```python
from forgeoauth.providers import get_provider_keys
class ExampleView(TemplateView):
template_name = "index.html"
def get_context_data(self, **kwargs):
context = super().get_context_data(**kwargs)
context["oauth_provider_keys"] = get_provider_keys()
return context
```
### Using a saved access token
```python
import requests
# Get the OAuth connection for a user
connection = user.oauth_connections.get(provider_key="github")
# If the token can expire, check and refresh it
if connection.access_token_expired():
connection.refresh_access_token()
# Use the token in an API call
token = connection.access_token
response = requests.get(...)
```
### Using the Django system check
This library comes with a Django system check to ensure you don't *remove* a provider from `settings.py` that is still in use in your database.
You do need to specify the `--database` for this to run when using the check command by itself:
```sh
python manage.py check --database default
```
## FAQs
### How is this different from [other Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?
The short answer is that *it does less*.
In [django-allauth](https://github.com/pennersr/django-allauth)
(maybe the most popular alternative)
you get all kinds of other features like managing multiple email addresses,
email verification,
a long list of supported providers,
and a whole suite of forms/urls/views/templates/signals/tags.
And in my experience,
it's too much.
It often adds more complexity to your app than you actually need (or want) and honestly it can just be a lot to wrap your head around.
Personally, I don't like the way that your OAuth settings are stored in the database vs when you use `settings.py`,
and the implications for doing it one way or another.
The other popular OAuth libraries have similar issues,
and I think their *weight* outweighs their usefulness for 80% of the use cases.
### Why aren't providers included in the library itself?
One thing you'll notice is that we don't have a long list of pre-configured providers in this library.
Instead, we have some examples (which you can usually just copy, paste, and use) and otherwise encourage you to wire up the provider yourself.
Often times all this means is finding the two OAuth URLs ("oauth/authorize" and "oauth/token") in their docs,
and writing two class methods that do the actual work of getting the user's data (which is often customized anyway).
We've written examples for the following providers:
- [GitHub](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/github.py)
- [GitLab](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/gitlab.py)
- [Bitbucket](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/bitbucket.py)
Just copy that code and paste it in your project.
Tweak as necessary!
This might sound strange at first.
But in the long run we think it's actually *much* more maintainable for both us (as library authors) and you (as app author).
If something breaks with a provider, you can fix it immediately!
You don't need to try to run changes through us or wait for an upstream update.
You're welcome to contribute an example to this repo,
and there won't be an expectation that it "works perfectly for every use case until the end of time".
### Redirect/callback URL mismatch in local development?
If you're doing local development through a proxy/tunnel like [ngrok](https://ngrok.com/),
then the callback URL might be automatically built as `http` instead of `https`.
This is the Django setting you're probably looking for:
```python
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/forgepackages/forge-oauth",
"name": "forge-oauth",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Dave Gaeddert",
"author_email": "dave.gaeddert@dropseed.dev",
"download_url": "https://files.pythonhosted.org/packages/cd/8b/799fae459849b8954e186b56a5300e29c73508a4df43f543a1d37f659335/forge_oauth-0.4.1.tar.gz",
"platform": null,
"description": "# forge-oauth\n\n**Add OAuth login support to your Django project.**\n\n[Watch on YouTube (3 mins) \u2192](https://www.youtube.com/watch?v=UxbxBa6AFsU)\n\nThis library is intentionally minimal.\nIt has no dependencies and a single database model.\nIf you simply want users to log in with GitHub, Google, Twitter, etc. (and maybe use that access token for API calls),\nthen this is the library for you.\n\nThere are three OAuth flows that it makes possible:\n\n1. Signup via OAuth (new user, new OAuth connection)\n2. Login via OAuth (existing user, existing OAuth connection)\n3. Connect/disconnect OAuth accounts to a user (existing user, new OAuth connection)\n\n\n## Usage\n\nInstall the package from PyPi:\n\n```sh\npip install forge-oauth\n```\n\nAdd `forgeoauth` to your `INSTALLED_APPS` in `settings.py`:\n\n```python\nINSTALLED_APPS = [\n ...\n \"forgeoauth\",\n]\n```\n\nIn your `urls.py`, include `forgeoauth.urls`:\n\n```python\nurlpatterns = [\n path(\"oauth/\", include(\"forgeoauth.urls\")),\n ...\n]\n```\n\nThen run migrations:\n\n```sh\npython manage.py migrate forgeoauth\n```\n\nCreate a new OAuth provider ([or copy one from our examples](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples)):\n\n```python\n# yourapp/oauth.py\nimport requests\n\nfrom forgeoauth.providers import OAuthProvider, OAuthToken, OAuthUser\n\n\nclass ExampleOAuthProvider(OAuthProvider):\n authorization_url = \"https://example.com/login/oauth/authorize\"\n\n def get_oauth_token(self, *, code, request):\n response = requests.post(\n \"https://example.com/login/oauth/token\",\n headers={\n \"Accept\": \"application/json\",\n },\n data={\n \"client_id\": self.get_client_id(),\n \"client_secret\": self.get_client_secret(),\n \"code\": code,\n },\n )\n response.raise_for_status()\n data = response.json()\n return OAuthToken(\n access_token=data[\"access_token\"],\n )\n\n def get_oauth_user(self, *, oauth_token):\n response = requests.get(\n \"https://example.com/api/user\",\n headers={\n \"Accept\": \"application/json\",\n \"Authorization\": f\"token {oauth_token.access_token}\",\n },\n )\n response.raise_for_status()\n data = response.json()\n return OAuthUser(\n id=data[\"id\"],\n username=data[\"username\"],\n email=data[\"email\"],\n )\n```\n\nCreate your OAuth app/consumer on the provider's site (GitHub, Google, etc.).\nWhen setting it up, you'll likely need to give it a callback URL.\nIn development this can be `http://localhost:8000/oauth/github/callback/` (if you name it `\"github\"` like in the example below).\nAt the end you should get some sort of \"client id\" and \"client secret\" which you can then use in your `settings.py`:\n\n```python\nOAUTH_LOGIN_PROVIDERS = {\n \"github\": {\n \"class\": \"yourapp.oauth.GitHubOAuthProvider\",\n \"kwargs\": {\n \"client_id\": environ[\"GITHUB_CLIENT_ID\"],\n \"client_secret\": environ[\"GITHUB_CLIENT_SECRET\"],\n # \"scope\" is optional, defaults to \"\"\n\n # You can add other fields if you have additional kwargs in your class __init__\n # def __init__(self, *args, custom_arg=\"default\", **kwargs):\n # self.custom_arg = custom_arg\n # super().__init__(*args, **kwargs)\n },\n },\n}\n```\n\nThen add a login button (which is a form using POST rather than a basic link, for security purposes):\n\n```html\n<h1>Login</h1>\n<form action=\"{% url 'forgeoauth:login' 'github' %}\" method=\"post\">\n {% csrf_token %}\n <button type=\"submit\">Login with GitHub</button>\n</form>\n```\n\nDepending on your URL and provider names,\nyour OAuth callback will be something like `https://example.com/oauth/{provider}/callback/`.\n\nThat's pretty much it!\n\n## Advanced usage\n\n### Email addresses should be unique\n\nWhen you're integrating with an OAuth provider,\nwe think that the user's email address is the best \"primary key\" when linking to your `User` model in your app.\nUnfortunately in Django, by default an email address is not required to be unique!\n**We strongly recommend you require email addresses to be unique in your app.**\n\n[As suggested by the Django docs](https://docs.djangoproject.com/en/4.0/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project),\none way to do this is to have your own `User` model:\n\n```python\n# In an app named \"users\", for example\nfrom django.contrib.auth.models import AbstractUser\n\nclass User(AbstractUser):\n email = models.EmailField(unique=True)\n\n\n# In settings.py\nAUTH_USER_MODEL = 'users.User'\n```\n\nYou'll also notice that there are no \"email confirmation\" or \"email verification\" flows in this library.\nThis is also intentional.\nYou can implement something like that yourself if you need to,\nbut the easier solution in our opinion is to use an OAuth provider you *trust to have done that already*.\nIf you look at our [provider examples](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples) you'll notice how we often use provider APIs to get the email address which is \"primary\" and \"verified\" already.\nIf they've already done that work,\nthen we can just use that information.\n\n### Handling OAuth errors\n\nThe most common error you'll run into is if an existing user clicks a login button,\nbut they haven't yet connected that provider to their account.\nFor security reasons,\nthe required flow here is that the user actually logs in with another method (however they signed up) and then *connects* the OAuth provider from a settings page.\n\nFor this error (and a couple others),\nthere is an error template that is rendered.\nYou can customize this by copying `oauth/error.html` to one of your own template directories:\n\n```html\n{% extends \"base.html\" %}\n\n{% block content %}\n<h1>OAuth Error</h1>\n<p>{{ oauth_error }}</p>\n{% endblock %}\n```\n\n\n\n### Connecting and disconnecting OAuth accounts\n\nTo connect and disconnect OAuth accounts,\nyou can add a series of forms to a user/profile settings page.\nHere's an very basic example:\n\n```html\n{% extends \"base.html\" %}\n\n{% block content %}\nHello {{ request.user }}!\n\n<h2>Existing connections</h2>\n<ul>\n {% for connection in request.user.oauth_connections.all %}\n <li>\n {{ connection.provider_key }} [ID: {{ connection.provider_user_id }}]\n {% if connection.can_be_disconnected %}\n <form action=\"{% url 'forgeoauth:disconnect' connection.provider_key %}\" method=\"post\">\n {% csrf_token %}\n <input type=\"hidden\" name=\"provider_user_id\" value=\"{{ connection.provider_user_id }}\">\n <button type=\"submit\">Disconnect</button>\n </form>\n {% endif %}\n </li>\n {% endfor %}\n</ul>\n\n<h2>Add a connection</h2>\n<ul>\n {% for provider_key in oauth_provider_keys %}\n <li>\n {{ provider_key}}\n <form action=\"{% url 'forgeoauth:connect' provider_key %}\" method=\"post\">\n {% csrf_token %}\n <button type=\"submit\">Connect</button>\n </form>\n </li>\n {% endfor %}\n</ul>\n\n{% endblock %}\n```\n\nThe `get_provider_keys` function can help populate the list of options:\n\n```python\nfrom forgeoauth.providers import get_provider_keys\n\nclass ExampleView(TemplateView):\n template_name = \"index.html\"\n\n def get_context_data(self, **kwargs):\n context = super().get_context_data(**kwargs)\n context[\"oauth_provider_keys\"] = get_provider_keys()\n return context\n```\n\n\n\n### Using a saved access token\n\n```python\nimport requests\n\n# Get the OAuth connection for a user\nconnection = user.oauth_connections.get(provider_key=\"github\")\n\n# If the token can expire, check and refresh it\nif connection.access_token_expired():\n connection.refresh_access_token()\n\n# Use the token in an API call\ntoken = connection.access_token\nresponse = requests.get(...)\n```\n\n### Using the Django system check\n\nThis library comes with a Django system check to ensure you don't *remove* a provider from `settings.py` that is still in use in your database.\nYou do need to specify the `--database` for this to run when using the check command by itself:\n\n```sh\npython manage.py check --database default\n```\n\n## FAQs\n\n### How is this different from [other Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?\n\nThe short answer is that *it does less*.\n\nIn [django-allauth](https://github.com/pennersr/django-allauth)\n(maybe the most popular alternative)\nyou get all kinds of other features like managing multiple email addresses,\nemail verification,\na long list of supported providers,\nand a whole suite of forms/urls/views/templates/signals/tags.\nAnd in my experience,\nit's too much.\nIt often adds more complexity to your app than you actually need (or want) and honestly it can just be a lot to wrap your head around.\nPersonally, I don't like the way that your OAuth settings are stored in the database vs when you use `settings.py`,\nand the implications for doing it one way or another.\n\nThe other popular OAuth libraries have similar issues,\nand I think their *weight* outweighs their usefulness for 80% of the use cases.\n\n### Why aren't providers included in the library itself?\n\nOne thing you'll notice is that we don't have a long list of pre-configured providers in this library.\nInstead, we have some examples (which you can usually just copy, paste, and use) and otherwise encourage you to wire up the provider yourself.\nOften times all this means is finding the two OAuth URLs (\"oauth/authorize\" and \"oauth/token\") in their docs,\nand writing two class methods that do the actual work of getting the user's data (which is often customized anyway).\n\nWe've written examples for the following providers:\n\n- [GitHub](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/github.py)\n- [GitLab](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/gitlab.py)\n- [Bitbucket](https://github.com/forgepackages/forge-oauth/tree/master/provider_examples/bitbucket.py)\n\nJust copy that code and paste it in your project.\nTweak as necessary!\n\nThis might sound strange at first.\nBut in the long run we think it's actually *much* more maintainable for both us (as library authors) and you (as app author).\nIf something breaks with a provider, you can fix it immediately!\nYou don't need to try to run changes through us or wait for an upstream update.\nYou're welcome to contribute an example to this repo,\nand there won't be an expectation that it \"works perfectly for every use case until the end of time\".\n\n### Redirect/callback URL mismatch in local development?\n\nIf you're doing local development through a proxy/tunnel like [ngrok](https://ngrok.com/),\nthen the callback URL might be automatically built as `http` instead of `https`.\n\nThis is the Django setting you're probably looking for:\n\n```python\nSECURE_PROXY_SSL_HEADER = (\"HTTP_X_FORWARDED_PROTO\", \"https\")\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "0.4.1",
"project_urls": {
"Documentation": "https://github.com/forgepackages/forge-oauth",
"Homepage": "https://github.com/forgepackages/forge-oauth",
"Repository": "https://github.com/forgepackages/forge-oauth"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8685d24462380223b3ee7ccdfc00414f5bea2356afb29059e418eb2c69d00012",
"md5": "17055be5a9cbe959c500032df5bafe96",
"sha256": "257d484bce442718aec2915e06e519ed16ebb564e4f2625baf632100cc0bdc05"
},
"downloads": -1,
"filename": "forge_oauth-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17055be5a9cbe959c500032df5bafe96",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 15109,
"upload_time": "2024-12-06T22:10:56",
"upload_time_iso_8601": "2024-12-06T22:10:56.869713Z",
"url": "https://files.pythonhosted.org/packages/86/85/d24462380223b3ee7ccdfc00414f5bea2356afb29059e418eb2c69d00012/forge_oauth-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd8b799fae459849b8954e186b56a5300e29c73508a4df43f543a1d37f659335",
"md5": "cd18f5a7a95ca05a68e70d2747eb912a",
"sha256": "36808871a60cb2e0255390a56fb467e96f8a7452c74b9ce5f4da21b48013eaa2"
},
"downloads": -1,
"filename": "forge_oauth-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "cd18f5a7a95ca05a68e70d2747eb912a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 15471,
"upload_time": "2024-12-06T22:10:58",
"upload_time_iso_8601": "2024-12-06T22:10:58.837938Z",
"url": "https://files.pythonhosted.org/packages/cd/8b/799fae459849b8954e186b56a5300e29c73508a4df43f543a1d37f659335/forge_oauth-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 22:10:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "forgepackages",
"github_project": "forge-oauth",
"github_not_found": true,
"lcname": "forge-oauth"
}
JSON
