django-ai-kit-auth 0.3.1

Index

• Quick Start

• Api Documentation

  • Login

  • Logout

  • Me

  • Registration

  • Initiate Password Reset

  • Password Reset

  • Validate Password

  • Activate User

• Error Codes

Quick Start

1.) Add ai_kit_auth to your INSTALLED_APPS like so:

INSTALLED_APPS = (
    # ...
    "rest_framework",
    # ...
    "ai_kit_auth",
    # ...
    "corsheaders",
)

rest_framework from the pip package djangorestframework and corsheaders from the pip package django-cors-headers are dependencies and must be installed.

The cors headers middleware has to be put into the middleware configuration like so:

MIDDLEWARE = (
    "corsheaders.middleware.CorsMiddleware",
    # ...
)

This middleware has to be put as high as possible in the middlware list.

For more details see the django-cors-headers documentation.

2.) Configuration is namespaced unter AI_KIT_AUTH like so:

AI_KIT_AUTH = {
    "FRONTEND": {
        "URL": "example.com",
    },
    # ...
}

Note that FRONTEND.URL is a required configuration that does not have a default. Default configurations are:

DEFAULTS = {
    # Templates for all the email notifications to the user
    "EMAIL_TEMPLATES": {
        # is send when the user is created by registration
        "USER_CREATED": {
            "TITLE": "ai_kit_auth/user_created_title.txt",
            "BODY_PLAINTEXT": "ai_kit_auth/user_created_body.txt",
            "BODY_HTML": "ai_kit_auth/user_created_body.html",
        },
        # is send to the user after they triggered the forget password
        # feature. Contains the time limited password reset link
        "RESET_PASSWORD": {
            "TITLE": "ai_kit_auth/reset_password_title.txt",
            "BODY_PLAINTEXT": "ai_kit_auth/reset_password_body.txt",
            "BODY_HTML": "ai_kit_auth/reset_password_body.html",
        },
    },
    # If true, the user has to specify a username in addition to the
    # mail address
    "USERNAME_REQUIRED": False,
    # information about the frontend, mostly the used routes. In most cases
    # the defaults are fine, but can be changed for localisation of the
    # urls.
    # Only the actual frontend url is unset and you will get an
    # configuration error if you don't specify it.
    "FRONTEND": {
        "URL": "",
        "ACTIVATION_ROUTE": "/auth/activation/",
        "RESET_PW_ROUTE": "/auth/reset_password/",
    },
}

In addition to that some general configuration is required:

CORS_ORIGIN_WHITELIST = [
    "http://localhost:8000",
    "http://localhost:3000",
    # add other front-end backend urls
]

CORS_ALLOW_CREDENTIALS = True

CSRF_USE_SESSIONS = True

CSRF_TRUSTED_ORIGINS = [
    "http://localhost:8000",
    "http://localhost:3000",
    # add other front-end backend urls
]

The CSRF_USE_SESSIONS configuration doesn’t need to be set to enable Ai-Kit-Auth, but in prevents problems with double logins, for example if a user is logged into the Admin interface and also logged in the frontend. Django saves CSRF tokens in cookies by default.

3.) Include the routes in your urls.py:

urlpatterns = [
    # ...
    path("api/v1/auth/", include("ai_kit_auth.urls"))
    # ...
]

4.) Run python manage.py migrate. Only required if you add the dependencies to your project since this package does not define models on its own.

Login

POST ../login/

visibility: everyone

expects

{
    ident: <username or email>,
    password: <the password>
}

both fields are required. The endpoint answers with the status code 200 and

{
    user: {
        username: <the username>,
        email: <the email address>,
        id: <the internal id>,
    },
    csrf: <csrf token>
}

Error cases:

Field specific errors are given back like so:

{
    <field name>: <error code>
}

fields are ident or password and the only possible error code is blank.

Errors that are not field specific are mapped to the key non_field_errors. Currently, the only error code that can be returned here is invalid_credentials.

Logout

POST ../logout/

visibility: authenticated users

expects

{}

and answers with status code 200 and

{
    csrf: <csrf token>
}

At least when the csrf token is stored via session storage, it changes at logout and you have to update it in the frontend.

Me

GET ../me/

visibility: everyone

The answer is very similar to login: status code 200 and

{
    user: null | {
        username: <the username>,
        email: <the email address>,
        id: <the internal id>,
    },
    csrf: <csrf token>
}

The only difference is that me is reachable for anonymous users that are not (yet) logged in. In that case, the user property is set to null.

Error Codes

The backend never sends user facing error messages, but general error codes. Internationalisation happens in the frontend.