Casdoor IAM and SSO on AWS User Guide

Overview

This guide covers the deployment and configuration of Casdoor on AWS using cloudimg AWS Marketplace AMIs. Casdoor is an open source, self hosted, UI first identity and access management (IAM) and single sign on platform. It is a full authentication server: it issues signed OIDC and OAuth2 tokens and also supports SAML, CAS, LDAP and WebAuthn, so one deployment can be the login for all of your applications. A rich admin console manages organizations, users, applications, providers, roles, permissions, certificates, sessions and tokens, alongside a customisable login and account web interface.

The image installs the official Casdoor release, a single self contained Go binary that bundles its pre built web console, verified by checksum and recorded in /opt/casdoor/VERSION. Casdoor runs under systemd as the unprivileged casdoor system user and uses an embedded SQLite database, so a complete identity provider with its web console runs with no external database. nginx terminates TLS on port 443 and reverse proxies to Casdoor, and a host firewall (ufw) keeps the application port reachable only through that TLS front, so the OIDC issuer and its tokens are always served over HTTPS.

The image ships with no known login. Casdoor seeds a built in admin user with a default password the first time it initialises an empty database, and the captured image ships an empty database with no baked secrets. On the first boot of every instance, a one shot service boots Casdoor against the empty database, generates a unique admin password for that specific instance, resets the admin to that password through the Casdoor API, proves the default password no longer works, and writes the new one to a file that only the root user can read. The JWT signing certificate and the built in application client secret are also generated fresh per instance. No credentials and no key material are ever shared between instances.

What is included:

• The official Casdoor release (a single Go binary with its full web console bundled), verified by checksum and run under systemd as the unprivileged casdoor system user

• An embedded SQLite database, so a full identity provider runs with no separate database to operate

• nginx terminating TLS on :443 and reverse proxying to Casdoor, with HSTS and sensible security headers

• A host firewall (ufw) that denies inbound traffic except 22, 80 and 443, so the application port 8000 is never exposed directly

• Port :80 returns a 301 redirect to HTTPS for every path except an unauthenticated /healthz endpoint (HTTP 200) for load balancer probes

• A self signed TLS certificate regenerated per instance on first boot (SAN includes the instance public IP, hostname and 127.0.0.1) — replace it with your own CA signed certificate for production

• A per instance admin password generated on first boot into /root/casdoor-credentials.txt (readable by root only) — the upstream default password is reset and proven rejected, and no shared credential is ever baked in

• A built in self test at /opt/casdoor/casdoor-selftest.sh that proves the admin login round trip end to end over TLS

• Ubuntu 24.04 LTS base with latest security patches applied at build time

• cloud-init integration for SSH key injection and per instance initialisation

• 24/7 cloudimg support with guaranteed 24 hour response SLA

Connecting to your instance

Connect over SSH on port 22 as the default login user for your AMI's operating system. Use the private key of the EC2 key pair you selected at launch.

Prerequisites

• An AWS account with permission to launch EC2 instances

• An EC2 key pair for administrative SSH access to the instance as the ubuntu user

• A security group allowing inbound TCP 443 (HTTPS) and 80 (redirect) from the networks that should reach the service, and 22 (SSH) from your management network only

• A recommended instance type of m5.large or larger

Step 1: Launch from the AWS Marketplace

1. Locate the Casdoor listing from cloudimg in AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch.

2. Choose the region, the m5.large (or larger) instance type, your VPC and subnet, and your EC2 key pair.

3. Configure the security group to allow inbound 443 and 80 from the clients and applications that will use single sign on, and restrict 22 to your management network.

4. Launch. When the instance is running, browse to https://<public-ip>/.

Step 2: Launch from the AWS CLI

You can launch the same AMI from the AWS CLI. Replace the AMI id, key name, security group and subnet as needed:

aws ec2 run-instances \
  --image-id ami-<casdoor-ami-id> \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=casdoor}]'

Step 3: Verify the Casdoor and nginx services

SSH in as ubuntu and confirm the services are active, and that nginx is the only public listener while the host firewall allows just 22, 80 and 443:

sudo systemctl is-active casdoor nginx casdoor-firstboot

ss -tln | grep -E ':8000|:80 |:443 '

sudo ufw status

You should see Casdoor on 0.0.0.0:8000 and nginx on 0.0.0.0:80 and 0.0.0.0:443, with ufw active and allowing only 22, 80 and 443 — so the application port 8000 is reachable only through the nginx TLS front, not from the network.

Step 4: Inspect the OIDC discovery document

Casdoor publishes its OpenID Connect configuration at the standard discovery URL. Confirm it answers over TLS and shows the issuer and the core OIDC endpoints your applications will use:

curl -sk https://127.0.0.1/.well-known/openid-configuration | python3 -m json.tool

The issuer is the HTTPS URL of this instance, and the document advertises the authorization, token, userinfo, device authorization, registration, introspection and JWKS endpoints that your applications use to integrate single sign on.

Step 5: Retrieve the per instance admin login

The unique admin password generated for this specific instance on first boot is written to a root only file. Read it to get the admin username and password:

