example-webapp-with-auth

features

• Security
  • development using https acme wildcard cert ( alternatively use selfsigned )
  • authorization through JWT cookie secure, httponly, samesite strict
  • webapi with roles authorization
• Developer friendly
  • breakpoints works for c# backend and typescript angular/react frontend from the same vscode session
• Backend
  • c# asp net core
  • configuration
    • development user-secrets
    • appsettings ( autoreload on change )
    • production environment variables
• Frontend
  • angular
    • openapi typescript/angular api services generated from backend swagger endpoint
    • layout with responsive menu
    • authguard protected pages routes
    • login / logout ( TODO: reset lost password through email link )
    • ( TODO: user manager )
    • light/dark theme
    • snacks
  • react
    • openapi typescript/axios api generated from backend swagger endpoint
    • layout with responsive menu
    • protected pages with react router dom
    • zustand global services
    • login / logout / reset lost password through email link
    • light/dark theme
    • snacks

quickstart

• clone repository

git clone https://github.com/devel0/example-webapp-with-auth.git
cd example-webapp-with-auth

• option 1 : angular frontend

git checkout frontend/angular

• option 2 : react frontend

git checkout frontend/react

• start development environment

code .

• restore exec permissions on helper scripts

source misc/restore-permissions.sh

• configure backend development variables

cd src/backend

dotnet user-secrets init

# change following as needed
SEED_ADMIN_EMAIL=some@domain.com
SEED_ADMIN_PASS="SEED_ADMIN_SECRET"
DB_PROVIDER="Postgres"
DB_CONN_STRING="Host=localhost; Database=DBNAME; Username=DBUSER; Password=DBPASS"

JWTKEY="$(openssl rand -hex 32)"

dotnet user-secrets set "AppConfig:Auth:Jwt:Key" "$JWTKEY"

dotnet user-secrets set "AppConfig:Database:Seed:Users:0:Username" "admin"
dotnet user-secrets set "AppConfig:Database:Seed:Users:0:Email" "$SEED_ADMIN_EMAIL"
dotnet user-secrets set "AppConfig:Database:Seed:Users:0:Password" "$SEED_ADMIN_PASS"
dotnet user-secrets set "AppConfig:Database:Seed:Users:0:Roles:0" "admin"

dotnet user-secrets set "AppConfig:Database:Connections:0:Name" "Development"
dotnet user-secrets set "AppConfig:Database:Connections:0:ConnectionString" "$DB_CONN_STRING"
dotnet user-secrets set "AppConfig:Database:Connections:0:Provider" "$DB_PROVIDER"

dotnet user-secrets set "AppConfig:Database:ConnectionName" "Development"

cd ../..

• start backend choosing C-S-P Debug: Select and Start Debugging then BACKEND

• start frontend by issueing

./run-frontend.sh

• start frontend debugger C-S-P Debug: Select and Start Debugging then FRONTEND ; this will open chrome to the named url and attaches the debugger

• to make things works with https acme cert you need a domain to set a CNAME record and certbot as described here

• then edit hosts sudo /etc/hosts like following in order to resolve name locally

127.0.0.1   dev-webapp-test.searchathing.com

• finally set nginx sudo apt install nginx by linking the conf

cd /etc/nginx/conf.d
ln -s ~/opensource/example-webapp-with-auth/deploy/nginx/dev/webapp-test.conf
service nginx reload

development settings for lost password recovery

cd src/backend

# MAILSERVER_SECURITY can be "Tls" or "Ssl" or "Auto" or "None"

dotnet user-secrets set "EmailServer:SmtpServerName" "$MAILSERVER_HOSTNAME"
dotnet user-secrets set "EmailServer:SmtpServerPort" "$MAILSERVER_PORT"
dotnet user-secrets set "EmailServer:Security" "$MAILSERVER_SECURITY"
dotnet user-secrets set "EmailServer:Username" "$MAILSERVER_USER_EMAIL"
dotnet user-secrets set "EmailServer:Password" "$MAILSERVER_USER_PASSWORD"

development setting for unit tests

when run backend unit tests with dotnet test the system will search for a configured db connection named "UnitTest"

⚠️ use a separate db because it will be destroyed when test executes

cd src/backend

dotnet user-secrets set "AppConfig:Database:Connections:1:Name" "UnitTest"
dotnet user-secrets set "AppConfig:Database:Connections:1:ConnectionString" "$UNIT_TEST_DB_CONN_STRING"
dotnet user-secrets set "AppConfig:Database:Connections:1:Provider" "$DB_PROVIDER"

deployment

a script to automate publish on production server is available

./publish -h sshname -sn test.searchathing.com -id mytest -sd searchathing.com

where

• -h is a configured ~/.ssh/config entry to allow to enter with a public key to a server within root user
• -sn is the application server hostname
• -id is a unique application id to allow more app on the same server
• -sd is the domain name where app run

published files and folders

folder	description
/root/security/mytest.env	copy (if not already exists) of webapp.env
/root/deploy/mytest	rsync of deploy folder
/srv/mytest/bin	rsync of self contained production src/backend/bin/Release/net9.0/linux-x64/publish/ folder
/etc/system/systemd/mytest-webapp.service	copy (if not already exists) of webapp.service
/etc/nginx/conf.d/mytest-webapp.conf	copy (if not already exists) of webapp.conf

prerequisites on server side:

apt install openssh-server rsync nginx

# to run the backend service as user
useradd -m user

editing configuration and logging production

• edit /root/security/mytest.conf setting variables accordingly to your production setup ( if not used EmailServer variables comment out with # )

to view backend service log

journalctl -u mytest-webapp -f

to restart backend service

service mytest-webapp restart

openapi generator

use provided script gen-api.sh to generate frontend api from the backend swagger openapi ; this script will detect if angular or react frontend and retrieve corresponding hostname information from environment or vite depending

how this project was built

• backend
• frontend