r/ouranos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
c32c3471e062bace32ffe69d08bc13b5fa48099d
ouranos/docs/casdoor.md

16 KiB
Raw Blame History

Casdoor SSO Identity Provider

Casdoor provides Single Sign-On (SSO) authentication for Ouranos services. This document covers the design decisions, architecture, and deployment procedures.

Design Philosophy

Security Isolation

Casdoor handles identity and authentication - the most security-sensitive data in any system. For this reason, Casdoor uses a dedicated PostgreSQL instance on Titania rather than sharing the PostgreSQL server on Portia with other applications.

This isolation provides:

  • Data separation: Authentication data is physically separated from application data
  • Access control: The casdoor database user only has access to the casdoor database
  • Blast radius reduction: A compromise of the shared database on Portia doesn't expose identity data
  • Production alignment: Dev/UAT/Prod environments use the same architecture

Native PostgreSQL with Docker Casdoor

The architecture splits cleanly:

┌──────────────────────────────────────────────────────────────┐
│  titania.incus                                               │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Native PostgreSQL 17 (systemd)                        │  │
│  │  - SSL enabled for external connections                │  │
│  │  - Local connections without SSL                       │  │
│  │  - Managed like any standard PostgreSQL install        │  │
│  │  - Port 5432                                           │  │
│  └────────────────────────────────────────────────────────┘  │
│           ▲                                                  │
│           │ localhost:5432                                   │
│           │ sslmode=disable                                  │
│           │                                                  │
│  ┌────────┴───────────────────────────────────────────────┐  │
│  │  Casdoor Docker Container (network_mode: host)         │  │
│  │  - Runs as casdoor:casdoor user                        │  │
│  │  - Only has access to its database                     │  │
│  │  - Cannot touch PostgreSQL server config               │  │
│  │  - Port 22081 (via HAProxy)                            │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘
         │
         │ External: SSL required
         │ sslmode=verify-ca
         ▼
  ┌─────────────┐
  │   PGadmin   │
  │ on Portia   │
  └─────────────┘

Why Not Docker for PostgreSQL?

Docker makes PostgreSQL permission management unnecessarily complex:

  • UID/GID mapping between host and container
  • Volume permission issues
  • SSL certificate ownership problems
  • More difficult backups and maintenance

Native PostgreSQL is:

  • Easier to manage (standard Linux administration)
  • Better integrated with systemd
  • Simpler backup procedures
  • Well-documented and understood

SSL Strategy

PostgreSQL connections follow a split SSL policy:

Connection Source SSL Requirement Rationale
Casdoor (localhost) sslmode=disable Same host, trusted
PGadmin (Portia) sslmode=verify-ca External network, requires encryption
Other external hostssl required Enforced by pg_hba.conf

This is controlled by pg_hba.conf:

# Local connections (Unix socket)
local   all             all                                     peer

# Localhost connections (no SSL required)
host    all             all             127.0.0.1/32            md5

# External connections (SSL required)
hostssl all             all             0.0.0.0/0               md5

System User Pattern

The Casdoor service user is created without hardcoded UID/GID:

- name: Create casdoor user
  ansible.builtin.user:
    name: "{{ casdoor_user }}"
    system: true  # System account, UID assigned by OS

The playbook queries the assigned UID/GID at runtime for Docker container user mapping.

Architecture

Components

Component Location Purpose
PostgreSQL 17 Native on Titania Dedicated identity database
Casdoor Docker on Titania SSO identity provider
HAProxy Titania TLS termination, routing
Alloy Titania Syslog collection

Deployment Order

1. postgresql_ssl/deploy.yml  → Install PostgreSQL, SSL, create casdoor DB
2. casdoor/deploy.yml         → Deploy Casdoor container
3. pgadmin/deploy.yml         → Distribute SSL cert to PGadmin (optional)

Network Ports

Port Service Access
22081 Casdoor HTTP Via HAProxy (network_mode: host)
5432 PostgreSQL SSL for external, plain for localhost
51401 Syslog Local only (Alloy)

Data Persistence

PostgreSQL data (native install):

/var/lib/postgresql/17/main/     # Database files
/etc/postgresql/17/main/         # Configuration
/etc/postgresql/17/main/ssl/     # SSL certificates

Casdoor configuration:

/srv/casdoor/
├── conf/
│   └── app.conf                 # Casdoor configuration
└── docker-compose.yml           # Service definition

Prerequisites

1. Terraform (S3 Buckets)

Casdoor can use S3-compatible storage for avatars and attachments:

cd terraform
terraform apply

2. Ansible Vault Secrets

Add to ansible/inventory/group_vars/all/vault.yml:

# PostgreSQL SSL postgres user password (for Titania's dedicated PostgreSQL)
vault_postgresql_ssl_postgres_password: "secure-postgres-password"

# Casdoor database password
vault_casdoor_db_password: "secure-db-password"

# Casdoor application secrets
vault_casdoor_auth_state: "random-32-char-string"
vault_casdoor_app_client_secret: "generated-client-secret"

