Skip to main content

Django Quickstart

Add authentication to your Django application in 5 minutes using the django-syauth package.

Before You Begin​

info

You need these credentials before starting. Get them from the SyAuth Dashboard.

What You NeedWhere to Find ItExample
Client IDDashboard → OAuth Clients → Your Appa1b2c3d4-5678-90ab-cdef-...
API KeyDashboard → API Keysxxxxxxxxxxxxx

New to SyAuth? Follow these steps first:

  1. Create a Nexorix account (SyAuth uses Nexorix for authentication)
  2. Create your first Application to get your credentials
  3. Choose Public Client type (recommended, uses PKCE)
  4. Add http://localhost:8000/auth/callback/ as a Redirect URI

Prerequisites​

  • Python 3.8+ and Django 4.2+
  • A SyAuth account with an Application created

Step 1: Install the SDK​

pip install django-syauth

This package handles OAuth authentication, token management, and user creation automatically.

Step 2: Configure Settings​

Update your settings.py with SyAuth configuration:

# settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add django_syauth
    'django_syauth',
]

# Add SyAuth authentication backend
AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',  # Keep for admin access
    'django_syauth.backend.SyAuthBackend',         # Add SyAuth authentication
]

# SyAuth Configuration
# Get these values from Dashboard → OAuth Clients → Your App
SYAUTH = {
    # The SyAuth API endpoint (include /e/v1 at the end)
    'API_URL': 'https://api.syauth.com/e/v1',
    
    # Your Client ID from the Dashboard
    'CLIENT_ID': 'your-client-id-here',

    # Your API Key from Dashboard → API Keys
    'API_KEY': 'your-api-key-here',
    
    # Where SyAuth redirects after login - must match Dashboard config!
    'REDIRECT_URI': 'http://localhost:8000/auth/callback/',
}

# Django login/logout settings
LOGIN_URL = '/auth/login/'           # Redirect here when @login_required fails
LOGIN_REDIRECT_URL = '/'             # Redirect here after successful login
LOGOUT_REDIRECT_URL = '/'            # Redirect here after logout

Configuration Parameters​

ParameterRequiredDescription
API_URL✅SyAuth API endpoint. Always include /e/v1 at the end
CLIENT_ID✅Your application's public identifier from the Dashboard
API_KEY✅Your workspace API Key for backend operations
REDIRECT_URI✅Must exactly match the Redirect URI in your Dashboard
tip

Production best practice: Use environment variables for secrets:

import os

SYAUTH = {
    'API_URL': os.environ.get('SYAUTH_API_URL'),
    'CLIENT_ID': os.environ.get('SYAUTH_CLIENT_ID'),
    'API_KEY': os.environ.get('SYAUTH_API_KEY'),
    'REDIRECT_URI': os.environ.get('SYAUTH_REDIRECT_URI'),
}

Step 3: Configure URLs​

Add the SyAuth authentication routes to your project's urls.py:

# your_project/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    
    # Add SyAuth authentication routes
    path('auth/', include('django_syauth.urls')),
    
    # Your app's routes...
    path('', include('your_app.urls')),
]

What this adds:

URLPurpose
/auth/login/Redirects to SyAuth Universal Login page
/auth/callback/Handles OAuth callback, exchanges code for tokens, creates/updates user
/auth/logout/Logs out user from Django and SyAuth

Add login and logout links to your templates:

<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
    <title>My Django App</title>
</head>
<body>
    <nav>
        {% if user.is_authenticated %}
            <span>Welcome, {{ user.first_name }}!</span>
            <a href="{% url 'syauth:logout' %}">Sign Out</a>
        {% else %}
            <a href="{% url 'syauth:login' %}">Sign In</a>
        {% endif %}
    </nav>

    <main>
        {% block content %}{% endblock %}
    </main>
</body>
</html>

Step 5: Protect Views​

Use Django's standard @login_required decorator to protect views:

# views.py
from django.contrib.auth.decorators import login_required
from django.shortcuts import render

@login_required
def dashboard(request):
    # request.user is a standard Django User object
    # populated with data from SyAuth (email, first_name, last_name)
    return render(request, 'dashboard.html', {
        'user': request.user
    })

@login_required 
def profile(request):
    return render(request, 'profile.html', {
        'email': request.user.email,
        'first_name': request.user.first_name,
        'last_name': request.user.last_name,
    })

For class-based views, use LoginRequiredMixin:

from django.contrib.auth.mixins import LoginRequiredMixin
from django.views.generic import TemplateView

class DashboardView(LoginRequiredMixin, TemplateView):
    template_name = 'dashboard.html'

How it works: When an unauthenticated user tries to access a protected view, Django automatically redirects them to /auth/login/, which redirects to SyAuth. After login, they're sent back to their original destination.

Test Your Integration​

  1. Run migrations (if needed):

    python manage.py migrate

  2. Start the development server:

    python manage.py runserver

  3. Open http://localhost:8000

  4. Click "Sign In"

    • You'll be redirected to the SyAuth login page
    • Log in or create an account
    • You'll be redirected back to your app, now authenticated!

Done! 🎉​

Your Django application now has:

  • ✅ OAuth 2.0 authentication with PKCE
  • ✅ Automatic user creation and sync
  • ✅ Session management
  • ✅ Protected views with @login_required
  • ✅ Standard Django User integration

Advanced Configuration​

Custom User Model​

If you use a custom user model, django-syauth automatically detects and uses it. Ensure your model has these fields:

# models.py
from django.contrib.auth.models import AbstractUser

class CustomUser(AbstractUser):
    # These fields are required for SyAuth integration
    email = models.EmailField(unique=True)
    first_name = models.CharField(max_length=150)
    last_name = models.CharField(max_length=150)
    
    # You can add extra fields
    avatar_url = models.URLField(blank=True)

Custom Claims Mapping​

Map additional claims from the ID token to your user model:

# settings.py
SYAUTH = {
    'API_URL': 'https://api.syauth.com/e/v1',
    'CLIENT_ID': 'your-client-id',
    'REDIRECT_URI': 'http://localhost:8000/auth/callback/',
    
    # Map JWT claims to user model fields
    'CLAIMS_MAPPING': {
        'picture': 'avatar_url',   # Maps 'picture' claim → 'avatar_url' field
        'locale': 'language',       # Maps 'locale' claim → 'language' field
    },
}

Troubleshooting​

"Invalid redirect_uri" Error​

Cause: The REDIRECT_URI in settings doesn't match your Dashboard configuration.

Fix:

  1. Go to Dashboard → OAuth Clients → Your App → Redirect URIs
  2. Ensure http://localhost:8000/auth/callback/ is listed (note the trailing slash!)
  3. The URI must match exactly

"Unauthorized / Invalid Client" Error​

Cause: Your Application is not configured as a Public Client or the Client ID is incorrect.

Fix:

  1. Go to Dashboard → OAuth Clients → Your App.
  2. Ensure Client Type is set to Public (required for PKCE flow).
  3. Verify the CLIENT_ID in your settings matches the one in the Dashboard.

User Not Created After Login​

Cause: Missing required fields in your custom user model.

Fix: Ensure your user model has email, first_name, and last_name fields.

Session Expires Immediately​

Cause: Session middleware not properly configured.

Fix: Ensure django.contrib.sessions.middleware.SessionMiddleware is in your MIDDLEWARE setting.

Next Steps​