DEV Community: Soldatov Serhii

From Django Library to AWS Cognito: My Journey Building Enterprise SSO

Soldatov Serhii — Sun, 12 Apr 2026 08:33:36 +0000

The Client Call That Started Everything

"We need SSO. Multiple providers. Per client. Starting next sprint."

That was the moment I realized I had no idea what I was actually getting into.

I'd built auth flows before — JWT, session-based, OAuth2 callbacks. But enterprise SSO at scale, where each tenant brings their own identity provider, where role sync needs to be automatic, where a user getting removed from an Azure group means they lose access in your app within minutes? That's a different animal entirely.

This is the story of how I went from frantically Googling "Django SSO library" to building a production system on AWS Cognito that handles Azure AD, Okta, and any OIDC provider — without touching a line of server code when a new provider is added.

V1: Wrestling a Library into Submission

The Starting Point

My first search led me to django-simple-sso — the only SSO-focused library I could find for Django at the time. The bones were reasonable. The problem? It was designed for one provider, one configuration, one-to-one everything.

My requirements were the opposite:

Multiple providers per client (a client might have Azure AD and Okta)
Dynamic provider selection by email domain
Automatic role mapping: admin, manager, etc., synced from the provider
Per-tenant configuration, entirely isolated

The Rearchitecture

So I stopped trying to configure the library and started reading its internals. Then I started rewriting them.

The data model went from one-to-one relationships to many-to-many. The auth flow got rewritten for dynamic provider resolution — when a user types their email, the backend queries which SSO configs are associated with that domain, selects the right provider, and redirects accordingly. Role mapping got its own layer.

Three weeks of heads-down work. By the end, it covered everything: multiple providers, automatic role sync, dynamic authentication. It was custom, it was complex, and it worked.

Until the next client call.

The Problem That Forced V2

The Request

"We need to add a new provider."

Fine. I'd done it before. Except this one was an obscure, legacy enterprise identity system — the kind that's only used in certain American B2B markets, where getting test credentials means purchasing a suite of products and weeks of vendor coordination. We literally could not test against it without significant time and cost investment.

And that's when the real problem became obvious: every new provider required code changes. Test access. Adjustment cycles. The library abstraction I'd built was still fundamentally tied to providers I could understand and validate myself.

The client's roadmap had more providers coming. We needed something universal.

The Decision

We removed everything. The library, the custom SSO code, all of it.

And we moved to AWS Cognito.

V2: Why Cognito Changed Everything

AWS Cognito sits between your application and any external identity provider. It speaks OIDC to the providers (Azure AD, Okta, Google, SAML, whatever) and speaks a single, consistent OAuth2 flow back to your app.

The transformation this unlocked:

Before (V1):
App <--> Custom SSO code <--> [Azure-specific logic] <--> Azure AD
                          <--> [Okta-specific logic]  <--> Okta
                          <--> [???-specific logic]   <--> Unknown provider

After (V2):
App <--> Cognito <--> Azure AD
                <--> Okta
                <--> Any OIDC provider

Adding a new provider now requires zero server-side code changes. Cognito normalises everything. The token your app receives is identical regardless of which provider the user authenticated against.

What We Built

The Django application I'm open-sourcing handles:

Dynamic config discovery — GET /api/oidc/check_config_exists/<email>/ returns the right Cognito client config for a given email domain
OAuth2 callback — exchanges the authorization code, decodes the ID token, maps roles, creates/updates the user and their membership record
Automated Cognito provisioning — clients send their identity provider credentials via a web form; the backend calls AWS APIs to configure the Cognito User Pool, no manual AWS console work required
Lifecycle events via webhooks — Azure AD and Okta can notify the app when a user is removed from a group or deleted. The system soft-deletes their membership, revoking access automatically

Browser          Django              Cognito          Azure AD / Okta
  |                 |                   |                   |
  |-- check email ->|                   |                   |
  |<- client_id  ---|                   |                   |
  |                 |                   |                   |
  |-------- redirect to Cognito ------->|                   |
  |                                     |--- OIDC flow ---->|
  |                                     |<-- user token ----|
  |<-------- redirect with ?code= ------|                   |
  |                 |                   |                   |
  |-- /callback  -->|                   |                   |
  |                 |-- exchange code ->|                   |
  |                 |<-- id_token ------|                   |
  |                 | decode + map roles                    |
  |                 | create/update User + Member           |
  |<- access_token--|                   |                   |

The Article Series

This repo comes with a full series of step-by-step guides. Think of them as the manual that I wish had existed when I started:

1. How to Configure AWS Cognito for SSO: A Step-by-Step Guide
The foundation. User Pool setup, custom attributes (custom:groups, custom:roles), app client configuration, and the callback URL wiring. Start here.

2. Azure Single Sign-On (SSO) Setup: A Step-by-Step Guide
Enterprise App registration in Azure AD, configuring OIDC claims, mapping Azure groups to Cognito attributes. Includes the Graph API setup for lifecycle webhooks.

3. Okta Single Sign-On (SSO) Setup: A Step-by-Step Guide
Okta application setup, OIDC configuration, group claims, and the Event Hook configuration for real-time deprovisioning.

4. How to Set Up SSO Authentication in Your App's Admin Panel
The Django side: the authentication backend, the callback handler, role mapping, and how the admin panel reflects SSO-managed memberships.

5. How to Test SSO Authentication with Cognito and OIDC Providers
End-to-end testing strategy — what to mock, what to hit for real, and the test patterns used in this repo.

The Repository

The code is on GitHub: django-cognito-sso-demo

It's a reference implementation, not a drop-in package. The parts you'll want to adapt for your own system:

apps/oidc_auth/services/sso.py — core SSO orchestration: config lookup, token exchange, role mapping
apps/oidc_auth/backends.py — Django authentication backend wired to Cognito
apps/users/cognito.py — boto3 wrapper for all Cognito API calls
apps/oidc_auth/services/notification.py — webhook processing for Azure and Okta lifecycle events

One intentional simplification worth noting: RightsHolderService.get_rights_holder_from_request resolves the tenant from the request user directly. In production, tenant resolution typically comes from middleware or a partnership context. Replace it with whatever your multi-tenancy layer provides.

What I'd Tell Past Me

Don't start with a library. Or rather: start with one to understand the problem space, but be honest about when you've outgrown it. The three weeks I spent rearchitecting django-simple-sso taught me exactly what I needed to know to make Cognito work well — I don't regret the time, but I wish I'd recognised sooner that the constraint wasn't the library, it was the model.

The "universal provider" requirement is the forcing function. If you know upfront that you need to support arbitrary OIDC providers without code changes, skip straight to an identity broker. Cognito is the obvious choice in AWS environments. There are others (Auth0, Keycloak). The architecture is the same.

Lifecycle events are not optional for enterprise. User deprovisioning is a security requirement, not a nice-to-have. Budget for the webhook infrastructure and the soft-deletion logic early. It's much harder to retrofit.

Encrypt your client secrets. SSOAccountConfig uses django-encrypted-model-fields for client_id and client_secret. If you're storing provider credentials in your database — and you will be — this is non-negotiable.

Where This Goes Next

The system in this repo handles everything the original client needed. The architecture has stayed stable through adding new providers, new tenants, and changes in the underlying identity providers themselves.

If you're building something similar and hit a wall, the article series has the detail. The repo has the code. And if neither answers your question, drop it in the comments.

Source code: github.com/your-username/django-cognito-sso-demo

How to Set Up SSO Authentication in Your App's Admin Panel

Soldatov Serhii — Sun, 12 Apr 2026 08:01:36 +0000

Prerequisites for all OIDC Providers

This guide covers the admin setup for SSO authentication built with Django and AWS Cognito. The full reference implementation is available on GitHub: django-cognito-sso-demo.

How SSO Works in This Setup

The user authenticates via an external OIDC provider (e.g., Azure or Okta)
AWS Cognito federates the identity
Your application validates:
- group membership
- email domain
Access is granted or denied

Requirements

Before configuring SSO, ensure the following:

Add an OIDC Provider to your Cognito User Pool
- Requires: Client ID, Client Secret, Issuer ID
Configure the groups claim in your OIDC provider

Important: This is required for group validation to function properly
Add a custom groups attribute in Cognito

Important: The attribute name must match the groups claim used by your OIDC providers

Provider Setup Guides

Azure Single Sign-On (SSO) Setup: A Step-by-Step Guide

Okta Single Sign-On (SSO) Setup: A Step-by-Step Guide

Other OIDC providers typically follow a similar setup process.

Creating SSO Account Configuration

After entering the admin panel, find SSO Account Configs under the OIDC Auth application and click Add.

Setting up SSO Account Configuration

