user_management

User-Management Application

Features

Role-Based Access Control

• each user can be assigned a custom set of roles, with each role containing specific set of low-level permissions
• the permission model defines whether a role is allowed to perform certain operation on specific resource of specific application.

Quota management

• enforces limits on various resource types (materials) within a specific application.
• each user can be assigned a custom set of quota arrangements

Authentication / Authorization

• manage login account
• JWT token setup with JWKS support
• identity verification, permission / quota check with JWT
• unauthenticated token-based account maintenance, with email notification

User Profile / Hierarchical Group Management

• user profile maintains contact information, quota, and role assignments
• supports inheritance of quotas / roles from group to their members
• Enable activation / deactivation of a linked login account.

High-Level Architecture

flowchart LR
    subgraph Clients
      AUTHUSR(["👤 Authenticated Users"])
      PUBUSER(["👤 Public User"])
    end

    subgraph Internal-Apps
      direction LR
      PROD_AP(["Product application"])
      STORE_AP(["Storefront application"])
      MEDIA_AP(["Media application"])
    end

    subgraph Web-Service-Layer
      subgraph Authenticated
        direction LR
        ROLE_AC[Role-based Access Control]
        QUOTA_ARNG[Quota Arrangement]
        JWT_SETUP[JWT token setup]
        USR_GRP_PROF_MGT[User Profile / Group Management]
      end
      subgraph Unauthenticated
        direction LR
        UNAUTH_ACC_RECOV[account recovery]
        UNAUTH_ACC_ACTIV[account activation]
        UNAUTH_PSWD_RST[password reset]
      end
    end

    subgraph RPC-Consumer-Layer
      EMAIL_NOTF[E-mail Nortification]
      JWKS_MGT[JWKS maintenance]
      USRPROF_FIND[User Profile Search]
    end

    subgraph Data-Store-Layer
      MARIA[MariaDB]
    end

    subgraph CronJob
    end

    AUTHUSR --> Authenticated
    PUBUSER --> Unauthenticated
    Web-Service-Layer --> Data-Store-Layer
    RPC-Consumer-Layer --> Data-Store-Layer
    CronJob --> JWKS_MGT
    Unauthenticated --> EMAIL_NOTF
    Internal-Apps --> USRPROF_FIND

Loading

Pre-requisite

software	version	installation/setup guide
Python	3.13.5	see here
MariaDB	11.8.2	see here
pipenv	2025.0.4	see here
pip	25.1	see here
OpenSSL	3.1.4	see here

Build

For full build / test instructions please refer to github action workflow script

Base Image for Application Environment

cd /path/to/project-home/services

docker build --tag=usrmgt-backend-base:latest --file=user_management/infra/Dockerfile  .

docker image rm  usrmgt-backend-base:latest

After custom image usrmgt-backend-base:latest is built successfully, use it for one of following tasks

• run application in development ensironment
• run all test cases

Local Environment Setup

You can create per-project virtual environment using the command:

PIPENV_VENV_IN_PROJECT=1 pipenv run python -m venv ./.venv

A virtual environment folder .venv will be created under the application folder ./user_management

Common Python modules

Note in this application the building process on common python modules is automated , see the [packages] section in Pipfile.

First time to initialize

pipenv install --dev

If you need to modify the Pipfile or pyproject.toml , update the virtual environment after you are done editing , by the command

pipenv update  <optional-specific-package>

Run

development environment

database server and migration process are encapsulated in docker container, check following command :

# build up database, docker network ... etc.
docker compose --file  ./infra/docker-compose-generic.yml --file ./infra/docker-compose-dev.yml \
    --env-file ./infra/interpolation-dev.env  up --detach

# stop database, docker network ... etc then remove them.
docker compose --file  ./infra/docker-compose-generic.yml --file ./infra/docker-compose-dev.yml \
    --env-file ./infra/interpolation-dev.env  down  --volumes

• database server is always started by default.
• consider extra options when starting application:
  • --profile serverstart: perform database schema migration, start API server, and RPC consumer database
  • --profile initialstart: set up minimal user data for initial application launch after database schema migration

---

application server

pipenv run python3 ./manage.py runserver --settings  settings.development  8008 \
    >& ../tmp/log/dev/usermgt_app.log &

RPC consumer

DJANGO_SETTINGS_MODULE="settings.development" SYS_BASE_PATH="${PWD}/.."  \
    pipenv run  celery --app=ecommerce_common.util  --config=user_management.celeryconfig \
    worker --concurrency 1 --loglevel=INFO  --hostname=usermgt@%h  -E  \
    --logfile=../tmp/log/dev/usermgt_celery.log  &

Note:

• -Q is optional, without specifying -Q, Celery will enable all queues defined in celery configuration module (e.g. user_management.celeryconfig) on initialization.
• --logfile is optional
• --concurrency indicates number of celery processes to run at OS level, defaults to number of CPU on your host machine

Test

cd /path/to/project-home/services

docker --debug run --interactive --tty  --network=ec-usrmgt-test-net \
  --volume "$PWD/user_management/infra/run_test_container:/app/entry/run_my_app" \
  --name usrmgt-backend-testapp-0  usrmgt-backend-base:latest

docker stop usrmgt-backend-testapp-0

alternatively you can use docker compose :

# build up database, docker network ... etc.
docker compose --file  ./infra/docker-compose-generic.yml --file ./infra/docker-compose-test.yml \
    --env-file ./infra/interpolation-test.env  up --detach

# stop database, docker network ... etc then remove them.
docker compose --file  ./infra/docker-compose-generic.yml --file ./infra/docker-compose-test.yml \
    --env-file ./infra/interpolation-test.env down  --volumes

Development

Code Formatter

pipenv run black  --line-length=100 --extend-exclude="src/migrations/.*\.py$"  ./src/ ./tests/  ./settings/

Linter

pipenv run ruff check  ./src/ ./tests/  ./settings/