Set Up Authentication

Securing your Oxy deployment with proper authentication is essential, especially when deployed on a cloud environment. This step is optional but highly recommended for cloud deployments.

Choose Authentication Method

Decide which authentication method to use based on your requirements:

Basic Auth: Simple username/password authentication, suitable for simple deployments
OAuth2: More advanced authentication with third-party providers like Google, GitHub, etc.

Configure Authentication

Follow the instructions for your chosen authentication method:

Configure Caddy for basic authentication by updating your Caddyfile:

# Generate password hash
caddy hash-password
# Enter your password when prompted

Then update your Caddyfile:

your-domain.com {
  basicauth {
    <username> <hashed_password>
  }
  reverse_proxy localhost:8080
}

Replace <username> with your desired username and <hashed_password> with the hash generated by caddy hash-password. For more details on Caddy’s basic authentication, see the Caddy basic_auth documentation.

For example, with username “Bob” and password “hiccup”:

your-domain.com {
  basicauth {
    Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
  }
  reverse_proxy localhost:8080
}

Apply the changes:

sudo systemctl reload caddy

Configure Caddy for basic authentication by updating your Caddyfile:

# Generate password hash
caddy hash-password
# Enter your password when prompted

Then update your Caddyfile:

your-domain.com {
  basicauth {
    <username> <hashed_password>
  }
  reverse_proxy localhost:8080
}

For example, with username “Bob” and password “hiccup”:

your-domain.com {
  basicauth {
    Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
  }
  reverse_proxy localhost:8080
}

Apply the changes:

sudo systemctl reload caddy

These instructions use Google as the OAuth2 provider. You’ll need to set up a Google OAuth2 client in the Google Cloud Console first. Follow the Google OAuth 2.0 setup guide to create your client ID and client secret.

Install OAuth2 Proxy:

# For arm64 architecture
OAUTH2_PROXY_VERSION="v7.8.2"
ARCH="linux-arm64"
wget "https://github.com/oauth2-proxy/oauth2-proxy/releases/download/${OAUTH2_PROXY_VERSION}/oauth2-proxy-${OAUTH2_PROXY_VERSION}.${ARCH}.tar.gz"
tar -xzf "oauth2-proxy-${OAUTH2_PROXY_VERSION}.${ARCH}.tar.gz"
sudo mv "oauth2-proxy-${OAUTH2_PROXY_VERSION}.${ARCH}/oauth2-proxy" /usr/local/bin/
sudo chmod +x /usr/local/bin/oauth2-proxy
rm -rf "oauth2-proxy-${OAUTH2_PROXY_VERSION}.${ARCH}"*

Create configuration for OAuth2 Proxy:

sudo mkdir -p /etc/oauth2-proxy
cat <<EOF | sudo tee /etc/oauth2-proxy/oauth2-proxy.cfg
provider = "google"
http_address = "127.0.0.1:4180"
upstreams = ["http://127.0.0.1:3000"]
email_domains = ["*"]
client_id = "your-client-id.apps.googleusercontent.com"
client_secret = "your-client-secret"
cookie_secret = "$(openssl rand -base64 32 | cut -c1-32)"
cookie_domains = ["your-domain.com"]
redirect_url = "https://your-domain.com/oauth2/callback"
cookie_secure = true
set_xauthrequest = true
pass_authorization_header = true
pass_access_token = true
skip_provider_button = true
EOF

Replace your-client-id.apps.googleusercontent.com and your-client-secret with your actual OAuth credentials from your provider (Google in this example).

Create a systemd service for OAuth2 Proxy:

cat <<EOF | sudo tee /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network.target

[Service]
User=ubuntu
ExecStart=/usr/local/bin/oauth2-proxy --config /etc/oauth2-proxy/oauth2-proxy.cfg
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable oauth2-proxy
sudo systemctl start oauth2-proxy

Configure Caddy to use OAuth2 Proxy:

your-domain.com {
    @static_assets {
        path *.js *.css *.svg *.json *.gif *.wasm
    }

    handle /auth {
        reverse_proxy 127.0.0.1:4180 {
            header_up x-real-ip {remote_host}
            header_up x-forwarded-uri {uri}
        }
    }

    # Skip auth for static assets
    handle @static_assets {
        reverse_proxy localhost:3000
    }

    handle {
        forward_auth 127.0.0.1:4180 {
            uri /auth
            header_up x-real-ip {remote_host}
            copy_headers x-auth-request-user x-auth-request-email x-auth-request-access-token authorization

            @error status 401
            handle_response @error {
                redir * /auth/sign_in?rd={scheme}://{host}{uri}
            }
        }

        reverse_proxy localhost:3000
    }
}

Apply the changes:

sudo systemctl reload caddy

Test Authentication

Test that your authentication is working correctly:

# Using curl to test basic auth
curl -u username:password https://your-domain.com

# Or test by accessing in a browser

Make sure you can access your Oxy deployment only after successful authentication.

Set Up Automatic Updates (Optional)

For automatic updates, you can set up a cron job:

# Update Oxy every day at midnight and restart the service
UPDATE_OXY_CRON="0 0 * * * curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/oxy-hq/oxy/refs/heads/main/install_oxy.sh | bash && cd ~/your-oxy-project && git pull origin main && sudo systemctl restart oxy"
(crontab -l 2>/dev/null | grep -v -F "$UPDATE_OXY_CRON"; echo "$UPDATE_OXY_CRON") | crontab -

Congratulations! Your Oxy deployment is now complete and secured with authentication.

Learn about deployment

Hands-on Guides

Set Up Authentication