To configure an SSO Client provider, you need the Client ID, Client Secret from you Cognito App Client, you can copy this in your App Client page.

Choose your Account.

Important: Only accounts with the required permissions can be selected in this field by SSO requirements.
Enter your application Cognito Client ID, Cognito Client Secret.
Enter Provider Names from your Cognito App client, one of the values in this list can be used as identity_provider in /oauth2/authorize Cognito URI.
Enable Is active to activate this provider.
Allowed Domains — users whose email domain matches one of these domains will be allowed to access your application via this SSO configuration.
Enter the OIDC Provider Groups that should have access your application via this SSO configuration.

Important: Only users who belong to these groups will be able to sign in.

Warning: The group name must exactly match the format in your OIDC provider’s ID token.

Make sure to check the correct group format (e.g., Okta = group name, Azure = group object ID).
Finally, click Save.

Here is an example of a completed form for my Account and Cognito application client.

SSO Notification Configuration

Azure

To configure SSO Provider Notification Config for Azure, you need the Client ID, Client Secret, and Tenant ID from your Azure application (copied during the final step of the Azure configuration documentation).

Choose Azure as a Provider Name.
Choose your Azure SSO Provider.
Enter your Azure application Client ID, Client Secret and Tenant ID.
Enter Notification url to your application Notification URL Endpoint (in my example it is https://dev.yourapp.com/api/oidc/notifications/azure).
Finally, click Save.

Okta

No additional configuration is required if Event Hooks are set up correctly.

Soft-delete functionality will work automatically.

✅ You have now successfully created SSO Providers in your application and can test it!

Admin API (Automating Setup)

POST /api/oidc/cognito/setup/

Purpose:

These endpoints automate the setup of SSO in Cognito and your app, reducing manual configuration and ensuring consistent integration between external OIDC providers and Cognito App Clients.

Creates one or more External Identity Providers inside the Cognito User Pool and then creates a Cognito App Client that is linked to all providers specified in the providers field.

!Important: This endpoint requires admin or privileged user access.

Request Fields:

provider (required)

An external OIDC provider to create in the Cognito User Pool.

Each provider entry must include:

client_id - Identity Provider Client ID
client_secret - Identity Provider Client Secret
oidc_issuer - Identity Provider Issuer URL

group

A group name used for group validation during the SSO login flow if the user does not exist in your app.

Make sure to check the correct group format in your provider first (for example, for Okta it’s the group name, while for Azure it’s the group object ID). Otherwise, group validation won’t be working.

allowed_domain

Users with this email domain will be allowed to access your application via this SSO configuration.

Example request for Okta:

{
    "provider": {
        "client_id": "0oavpnkcas2Otd5s697", // Identity Provider Client ID
        "client_secret": "YRlFfB8wXkEkIasdWlmxC_UQenDNWTbCLmhasdGGBoDKsF00njihZ", // Identity Provider Client Secret
        "oidc_issuer": "https://integrator-2000932.okta.com/oauth2/default"  // Identity Provider Issuer URL (Okta Format)
    },
    "group": "ada2a854-1asdd-475b-8e00-c7841dc99147", // Okta format group
    "allowed_domain": "test-company.com"  // Allowed domain for SSO Provider
}

Example Request for Azure AD:

{
    "provider": {
        "client_id": "b4asdaf-315c-4236-964b-d0d6ebbe6725", // Azure App Client ID
        "client_secret": "XOQ8Q~iUoWahILy6mpzIvsoSsGZT7cii", // Azure App Client Secret
        "oidc_issuer": "https://login.microsoftonline.com/d277adb7-1729-42x2-98a0-asda0b7/v2.0"  // Azure App Issuer URL
    },
    "group": "asds2-1f3d-475b-8e00-c7841dc99147", // group fom Azure AD
    "allowed_domain": "test-company.com"  // Allowed domain for SSO Provider
}

Possible Errors:

Provider does not exists in User Pool 400:

{
    "status": "failed",
    "message": "Failed to create Cognito client or SSO provider.",
    "error": "{'message': ErrorDetail(string='The provider TestProvider does not exist for User Pool eu-north-1_....', code='cognito_error')}"
}

Provider with same name already exists in User Pool 400:

{
    "status": "failure",
    "message": "Failed to create OIDC provider.",
    "error": "{'message': ErrorDetail(string='OktaTestProvider already exists for tenant eu-north-1_....', code='cognito_error')}"
}

Successful Response 201:

{
    "status": "success",
    "message": "OIDC provider created successfully."
}

Triggering Azure notification events

To trigger a soft-delete of a user in your application, you need to either remove the user from an Azure group or fully delete the user from Azure IAM.

Delete user from group:

To soft-delete a user from all rights holders where the user was, you need to remove the user from the corresponding Azure AD group (the group with the objectId defined in your SSO Client Provider).

Step 1: Navigate to Group

Go to: Your Azure Active Directory instance → Groups → All groups
Click on the Group to which you want to delete users.

Step 2: Navigate to Members tab

Click the “Members” button on the sidebar.

Step 3: Remove members from the Groups

Select the users you want to remove from the group.
After you select all users you want to delete from the group. Click Remove.
A modal window will appear with the configuration form. Click Yes

After this, if a member with this ObjectID exists in your app, the system will soft-delete the user.

Delete user from IAM:

Step 1: Navigate to Users Page

Go to: Your Azure Active Directory instance → Users.
Select the users you want to delete.
Click the “Delete” button, then confirm by clicking “Ok” in the modal window.

Step 2: Navigate to Deleted users tab

Click the “Deleted users” button on the sidebar.

Step 3: Permanently delete the User

Select the user you delete in Step 1 or you want to delete.
Click “Delete permanently”, then confirm by clicking “Ok” in the modal window.

After this, the selected users will be completely deleted from Azure IAM.

If a user with the same User ObjectID exists in your app, that user will also be soft-deleted from your app.

Note: The User ObjectID is linked to a user in your app only after the user logs into your app via the Azure SSO Provider.

Okta: Triggering Notification Events

To trigger a soft-delete of a user in your application, you need to either remove the user from an Okta group or fully delete the user from Okta IAM.

Delete user from group:

To soft-delete a user from all rights holders where the user was, you need to remove the user from the corresponding Okta group (the group with the Group name defined in your SSO Client Provider).

In the side menu, navigate to the Groups page and click on the group which you want to remove users:

Next to the user you want to remove, click on the cross (x) icon and the user will be removed.

Once the user is removed from the group, they will be soft-deleted in your application.

Note: Users will be removed only when deleted from groups that are present in your app SSO Providers Group name, if not this event hook will be skipped.

Delete user from IAM:

In the side menu, navigate to the People page and select the the user which you want to delete:

You will be redirected to the User Profile page. Click on the More Actions button, then click Deactivate to deactivate the user.

A modal window will appear with. Click Deactivate.

Then after the user deactivated, the Delete button will appear. Click Delete to completely delete the user from IAM.

A modal window will appear with. Click Delete.

After this, the selected user will be completely deleted from Okta IAM.

If a user with the same email exists in your application, that user will also be soft-deleted in your application.

How to Test SSO Authentication with Cognito and OIDC Providers

Soldatov Serhii — Sun, 12 Apr 2026 07:51:41 +0000

Prerequisites for all OIDC Providers

This guide covers the admin setup for SSO authentication built with Django and AWS Cognito. The full reference implementation is available on GitHub: django-cognito-sso-demo.

To ensure SSO works correctly in your application, you must complete the following steps:

Add OIDC Provider to the Cognito user pool to External Providers, for this you need Client ID, Client Secret and Issuer ID of OIDC Provider.
Make sure that SSO Provider with this App Client credentials exists on your application.
Configure the “groups” claim in the ID Token on your OIDC provider.

This is required for group validation to function properly in SSO.

Add a custom group claim to Cognito by creating a custom attribute named groups.

The name must match the “groups” claim used in all OIDC providers that will be included in your application SSO.

After setting up the Admin Panel, we are ready to test SSO authentication.

Provider Setup Guides

Azure Single Sign-On (SSO) Setup: A Step-by-Step Guide

Okta Single Sign-On (SSO) Setup: A Step-by-Step Guide

Other OIDC providers typically follow a similar setup process.

Log in via Cognito

Step 1: To log in to your application via the Azure SSO Provider, send a GET request to:

<cognito_domain>/login?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code&scope=openid&state=<client_id>

where:

cognito_domain - the AWS Cognito Domain
region - the AWS region where your Cognito User Pool is hosted (e.g., eu-central-1);
client_id - the Cognito App Client ID for the specific tenant (client);
redirect_uri - the callback URL configured in Cognito for your application (e.g., https://yourapp.com/api/oidc/cognito/callback/);
state - a parameter used to maintain state between the request and callback (here you must reuse the client_id).
Click on your Continue with your OIDC Provider name, that you enter in Cognito.

Step 2 After sending the request, you will be redirected to the Your OIDC Provider login page, in my case it’s Microsoft login page. Click Receive Code.

Step 3: Enter the code sent to user_email, then click Yes.

Step 4: After successful authentication, you will receive a response with your authentication tokens.

Step 5: To check if a user was actually created after SSO login, you can:

Check via the Admin Panel: Go to Admin Panel → Users and search for the user by email.
Check via API: Send a GET request to: /api/users/me/

Testing Log out

To log out, send a POST or GET request to:

/api/oidc/cognito/logout/

After successful logout you will receive a response with your message “Logout successful”.

Group Validation

If the user is not a member of the IAM group, the group name is incorrect in the Admin Panel for the SSO Provider, or the user’s email domain is not linked with a rights holder of the app_id, the login attempt will fail, showing an error, where provider 19 is SSO Client Provider ID.

✅ You have now successfully SSO authentication!

How to Configure AWS Cognito for SSO: A Step-by-Step Guide

Soldatov Serhii — Sun, 12 Apr 2026 07:51:07 +0000

Creating App Client for Each Customer

According to the multi-tenant application model, we need to create a separate Cognito App Client for each customer and attach their corresponding external OIDC providers.

Step 1: Creating Application Client

To create App Client navigate to Application - App client, click to Create App Client

In the setup form, choose Traditional web application as the application type.

Step 2: Adding custom attribute

To include user groups in the ID token, we need to add a custom attribute to the Cognito User Pool.

Navigate to Authentication - Sign Up, then click Add custom attribute:

In the form, enter the attribute name as shown below, and then click Save changes.

Adding roles custom attribute

If “roles” scope is configured in Customer OIDC provider, you can add a custom “roles” attribute as well and include this attribute in External Cognito Provider.

Step 3: Creating External Provider

Navigate to Authentication - Social and external providers

In from enter your OIDC Provider credentials, Client ID, Client Secret and Issuer URI.
Add custom “groups” attributes that you created in the previous step and include email attributes. (username will be added automatically after you created the provider).

!Important: In the form, enter the OpenID Connect attribute to groups exactly as shown below, and then click Save changes.

Clarification: We configure these attributes so that the group and role information (optional) is included in the ID Token returned by the Identity Provider. If your application uses different scope names, make sure to update the values in the Cognito accordingly (for example, if Provider sends roles under app_groups scope, you should set OpenID Connect attribute to app_groups).

Info: If you added a “custom:roles” attribute in the previous step, you can include the “roles” attribute here as well.

Step 4: Attach External Provider to App client

Navigate to App Clients - Your App - Login Pages
Click Edit button.

In the configuration form:

Add allowed callback URLs (e.g.

https://yourapp.com/api/oidc/cognito/callback/

or http://localhost:8000/api/oidc/cognito/callback/ for local testing).

Attach the identity providers you created in the previous steps.
!Important: Under OpenID Connect scopes, select only the OpenId scope.
Click Save changes.

After custom attributes setup check in Attribute Permission that Read and Write permissions are checked:

Step 5: Attach Login Page to the App client

Navigate to Your User Pool - Managed login.
Click Create a style button.

Select the App client you want to attach a login page to.
Click Create.

After creation, the login page for your App Client will become available and can be accessed directly via its generated URL.

How to connect to your application

To enable Cognito login for your users in your application, you need to retrieve the following three parameters:

Client ID
Client Secret
User Pool Cognito domain

You can find this data on our Cognito User Pool and App client pages.

To copy Client ID and Client Secret Navigate to corresponding App client:

To get User Pool Cognito domain, navigate to Domain page:

✅ Cognito Setup Complete. Your Cognito configuration is now complete and ready for SSO testing.

Okta Single Sign-On (SSO) Setup: A Step-by-Step Guide

Soldatov Serhii — Sat, 11 Apr 2026 15:36:12 +0000

Configuring SSO authentication in Okta

After logging into the Okta panel, you will be redirected to the dashboard. From here, we will configure Okta to enable Single Sign-On (SSO) authentication for our application.

Assigning users to group

We need to add groups and add the required users to the appropriate group.

!Note: Only users who are members of this group will be able to sign in to your application.

In the side menu, navigate to the Groups page

then click to the Add group button

A modal window will appear with the configuration form.

Fill this form with the group name and description, then click the Save button.

In the side menu, navigate to the People page, then choose a particular person in the list and click to navigate to the Person page

Click on the Groups subtitle to navigate to the profile page

Click on the Search field and enter the group name that you want to assign the user with, then click to the appearing group.

Creating an application

An application refers to a cloud or on-premises service integrated with Okta for single sign-on, enabling users to securely access and authenticate across multiple applications with a single set of credentials.

Next, navigate to the Applications page (as shown in the screenshot)

Click on the Create App Integration button

A modal window will appear with configuration options. Select the options as shown in the screenshot, then click the Next button.

You will be redirected to the configuration page:

Follow the instructions below and configure the settings as marked in the next two screenshots:

I will set my app name to "SSO OIDC", but you can use just "your application".
Sign-in redirect URIs: The format should be: https://<your-user-pool-domain>/oauth2/idpresponse where <your-user-pool-domain> is your Cognito User Pool Domain

(example: https://eu-north-2uasd2wr7mv.auth.eu-north-1.amazoncognito.com/oauth2/idpresponse).

Sign-out redirect URIs: This ensures users are properly signed out when logging out of our application. Input: https://yourapp.com/
Right holder access: choose the Limit access to selected groups option and enter group names you want to give access to your application application.
Click on the Save button.

You will then be redirected to the newly created application's page.

Configuring a User Okta profile (Add Roles to Profile)

In Okta, we can define roles for users to manage permissions within our application.

These roles determine the level of access a user has, such as admin, manager, etc.

In the side menu, navigate to the Profile Editor page

Click to User (default) link to open User Okta Profile edit page:

Click on the Add Attribute button to add a new attribute for roles in the Okta User profile:

A modal window will appear with configuration form.

Fill this form as shown in the following screenshot, then click the Save button.

Configuring an OIDC client profile for the app

In the side menu, navigate to the Profile Editor page:

Click on the SSO OIDC User (name of our application) link to navigate to the OIDC Client Profile edit page:

Click on the Add Attribute button to add a new attribute for roles in the OIDC Client Profile.

A modal window will appear with configuration form.

Fill this form as shown in the following screenshot, then click the Save button.

Click on the Mappings button to configure the mapping between the Okta User Profile and the OIDC Client Profile:

A modal window will appear with configuration fields for each relation.

Slide to the last field, type in the field user.userRoles. Click on the relation button which mark on the following screenshot:

Choose an Apply mapping on user create and update option:

Now, this should look like as shown below. Click on the Save Mappings button.

Configuring an API Authorization

In the side menu, navigate to the API page

Click on the default link (I use default_2, because default in my account already configured), which is marked in the following screenshot:

Configuring a group scope

Now, let's configure scopes to define the permissions our application can request.

Click on the Scopes subtitle to navigate to the scopes configuration page:

Click on the Add Scope button to add a new scope, which will be used for groups

A modal window will appear with configuration form. Fill this form as shown in the following screenshot, then click the Create button.

!Important: Scope name must be "groups", values in the "Display phrase" and "Description" fields are not that important.

Configuring role scope

Click on the Add Scope button to add a new scope, which will be used for roles

A modal window will appear with configuration form. Fill this form as shown in the following screenshot, then click the Create button.

Configuring a new groups claim

Configuring a claim after the scope for Okta SSO ensures that the appropriate user attributes are securely included in the authentication token, enabling seamless access control and personalized experiences across integrated applications.

Click on the Claims subtitle to navigate to the claims configuration page:

Click on the Add Claim button to add a new claim, which will be used for groups:

A modal window will appear with configuration form. Fill this form as shown in the following screenshot, then click the Create button.

!Important: Claim name must be "groups" and all other values must be identical as on screenshot!

Configuring a new roles claim

Click on the Add Claim button to add a new claim, which will be used for roles.

A modal window will appear with configuration form. Fill this form as shown in the following screenshot, then click the Create button.

Configuring a new access policy

Access policies and rules in Okta SSO allow administrators to define and enforce conditions for user authentication, ensuring secure and granular control over who can access applications based on factors like location, device, and user group.

Click on the Access Policies subtitle to navigate to the access policies configuration page:

Click on the Add Policy button to add a new policy:

A modal window will appear with a configuration form. Fill this form as shown in the following screenshot, then click the Create Policy button.

Click on the Add rule button to add a new rule

A modal window will appear with the configuration form. Fill in this form as shown in the screenshot.

In the "User is" section, select the group you want to allow access to your application.
In my case, it is the users from "test_group".

You can also add individual users if needed.

Then, click the Create rule button.

Only users who are members of the selected group (and assigned the app) will be able to sign in.

Configuring a new Event Hooks

Event Hooks in Okta SSO allow your application to track IAM related events.
We will create an event hook that listens for two specific events:

User removed from group
User deleted

These events will trigger a soft delete of the corresponding user in your application.

In the side menu, navigate to the Event hooks page:

Click on the Create Event Hook button to add an event hook

A modal window will appear with a configuration form.

Fill this form as shown in the following screenshot, then click the Save & Continue button.

Another more modal window will appear with a configuration form.

Click Verify to confirm that the webhook is active and reachable.

You will then be redirected to the newly created event hook page.

Assigning user roles

In the side menu, navigate to the People page, then choose a particular person in the list and click to navigate to the Person page

Click on the Profile subtitle to navigate to the profile page

Click on the Edit button to enable editing attributes of the profile. Slide down to the bottom of the page.

Now, you can choose any number of roles from the list for the particular user. Click the Save button.

Deleting users

Delete user from group:

To trigger a soft-delete of a user in your application, you need to either remove the user from an Okta group or fully delete the user from Okta IAM.

To soft-delete a user from all rights holders where the user was, you need to remove the user from the corresponding Okta group (the group with the Group name defined in your SSO Client Provider).

In the side menu, navigate to the Groups page and click on the group which you want to remove users:

Next to the user you want to remove, click on the cross (x) icon and the user will be removed.

Once the user is removed from the group, they will be soft-deleted in your application.

Note: Users will be removed only when deleted from groups that are present in your app SSO Providers Group name, if not this event hook will be skipped.

Delete user from IAM:

In the side menu, navigate to the People page and select the the user which you want to delete:

You will be redirected to the User Profile page. Click on the More Actions button, then click Deactivate to deactivate the user.

A modal window will appear with. Click Deactivate.

Then after the user deactivated, the Delete button will appear. Click Delete to completely delete the user from IAM.

A modal window will appear with. Click Delete.

After this, the selected user will be completely deleted from Okta IAM.

If a user with the same email exists in your application, that user will also be soft-deleted in your application.

(Optional) Multi Factor Authentication

Configuring Global Session Policy

Multi-Factor Authentication (MFA) adds an additional layer of security to user login. When enabled, users must verify their identity using a second factor, such as the Okta Verify app, in addition to their password.

In the side menu, navigate to the Global Session Policy page. Сlick Add policy button

A modal window will appear. Enter Policy name, Policy Description and assign it to the group you want to enforce MFA for. In my case this will be a group of Everyone. Click Create policy and add rule.

Another modal window will appear with adding policy rule. Enter Rule name, Set MFA to Required, In User will be prompted for MFA, select the desired option. Then click Create rule.

Configuring authentication policies

In the side menu, navigate to the Authentication Policies page and click on App sign-in button:

You will be redirected to the App sign-in policies page. Click Create policy to add a new policy.

In the modal window, provide a Policy name and Description, then click Create Policy.

You will be redirected to your policy page. Click Add rule.

A modal window will appear.
Enter rule name, select the Groups you want to enforce MFA for.Configure other fields as shown in the screenshots below. Then click Save.

Your new authentication policy rule will be added.

Configuring Authenticators

In the side menu, navigate to the Authenticators page and click on Enrollment tab:

Then click Actions next to the default policy and select Edit.

In the modal window that appears, ensure that Okta Verify is set to Required, then click Save.

✅ That's it!

Okta Multi-Factor Authentication (MFA) is now successfully configured.

How to connect to your application

To enable Okta login for your users in your application, you need to retrieve the following three parameters:

Client ID
Client Secret
Okta domain

You can find this data on our Application details page. In the side menu (Okta panel), navigate to the Applications

Choose an application which you created previously. In my case, it is an SSO OIDC (marked below)

Instructions for copying the whole information that we should fill in your application can see below

Copy a issuer URL

To obtain the Issuer URL for your application, open: https://{yourOktaDomain}/.well-known/openid-configuration (In my case it is: https://integrator-1609932.okta.com/.well-known/openid-configuration)

Then copy the value of the issuer field from the returned JSON:

✅ Now, you have all the required credentials to connect to your application!

Azure Single Sign-On (SSO) Setup: A Step-by-Step Guide

Soldatov Serhii — Sat, 11 Apr 2026 15:36:01 +0000

To enable Single Sign-On (SSO) for your application, we first need to register it in Azure Active

Navigate to Microsoft Entra ID:

Click to Add button and select App registration:

Fill in the Name field (you can choose any meaningful name).

Set the Redirect URI, which look like this:

https://your-user-pool-domain/oauth2/idpresponse

where your-user-pool-domain is your Cognito User Pool Domain

(example: https://eu-north-asr1mv.auth.eu-north-1.amazoncognito.com/oauth2/idpresponse).

Other fields of this form fill as shown in the following screenshot:

Configuring Logout URL & Enabling ID Tokens

To complete the authentication setup, we need to:

Enable ID Tokens - Since we are using OpenID Connect (OIDC) to authenticate users, ID tokens must be enabled.
Set the Logout URL - This ensures users are properly signed out when logging out of our application.

Steps to Configure:

Go to Authentication in the registered app:

Your Azure Active Directory instance -> App registrations -> < YourApp > -> Authentication
Set the Logout URL to:

https://your-app-domain/api/oidc/logout/

Creating scopes

After creating the application, you will be redirected to the App Overview page. Now, let's configure scopes to define the permissions our application can request.

Step 1: Navigate to Expose an API

Click on Expose an API

Step 2: Set Application ID URI

If this is your first time accessing this section, you will see a prompt asking you to add an Application ID URI before proceeding. This step is required to define unique identifiers for your API.

Follow the prompt to add an Application ID URI (generates automatically).

Step 3: Add a Group Scope

Now that the Application ID URI is set, we can define the scopes our application needs.

Click Add a Scope.
Scopes in OIDC determine what permissions the application can request from the identity provider. They allow access to specific user attributes, such as groups, roles, email, or profile information.
In our case, we need the group scope to retrieve user groups during authentication. This enables proper access control and permission management in our application.
Fill this form as shown in the following screenshot, then click the Add scope button.

Step 3.1: Add a Roles Scope

Click Add a Scope.
Scopes in OIDC determine what permissions the application can request from the identity provider. They allow access to specific user attributes, such as roles, email, or profile information.
In our case, we need the roles scope to retrieve user roles (e.g., admin, manager) during authentication. This enables proper access control and permission management in our application.
Fill this form as shown in the following screenshot, then click the Add scope button

Step 4: Add a Client Application

Once the scope is created, we need to associate it with our client application.

Click Add a client application.
The Client ID can be found in the Application ID URI.

With these steps completed, our application is now set up to request and utilize user groups during authentication.

Step 5: Add a Groups to Token Configuration

After all is created we must create group claim

Click Add group claim button.
Fill the form as shown in the following screenshot, then click the Save button.

That's it, the group's scope and claim is configured.

Extending API Permissions

Retrieving the email, openid, and profile claims in the ID token, as well as creating notification subscriptions for soft delete support, requires enabling the appropriate API permissions.

Navigate to

Your Azure Active Directory instance -> App registrations -> < YourApp > -> API Permissions

Click Add permission.

In the sidebar that appears, select APIs my organization uses, then choose Microsoft Graph.

Choose Delegated permissions, then enable: email, openid, profile, User.Read.

Choose Application permissions, then enable: Directory.Read.All and User.ReadAll. Then Click on the Add permissions button.

This is what the correct configuration should look like:

Creating roles

In Azure Active Directory (AAD), we can define roles for users to manage permissions within our application. These roles determine the level of access a user has, such as admin, manager, etc.

In the Azure Active Directory we should create roles for users.

Step 1: Access the Manifest

To create roles, we need to edit the application's Manifest, which is a JSON file defining the application's configuration.

Navigate to: Your Azure Active Directory instance -> App registrations -> < YourApp > -> Manifest

In the Manifest, you will find a section for role definitions. If you haven't created any roles yet, this section will be empty (highlighted in red in the screenshot).

Example of one role:

{
    "allowedMemberTypes": [
        "User"
    ],
    "description": "Administrators can manage resources.",
    "displayName": "Admin",
    "id": "a1234567-89ab-cdef-0123-456789abcdea",
    "isEnabled": true,
    "origin": "Application",
    "value": "admin"
}

Important:

Each role must have a unique ID.
Use a GUID generator to create unique IDs. You can use this free tool: 👉GUID Generator

Step 2: Add All Required Roles

For convenience, you can copy and paste the pre-defined role objects into your Manifest.

Copy the prepared role definitions.
Replace the role IDs with newly generated GUIDs.
Press the "Save" button to apply the changes.

Once saved, your roles should appear correctly in the Manifest.

Here's prepared user roles, you can just copy-paste the whole object, BUT do not forget to use your own ids by using GUID, after pasting press "Save" button:

"appRoles": [
    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "Full admin access.",
        "displayName": "ADMIN",
        "id": "18846fd3-94e1-4f47-a8e5-27edb66a14b8",
        "isEnabled": true,
        "origin": "Application",
        "value": "admin"
    },
    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "Booking and campaign management access.",
        "displayName": "MANAGER",
        "id": "b2345678-90ab-cdef-0123-456789abcdeb",
        "isEnabled": true,
        "origin": "Application",
        "value": "manager"
    },
    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "Booking and campaign management access.",
        "displayName": "REPORT",
        "id": "cd4062ff-2eb9-4960-93c1-1d20637f1d23",
        "isEnabled": true,
        "origin": "Application",
        "value": "report"
    },
]

Here's how it should look like:

Creating groups

In Azure Active Directory (AAD), we can define groups for users to manage permissions within our application. Groups allow us to control which users have access to the app. A user must be assigned to the appropriate group in order to sign in.

!Note: If a user is not a member of the group, they will not be able to access your application.

Step 1: Navigate to groups

To create groups:

Navigate to: Your Azure Active Directory instance -> Groups Manifest
You should see a screen similar to the one below:
Click the "New group" button.

Step 2: Create Group

To create groups:

Choose Security type in Group type input
Fill other fields
Click the "Create" button. And Security group will be created

Step 3: Assign users to group

To assign users to group, follow these steps:

Step 1: Navigate to Group

Go to: Your Azure Active Directory instance -> Groups -> All groups
Click on the Group to which you want to add users.

Step 2: Navigate to Members tab

Click the "Members" button on the sidebar.

Step 3: Add members to the Groups

Click Add members
Select the users you want to add to the group as on the screenshot below.
After you select all users you want to add to the group. Click Select

Assigning user roles

To assign roles to users, follow these steps:

Step 1: Navigate to User Role Assignment

Go to: Your Azure Active Directory instance -> Enterprise applications -> < YourApp > -> Users and groups
Click the "Add user" button.

Step 2: Select Users and Assign Roles

First, select the users you want to assign roles to. (See Screenshot below)
On the next screen, choose the appropriate role for the user.
Click Assign button

For production environments, it's not recommended to assign roles to individual users. Instead, assign roles to groups to simplify user management and reduce maintenance efforts.

Step 3: Confirm Role Assignment

Click the "Assign" button to finalize the role assignment.
You will be redirected to the Users and groups view, where you can see the assigned roles.

That's it! The Role assignment is now complete.

Now you have completed all preparation steps and your application is ready to use Azure SSO.

Deleting users

To trigger a soft-delete of a user in your application, you need to either remove the user from an Azure group or fully delete the user from Azure IAM.

Delete user from group:

To soft-delete a user from all rights holders where the user was, you need to remove the user from the corresponding Azure AD group (the group with the objectId defined in your SSO Client Provider).

Step 1: Navigate to Group

Go to: Your Azure Active Directory instance -> Groups -> All groups
Click on the Group to which you want to delete users.

Step 2: Navigate to Members tab

Click the "Members" button on the sidebar.

Step 3: Remove members from the Groups

Select the users you want to remove from the group.
After you select all users you want to delete from the group. Click Remove.
A modal window will appear with the configuration form. Click Yes

After this, if a member with this ObjectID exists in your application, the system will soft-delete the user.

Delete user from IAM:

Step 1: Navigate to Users Page

Go to: Your Azure Active Directory instance -> Users
Select the users you want to delete.
Click the "Delete" button, then confirm by clicking "Ok" in the modal window.

Step 2: Navigate to Deleted users tab

Click the "Deleted users" button on the sidebar.

Step 3: Permanently delete the User

Select the user you delete in Step 1 or you want to delete.
Click "Delete permanently", then confirm by clicking "Ok" in the modal window.

After this, the selected users will be completely deleted from Azure IAM.

If a user with the same User ObjectID exists in your application, that user will also be soft-deleted.

Note: The User ObjectID is linked to a user in your application only after the user logs in via the Azure SSO Provider.

(Optional) Multi Factor Authentication

Multi-Factor Authentication (MFA) adds an additional layer of security to user login. When enabled, users must verify their identity using a second factor, such as the Microsoft Authenticator app, in addition to their password.

Step 1:

Navigate to: Your Azure Active Directory instance -> Properties
Make sure that Security Defaults are enabled. if not - enable it.

After enabling Security Defaults, when a user from your organization attempts to log in, they will be prompted for MFA.

The user will need to use the Microsoft Authenticator app (or another supported MFA method) to complete the login.
A screen similar to the one below will appear, guiding the user through the MFA verification process:

On next login attempts, the user will be required to complete MFA using the Microsoft Authenticator app.

How to connect your application

To enable Azure login for your users, you need to retrieve the following three parameters:

Client ID
Client Secret
Tenant ID

Step 1: Retrieve Client ID & Tenant ID

Navigate to: Your Azure Active Directory instance -> App registrations -> < YourApp >
Locate the Client ID and Tenant ID in the App Overview section.

Step 2: Generate Client Secret

Click on Client credentials (as shown in Screenshot above).
Create a new Client Secret. (See Screenshot below)
After creating the secret, copy the "Value" immediately, as it will no longer be visible once you refresh or leave the page.

After creation you should copy Value

Note! after updating page it won't be visible anymore

Copy a issuer URL

Reference: https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri

To obtain the Issuer URL for your application, copy: https://login.microsoftonline.com/{tenant}/v2.0 and replace {tenant} with your application's tenant ID.

✅ Now you have all the required credentials to configure Azure SSO for your application!

Django Without the Mess: Repositories for Data, Services for Rules

Soldatov Serhii — Sun, 07 Sep 2025 11:58:40 +0000

The Elephant in the Room: Django's Fat Model Problem

Let’s talk about the elephant in every Django project: that one models.py file. You know the one. It started pure and simple, a beautiful reflection of your database schema. Now, it's a 2,000-line behemoth, bloated with custom managers, @property decorators that hide monstrous queries, and save() methods that seem to have more side effects than a late-night infomercial product.

Your views are a mess, your business logic is scattered, and making any change feels like performing surgery with a butter knife. In this moment of desperation, a seemingly elegant solution appears: "selectors." Just pull all those messy queries out into a separate selectors.py file! It feels clean. It feels right.

But I'm here to tell you that selectors are a trap. They’re a quick fix that feels like progress but ultimately leads you down a path of architectural pain. There’s a better way, a more structured approach that will save you from future headaches: the Repository and Service patterns. Let’s break down why this combination wins, and why selectors just don’t hold up in the long run.

How We All Got Here

No one sets out to write messy code. We typically arrive here by following well-intentioned advice. In the Django world, the classic mantra is "fat models, thin views." The idea is to keep your views lean and push all the logic related to your data into the corresponding model.

And for a small project, this works beautifully! A User model with a method like is_profile_complete() is perfectly reasonable. But what happens when the logic gets more complex? Soon, you have user.get_recent_orders(), user.calculate_lifetime_value(), and user.send_password_reset_email(). Your model is no longer just a data structure; it's a tangled web of business rules, database queries, and external interactions.

This is when developers, rightly, look for a way to clean up. The selectors.py file is born. You create functions like user_get_active_with_recent_orders() and product_get_top_sellers(). The model slims down, the view calls a clean function—problem solved, right?

Not quite. Honestly, this is like sweeping a pile of dirt under the rug. The room looks cleaner at a glance, but you haven't actually dealt with the mess. You’ve just moved it. This separation is superficial, and as we’ll see, it creates a whole new set of problems.

Repository Pattern 101: Your Data's Bodyguard

So, what’s the alternative? Let’s start with the first piece of the puzzle: the Repository Pattern.

In the simplest terms, a repository is an abstraction layer that sits between your application's business logic and your database. Its one and only job is to handle data access. Think of it as a specialized agent for a particular model. If you need to get users, save a user, or delete a user, you talk to the UserRepository. You design it to serve your use cases, not to mirror every possible query.

Structure:

your_app/
  users/
    models.py
    repositories/
      __init__.py
      users.py
    services/
      __init__.py
      users.py

And here’s what that UserRepository might look like, inheriting from a BaseRepository (like the one here):

# your_app/users/repositories/users.py

from your_app.apps.common.repositories import BaseRepository 
from your_app.users.models import User
from typing import Optional


class UserRepository(BaseRepository):
    def get_by_id(self, user_id: int) -> Optional[User]:
        return self.filter(id=user_id).first()

    def get_by_email(self, email: str) -> Optional[User]:
        return self.filter(email=email).first()

Why this matters

Clear contract. It provides a single, explicit interface for data operations. No more User.objects.filter(...) scattered across 20 different files. You centralize your query logic in one place.
Centralized query intent. If a flow needs special prefetch or annotations, you add a method and keep it consistent.
Test seams. You can pass a fake repository in tests. You can add caching or logging in one place without hunting through views.

The service layer, also known as the brain

If repositories are your data's bodyguards, services are the brain of the operation. Services sit above repositories to orchestrate business workflows and enforce rules. They are where your transactions should begin and end. If a business rule changes—like "premium users get priority processing"—you want one, and only one, place to make that change.

The best analogy is this: Repositories fetch the ingredients. Services follow the recipe to cook the meal.

A service doesn't know how the ingredients are fetched (that's the repository's job), and the view doesn't know how the meal is cooked. The view just says, "I'd like to order the 'New User Registration' please."

# users/services/users.py

from .repositories import UserRepository
# Assume a NotificationService exists elsewhere
from notifications.services import NotificationService

class UserService:
    def __init__(self, user_repo: UserRepository, notification_service: NotificationService):
        self.user_repo = user_repo
        self.notification_service = notification_service

    def register_user(self, email: str, name: str) -> User:
        # Business rule: check if user already exists
        if self.user_repo.get_by_email(email):
            raise ValueError("User with this email already exists.")

        # Step 1: Create the user via the repository
        user = self.user_repo.create(email=email, name=name)

        # Step 2: Orchestrate another action
        self.notification_service.send_welcome_email(user.email)

        return user

This is clean, transactional, and easy to follow.

The Real Risk of Selectors: A Slippery Slope

So if services are the brain, why not just use selectors for the data? The risk isn't that selectors are inherently bad, but that they are a slippery slope.

They lack a strong architectural boundary, making it too easy to add "just one little piece" of business logic. Over time, these small compromises turn your clean query file into a tangled, secondary business logic layer.

The Repository and Service pattern prevents this by creating explicit guardrails.

Repositories have one job: get data.
Services have one job: enforce business rules.

This clear separation makes the right path the easy path and prevents the slow decay of your architecture.

Admin actions, celery tasks, and the rest of the crew

Keep the same pattern everywhere. Admin actions call services. Celery tasks call services. Management commands call services. One flow. One place for idempotency and retries. If a task runs twice, the service checks state and either skips or continues.

Common questions you will hear on the team

Can I keep a small helper on the model. Yes, if it only touches that model’s state.
Do I always need a service. If a view is a straight read, repo to serializer can be fine. When you branch or change state, reach for a service.
Do I need a repo per model. Start where it helps most. Big aggregates, heavy queries, hot paths. Let the layer grow with need.
Can selectors live beside repos. If they exist, make them thin wrappers over repos, not a separate source of truth.

Why this matters on teams, not only in code

Clean layers make it easier to talk. A PM says, payment failed on retry. You look at one place. A junior asks, where should I put this logic. You have a ready answer. A reviewer reads a PR and knows exactly which patterns to expect. The shape of the system stays steady as the people change.

Also, repositories act like discreet places to teach performance. You can add little comments, like why you used select_for_update here, or why an index matters. New teammates learn by seeing the same pattern in many methods. That is softer than sending a long wiki doc that nobody reads twice.

Conclusion: Choose Clarity Over Convenience

Look, selectors aren't born from malice. They come from a good place: the desire to clean up messy code. They offer a moment of relief, a feeling of organization. But it’s a temporary fix. They are a crutch, not a long-term architectural strategy.

The Repository and Service patterns require a bit more discipline upfront. You have to think about your application's layers and enforce those boundaries
Keep models slim. Put data access in repositories. Put rules in services. Own transactions at the service layer. Be consistent.

Part 2: Django REST Framework: When (and When Not) to Override Serializers and Viewsets

Soldatov Serhii — Sun, 10 Aug 2025 14:55:02 +0000

DRF, Part 2: ViewSet Overrides

Welcome to the second half of our guide on DRF architecture. In Part 1, we established a clear rule: serializers are the guardians of your data. They handle validation, transformation, and representation. They ensure that the data entering your system is clean and the data leaving is well-formed.

But that’s only half the picture.

The ViewSet's Core Mission: Orchestration

Viewsets handle the HTTP journey. They don't care if a start_date is before an end_date — that's the serializer's job. They care about things like:

Parsing the incoming request.
Checking permissions and authentication.
Calling the serializer to validate data.
Triggering the save operation.
Formatting the final Response with the right data and status code.

Let's explore the most common and powerful methods you can override.

The Big Showdown: `create` vs. `perform_create`

This is where so much confusion happens. Both seem to do the same thing! But their purpose is completely different, and choosing the right one is key to clean code.

Override create(self, request, *args, **kwargs) when you need to change the orchestration of the request or the shape of the final response. Do you need to return a 202 Accepted instead of a 201 Created? Do you need to wrap the response in a { "data": ... } envelope? Do you need to do something before the serializer is even validated? That's a job for create.
Override perform_create(self, serializer) when you just need to tweak how the object is saved. This is a much cleaner, more focused hook. The default create method calls this after validation is successful. It's the perfect place to inject the current user or tenant ID right before saving.

A practical rule of thumb: Always try to use perform_create first. Only override the full create method if you absolutely have to manipulate the HTTP response or the flow itself.

# In your OrderViewSet
class OrderViewSet(viewsets.ModelViewSet):
    # ... queryset and serializer_class definitions ...

    # This is the CLEAN way to stamp the user
    def perform_create(self, serializer):
        # The serializer is already validated here.
        serializer.save(customer=self.request.user)

    # Only override this if you need to change the whole dance
    def create(self, request, *args, **kwargs):
        # Maybe you need to check inventory before even trying to validate
        if not check_inventory(request.data):
            return Response({"error": "Item out of stock"}, status=status.HTTP_400_BAD_REQUEST)

        # Now call the original 'create' logic
        return super().create(request, *args, **kwargs)

This principle of separating the HTTP-level orchestration (create) from the persistence hook (perform_create) is key. Now, let's apply that same logic to updates.

The Update Trinity: `update` (PUT), `partial_update` (PATCH), and `perform_update`

Updates are more complex than creates because there are two different ways to do them: a full update (PUT) and a partial one (PATCH). DRF gives you three distinct methods to control this process.

First, let's get the flow right. It's a common point of confusion. The methods update and partial_update are peers; one does not call the other.

A PUT request is routed to the update() method. After validation, update() calls perform_update() to save the changes.
Flow: PUT Request → update() → perform_update() → serializer.save()
A PATCH request is routed to the partial_update() method. After partial validation, partial_update() also calls perform_update() to save the changes.
Flow: PATCH Request → partial_update() → perform_update() → serializer.save()

perform_update() is the shared, final step for both. With that in mind, here’s when to override each one.

When to Override `perform_update(self, serializer)`

This is your go-to hook for 90% of update logic. Override perform_update when you have code that must run for any update, whether it's a PUT or a PATCH. It keeps your code DRY (Don't Repeat Yourself) by providing a single place for shared save-time logic.

Why Override? You need to stamp a field, clear a cache, or log an update without caring if it was a full or partial change.
Example: You always want to record which user was the last person to modify an object.

def perform_update(self, serializer):
    # This logic runs for both PUT and PATCH, after validation.
    # It's the cleanest place for shared save-time hooks.
    serializer.save(last_updated_by=self.request.user)

When to Override `partial_update(self, request, *args, **kwargs)`

Override the partial_update method for logic that should only run during a partial change (PATCH). This is incredibly useful for implementing fine-grained permissions or triggering specific side effects when certain fields are modified

Why Override? You want to allow different update rules for different fields, or you want to react to specific, targeted changes.
Example: In a project management system, maybe anyone can PATCH a task's description, but only a manager can PATCH its due_date. Overriding partial_update is the perfect place to check for this.

def partial_update(self, request, *args, **kwargs):
    # Custom logic just for PATCH
    if 'due_date' in request.data and not request.user.is_manager:
        return Response({"error": "Only managers can change the due date."}, status=status.HTTP_403_FORBIDDEN)

    # Another example: trigger a notification ONLY if the status changes
    if 'status' in request.data:
        instance = self.get_object()
        old_status = instance.status
        new_status = request.data['status']
        if old_status != new_status:
            notify_team_of_status_change(instance, new_status)

    return super().partial_update(request, *args, **kwargs)

When to Override `update(self, request, *args, **kwargs)`

Override the update method when you need to add logic that is specific to a full resource replacement (PUT). Because PUT implies replacing the entire resource, you might have preconditions or post-conditions that don't apply to a simple PATCH.

Why Override? You want to enforce a strict "all or nothing" replacement policy or perform an action that only makes sense when the entire object is changed.
Example: Imagine you have a Settings object. You could override update to ensure that a PUT request truly contains every single required setting field, preventing users from accidentally wiping out settings by sending an incomplete object. You could also log a specific "Settings Overwritten" event that is more severe than a simple field change.

def update(self, request, *args, **kwargs):
    # Custom logic just for PUT
    if not all(key in request.data for key in ['theme', 'notifications', 'timezone']):
        return Response({"error": "A full update requires all setting keys."}, status=status.HTTP_400_BAD_REQUEST)

    # Log the major change
    log_settings_overwritten(user=request.user)

    return super().update(request, *args, **kwargs)

Other Useful ViewSet Hooks

Beyond create and update, other methods give you powerful control over the request lifecycle:

list(): Override this when you need to reshape the entire list response beyond a simple array of objects, for example, by adding metadata or aggregation summaries.
retrieve(): Perfect for when a single object's response needs extra context that depends on the request, like adding a can_edit flag for the current user.
destroy(): The default just deletes the object. Override this to implement soft deletes, check for dependencies, or record an audit log event.
get_queryset(): This is one of the most important overrides for performance and security. It’s where you scope the data (e.g., a user only sees their own invoices) and where you should add performance boosters like select_related and prefetch_related.
get_serializer_class(): Your viewset's "chameleon." It lets you use different serializers for different actions (e.g., a summary for list, details for retrieve).
get_permissions(): Great for when permissions change based on the action (e.g., anyone can GET, but only staff can POST).

The Decision Guide: Where Does This Logic Go?

Let’s boil everything from both articles down to a simple cheat sheet for a clean DRF architecture:

Is it about the shape, structure, or validity of data?
- Answer: Serializer (validate, validate_<field>, to_representation).
Is it about managing the HTTP request/response flow, like returning a custom status code or handling action-specific permissions?
- Answer: ViewSet action (create, update, list, etc.).
Is it about changing how an object is saved after validation, for both PUT and PATCH?
- Answer: ViewSet perform_* method (perform_create, perform_update).
Is it about filtering the main list of objects based on the user or request?
- Answer: ViewSet get_queryset method.

Keeping these boundaries clear isn't just an abstract architectural exercise. It’s a practical strategy for building software that can grow and adapt without collapsing under its own weight. Your team will thank you. And more importantly, your future self will, too.

Part 1: Django REST Framework: When (and When Not) to Override Serializers and Viewsets

Soldatov Serhii — Sun, 10 Aug 2025 14:54:57 +0000

DRF, Part 1: Serializer Overrides

Ask any Django developer where to put validation, formatting, and orchestration logic, and you’ll often get different answers — some say “just put it in the serializer,” others drop everything in the viewset.

This works… until it doesn’t.
When your API grows, mixing concerns makes code brittle, hard to test, and painful to maintain. Knowing exactly when to override a serializer method and when to override a viewset method is key to keeping a codebase clean.

The Serializer's Core Mission

Think of your serializer as the security guard at the door of your database. It's responsible for three primary tasks:

Validation: Checking the ID of incoming data to ensure it's legitimate.
Transformation: Making sure the data is in the right format before being saved.
Representation: Deciding how the data should be presented when it's sent back out.

Its world is small and focused: just the data. Let's look at the tools it uses.

1) Serializer method overrides

