EasyTokens

A device-code phishing server for adversary emulation. Captures Microsoft 365 OAuth tokens via the Device Authorization Grant flow. Inspired by GraphSpy.

Warning — Authorized Use Only. This tool is intended for penetration testers and red teamers operating under explicit written authorization. Misuse may violate computer fraud laws.

How It Works

1. Operator creates a device code campaign via the operator UI.
2. A victim-facing enrollment page (Dunder Mifflin themed) displays the user code and prompts the target to authenticate at microsoft.com/devicelogin.
3. A background poller detects when the target completes authentication and stores the captured access/refresh token in SQLite.
4. The victim's browser is redirected to a post-auth search page.
5. The operator can search the victim's OneDrive and email via Microsoft Graph using the captured token.

Architecture

Python backend (one port per campaign) + nginx front-end + SQLite persistence.

main_server.py          ← unified entry point (run this)
db.py                   ← SQLite persistence layer
html_enroll.py          ← victim enrollment page builder
html_search.py          ← victim post-auth search page builder
css_shared.py           ← shared CSS for operator UI
nginx_helper.py         ← auto-generates and reloads nginx reverse-proxy config
nginx.conf              ← base nginx config (includes /etc/nginx/conf.d/*.conf)

Routes

Nginx — Domain Campaigns

When a campaign is created with a domain set, nginx_helper.py automatically writes a per-domain server block to NGINX_CONF (/etc/nginx/conf.d/easytokens.conf by default) and reloads nginx. Victim traffic arriving on port 80 for that domain is proxied to the correct Python server instance.

• Campaigns without a domain are served directly on the Python port (default 3000).
• Campaigns with a domain are served through nginx on port 80.
• The base nginx.conf drops any request whose Host header does not match a known campaign (return 444), preventing accidental exposure of the Python backend.
• Set NGINX_CONF='' or NGINX_RELOAD_CMD='' to disable automatic nginx management.

Quick Start (Docker)

docker compose up --build

Ports exposed by Docker:

• Victim page (direct): http://localhost:3000/
• Operator UI: http://localhost:3000/app
• Domain campaigns: http://<campaign-domain>/ (routed through nginx on port 80)

Captured tokens and logs are persisted to Docker volumes:

Manual Setup

Requirements: Python 3.12+, no third-party packages.

python main_server.py

Environment Variables

PHP Relay Node

The php-relay/ directory contains a standalone Apache/PHP container that acts as a distributed victim-facing node. It serves the same device-code enrollment page as the main server, polls Microsoft directly, and forwards captured tokens to the main panel via POST /webhook.

How It Works

1. On startup, checkin.php POSTs to POST /relay/checkin on the main panel, authenticating with RELAY_SECRET. The panel registers the node and returns a node_id.
2. Victims browse to the relay's enrollment page (index.php), which initiates a fresh device-code flow.
3. Browser-side JS polls poll.php. When a token is captured, poll.php forwards it to POST /webhook on the main panel, tagged with the node_id.

Relay Environment Variables

Configure in php-relay/.env:

Quick Start

Both containers simultaneously (recommended):

# from EasyTokens/
docker compose -f docker-compose.yml -f php-relay/docker-compose.yml up --build

Running both with a single -f merge puts them on the same Docker network, so MAIN_SERVER_URL=http://easytokens:3000 resolves correctly.

Access:

Relay only (remote panel):

cd php-relay
# Set MAIN_SERVER_URL to the public panel URL in .env
docker compose up --build

Shared Secret Setup

1. Generate a secret: openssl rand -hex 32
2. Set RELAY_SECRET=<secret> in EasyTokens/.env (picked up by the main panel via docker-compose.yml)
3. Set the same value in php-relay/.env

Database

Two tables in the SQLite database:

• tokens — every captured access/refresh token (UPN, access token, refresh token, id token, scope, source, capture timestamp)
• device_codes — operator-initiated campaigns (user code, device code, verification URL, status, linked token ID, port, domain)

Microsoft OAuth Details

License

MIT — Copyright (c) 2026 Casey Smith