Wiindows workstation with Linux vm

This guide documents a working setup for oauth2-proxy, Keycloak, and NGINX running inside a Linux Virtual Machine, designed for a Windows-based development workflow with IntelliJ IDEA and backend services running on the Windows host.
Reason for not using a Docker environment is because of the peculiarities of WSL2 as well as the Docker networking, where it is increasingly difficult to configure all required redirects (especially if the nginx server does not run in a container).

---

🖥 Environment Overview

• Windows Host: runs the backend API (e.g. at host.local)
• Linux VM: runs NGINX, oauth2-proxy, and Keycloak
• Website frontend is deployed to Linux VM over SFTP into NGINX’s www directory
• Static domain: https://tqadm-dev.vanevski.net
• Keycloak is accessible at http://tqadm-dev.vanevski.net:8080

---

🔧 NGINX Configuration (/etc/nginx/nginx.conf)

http {
    proxy_headers_hash_max_size 1024;
    proxy_headers_hash_bucket_size 128;

    server {
        listen 443 ssl;
        server_name tqadm-dev.vanevski.net;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        location /oauth2/auth {
            internal;
            proxy_pass http://127.0.0.1:4180;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

        location /oauth2/ {
            proxy_pass http://127.0.0.1:4180;
            include proxy_params;
        }

        location /auth/ {
            proxy_pass http://127.0.0.1:8080/;
            include proxy_params;
        }

        location / {
            auth_request /oauth2/auth;
            error_page 401 = @oauth2_signin;
            root /var/www/html;
            index index.html;
        }

        location @oauth2_signin {
            return 302 /oauth2/start?rd=$request_uri;
        }
    }
}

---

⚙️ oauth2-proxy Config (/etc/oauth2-proxy/oauth2-proxy-adm.cfg)

provider = "keycloak-oidc"
oidc_issuer_url = "http://tqadm-dev.vanevski.net:8080/realms/tqpro-adm"
client_id = "tqweb-adm"
client_secret = "REPLACE_ME"

http_address = "0.0.0.0:4180"
redirect_url = "https://tqadm-dev.vanevski.net/oauth2/callback"

whitelist_domains = ["tqadm-dev.vanevski.net", "tqadm-dev.vanevski.net:8080"]

cookie_secret = "GENERATED_BASE64_SECRET"
cookie_secure = true
cookie_samesite = "lax"
cookie_domains = ["tqadm-dev.vanevski.net"]
cookie_name = "_oauth2_proxy"

email_domains = ["*"]
set_xauthrequest = true
pass_user_headers = true
pass_access_token = true
skip_provider_button = true

auth_logging = true
request_logging = true
standard_logging = true

---

🔌 Systemd: oauth2-proxy

/etc/systemd/system/oauth2-proxy.service

[Unit]
Description=OAuth2 Proxy
After=network.target

[Service]
Type=simple
User=oauth2
ExecStart=/usr/local/oauth2-proxy --config /etc/oauth2-proxy/oauth2-proxy-adm.cfg
Restart=always

[Install]
WantedBy=multi-user.target

---

🔌 Systemd: Keycloak

/etc/systemd/system/keycloak.service

[Unit]
Description=Keycloak Server
After=network.target

[Service]
Type=simple
User=keycloak
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start-dev --hostname=tqadm-dev.vanevski.net --hostname-strict=false
Restart=on-failure

Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk
Environment=KEYCLOAK_ADMIN=admin
Environment=KEYCLOAK_ADMIN_PASSWORD=admin

[Install]
WantedBy=multi-user.target

---

🧪 Logout Best Practice (Server-Side)

Your backend should:

1. Call Keycloak logout endpoint:

   POST http://tqadm-dev.vanevski.net:8080/realms/tqpro-adm/protocol/openid-connect/logout
   Content-Type: application/x-www-form-urlencoded
   id_token_hint=<user_id_token>
   

2. Redirect user to:

   /oauth2/sign_out?rd=/loggedout.html
   

---

📂 Website Deployment

• Upload static content (e.g. index.html, loggedout.html) to /var/www/html/ via SFTP from Windows host
• You can use IntelliJ SFTP deployment to sync automatically

---

✅ Final Notes

• Make sure port 80, 8080 and 443 is exposed from VM and accessible from Windows
• Add tqadm-dev.vanevski.net → VM IP to Windows hosts file
• Ensure SSL certs are valid or trusted on local machine

---