Role
Serializers control what may enter and how it leaves: validation, input normalization, output formatting.

validate_<field_name>(self, value) - field-level checks
This is your go-to for single-field validation. Django's model fields and DRF's serializer fields handle the basics, like checking if a field is an integer or a valid email. But what about your specific business rules?

Use this when a single field has a rule that only it needs to worry about.

Example: Imagine you have a Product model with a discount_percentage field. For most products, any discount is fine. But for the "Electronics" category, you need to cap it at 50% to protect your margins.

validate(self, data) - cross-field validation
Sometimes fields can't be validated in isolation. They have relationships; they depend on each other. validate is where your fields have a conversation. It runs after all the individual validate_<field> methods have passed.

Use this for cross-field validation.
Example: A classic case is a PromoCampaign model with a start_date and an end_date. It makes no sense for the promotion to end before it even begins.

def validate(self, data):
    """
    Check that the start date is before the end date.
    """
    if data['start_date'] > data['end_date']:
        raise serializers.ValidationError("End date must occur after start date.")
    return data

Simple enough, right? This keeps your data integrity rules right next to the data definition.

create(self, validated_data)
DRF's default create method is wonderfully simple: it just unpacks your validated data and calls YourModel.objects.create(**validated_data). But sometimes "simple" isn't enough.

