Authentication

Overview

Inventario uses Django’s built-in session-based authentication with CSRF protection. The system also supports OAuth 2.0 via Google Sign-In through Django Allauth.

Authentication Methods

Session Authentication

The primary authentication method uses Django sessions with cookies.

curl -X POST http://localhost:8000/login/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=securepassword"

username

string

required

User’s username

password

string

required

User’s password

Response: Redirects to /dashboard/ with session cookie set

Logout

curl -X POST http://localhost:8000/logout/ \
  -H "Cookie: sessionid=<your-session-id>"

Response: Session terminated, redirects to home page

Google OAuth 2.0

Inventario supports Google Sign-In via Django Allauth.

curl http://localhost:8000/accounts/google/login/

This redirects to Google’s OAuth consent screen. After authorization, users are redirected to:

http://localhost:8000/after-google-login/

CSRF Protection

All POST, PUT, DELETE requests require a valid CSRF token.

Getting CSRF Token

From Cookie: Django sets csrftoken cookie on first visit
From HTML Form: Extract from hidden input in rendered forms

Using CSRF Token

Form-Encoded Requests

curl -X POST http://localhost:8000/productos/nuevo/ \
  -H "Cookie: csrftoken=<token>; sessionid=<session>" \
  -H "X-CSRFToken: <token>" \
  -d "nombre=Laptop&precio=1500.00"

AJAX/JSON Requests

fetch('/ventas/api/buscar-producto/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRFToken': getCookie('csrftoken')
  },
  body: JSON.stringify({ codigo_barras: '1234567890' })
})

User Registration

Create New User Account

curl -X POST http://localhost:8000/registro/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=newuser&[email protected]&password1=SecurePass123&password2=SecurePass123"

username

string

required

Unique username

string

required

Valid email address (must be unique)

password1

string

required

Password (minimum length validation applies)

password2

string

required

Password confirmation (must match password1)

Response: User created with admin role by default, redirects to email verification

Email Verification

New users must verify their email address.

Verification Flow

User registers
System generates 64-character token
Verification email sent with link: /verificar-email/<uidb64>/
Token valid for 24 hours
User clicks link to verify

Verify Email Endpoint

curl http://localhost:8000/verificar-email/<uidb64>/

Response: Sets email_verified=True, redirects to login

Password Reset

Inventario implements a custom 6-digit code password reset flow.

Step 1: Request Reset Code

curl -X POST http://localhost:8000/recuperacion/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]"

string

required

Registered email address

Response: 6-digit code sent to email (valid for 10 minutes)

Step 2: Verify Reset Code

curl -X POST http://localhost:8000/recuperacion/verificar/ \
  -d "code=123456"

code

string

required

6-digit verification code from email

Response: Session marked for password reset

Step 3: Set New Password

curl -X POST http://localhost:8000/recuperacion/establecer/ \
  -d "new_password1=NewSecurePass123&new_password2=NewSecurePass123"

new_password1

string

required

New password

new_password2

string

required

Password confirmation

Response: Password updated, redirects to login

User Model

The custom User model extends Django’s AbstractUser:

integer

Unique user identifier

username

string

Unique username

string

Unique email address (required)

rol

string

User role: admin or vendedor

nombre

string

First name (optional)

apellido

string

Last name (optional)

telefono

string

Phone number (optional)

foto_perfil

file

Profile photo upload

foto_google_url

string

Google profile photo URL (for OAuth users)

email_verified

boolean

Email verification status

tutorial_visto

boolean

Whether user has completed tutorial

debe_cambiar_password

boolean

Forces password change on next login (for vendedor accounts)

creado_por

integer

Foreign key to admin user who created this account (for vendedor users)

Role-Based Access Control

Admin Role (`rol='admin'`)

Full access to all endpoints:

Create, edit, delete products
Manage purchases
Create/manage vendedor accounts
Access all reports
System configuration

Vendedor Role (`rol='vendedor'`)

Limited access:

View products (read-only)
Create sales
View own sales history
Cannot modify products or purchases

Enforcing Permissions

Many endpoints use the @admin_required decorator:

from applications.cuentas.decorators import admin_required

