Siwe Authentication - Django
Siwe Authentication is a Django app designed for Ethereum-based authentication using the Sign-In with Ethereum (EIP-4361) standard. It allows users to sign in using their Ethereum wallets, and provides flexible settings for customization.
Table Of Contents
- Get Started
- Installation
- Configuration
- Run migrations
- Usage
- Custom Groups
- Django User Model
- Contrubuting
- License
Get Started
Installation
Install the package using pip with the following command:
pip install siwe-auth-django
Configuration
Add 'siwe_auth'
to INSTALLED_APPS
in your settings.py file:
INSTALLED_APPS = [
'siwe_auth',
]
Add authentication configurations in your settings.py file:
AUTH_USER_MODEL = "siwe_auth.Wallet"
AUTHENTICATION_BACKENDS = [
"siwe_auth.backends.SiweBackend",
"django.contrib.auth.backends.ModelBackend"
]
SESSION_COOKIE_AGE = 3 * 60 * 60
If you need to create a customized auth user model refer to Django User Model section (Recommended).
Add the SIWE_AUTH
configuration in your settings.py file:
Available settings:
"CSRF_EXEMPT"
: Flag indicating whether CSRF protection is exempted for Siwe Authentication views (if you are creating an REST API must be True
).
"PROVIDER"
: Ethereum provider URL (it is required).
"CREATE_GROUPS_ON_AUTH"
: Flag indicating whether to create groups on user authentication.
"CREATE_ENS_PROFILE_ON_AUTH"
: Flag indicating whether to create ENS profiles on user authentication.
"CUSTOM_GROUPS"
: List of custom groups to be created on user authentication. If you need to create more group manager refer to Custom Groups section.
from siwe_auth import group
SIWE_AUTH = {
"CSRF_EXEMPT": True,
"PROVIDER": "https://mainnet.infura.io/v3/...",
"CREATE_GROUPS_ON_AUTH": True,
"CREATE_ENS_PROFILE_ON_AUTH": True,
"CUSTOM_GROUPS": [
("usdt_owners", groups.ERC20OwnerManager(config={'contract': '0x82E...550'})),
("nft_owners", groups.ERC721OwnerManager(config={'contract': '0x785...3A5'})),
],
}
Include the Siwe Authentication URLs in your project's urls.py:
from django.urls import include, path
urlpatterns = [
path('api/auth', include('siwe_auth.urls', namespace='siwe_auth')),
]
Run migrations:
python manage.py migrate
Usage
You need to follow this steps to successful authentication using SIWE protocol (EIP-4361):
- Get nonce: GET Method
/api/auth/nonce
. - Use that nonce to create a SIWE message in frontend and sign the message with your metamask or another wallet.
- Login: POST Method
/api/auth/login
, using the message and signature. Example request body:
{
"message": {
"domain": "your_domain.com",
"address": "0xA8f1...61905",
"statement": "This is a test statement.",
"uri": "https://your_domain.com",
"version": "1",
"chainId": 1,
"nonce": "2483e73dedffbd2616773506",
"issuedAt": "2024-01-27T18:43:48.011Z"
},
"signature": "0xf5b4ea...7bda4e177276dd1c"
}
- Now you have the sessionid in cookies so you can use it for authenticated required views.
- Refresh the sessionid: POST Method
api/auth/refresh
. - Verify if you are authenticated: GET Method
api/auth/verify
. - Logout: POST Method
api/auth/logout
.
Three custom group managers are provided by default:
ERC20OwnerManager
ERC721OwnerManager
ERC1155OwnerManager
You can create more group managers by extending the GroupManager
class:
from web3 import HTTPProvider
from siwe_auth.groups import GroupManager
class MyCustomGroup(GroupManager):
def __init__(self, config: dict):
pass
def is_member(self, wallet: object, provider: HTTPProvider) -> bool:
pass
You can create custom groups in your settings.py:
from siwe_auth import group
SIWE_AUTH = {
"CUSTOM_GROUPS": [
("usdt_owners", groups.ERC20OwnerManager(config={'contract': '0x82E...550'})),
("nft_owners", groups.ERC721OwnerManager(config={'contract': '0x785...3A5'})),
("token_owners", groups.ERC1154OwnerManager(config={'contract': '0x872...5F5'})),
],
}
Then you can manage these groups with the django GroupManager, example:
from django.contrib.auth.models import Group
usdt_owners_group = Group.objects.get(name='usdt_owners')
all_usdt_owners = usdt_owners_group.user_set.all()
By default, Siwe Authentication uses the Wallet
model as the user model. If you prefer to use a specific user model, you can either use the provided AbstractWallet
model or create your own user model. For more details, refer to the Configuration section.
from siwe_auth.models import AbstractWallet
class MyUserModel(AbstractWallet):
If you use a customized user model you need to register a customized admin site.
from django.contrib import admin
from django.contrib.auth import get_user_model
from siwe_auth.admin import WalletBaseAdmin
WalletModel = get_user_model()
class WalletAdmin(WalletBaseAdmin):
admin.site.register(WalletModel, WalletAdmin)
Contributing
Contributions are welcome! Please create issues for bugs or feature requests. Pull requests are encouraged.
This project is licensed under the MIT License - see the LICENSE file for details.