Override create when you need to control exactly how a new object instance comes into being. This could mean:
Creating related objects in the same transaction.
Injecting data that doesn't come from the user, like created_by=self.context['request'].user.
Handling nested serializers for write operations.

# In a UserProfileSerializer that also creates a user
def create(self, validated_data):
    user_data = validated_data.pop('user')
    user = User.objects.create_user(**user_data)
    # Stamp the current user from the view's context
    created_by_user = self.context['request'].user
    profile = UserProfile.objects.create(user=user, created_by=created_by_user, **validated_data)
    return profile

update(self, instance, validated_data)
Just like create, the default update method loops through the validated data and does a setattr(instance, key, value) for each item before calling instance.save(). You should override it when you have more complex update logic.

Maybe you need to prevent updates if an order is already "shipped." Or perhaps updating one field requires a calculated change to another.

Example: When updating a blog post, you want to replace all its tags, not just add new ones. The default update for a many-to-many relationship might not do exactly what you want.

# In a PostSerializer with a 'tags' field
def update(self, instance, validated_data):
    tags_data = validated_data.pop('tags', None)

    # This is the default behavior for all other fields
    instance = super().update(instance, validated_data)

    # Now, handle the tags with our custom logic
    if tags_data is not None:
        instance.tags.set(tags_data) # Replaces all existing tags

    return instance