sudo cat /root/casdoor-credentials.txt

The default admin user is admin. Note the casdoor.admin_password value — you will use it to log in in the next step, and you should change it immediately afterwards. The upstream default password is reset on first boot and is proven rejected, so it can never be used to reach your instance.

Step 6: Sign in to the Casdoor web console

Browse to https://<public-ip>/. Because the certificate is self signed and generated per instance, your browser will warn about the certificate the first time. Accept it (or install your own certificate, see Step 13). You are presented with the Casdoor sign in form. Enter the admin username admin and the per instance password from Step 5, then select Sign In.

Step 7: Review the admin dashboard

After signing in you land on the Dashboard. It summarises the instance at a glance: total and new users, and counts of organizations, applications, tokens and providers, with activity charts. The left hand navigation gives you User Management, Identity, Authorization, Auditing and Admin sections for the whole platform.

Step 8: Manage users

Open User Management then Users to see the users in your organizations. The built in organization ships with the single admin user. From here you can add users, edit their profiles and roles, impersonate a user for troubleshooting, or import users in bulk. Every user here can sign in through the applications you connect to Casdoor.

Step 9: Review your applications

Open Identity then Applications. An application in Casdoor is a login integration: each one has its own client id and secret, redirect URIs, sign in methods and branding. The built in app-built-in application powers this console. To add single sign on to your own service, create a new application here, set its redirect URI, and give your service the client id, client secret and the endpoints from the discovery document in Step 4.

Step 10: Prove the admin login from the command line

The image ships a self test that proves the per instance admin credential authenticates end to end over TLS, and that the upstream default password is rejected. It performs the real login flow: it rejects admin/123 (the upstream default), then accepts the per instance password and completes an authenticated session round trip:

sudo /opt/casdoor/casdoor-selftest.sh

The expected output reports round-trip OK, confirming the default admin/123 was rejected and the per instance password was accepted over TLS.

Step 11: Check the baked version and appliance info

The exact Casdoor version and the release tarball checksum baked into the image are recorded on the instance, and the per instance credentials file is root only:

cat /opt/casdoor/VERSION

sudo ls -l /root/casdoor-credentials.txt

Step 12: Change the admin password

Change the per instance admin password to one you control as your first action after signing in. In the console, open the admin user (User Management then Users then Edit on the admin user), set a new password in the password field and save. From the same page you can enable multi factor authentication, manage roles and maintain the profile fields that Casdoor exposes as OIDC claims to your connected applications.

Step 13: Use your own domain and a trusted certificate (production)

The image ships a self signed certificate and is served on the instance's IP address, so it is secure out of the box but browsers will warn on the certificate. For production, point a DNS name at the instance, set the public issuer URL to your domain, and install a CA signed certificate. Using a domain also makes Casdoor advertise a clean https://<your-domain> issuer to your applications.

First set the public issuer URL so the OIDC issuer and generated links use your domain. Edit /opt/casdoor/conf/app.conf and set origin and originFrontend, then restart Casdoor:

sudo sed -i \
  -e 's#^origin = .*#origin = https://<your-domain>#' \
  -e 's#^originFrontend = .*#originFrontend = https://<your-domain>#' \
  /opt/casdoor/conf/app.conf
sudo systemctl restart casdoor

Then obtain a free CA signed certificate for your domain with Let's Encrypt:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

Certbot installs the certificate into nginx and sets up automatic renewal.

Step 14: Managing the Casdoor service

sudo systemctl restart casdoor

sudo journalctl -u casdoor.service --no-pager | tail -20

Casdoor's configuration lives in /opt/casdoor/conf/app.conf, and its SQLite database and logs are under /var/lib/casdoor. After editing the configuration, run sudo systemctl restart casdoor.

Step 15: Security recommendations

• Change the admin password immediately. The per instance password in /root/casdoor-credentials.txt is for first sign in only; change it from the admin user page (Step 12) as your first action.

• Restrict SSH. Allow inbound 22 only from your management network; keep 443 (and 80 for the redirect) open to the applications and users that need single sign on. The host firewall already blocks the application port 8000 from the network.

• Install a trusted certificate and a real domain. Replace the self signed certificate with a CA signed one (Step 13) so users are not trained to click through warnings, and so Casdoor advertises a clean https issuer.

• Enable multi factor authentication. Casdoor supports WebAuthn passkeys and one time passwords; enable MFA on the admin account and require it for your users.

• Keep the image updated. Unattended security upgrades remain enabled so the OS keeps receiving patches.

Step 16: Support and Licensing

Casdoor is open source software distributed under the Apache License 2.0. This image bundles the upstream Casdoor release unmodified; the licence is retained on the image. cloudimg packaging, hardening and support are provided by cloudimg.

Deploy on AWS

Find this image on AWS Marketplace and deploy it in minutes. See www.cloudimg.co.uk for the full catalogue.

Need Help?

cloudimg provides 24/7 support with a guaranteed 24 hour response SLA. Contact us through www.cloudimg.co.uk for deployment assistance, configuration help or any questions about this image.