An opinionated Django app to provide user authentication.
Project description
ckl-rest-auth
An opinionated Django app to provide user authentication.
Installation
pip install cklauth
- Add to your project's
INSTALLED_APPS
:
rest_framework
rest_framework.authtoken
corsheaders
cklauth
- Include
ckl-rest-auth
urls to your project: Onurls.py
addpath('', include('cklauth.urls'))
- Add settings according to the project requirements
- For Django's default user config:
# Field used for authencation together with password (required)
'LOGIN_FIELD': 'email',
# Fields used on user serializer
'REGISTER_FIELDS': ('username', 'email'),
# From email used on password reset emails (optional)
'FROM_EMAIL': 'default@email.com',
# Google authentication settings (optional)
'GOOGLE': {
'CLIENT_ID': 'insert-your-key',
'CLIENT_SECRET': 'insert-your-key',
'REDIRECT_URI': 'insert-your-uri',
},
# Facebook authentication settings (optional)
'FACEBOOK': {
'CLIENT_ID': 'insert-your-key',
'CLIENT_SECRET': 'insert-your-key',
'REDIRECT_URI': 'insert-your-uri',
},
Note that the default LOGIN_FIELD
is email
and then you need to use the helper
authentication backend:
AUTHENTICATION_BACKENDS = ['cklauth.auth.EmailOrUsernameModelBackend']
- For a custom user model, you can define additional options:
CKL_REST_AUTH = {
# Field used for authencation together with password (required)
'LOGIN_FIELD': 'email',
# Override the default serializer used on registration and authentication responses (optional)
'USER_SERIALIZER': 'cklauth.api.v1.serializers.UserSerializer',
# Fields used on user serializer (not used if USER_SERIALIZER is defined above)
'REGISTER_FIELDS': ('username', 'email'),
# From email used on password reset emails (optional)
'FROM_EMAIL': 'default@email.com',
# Google authentication settings (optional)
'GOOGLE': {
'CLIENT_ID': 'insert-your-key',
'CLIENT_SECRET': 'insert-your-key',
'REDIRECT_URI': 'insert-your-uri',
# Define a callable that receives the social user payload and returns the value on of the
# User model USERNAME_FIELD (username, for instance). The default function already checks
# if the value is in use. Set it to `None`, if you don't want to generate a USERNAME_FIELD.
'AUTH_FIELD_GENERATOR': 'cklauth.utils.auth_field_generator',
# How to map the social user payload to the User model fields. It accepts a callable that
# receives the whole social user payload to map more complex data.
'USER_INFO_MAPPING': {
'full_name': 'full_name': lambda info: '{} {}'.format(
info.get('given_name'),
info.get('family_name')
),
'email': 'email',
},
},
# Facebook authentication settings (optional)
'FACEBOOK': {
'CLIENT_ID': 'insert-your-key',
'CLIENT_SECRET': 'insert-your-key',
'REDIRECT_URI': 'insert-your-uri',
'AUTH_FIELD_GENERATOR': 'cklauth.utils.auth_field_generator',
'USER_INFO_MAPPING': {
'full_name': 'full_name': lambda info: '{} {}'.format(
info.get('first_name'),
info.get('last_name')
),
'email': 'email',
},
},
}
Basic Endpoints
POST /api/v1/login
Body (depends on LOGIN_FIELD)
{
"email": "example@example.com",
"password": "secret"
}
Response (depends on REGISTER_FIELDS and USER_SERIALIZER) - 200 OK
{
"token": "supersecret",
"user": {
"id": 1,
"email": "example@example.com",
"first_name": "Example",
"last_name": "Example"
}
}
Note: the user payload may vary according to specified REGISTER_FIELDS and USER_SERIALIZER.
POST /api/v1/register
Body (depends on REGISTER_FIELDS and USER_SERIALIZER -- always has a password)
{
"email": "example@example.com",
"password": "secret",
"first_name": "Example",
"last_name": "Example"
}
Response (depends on REGISTER_FIELDS and USER_SERIALIZER) - 201 CREATED
{
"token": "supersecret",
"user": {
"id": 1,
"email": "example@example.com",
"first_name": "Example",
"last_name": "Example"
}
}
Note: the user payload may vary according to specified REGISTER_FIELDS and USER_SERIALIZER.
POST /api/v1/password-reset/
Body
{
"email": "example@example.com"
}
Response - 200 OK
{
"email": "example@example.com"
}
Note: it always returns success, even if the provided email is not registered.
Social Endpoints
GET /api/v1/social/google
GET /api/v1/social/facebook
Note: this should not be XHR request, the user will be redirected to consent screen. After
consent, the user is redirected to platform REDIRECT_URI added on settings, where a code is
extracted from the URL hash.
POST /api/v1/social/google
POST /api/v1/social/facebook
Body
{
"code": "<code from previous step>",
"user_extra_fields": {
"role": "admin"
}
}
Note: You can pass additional user fields in the user_extra_fields
key, as long as they are
part of the main REGISTER_FIELDS
list.
Response - 200 OK
{
"token": "supersecret",
"user": {
"id": 1,
"email": "example@example.com",
"first_name": "Example",
"last_name": "Example"
}
}
Note: the user payload may vary according to specified REGISTER_FIELDS and USER_SERIALIZER.
Contributing
The library code is under cklauth
folder and tests are in a test project under testapp
folder.
Running tests:
- Ensure that you have the app requirements installed
pip install -r requirements.txt
pip install -e cklauth
- Run the tests
python -m pytest test_default_user
python -m pytest test_custom_user
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.