to_representation(self, instance)
This is the "glow-up" method. It's the last stop before your data is serialized and sent out into the world. Its job is to shape the outbound data. The model might store a user ID, but you want to show their full name. The database has a first_name and last_name, but you want to add a full_name field to the API response.

Example: Add a computed field to your User serializer.

# In your UserSerializer
def to_representation(self, instance):
    # Get the default representation
    representation = super().to_representation(instance)
    # Add our custom field
    representation['full_name'] = instance.get_full_name()
    return representation

So, When Should Serializers Just Say No?

This is just as important. A serializer that does too much becomes a god object. Here’s what doesn't belong in a serializer:

Heavy Side Effects: Sending emails, charging credit cards, updating inventory in another system, calling third-party APIs. This is a one-way ticket to a maintenance nightmare. If the database transaction fails after the email is sent, what do you do? This logic belongs elsewhere.

Complex Queries: A serializer's validate method shouldn't be making five different database calls to check a condition. That logic should live in a dedicated place (like a "selector" function or repository's function) and be called from the view.

Business Workflows: A multi-step process, like "register user, create trial subscription, and schedule a welcome email," is a business workflow. It's too high-level for a serializer. This is a job for a service layer.

In Part 2 of this series, we’ll dive into the ViewSet's role as the orchestra's conductor and explore how to use its methods—and a service layer—to keep your application logic clean and organized.

Why Django REST Framework doesn't show your custom validation error messages (and what to do about it)

Soldatov Serhii — Wed, 21 May 2025 12:52:56 +0000

The GitHub Discussion: link

Issue developers face:

When developing with Django REST Framework (DRF), developers typically run into issues where error messages for custom validation specified on Django model constraints (e.g., UniqueConstraint.violation_error_message) are not passed through to API responses. DRF returns default validation error messages instead.

For example, a custom error message like:

UniqueConstraint(
    fields=['email', 'username'],
    violation_error_message='This email and username combination already exists.'
)

...might never actually reach the API client.

Instead, you'll see something generic like:

{"non_field_errors": ["The fields email, username must make a unique set."]}

This is what the DRF maintainers had to say about it:

DRF validation is deliberately occurring at the serializer level, before the creation of the model instance.
It intentionally avoids calling Django's full_clean() in this processes, as serializers are meant to validate incoming data instead of an already-created model instance.
Due to the complexity and backward compatibility issues, there are no immediate plans from DRF for changing this behavior.

In other words - DRF prioritises serialiser checking for API input, which means that unless you explicitly call model checking (e.g. via full_clean()), constraint errors and their custom messages will never be called or shown in API responses.

Possible solutions:

Developers can tackle this issue through several practical approaches:

Explicitly calling full_clean():

def create(self, validated_data):
    instance = MyModel(**validated_data)
    try:
        instance.full_clean()
    except DjangoValidationError as e:
        raise DRFValidationError(e.message_dict)
    instance.save()
    return instance

Custom serializer validators:

This method just overrides DRF's built-in UniqueTogetherValidator just to replace the error message.

class CustomUniqueValidator(UniqueTogetherValidator):
    def __call__(self, attrs, serializer):
        try:
            super().__call__(attrs, serializer)
        except serializers.ValidationError:
            raise serializers.ValidationError("This email and username combination already exists.")

Sometimes just double your validation code: Sometimes, custom validators and extra abstractions aren't needed. Although we all know the DRY principle, sometimes it's acceptable to just dublicate simple validation logicdirectly into your serializer

class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = ['email', 'username']
        validators = [
            UniqueTogetherValidator(
                queryset=MyModel.objects.all(),
                fields=['email', 'username'],
                message="This email and username combination already exists."
            )
        ]

Summary:

Issue: DRF doesn't carry forward any custom validation messages defined in Django.

Reason: For reasons of architecture and backward compatibility, DRF validates its data independently from Django's model validation.

Important Warnings:

Be careful where you place validation logic. Django models can be modified via the admin interface, serializers, or directly with bulk operations (.update()).

Placing the critical validation logic into save() or full_clean() is problematic, as those aren't called when performing bulk updates or certain direct model manipulations. Always bear these edge cases in mind when developing your validation plans.

This approach keeps your validation logic consistent, reusable, and well-documented throughout your project.

Boost Your Django Docker Images by using UV package and project manager

Soldatov Serhii — Sun, 30 Mar 2025 14:55:56 +0000

What's UV?

UV is an ultra-fast Python package manager written in Rust by the Astral team.
You might already be familiar with another great product from Astral - ruff (popular Python linter).

It drastically reduces dependency installation time and produces smaller, optimized Docker images—ideal for enhancing your Django project's Docker workflow.
Let's dive in!

Quick start:

Follow these simple steps to get your local environment ready:

uv venv    # 1. Create a UV Virtual Environment
source .venv/bin/activate    # 2. Activate the Virtual Environment
uv sync --all-groups    # 3. Install Project Dependencies
docker-compose up --build

Note: This installs both production and development dependencies.
Use uv sync --no-dev if you want production-only packages.

Dockerfile

Here's a breakdown of a Dockerfile designed specifically for Django applications using UV to manage Python dependencies:

FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS base
FROM base AS builder

# Set up environment
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

WORKDIR /app

# Install the project's dependencies using the lockfile and settings
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project --all-groups

# Then, add the rest of the project source code and install it
# Installing separately from its dependencies allows optimal layer caching
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --all-groups

FROM base
COPY --from=builder /app /app
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000

CMD ["uv", "run", "python", "manage.py", "runserver", "0.0.0.0:8000"]

Base Image

We start by leveraging a slim Python image with UV pre-installed, optimized for minimal size and maximum speed.

FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS base
FROM base AS builder

Environment Setup

PYTHONDONTWRITEBYTECODE prevents Python from writing .pyc files to disk.

PYTHONUNBUFFERED ensures immediate logging output.

UV_COMPILE_BYTECODE compiles Python bytecode for faster startup.

UV_LINK_MODE=copy configures UV to copy dependencies instead of symlinking (improving compatibility).

UV_PROJECT_ENVIRONMENT sets the virtual environment path.

!Permission denied issue:
You might encounter permission issues when using the default virtual environment paths provided by UV as and I faced:

You can handle this issue in two ways:

(Recommended) By adding second volume entry(/app/.venv) in your docker-compose file. Since the .venv directory in the container is now completely isolated from your host filesystem and Docker can't change ownership or permissions on your local .venv folder, which solves your permission issues.

2.By explicitly setting UV_PROJECT_ENVIRONMENT to a dedicated path (/app/venv), we create a clean separation from default or locally-created environments, effectively resolving permission conflicts.

Dependency Installation (Optimized Caching)

This example is adapted from the official UV example: Dockerfile

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project --all-groups

UV installs dependencies from pyproject.toml and uv.lock.

⚠️ Important:
Here, I've used --all-groups to install every dependency group defined in pyproject.toml (including development dependencies like linting tools). For production builds, consider switching to --no-dev to install only production dependencies. For detailed guidance on managing dependency groups, refer to the official Dependency Groups documentation.

Adding Project Source and Finalizing Installation

COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --all-groups

!Note: I've also used --all-groups in there.
By adding your project's source after installing dependencies, Docker efficiently caches layers, speeding up rebuilds when code changes occur.

Final Runtime Stage

FROM base
COPY --from=builder /app /app
ENV PATH="/app/venv/bin:$PATH"
EXPOSE 8000

CMD ["uv", "run", "python", "manage.py", "runserver", "0.0.0.0:8000"]

In this final image:
✅ Only the necessary files and pre-installed dependencies are copied from the builder stage.
✅ Django runs within UV's isolated virtual environment.

⚠️ Important Considerations:

Production Use: This setup uses Django’s built-in development server (runserver). For production environments, consider switching to a production-grade server like gunicorn or uvicorn.
Running Commands with UV: After configuring your virtual environment with UV, you MUST prefix your commands with uv run, e.g.:

uv run python manage.py ...
uv run pytest -s -v

Otherwise, commands executed outside UV's context will fail.

Here's how can look like your start.sh:

#!/usr/bin/env bash

set -o errexit
set -o pipefail
set -o nounset
set -o xtrace

uv run wait_for_postgres.py

uv run manage.py migrate
uv run manage.py runserver 0.0.0.0:8000

Your optimized Dockerfile is now ready, resulting in faster builds, smaller images, and better caching strategies for your Django application.

Here's quick time comparison:

With the optimized Dockerfile, the build process completed in just 15.8s, with only 6.7s dedicated to installing dependencies.
In contrast, the previous Dockerfile took 34.6s, spending 28.3s installing dependencies.

You can easily measure this improvement yourself by running:

time docker build -t container-name . --no-cache

And finally, here's an example of pyproject.toml and docker-compose.yml part:

[project]
name = "piedpiper-web"
version = "0.1.0"
description = "Piedpiper web"
readme = "README.md"
requires-python = ">=3.13"

# Core application dependencies
dependencies = [
    "boto3~=1.37",
    "dj-database-url==2.3.0",
    "dj-rest-auth==7.0.1",
    "django==5.1.7",
    "django-allauth==65.3.0",
    "django-autoslug==1.9.9",
    "django-configurations==2.5.1",
    "django-cors-headers==4.7.0",
    "django-filter==25.1",
    "django-model-utils==5.0.0",
    "django-role-permissions==3.2.0",
    "django-storages==1.14.5",
    "django-unique-upload==0.2.1",
    "djangorestframework==3.15.2",
    "djangorestframework-api-key==3.0.0",
    "djangorestframework-simplejwt==5.5.0",
    "gunicorn==23.0.0",
    "pillow~=11.1",
    "psycopg2-binary==2.9.10",
    "python-dotenv==1.0.1",
    "requests==2.32.3",
    "setuptools==77.0.3",
]

[dependency-groups]
# Linting and code quality dependencies
lint = [
    "black==25.1.0",
    "flake8==7.1.2",
    "isort==6.0.1",
    "pre-commit==4.2.0",
    "ruff==0.11.2",
]

# dev dependencies
dev = [
    "django-silk>=5.3.2",
    "nplusone>=1.0.0",
    "ipdb==0.13.13",
    "ipython==8.34.0",
    "mock==5.2.0",
    "coverage~=7.7",
    "pytest-django==4.10.0",
    "factory-boy==3.3.3"
    "drf-yasg~=1.21",
]

docker-compose:

  web:
    restart: always
    build:
      context: .
      dockerfile: Dockerfile
      target: builder
    command: bash scripts/start.sh
    working_dir: /app
    volumes:
      - ./:/app
      - /app/.venv
    ports:
      - "8000:8000"
    depends_on:
      - postgres
    env_file:
      - .env

More resourses:

Official documentation
uv: An In-Depth Guide to Python's Fast and Ambitious New Package Manager
Best practice Dockerfile for Python with uv

Hope it was useful,
Thanks for reading 🙌