Login

API Views

There are two views used in the login workflow:

login

rest_registration.api.views.login(request, *args, **kwargs)

logout

rest_registration.api.views.logout(request, *args, **kwargs)

Default serializers

DefaultLoginSerializer

class rest_registration.api.serializers.DefaultLoginSerializer(*args, **kwargs)[source]

Default serializer used for user login. Please keep in mind that the authentication is done by separate function defined by ‘LOGIN_AUTHENTICATOR’ setting.

By default ‘LOGIN_AUTHENTICATOR’ function will use ‘USER_LOGIN_FIELDS’ setting to extract the login field from the validated serializer data either by using the ‘login’ key (which is used here) or the specific login field name(s) (e.g. ‘username’, ‘email’).

If you want different behavior, you need to override ‘LOGIN_AUTHENTICATOR’ in your settings.

Custom token generation

One can replace ‘AUTH_TOKEN_MANAGER_CLASS’ with his / her own class, which should inherit from / implement rest_registration.auth_token_managers.AbstractAuthTokenManager. The AbstractAuthTokenManager class has following methods:

class rest_registration.auth_token_managers.AbstractAuthTokenManager[source]
get_app_names() Sequence[str][source]

Return the Django app names which need to be installed so this token manager class works properly.

Overriding this method is not required but recommended as it provides additional check during the Django startup.

get_authentication_class() Type[BaseAuthentication][source]

Return authentication class which is able to parse the token. This is used to ensure that the class is added in REST_FRAMEWORK['DEFAULT_AUTHENTICATION_CLASSES'] setting.

provide_token(user: AbstractBaseUser) AuthToken[source]

Get or create token for given user. If there is no token to provide, raise rest_registration.exceptions.AuthTokenError.

revoke_token(user: AbstractBaseUser, *, token: AuthToken | None = None) None[source]

Revoke the given token for a given user. If the token is not provided, revoke all tokens for given user. If the provided token is invalid or there is no token to revoke, raise rest_registration.exceptions.AuthTokenError.

This method may not be implemented in all cases - for instance, in case when the token is cryptographically generated and not stored in the database.

If you’re using custom authentication class, you should set ‘LOGIN_RETRIEVE_TOKEN’ explicitly to True as token retrieval can be automatically turned on only when rest_framework.authentication.TokenAuthentication (or a subclass) is used.

List of settings

These settings can be used to configure login views. You should add them as keys (with values) to your settings.REST_REGISTRATION dict.

‘LOGIN_SERIALIZER_CLASS’

  • Default: 'rest_registration.api.serializers.DefaultLoginSerializer'

No description available, please add it here!

‘LOGIN_AUTHENTICATOR’

  • Default: 'rest_registration.utils.users.authenticate_by_login_data'

By default the login authenticator function will use ‘USER_LOGIN_FIELDS’ setting to extract the login field from the validated serializer data either by using the ‘login’ key or the specific login field name(s) (e.g. ‘username’, ‘email’). Then, it uses django.contrib.auth.authenticate() to find a matching user.

You can change that behavior by overriding this setting.

The authenticator function receives these parameters as positional arguments:

  • data - the validated data from the login serializer.

and these parameters as keyword arguments:

  • serializer - the source login serializer which generated the input data. This parameter could be dropped in the future, so it should be retrieved via kwargs.get() instead be named directly.

If the user cannot be found, the function should raise UserNotFound exception (from rest_registration.exceptions).

If the user can be found, it should be returned. The implementer should ensure that the right authentication backend (if it was used to find a match) is provided as backend attribute of the returned user.

‘LOGIN_AUTHENTICATE_SESSION’

  • Default: None

No description available, please add it here!

‘LOGIN_RETRIEVE_TOKEN’

  • Default: None

When set to True, the login view will returns the token.

To make sure that the token can be returned, rest_framework.authtoken must be added to the INSTALLED_APPS in your settings.

After added rest_framework.authtoken to the INSTALLED_APPS, you need to run python manage.py migrate to apply changes.

To use the token authentication, you have two options:

add rest_framework.authtoken.authentication.TokenAuthentication to the DEFAULT_AUTHENTICATION_CLASSES in your settings.

or set authentication_classes = [TokenAuthentication] in your view.

example 1:

REST_FRAMEWORK = {
    # ...
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.TokenAuthentication",
        # ...
    ],
}

example 2:

from rest_framework.authentication import TokenAuthentication

class SomeAwesomeView(APIView):
    authentication_classes = [TokenAuthentication]
    # ...

Then you can get token from the login response:

{
    "detail": "Login successful",
    "token": "18eb5c64d21fcc6219facdcd05016d277f92cd90"
}

When you send a request to the protected view, you need to add the token to the request header:

Authorization: Token ${YourToken}

‘AUTH_TOKEN_MANAGER_CLASS’

  • Default: 'rest_registration.auth_token_managers.RestFrameworkAuthTokenManager'

The token manager class used by login and logout which provides an interface for providing and optionally revoking the token. The class should inherit from rest_registration.token_managers.AbstractTokenManager.

‘LOGIN_DEFAULT_SESSION_AUTHENTICATION_BACKEND’

  • Default: None

This setting allows to override the backend used in the login function.

It may be useful if Django AUTHENTICATION_BACKENDS setting does contain multiple values.

The value must be a dotted import path string or None.