# Casdoor initial user passwords (changed after first login)
vault_casdoor_admin_password: "initial-admin-password"
vault_casdoor_hostmaster_password: "initial-hostmaster-password"

# Optional (for RADIUS protocol)
vault_casdoor_radius_secret: "radius-secret"

Generate secrets:

# Database password
openssl rand -base64 24

# Auth state
openssl rand -hex 16

3. Alloy Log Collection

Ensure Alloy is deployed to receive syslog:

ansible-playbook alloy/deploy.yml --limit titania.incus

Deployment

Fresh Installation

cd ansible

# 1. Deploy PostgreSQL with SSL
ansible-playbook postgresql_ssl/deploy.yml

# 2. Deploy Casdoor
ansible-playbook casdoor/deploy.yml

# 3. Update PGadmin with SSL certificate (optional)
ansible-playbook pgadmin/deploy.yml

Verify Deployment

# Check PostgreSQL status
ssh titania.incus "sudo systemctl status postgresql"

# Check Casdoor container
ssh titania.incus "cd /srv/casdoor && docker compose ps"

# Check logs
ssh titania.incus "cd /srv/casdoor && docker compose logs --tail=50"

# Test health endpoint
curl -s http://titania.incus:22081/api/health

Redeployment

To redeploy Casdoor only (database preserved):

ansible-playbook casdoor/remove.yml
ansible-playbook casdoor/deploy.yml

To completely reset (including database):

ansible-playbook casdoor/remove.yml
ssh titania.incus "sudo -u postgres dropdb casdoor"
ssh titania.incus "sudo -u postgres dropuser casdoor"
ansible-playbook postgresql_ssl/deploy.yml
ansible-playbook casdoor/deploy.yml

Configuration Reference

Host Variables

Located in ansible/inventory/host_vars/titania.incus.yml:

# PostgreSQL SSL (dedicated identity database)
postgresql_ssl_postgres_password: "{{ vault_postgresql_ssl_postgres_password }}"
postgresql_ssl_port: 5432
postgresql_ssl_cert_path: /etc/postgresql/17/main/ssl/server.crt

# Casdoor service account (system-assigned UID/GID)
casdoor_user: casdoor
casdoor_group: casdoor
casdoor_directory: /srv/casdoor

# Web
casdoor_port: 22081
casdoor_runmode: dev  # or 'prod'

# Database (connects to localhost PostgreSQL)
casdoor_db_port: 5432
casdoor_db_name: casdoor
casdoor_db_user: casdoor
casdoor_db_password: "{{ vault_casdoor_db_password }}"
casdoor_db_sslmode: disable  # Localhost, no SSL needed

# Logging
casdoor_syslog_port: 51401

SSL Certificate

The self-signed certificate is generated automatically with:

  • Common Name: titania.incus
  • Subject Alt Names: titania.incus, localhost, 127.0.0.1
  • Validity: 10 years (+3650d)
  • Key Size: 4096 bits
  • Location: /etc/postgresql/17/main/ssl/

To regenerate certificates:

ssh titania.incus "sudo rm -rf /etc/postgresql/17/main/ssl/*"
ansible-playbook postgresql_ssl/deploy.yml
ansible-playbook pgadmin/deploy.yml  # Update cert on Portia

PGadmin Connection

To connect from PGadmin on Portia:

  1. Navigate to https://pgadmin.ouranos.helu.ca
  2. Add Server:
    • General tab
      • Name: Titania PostgreSQL (Casdoor)
    • Connection tab
      • Host: titania.incus
      • Port: 5432
      • Database: casdoor
      • Username: casdoor
      • Password: (from vault)
    • SSL tab
      • SSL Mode: Verify-CA
      • Root certificate: /var/lib/pgadmin/certs/titania-postgres-ca.crt

The certificate is automatically distributed by ansible-playbook pgadmin/deploy.yml.

Application Branding & CSS Customization

Casdoor allows extensive customization of login/signup pages through CSS and HTML fields in the Application settings.

Available CSS/HTML Fields

Field Purpose Where Applied
formCss Custom CSS for desktop login forms Login, signup, consent pages
formCssMobile Mobile-specific CSS overrides Mobile views
headerHtml Custom HTML in page header All auth pages (can inject <style> tags)
footerHtml Custom footer HTML Replaces "Powered by Casdoor"
formSideHtml HTML beside the form Side panel content
formBackgroundUrl Background image URL Full-page background
formBackgroundUrlMobile Mobile background image Mobile background
signupHtml Custom HTML for signup page Signup page only
signinHtml Custom HTML for signin page Signin page only

Configuration via init_data.json

Application branding is configured in ansible/casdoor/init_data.json.j2:

{
  "applications": [
    {
      "name": "app-heluca",
      "formCss": "<style>/* Your CSS here */</style>",
      "footerHtml": "<div style=\"text-align:center;\">Powered by Helu.ca</div>",
      "headerHtml": "<style>/* Additional CSS via style tag */</style>",
      "formBackgroundUrl": "https://example.com/bg.jpg"
    }
  ]
}