@login_required
@admin_required
def crear_producto(request):
    # Only admin users can access
    pass

Response for unauthorized access: HTTP 403 Forbidden

Session Management

Django sets a sessionid cookie upon successful authentication:

Set-Cookie: sessionid=<session-hash>; HttpOnly; Path=/; SameSite=Lax

Session Timeout

Configured in Django settings (default: 2 weeks)

Checking Authentication Status

All views decorated with @login_required will redirect to /login/ if not authenticated.

# Authenticated request
curl http://localhost:8000/dashboard/ \
  -H "Cookie: sessionid=<your-session-id>"

Unauthenticated Response: HTTP 302 redirect to /login/

Security Features

Password Validation

Custom validators in applications.cuentas.validators:

LongitudMinimaValidator - Minimum length requirement
ContraseñaComunValidator - Prevents common passwords
ContraseñaNumericaValidator - Prevents purely numeric passwords

CSRF Protection

Enabled via CsrfViewMiddleware - all state-changing operations require valid CSRF token

Force Password Change

Vendedor users created by admin have debe_cambiar_password=True and are redirected via ForzarCambioPasswordMiddleware until they set a new password.

Example: Complete Authentication Flow

# 1. Get CSRF token
curl -c cookies.txt http://localhost:8000/login/

# 2. Login with credentials
curl -b cookies.txt -c cookies.txt -X POST http://localhost:8000/login/ \
  -H "X-CSRFToken: $(grep csrftoken cookies.txt | cut -f7)" \
  -d "username=admin&password=mypassword"

# 3. Make authenticated request
curl -b cookies.txt http://localhost:8000/productos/

# 4. Logout
curl -b cookies.txt -X POST http://localhost:8000/logout/ \
  -H "X-CSRFToken: $(grep csrftoken cookies.txt | cut -f7)"

Overview

Endpoints

Overview

Authentication Methods

Session Authentication

Logout

Google OAuth 2.0

CSRF Protection

Getting CSRF Token

Using CSRF Token

Form-Encoded Requests

AJAX/JSON Requests

User Registration

Create New User Account

Email Verification

Verification Flow

Verify Email Endpoint

Password Reset

Step 1: Request Reset Code

Step 2: Verify Reset Code

Step 3: Set New Password

User Model

Role-Based Access Control

Admin Role (`rol='admin'`)

Vendedor Role (`rol='vendedor'`)

Enforcing Permissions

Session Management

Session Timeout

Checking Authentication Status

Security Features

Password Validation

CSRF Protection

Force Password Change

Example: Complete Authentication Flow

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Authentication Methods

​Session Authentication

​Login

​Logout

​Google OAuth 2.0

​Initiate Google Login

​CSRF Protection

​Getting CSRF Token

​Using CSRF Token

​Form-Encoded Requests

​AJAX/JSON Requests

​User Registration

​Create New User Account

​Email Verification

​Verification Flow

​Verify Email Endpoint

​Password Reset

​Step 1: Request Reset Code

​Step 2: Verify Reset Code

​Step 3: Set New Password

​User Model

​Role-Based Access Control

​Admin Role (rol='admin')

​Vendedor Role (rol='vendedor')

​Enforcing Permissions

​Session Management

​Session Cookie

​Session Timeout

​Checking Authentication Status

​Security Features

​Password Validation

​CSRF Protection

​Force Password Change

​Example: Complete Authentication Flow

Build docs developers (and LLMs) love

Overview

Authentication Methods

Session Authentication

Login

Logout

Google OAuth 2.0

Initiate Google Login

CSRF Protection

Getting CSRF Token

Using CSRF Token

Form-Encoded Requests

AJAX/JSON Requests

User Registration

Create New User Account

Email Verification

Verification Flow

Verify Email Endpoint

Password Reset

Step 1: Request Reset Code

Step 2: Verify Reset Code

Step 3: Set New Password

User Model

Role-Based Access Control

Admin Role (`rol='admin'`)

Vendedor Role (`rol='vendedor'`)

Enforcing Permissions

Session Management

Session Cookie

Session Timeout

Checking Authentication Status

Security Features

Password Validation

CSRF Protection

Force Password Change

Example: Complete Authentication Flow