Example: Custom Theme CSS

The formCss field contains CSS to customize the Ant Design components:

<style>
/* Login panel styling */
.login-panel {
  background-color: #ffffff;
  border-radius: 10px;
  box-shadow: 0 0 30px 20px rgba(255,164,21,0.12);
}

/* Primary button colors */
.ant-btn-primary {
  background-color: #4b96ff !important;
  border-color: #4b96ff !important;
}
.ant-btn-primary:hover {
  background-color: #58c0ff !important;
  border-color: #58c0ff !important;
}

/* Link colors */
a { color: #ffa415; }
a:hover { color: #ffc219; }

/* Input focus states */
.ant-input:focus, .ant-input-focused {
  border-color: #4b96ff !important;
  box-shadow: 0 0 0 2px rgba(75,150,255,0.2) !important;
}

/* Checkbox styling */
.ant-checkbox-checked .ant-checkbox-inner {
  background-color: #4b96ff !important;
  border-color: #4b96ff !important;
}
</style>

Example: Custom Footer

Replace the default "Powered by Casdoor" footer:

<div style="text-align:center;padding:10px;color:#666;">
  <a href="https://helu.ca" style="color:#4b96ff;text-decoration:none;">
    Powered by Helu.ca
  </a>
</div>

Organization-Level Theme

Organization settings also affect theming. Configure in the Organization settings:

Setting Purpose
themeData.colorPrimary Primary color (Ant Design)
themeData.borderRadius Border radius for components
themeData.isCompact Compact mode toggle
logo Organization logo
favicon Browser favicon
websiteUrl Organization website

Updating Existing Applications

Changes to init_data.json only apply during initial Casdoor setup. For existing deployments:

  1. Via Admin UI: Applications → Edit → Update CSS/HTML fields
  2. Via API: Use Casdoor's REST API to update application settings
  3. Database reset: Redeploy with initDataNewOnly = false (overwrites existing data)

CSS Class Reference

Common CSS classes for targeting Casdoor UI elements:

Class Element
.login-panel Main login form container
.login-logo-box Logo container
.login-username Username input wrapper
.login-password Password input wrapper
.login-button-box Submit button container
.login-forget-password Forgot password link
.login-signup-link Signup link
.login-languages Language selector
.back-button Back button
.provider-img OAuth provider icons
.signin-methods Sign-in method tabs
.verification-code Verification code input
.login-agreement Terms agreement checkbox

Initial Setup

After deployment, access Casdoor at https://id.ouranos.helu.ca:

  1. Login with default credentials: admin / 123
  2. Change admin password immediately
  3. Create organization for your domain
  4. Create applications for services that need SSO:
    • SearXNG (via OAuth2-Proxy)
    • Grafana
    • Other internal services

OAuth2 Application Setup

For each service:

  1. Applications → Add
  2. Configure OAuth2 settings:
    • Redirect URI: https://service.ouranos.helu.ca/oauth2/callback
    • Grant types: Authorization Code
  3. Note the Client ID and Client Secret for service configuration

Troubleshooting

PostgreSQL Issues

# Check PostgreSQL status
ssh titania.incus "sudo systemctl status postgresql"

# View PostgreSQL logs
ssh titania.incus "sudo journalctl -u postgresql -f"

# Check SSL configuration
ssh titania.incus "sudo -u postgres psql -c 'SHOW ssl;'"
ssh titania.incus "sudo -u postgres psql -c 'SHOW ssl_cert_file;'"

# Test SSL connection externally
openssl s_client -connect titania.incus:5432 -starttls postgres

Casdoor Container Issues

# View container status
ssh titania.incus "cd /srv/casdoor && docker compose ps"

# View logs
ssh titania.incus "cd /srv/casdoor && docker compose logs casdoor"

# Restart
ssh titania.incus "cd /srv/casdoor && docker compose restart"

Database Connection

# Connect as postgres admin
ssh titania.incus "sudo -u postgres psql"

# Connect as casdoor user
ssh titania.incus "sudo -u postgres psql -U casdoor -d casdoor -h localhost"

# List databases
ssh titania.incus "sudo -u postgres psql -c '\l'"

# List users
ssh titania.incus "sudo -u postgres psql -c '\du'"

Health Check

# Casdoor health
curl -s http://titania.incus:22081/api/health | jq

# PostgreSQL accepting connections
ssh titania.incus "pg_isready -h localhost"

Security Considerations

  1. Change default admin password immediately after deployment
  2. Rotate database passwords periodically (update vault, redeploy)
  3. Monitor authentication logs in Grafana (via Alloy/Loki)
  4. SSL certificates have 10-year validity, regenerate if compromised
  5. Backup PostgreSQL data regularly - contains all identity data: 
    ssh titania.incus "sudo -u postgres pg_dump casdoor > casdoor_backup.sql"

Related Documentation

Reference in New Issue View Git Blame Copy Permalink